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 embeds the same local viewer inside VS Code;
• 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.

The Viewer

A local, read-only board over your logics/* documents — requests, backlog items, tasks, product briefs, and architecture decisions as columns, filterable, searchable, grouped by whatever you're deciding. It runs standalone (logics-manager view) or embedded in the VS Code extension.

Opening a card reads the document in place — indicators, acceptance criteria, and all — without leaving the board.

Health surfaces lint, audit, and workflow findings from the real viewer, with a styled repair action when automated fixes are available.

Insights summarizes the workflow shape and attention signals without leaving the viewer.

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;
• roadmap: versioned long-term plan such as 0.1 -> 0.2 -> 1.0;
• 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:

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

Quick Start

The recommended install path is the npm package. It bundles the CLI runtime in a self-contained launcher that works the same on macOS, Linux, and Windows / WSL:

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

Install the CLI from this repository when developing locally:

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

Python install paths (legacy, not recommended)

Deprecated. pip and pipx installs are still published for backwards compatibility, but they are no longer the supported path: they break on PEP 668 distros, on WSL (slow /mnt/<drive> IO and gio opener failures), and on Python interpreters that diverge from the build matrix. Prefer the npm install above. The PyPI release will keep shipping — we only stop recommending it for end users.

PyPI:

python3.11 -m pip install logics-manager

Isolated user-level install via pipx (still published, no longer recommended; reach for npm if you hit PEP 668 or externally-managed Python errors):

pipx install logics-manager

Initialize or check a repository:

logics-manager bootstrap --check

Create the first workflow document:

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

Create a longer-term plan when the work spans several versions:

logics-manager flow roadmap propose --title "Improve onboarding" --milestone "0.1: MVP" --milestone "0.2: Guided setup"

Validate the workflow corpus:

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

Obsidian-friendly Markdown usage

Logics docs are plain Markdown, so you can open either the repository root or the logics/ directory as an Obsidian vault for reading, search, backlinks, and graph navigation. The local .obsidian/ workspace directory is ignored by Git, so vault layout, plugin choices, and workspace state stay local to each user.

Recommended setup:

• Open the full repository when you want README, source files, and Logics docs in one vault.
• Open logics/ when you want a focused workflow-document vault.
• Use Obsidian for navigation, review, notes, and light Markdown edits.
• Use logics-manager flow ... for lifecycle changes such as create, promote, closeout, finish, and status transitions.

Safe editing rules:

• Do not hand-edit Logics indicators such as Status, Progress, Understanding, Confidence, lineage links, Mermaid signatures, or generated done/closeout evidence.
• Keep canonical Logics references as repo-relative paths or refs. obsidian sync adds [[wikilink]] navigation hints as a derived, opt-in projection — Logics Manager parsing never requires them, and canonical files under logics/ are never rewritten by hand from this.
• Frontmatter, tags, and aliases are not written to canonical files; they only ever exist in the opt-in projection, generated deterministically and non-destructively, and validated against the canonical Logics doc type, ref, status, and title.

After editing workflow docs in Obsidian, validate from the repository root:

logics-manager lint --require-status
logics-manager audit --group-by-doc

Documentation

Full documentation lives in docs/, split by surface so each topic stays readable on its own. GitHub renders every page and the links below are clickable.

A short tour of each surface:

• The CLI is the canonical workflow engine. It creates requests, backlog items, tasks, product briefs, roadmaps, and ADRs; promotes and splits them; closes work with consistency checks; lints and audits traceability; exports indexes, context packs, and graph data; and serves both the local browser viewer and the bounded MCP tool surface. It also builds prompt packs for external image generators with design prompt, per asset kind, so a sheet and a single hero image never receive the same instructions. See docs/cli.md.
• The VS Code extension hosts the same local viewer inside VS Code and keeps editor-specific commands limited to viewer lifecycle and focus shortcuts. See docs/vscode.md.
• The MCP server gives assistants a bounded tool API over the same CLI without arbitrary filesystem or shell access. See docs/mcp.md.

Security

See SECURITY.md for supported versions and vulnerability reporting guidance. Do not publish suspected vulnerabilities in public issues until they are triaged; use GitHub's private vulnerability reporting or a private security advisory draft for this repository.