Cadre is one publishable TypeScript package that installs native user plugins for Codex and Claude Code plus a stable integration using global skills and a custom MCP server for Zed Agent. The target repository stores delivery state, not runtime code.
Repository Layout
harness/
├── skills/<workflow>/
│ ├── SKILL.md
│ └── agents/openai.yaml
├── agents/
│ ├── cadre-phase-worker.md
│ └── cadre-task-worker.md
├── src/
│ ├── domain/
│ └── mcp/server.ts
├── scripts/
├── templates/
│ ├── v1/ # immutable published legacy set
│ ├── v2/ # immutable compact legacy set
│ ├── v3–v5/ # immutable historical fixtures (not shipped)
│ └── v6/ # active receipt-based template set
├── test/
├── .codex-plugin/plugin.json
├── .claude-plugin/plugin.json
├── .mcp.codex.json
├── .mcp.json
└── marketplace/Root docs/ is the public Next.js documentation site. Root workspace files
coordinate the cadre-ai and cadre-docs packages.
Source Boundaries
| Path | Responsibility |
|---|---|
skills/*/SKILL.md | Human-facing workflow, approval, recovery, and tool-use contracts. |
skills/*/agents/openai.yaml | Explicit Codex picker metadata. |
agents/ | Claude phase/task worker isolation contracts. |
src/domain/templates.ts | Immutable template catalog and styleguide resolution. |
src/domain/init.ts | Digest-gated project initialization and receipt promotion. |
src/domain/staging.ts | Safe project-local candidate paths, bounded reads, and manifest inputs. |
src/domain/candidate-apply.ts | Validated candidate promotion and lifecycle reconciliation. |
src/domain/operation-receipts.ts | Immutable operation receipts, interrupted promotion recovery and unique Git commit verification. |
src/domain/state.ts | Project discovery, validation, status, and derived track index. |
src/domain/plan.ts | Plan parsing and DAG/manual-barrier validation. |
src/domain/execution.ts | Execution journals, node transitions, and finish gating. |
src/domain/worktrees.ts | Constrained worktree creation, integration, status, and cleanup. |
src/domain/governance.ts | Review completion and archive-batch governance. |
src/mcp/server.ts | MCP server instructions, resource registration, schemas, and tool adapters. |
scripts/ | Build, CLI, installation, uninstall, permissions, packaging, and source validation. |
templates/v1/ through templates/v5/ | Immutable historical source fixtures, excluded from the installed payload. |
templates/v6/ | Active cohesive-change, receipt, dependency-context, workflow, and styleguide templates. |
The domain directory currently includes filesystem and Git-aware behavior; it is not a pure dependency-free DDD layer. Preserve the real capability boundaries rather than imposing an architecture the source does not have.
Build Outputs
pnpm --filter cadre-ai build uses esbuild to create two ignored bundles:
dist/cadre-cli.mjs— executable installer/doctor/uninstaller;dist/cadre-mcp.mjs— self-contained stdio MCP server.
Both target Node.js 18 and bundle their runtime dependencies. The published package declares no production dependencies.
Never edit dist/ directly.
Plugin Sources And Installed Marketplace
The tracked .codex-plugin/, .claude-plugin/, MCP configs, skills, agents,
templates, and marketplace catalogs are package sources.
At installation time, packagePluginMarketplace copies those sources plus the
built MCP bundle into ~/.cadre/marketplaces/cadre/plugins/cadre. It creates
Codex and Claude marketplace roots and adds product-specific SemVer build
metadata as a cache-buster. It also derives collision-safe Zed adapters under
zed-skills/cadre-* from the canonical skills. The package version remains
unchanged.
The prior owned marketplace payload is renamed to a timestamped backup before the replacement is activated.
Client Differences
Codex discovers skills from the plugin manifest and uses .mcp.codex.json to
run node ./dist/cadre-mcp.mjs with plugin-root cwd. Claude discovers the same
skills through its plugin namespace, loads worker agent definitions, and uses
${CLAUDE_PLUGIN_ROOT}/dist/cadre-mcp.mjs from .mcp.json.
Zed discovers global cadre-* skill links under ~/.agents/skills/ and starts
the same packaged runtime from context_servers.cadre in its JSONC settings.
Its adapters request text-mode template bundles because Zed does not expose
embedded MCP resource bodies to the agent, and unsupported form elicitation
falls back to one concise chat question.
All three clients operate the same workflow and state contracts. Client-specific metadata does not create different lifecycle semantics.
Safety Architecture
- Every project root is canonicalized and broad roots are rejected.
- Templates are immutable and addressed by versioned logical IDs/resources.
- Deterministic mutations bind their exact proposal to a SHA-256 digest.
- Multi-step workflow mutations journal before artifact or Git changes.
- Worktree Git operations use derived paths/branches and refuse unsafe cleanup.
- The main agent is the sole scheduler, integrator, conflict resolver, Cadre state writer, and recorder of human approval.
- The runtime does not expose arbitrary shell execution or general file edits.