logics-manager

logics-manager is a local workflow runtime for projects that keep their delivery memory in Markdown.

The core product is the CLI. It creates, promotes, validates, audits, and closes the logics/* documents that describe work:

request -> backlog item -> task -> implementation

Everything else in this repository is a client around that runtime:

• the VS Code extension gives humans a board, details panel, previews, search, and insights;
• the MCP server gives assistants a bounded tool API over the same CLI;
• the npm package and Python package are distribution paths for the same runtime.

The source of truth stays in your repository. Logics documents are plain Markdown, versioned with git, readable in reviews, and reusable by humans or AI assistants across sessions.

What It Solves

AI-heavy projects often lose context between chats, agents, and implementation passes. Logics turns that context into durable project artifacts:

• request: the problem, need, and acceptance criteria;
• backlog item: a scoped delivery slice;
• task: executable implementation work;
• product brief: product framing and intent;
• ADR: architectural decisions;
• spec: behavioral contract.

The result is a repo-local memory layer that reduces re-explaining, keeps implementation grounded, and gives every assistant or human the same inspectable workflow state.

Product Shape

logics-manager has one core and several integrations:

Layer	Purpose
CLI runtime	Canonical workflow engine for creating, promoting, auditing, repairing, and closing Logics docs.
VS Code extension	Human-facing cockpit for navigating and managing the Markdown corpus.
MCP server	Assistant-facing adapter that exposes bounded Logics tools without giving agents a shell.
npm / Python packaging	Installation paths for the same CLI/runtime.

The CLI owns the behavior. The extension and MCP server call into it instead of reimplementing workflow logic.

Quick Start

Install the CLI from this repository:

python3.11 -m pip install .
logics-manager --help

Or install the npm package:

npm install -g @grifhinz/logics-manager
logics-manager --help

Initialize or check a repository:

logics-manager bootstrap --check

Create the first workflow document:

logics-manager flow new request --title "Improve onboarding"

Validate the workflow corpus:

logics-manager lint --require-status
logics-manager audit

Core CLI

The CLI is the stable contract for Logics. It supports:

• bootstrapping the logics/ tree;
• creating requests, backlog items, tasks, product briefs, and ADRs;
• promoting request -> backlog and backlog -> task;
• splitting large requests or backlog items;
• closing tasks, backlog items, and requests with consistency checks;
• linting and auditing workflow traceability;
• exporting indexes, context packs, and graph data;
• serving the bounded MCP tool surface.

Useful commands:

logics-manager flow list
logics-manager flow promote request-to-backlog logics/request/req_001_example.md
logics-manager flow promote backlog-to-task logics/backlog/item_001_example.md
logics-manager flow finish task logics/tasks/task_001_example.md
logics-manager sync context-pack req_001_example --format json

To update the installed CLI later:

logics-manager self-update

VS Code Extension

The VS Code extension is the human cockpit around the same runtime. It helps you:

• browse workflow docs as a board or list;
• preview Logics Markdown with clickable references and Mermaid rendering;
• create and promote workflow items without leaving the editor;
• inspect recent activity, status, theme, confidence, stale work, and backlog coverage;
• run validation-oriented actions from the UI.

Install from the Marketplace:

https://marketplace.visualstudio.com/items?itemName=cdx-logics.cdx-logics-vscode

For local development or manual VSIX testing:

npm install
npm run package
npm run install:vsix

MCP For Assistants

The MCP server is an assistant-facing adapter over the CLI. It is useful when a chat assistant should work with Logics documents without getting arbitrary filesystem or shell access.

The MCP surface can:

• create and promote workflow docs;
• read, list, search, and build context packs from approved Logics docs;
• update controlled indicators and append bounded notes;
• finish or close workflow docs through canonical commands;
• run lint, audit, deterministic repairs, split operations, and Logics-scoped diffs.

Inspect the exposed tools:

python3 -m logics_manager mcp tools

Run the local stdio server:

python3 -m logics_manager mcp serve --repo-root .

Run the local HTTP server for an HTTPS tunnel:

LOGICS_MCP_BEARER_TOKEN="$(openssl rand -hex 32)" python3 -m logics_manager mcp serve-http --repo-root . --host 127.0.0.1 --port 8765

POST /mcp accepts Authorization: Bearer <token> when LOGICS_MCP_BEARER_TOKEN or --bearer-token is set. Keep /health unauthenticated for smoke checks, but do not expose /mcp publicly without a bearer token.

Start the local server and a temporary localtunnel session in one command:

python3 -m logics_manager mcp tunnel --repo-root . --port 8765

For short-lived live debugging only, run without bearer auth:

python3 -m logics_manager mcp tunnel --repo-root . --port 8765 --no-bearer

During project development, the same commands can be run through the repository binary:

node scripts/npm/logics-manager.mjs mcp tunnel --repo-root . --port 8765
node scripts/npm/logics-manager.mjs mcp tunnel --repo-root . --port 8765 --no-bearer

Generate a local connector plan:

python3 -m logics_manager mcp connect --repo-root . --port 8765

With an HTTPS tunnel URL:

python3 -m logics_manager mcp connect --repo-root . --public-url https://example-tunnel.example --check

For a no-bearer plan:

python3 -m logics_manager mcp connect --repo-root . --public-url https://example-tunnel.example --no-bearer --check

The connector plan prints the bearer token when used, server command, tunnel target, assistant connector URL, auth mode, auth header, smoke checks, warnings, and cleanup steps.

Assistant Model

The project is local-first:

• each operator runs the CLI and MCP server against their own repository;
• remote chat assistants connect through a short-lived HTTPS tunnel when needed;
• coding agents consume prepared tasks and run validations in the repo;
• shared GPTs or assistant configs can carry instructions, but each user keeps their own local connector URL and token.

This avoids a hosted multi-tenant Logics service while still allowing ChatGPT, Claude, Codex, or another MCP-capable assistant to work against the same workflow contract.

Onboarding Prompts

Use these as quick starting points when you want the plugin or the shared Logics flow to help frame work before execution.

(1) Need

Start a new request for this problem: <describe the need or pain point>

Ask me any clarifying questions that would make the request stronger. Suggest helpful options if I need guidance.

(2) Framing

Generate backlog items for the new requests and split them into separate delivery slices.

Ask me any questions that would increase your confidence or improve your understanding before you finalize the backlog.

(3) Orchestration Tasks

Create the orchestration tasks needed to execute the backlog slices, one bounded task per coherent delivery wave.

If the slice is still broad, propose a split before you draft the tasks and ask any questions that would reduce ambiguity.

(4) Execution

Execute task <task id or title>. Commit after each wave, keep going until the work is done, and do not stop early.

If you need to make assumptions, state them briefly and keep the task moving.

What the docs are for

• If you think "here is the problem and context..." -> request
• If you think "this needs a scoped delivery slice..." -> item
• If you think "we want..." -> product brief
• If you think "we decided..." -> ADR
• If you think "the system should..." -> spec
• If you think "let's do..." -> task

Board panel

Filter panel

List panel

Requirements

• To use the extension:
  • A workspace folder open in VS Code.
  • Git on PATH for workspace and repository repair flows.
  • logics/ is bootstrapped automatically when needed.
  • The normal path uses the bundled runtime and logics-manager.
  • Python 3 on PATH for script-backed workflow actions. The extension accepts python3, python, py -3, or py.
• To build, package, or test the extension locally:
  • Node.js + npm.
• Optional CLI tooling:
  • VS Code CLI code on PATH for terminal-based VSIX install or npm run dev.

Windows notes:

• You do not need the code CLI for normal extension usage inside VS Code.
• If Python is installed through the Windows launcher, py -3 is supported by the extension.
• Repository-managed text files are normalized through .gitattributes; let Git handle CRLF/LF conversion instead of rewriting line endings manually.

Runtime Compatibility

• Canonical CLI and runtime contract: logics-manager
• The bundled runtime is the supported steady-state path for the extension.
• If the bundled runtime is missing or incompatible, create/promote actions fail with explicit error messaging in the extension.

Runtime smoke checklist

• Create a request from UI (New Request) and confirm markdown is generated.
• Create a fixture request with logics-manager flow new request --title "Smoke test" and confirm the compact synthetic request shape is generated.
• Create a backlog item and a task from the UI and confirm markdown is generated.
• Open Read on a Mermaid-bearing doc and confirm the graph is rendered.
• Promote request -> backlog and confirm links are updated.
• Confirm request/backlog/task generation fails fast if a Mermaid signature or traceability block is stale instead of waiting for audit to find it later.
• Promote backlog -> task and confirm task document is generated.
• Refresh board/details and confirm data remains consistent.

VS Code Extension Installation

This section is only for installing the VS Code extension. For the core CLI, use the Quick Start section above.

Marketplace

https://marketplace.visualstudio.com/items?itemName=cdx-logics.cdx-logics-vscode

VSIX

code --install-extension logics-manager-<version>.vsix --force

If you don't have the code CLI on PATH:

• Windows: either use the VS Code installer option that adds code to PATH, or install the .vsix from the VS Code UI via Extensions -> ... -> Install from VSIX....
• macOS/Linux: you can enable it from Command Palette -> Shell Command: Install 'code' command in PATH.

Extension Development From Source

npm install
npm run compile
npm run test

Run the extension:

• In VS Code: Run -> Start Debugging (F5)
• The Extension Development Host opens.
• Open the Logics panel at the bottom -> Orchestrator.

If you prefer the terminal helper:

npm run dev

npm run dev requires the code CLI on PATH, so the F5 path above remains the safest cross-platform dev entrypoint.

Deploy / Release (VSIX)

1. Bump the version in package.json, pyproject.toml, and root VERSION when preparing a release manually.
2. Curate the matching changelog entry in changelogs/CHANGELOGS_X_Y_Z.md.
3. Validate that the changelog matches the current package version:

npm run release:changelog:validate

4. Build and package:

npm run package

This creates logics-manager-<version>.vsix in the repo root.

5. Smoke-test the package locally:

npm run install:vsix

6. Distribute the .vsix and use the matching release notes when publishing.

If the current plugin version is already published, logics-manager assist next-step can now propose the next release step instead of stalling on an already-live tag.

Commands

• Logics: Refresh
• Logics: Refresh Agents
• Logics: Select Agent
• Logics: Open Item
• Logics: Promote Item
• Logics: New Request
• Logics: Create Companion Doc
• Logics: Check Environment
• Logics: Open Hybrid Insights
• Logics: Open Logics Insights
• Logics: Triage Item
• Logics: Assess Diff Risk
• Logics: Build Validation Checklist
• Logics: Review Doc Consistency

Validation

• Compile: npm run compile
• Lint TS: npm run lint
• Unit tests: npm run test
• Plugin coverage: npm run test:coverage
• VSIX package validation: npm run package:ci
• Logics docs lint: npm run lint:logics
• Logics workflow audit + docs lint: npm run audit:logics
• Strict Logics governance audit: npm run audit:logics:strict
• Fast extension-focused local check: npm run ci:fast
• Full CI-equivalent local check: npm run ci:check
• Security audit policy gate: npm run audit:ci

npm run audit:logics uses the default active-work profile. It blocks correctness and traceability failures, but reports early companion-doc polish such as missing overview Mermaid diagrams as warnings so drafting and agent handoffs can continue.

npm run audit:logics:strict uses the strict governance profile. Use it before release or governance review when companion docs must be complete and warning-class findings should be resolved.

logics-manager audit --format json and logics-manager lint --format json expose issue_count, warning_count, strict_count, finding_count, can_continue, and release_ready. Agents should treat issue_count > 0 as blocking active work, and release_ready: false as a signal that cleanup remains before release-grade validation.

npm run ci:check mirrors the blocking repository CI contract, including Logics strict-status lint, request auto-close sync verification, workflow audit, Python tests, CLI smoke checks, TypeScript validation, extension tests, and VSIX packaging.

npm run audit:ci enforces the repository audit policy locally. It blocks new actionable vulnerabilities and only allows the explicitly documented temporary exceptions tracked in the backlog.

CI runs compile, lint, tests, Logics docs lint, and VSIX packaging validation on every push and pull_request via .github/workflows/ci.yml.

Windows Validation From macOS

Use a two-layer strategy:

• CI is the fast default. The repository now validates supported Windows flows in GitHub Actions on windows-latest.
• A real Windows VM is still required for targeted debugging and release confidence on shell, PATH, launcher, filesystem, and VS Code host behavior.

Recommended local VM path from macOS:

• Apple Silicon: UTM with Windows 11 ARM is the pragmatic low-cost option.
• Intel Mac: UTM or another Windows-capable VM is fine.

Suggested VM checklist:

1. Install VS Code, Git, Python 3, and Node.js inside the VM.
2. Confirm launchers from the Windows shell you actually care about (git --version, py -3 --version or python --version, node --version, npm --version).
3. Clone the repo and run npm ci.
4. Run the automated baseline first: npm run ci:check and python -m logics_manager lint.
5. Smoke the real Windows-only paths:
   • install the .vsix from VS Code or with code --install-extension ...
   • trigger Bootstrap Logics
   • run Logics: Check Environment
   • run logics-manager assist runtime-status --format json and confirm windows_safe_entrypoint still points to python -m logics_manager flow assist ...
   • run logics-manager assist diff-risk --backend auto --format json and logics-manager assist validation-checklist --format json
   • confirm those shared-runtime commands still work without relying on any repo-local Codex overlay path
   • create a request, backlog item, and task
   • promote request -> backlog and backlog -> task
   • confirm py -3 or python launcher resolution works as expected
6. Use the VM for release preparation and any bug that smells like shell quoting, PATH resolution, case-insensitive paths, symlink restrictions, or extension-host behavior. Do not treat macOS-only local simulation as a full Windows substitute.

Closing Logics Work

Do not mark a Logics task as Done by editing markdown indicators manually. Use the canonical logics-manager guarded finish command so closure propagates correctly from task -> backlog -> request and the linked chain is verified.

npm run logics:finish:task -- logics/tasks/task_020_orchestration_delivery_for_req_019_req_020_and_req_021.md

This uses the runtime-native command:

• logics-manager flow finish task ...

If you want a full repository-wide check afterward, run:

• npm run audit:logics

If you edit statuses by hand, the docs can look valid while the request/backlog chain is left out of sync.

For multi-wave delivery work, prefer coherent checkpoints:

• update the linked Logics docs during the wave that changes the behavior;
• leave the repo in a commit-ready state at the end of the wave;
• then create the reviewed commit checkpoint instead of batching several undocumented partial states.

Accessibility Baseline

For new UI controls in this project:

• Every interactive control must expose an accessible name (aria-label or visible text).
• Icon-only controls must include a title tooltip for discoverability.
• Dynamic toggles must keep ARIA state in sync (aria-expanded, aria-disabled, aria-pressed).
• Custom interactive elements must be keyboard reachable (tabindex) and activatable (Enter/Space).
• Keep hover/focus descriptions consistent across toolbar, board, menus, and details panel.

Notes

• Promotion is only allowed for request/backlog items that are not already used.
• Items with Progress: 100% are treated as completed.
• The UI reads and writes the existing Markdown files; it does not manage a separate database.
• For stable references in the board/details panel, use canonical markdown links:
  • Derived from \logics//.md`orPromoted from `...``
  • # Backlog section in requests
  • # References and # Used by sections with backticked relative paths
• For companion docs (prod_*, adr_*), Related request/backlog/task/architecture indicators are also indexed as managed-doc links.
• Companion docs should still mirror those links under # References with canonical relative paths so the runtime and plugin stay aligned.
• Legacy nested list blocks (- References: / - Used by:) are also parsed for backward compatibility.