agentpack-cli 0.1.6 → 0.1.8

package/docs/agentpack-architecture.json

@@ -0,0 +1,838 @@
+{
+  "schemaVersion": 1,
+  "title": "agentpack — Architecture & Flows",
+  "description": "Local task-state ledger for AI coding agents. Pick a flow on the right to highlight the path through CLI, MCP tools, durable state, and generated handoff context.",
+  "repository": "agentpack-cli",
+  "package": "agentpack-cli",
+  "binary": "agentpack",
+  "engines": {
+    "node": ">=20"
+  },
+  "columns": [
+    {
+      "id": "actors",
+      "label": "Actors"
+    },
+    {
+      "id": "entry",
+      "label": "CLI / MCP entry"
+    },
+    {
+      "id": "dispatch",
+      "label": "Dispatch & tools"
+    },
+    {
+      "id": "operations",
+      "label": "Operations"
+    },
+    {
+      "id": "core",
+      "label": "Core builders"
+    },
+    {
+      "id": "storage",
+      "label": ".agentpack/ state"
+    },
+    {
+      "id": "outputs",
+      "label": "Outputs"
+    },
+    {
+      "id": "quality",
+      "label": "Tests & release"
+    }
+  ],
+  "legend": [
+    {
+      "type": "actor",
+      "label": "Actor"
+    },
+    {
+      "type": "entry",
+      "label": "CLI / MCP entry"
+    },
+    {
+      "type": "tool",
+      "label": "Dispatch / tool"
+    },
+    {
+      "type": "operation",
+      "label": "Operation"
+    },
+    {
+      "type": "core",
+      "label": "Core builder"
+    },
+    {
+      "type": "state",
+      "label": ".agentpack state"
+    },
+    {
+      "type": "output",
+      "label": "Output artifact"
+    },
+    {
+      "type": "quality",
+      "label": "Tests / CI"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "human",
+      "column": "actors",
+      "type": "actor",
+      "title": "Developer",
+      "summary": "Runs setup commands, reviews handoffs, steers coding-agent work.",
+      "files": [
+        "README.md",
+        "docs/CLI.md"
+      ]
+    },
+    {
+      "id": "agent",
+      "column": "actors",
+      "type": "actor",
+      "title": "Coding agent",
+      "summary": "Codex / Claude Code / Cursor / any MCP client. Reads instructions, calls MCP tools.",
+      "files": [
+        "AGENTS.md",
+        "CLAUDE.md",
+        ".agentpack/instructions/"
+      ]
+    },
+    {
+      "id": "ci",
+      "column": "actors",
+      "type": "actor",
+      "title": "CI / release",
+      "summary": "GitHub Actions builds, tests, smokes MCP, packs, publishes provenance releases.",
+      "files": [
+        ".github/workflows/ci.yml",
+        ".github/workflows/publish.yml"
+      ]
+    },
+    {
+      "id": "agentpack-bin",
+      "column": "entry",
+      "type": "entry",
+      "title": "agentpack",
+      "subtitle": "package bin",
+      "summary": "package.json#bin → dist/src/agentpack.js after TypeScript build.",
+      "files": [
+        "package.json",
+        "src/agentpack.ts"
+      ]
+    },
+    {
+      "id": "cli",
+      "column": "entry",
+      "type": "entry",
+      "title": "src/cli/index.ts",
+      "subtitle": "495 lines",
+      "summary": "Parses commands and flags, resolves --root / AGENTPACK_ROOT / cwd, dispatches CLI operations, can start MCP mode.",
+      "files": [
+        "src/cli/index.ts"
+      ]
+    },
+    {
+      "id": "mcp-start",
+      "column": "entry",
+      "type": "entry",
+      "title": "agentpack mcp",
+      "subtitle": "stdio launcher",
+      "summary": "Launches JSON-RPC over stdio. Root resolution: --root → AGENTPACK_ROOT → cwd.",
+      "files": [
+        "src/cli/index.ts",
+        "src/mcp/server.ts"
+      ]
+    },
+    {
+      "id": "mcp-server",
+      "column": "dispatch",
+      "type": "tool",
+      "title": "src/mcp/server.ts",
+      "subtitle": "397 lines",
+      "summary": "MCP tools: load_context, source_status, record_source, record_decision, record_dead_end, attach_evidence, checkpoint, diff, replay, resume.",
+      "files": [
+        "src/mcp/server.ts",
+        "docs/MCP.md"
+      ]
+    },
+    {
+      "id": "commands",
+      "column": "dispatch",
+      "type": "tool",
+      "title": "CLI commands",
+      "subtitle": "human surface",
+      "summary": "init · set · record · note · source · evidence · run · checkpoint · resume · export · diff · replay · doctor.",
+      "files": [
+        "src/cli/index.ts",
+        "docs/CLI.md"
+      ]
+    },
+    {
+      "id": "install",
+      "column": "dispatch",
+      "type": "tool",
+      "title": "installIntegration()",
+      "subtitle": "client installer",
+      "summary": "Generates Codex / Claude / Claude Desktop / Cursor instructions + MCP config. Dry-run unless --write.",
+      "files": [
+        "src/integrations/install.ts",
+        "docs/INTEGRATIONS.md"
+      ]
+    },
+    {
+      "id": "operations",
+      "column": "operations",
+      "type": "operation",
+      "title": "src/operations.ts",
+      "subtitle": "268 lines",
+      "summary": "Source records, evidence files, source status, replay output, git-status labels, redaction at the operation boundary.",
+      "files": [
+        "src/operations.ts"
+      ]
+    },
+    {
+      "id": "doctor",
+      "column": "operations",
+      "type": "operation",
+      "title": "core/doctor.ts",
+      "summary": "Pack health, ignore gaps, project MCP names, stale roots, Desktop config, launcher risks.",
+      "files": [
+        "src/core/doctor.ts"
+      ]
+    },
+    {
+      "id": "git",
+      "column": "operations",
+      "type": "operation",
+      "title": "core/git.ts",
+      "summary": "Branch, head commit, working-tree status, bounded diff context for resumes.",
+      "files": [
+        "src/core/git.ts"
+      ]
+    },
+    {
+      "id": "hash",
+      "column": "operations",
+      "type": "operation",
+      "title": "core/hash.ts",
+      "summary": "sha256File + getFileRecord. Powers source-cache identity and stale detection.",
+      "files": [
+        "src/core/hash.ts"
+      ]
+    },
+    {
+      "id": "store",
+      "column": "core",
+      "type": "core",
+      "title": "core/store.ts",
+      "subtitle": "286 lines",
+      "summary": "Finds pack roots, initPack(), appends ignore patterns, reads/writes state, appends events, serializes writes with .lock.",
+      "files": [
+        "src/core/store.ts"
+      ]
+    },
+    {
+      "id": "checkpoints",
+      "column": "core",
+      "type": "core",
+      "title": "core/checkpoints.ts",
+      "summary": "Creates checkpoint directories, manifests, resume snapshots, updates state pointer, diffs checkpoint pairs.",
+      "files": [
+        "src/core/checkpoints.ts"
+      ]
+    },
+    {
+      "id": "resume",
+      "column": "core",
+      "type": "core",
+      "title": "core/resume.ts",
+      "summary": "Builds budgeted markdown context: state + git + source cache + decisions + dead ends + evidence + recent timeline.",
+      "files": [
+        "src/core/resume.ts"
+      ]
+    },
+    {
+      "id": "budget",
+      "column": "core",
+      "type": "core",
+      "title": "core/budget.ts",
+      "summary": "Token estimator + section packer. Required sections kept, optionals truncated, omissions reported.",
+      "files": [
+        "src/core/budget.ts",
+        "src/core/presets.ts"
+      ]
+    },
+    {
+      "id": "redaction",
+      "column": "core",
+      "type": "core",
+      "title": "core/redaction.ts",
+      "summary": "Strips root paths and configured secret patterns before state leaves the local ledger.",
+      "files": [
+        "src/core/redaction.ts"
+      ]
+    },
+    {
+      "id": "state",
+      "column": "storage",
+      "type": "state",
+      "title": "state.json",
+      "summary": "Goal · current status · next actions · current checkpoint pointer.",
+      "files": [
+        ".agentpack/state.json"
+      ]
+    },
+    {
+      "id": "events",
+      "column": "storage",
+      "type": "state",
+      "title": "events.jsonl",
+      "summary": "Append-only timeline: decisions, notes, evidence, commands, sources, checkpoints.",
+      "files": [
+        ".agentpack/events.jsonl"
+      ]
+    },
+    {
+      "id": "sources",
+      "column": "storage",
+      "type": "state",
+      "title": "sources.json",
+      "summary": "Source-cache summaries keyed by path + sha256 so future agents avoid stale assumptions.",
+      "files": [
+        ".agentpack/sources.json"
+      ]
+    },
+    {
+      "id": "evidence",
+      "column": "storage",
+      "type": "state",
+      "title": "evidence/",
+      "summary": "Local evidence payloads attached from command output, files, notes, links.",
+      "files": [
+        ".agentpack/evidence/"
+      ]
+    },
+    {
+      "id": "checkpoint-store",
+      "column": "storage",
+      "type": "state",
+      "title": "checkpoints/",
+      "summary": "Durable checkpoint manifests and resume snapshots for recovery & comparison.",
+      "files": [
+        ".agentpack/checkpoints/"
+      ]
+    },
+    {
+      "id": "instructions",
+      "column": "storage",
+      "type": "state",
+      "title": "instructions/",
+      "summary": "Generated client instructions for the Agentpack workflow.",
+      "files": [
+        ".agentpack/instructions/"
+      ]
+    },
+    {
+      "id": "resume-output",
+      "column": "outputs",
+      "type": "output",
+      "title": "resume / load_context",
+      "summary": "Markdown task context: pack root, state, git, source-cache guidance, decisions, evidence, next actions.",
+      "files": [
+        "docs/MCP.md",
+        "docs/CLI.md"
+      ]
+    },
+    {
+      "id": "handoff-export",
+      "column": "outputs",
+      "type": "output",
+      "title": "exports/",
+      "summary": "Markdown handoff fallback for clients that cannot read local MCP tools.",
+      "files": [
+        ".agentpack/exports/"
+      ]
+    },
+    {
+      "id": "client-config",
+      "column": "outputs",
+      "type": "output",
+      "title": "Client MCP config",
+      "summary": "Project-local Codex / Claude / Cursor. Claude Desktop gets a merge snippet for global config.",
+      "files": [
+        ".codex/config.toml",
+        ".mcp.json",
+        ".cursor/mcp.json"
+      ]
+    },
+    {
+      "id": "doctor-output",
+      "column": "outputs",
+      "type": "output",
+      "title": "doctor report",
+      "summary": "Ok / warn / fail checks for pack setup, ignore rules, MCP launcher safety.",
+      "files": [
+        "src/core/doctor.ts"
+      ]
+    },
+    {
+      "id": "tests",
+      "column": "quality",
+      "type": "quality",
+      "title": "tests/agentpack.test.ts",
+      "summary": "node --test suite covering CLI, pack state, source status, resumes, MCP tools, doctor, installs, redaction, budget.",
+      "files": [
+        "tests/agentpack.test.ts"
+      ]
+    },
+    {
+      "id": "smoke",
+      "column": "quality",
+      "type": "quality",
+      "title": "scripts/mcp-smoke.mjs",
+      "summary": "Builds CLI, starts MCP, sends initialize / tools/list / resume JSON-RPC, validates output.",
+      "files": [
+        "scripts/mcp-smoke.mjs"
+      ]
+    },
+    {
+      "id": "release",
+      "column": "quality",
+      "type": "quality",
+      "title": "release workflow",
+      "summary": "ci.yml builds + tests + smokes + packs. publish.yml releases npm with provenance via OIDC Trusted Publisher.",
+      "files": [
+        ".github/workflows/ci.yml",
+        ".github/workflows/publish.yml",
+        "docs/RELEASING.md"
+      ]
+    }
+  ],
+  "edges": [
+    {
+      "id": "e-human-bin",
+      "from": "human",
+      "to": "agentpack-bin"
+    },
+    {
+      "id": "e-agent-mcp",
+      "from": "agent",
+      "to": "mcp-start"
+    },
+    {
+      "id": "e-ci-bin",
+      "from": "ci",
+      "to": "agentpack-bin"
+    },
+    {
+      "id": "e-bin-cli",
+      "from": "agentpack-bin",
+      "to": "cli"
+    },
+    {
+      "id": "e-cli-mcp",
+      "from": "cli",
+      "to": "mcp-start"
+    },
+    {
+      "id": "e-mcp-server",
+      "from": "mcp-start",
+      "to": "mcp-server"
+    },
+    {
+      "id": "e-mcp-commands",
+      "from": "mcp-server",
+      "to": "commands"
+    },
+    {
+      "id": "e-cli-commands",
+      "from": "cli",
+      "to": "commands"
+    },
+    {
+      "id": "e-cli-install",
+      "from": "cli",
+      "to": "install"
+    },
+    {
+      "id": "e-commands-operations",
+      "from": "commands",
+      "to": "operations"
+    },
+    {
+      "id": "e-commands-doctor",
+      "from": "commands",
+      "to": "doctor"
+    },
+    {
+      "id": "e-mcp-operations",
+      "from": "mcp-server",
+      "to": "operations"
+    },
+    {
+      "id": "e-operations-hash",
+      "from": "operations",
+      "to": "hash"
+    },
+    {
+      "id": "e-operations-git",
+      "from": "operations",
+      "to": "git"
+    },
+    {
+      "id": "e-commands-store",
+      "from": "commands",
+      "to": "store"
+    },
+    {
+      "id": "e-install-store",
+      "from": "install",
+      "to": "store"
+    },
+    {
+      "id": "e-commands-checkpoints",
+      "from": "commands",
+      "to": "checkpoints"
+    },
+    {
+      "id": "e-mcp-checkpoints",
+      "from": "mcp-server",
+      "to": "checkpoints"
+    },
+    {
+      "id": "e-commands-resume",
+      "from": "commands",
+      "to": "resume"
+    },
+    {
+      "id": "e-mcp-resume",
+      "from": "mcp-server",
+      "to": "resume"
+    },
+    {
+      "id": "e-store-state",
+      "from": "store",
+      "to": "state"
+    },
+    {
+      "id": "e-store-events",
+      "from": "store",
+      "to": "events"
+    },
+    {
+      "id": "e-store-sources",
+      "from": "store",
+      "to": "sources"
+    },
+    {
+      "id": "e-operations-sources",
+      "from": "operations",
+      "to": "sources"
+    },
+    {
+      "id": "e-operations-evidence",
+      "from": "operations",
+      "to": "evidence"
+    },
+    {
+      "id": "e-operations-events",
+      "from": "operations",
+      "to": "events"
+    },
+    {
+      "id": "e-checkpoints-store",
+      "from": "checkpoints",
+      "to": "checkpoint-store"
+    },
+    {
+      "id": "e-checkpoints-state",
+      "from": "checkpoints",
+      "to": "state"
+    },
+    {
+      "id": "e-checkpoints-events",
+      "from": "checkpoints",
+      "to": "events"
+    },
+    {
+      "id": "e-install-instructions",
+      "from": "install",
+      "to": "instructions"
+    },
+    {
+      "id": "e-resume-state",
+      "from": "resume",
+      "to": "state"
+    },
+    {
+      "id": "e-resume-sources",
+      "from": "resume",
+      "to": "sources"
+    },
+    {
+      "id": "e-resume-events",
+      "from": "resume",
+      "to": "events"
+    },
+    {
+      "id": "e-resume-git",
+      "from": "resume",
+      "to": "git"
+    },
+    {
+      "id": "e-resume-budget",
+      "from": "resume",
+      "to": "budget"
+    },
+    {
+      "id": "e-resume-redaction",
+      "from": "resume",
+      "to": "redaction"
+    },
+    {
+      "id": "e-resume-out",
+      "from": "resume",
+      "to": "resume-output"
+    },
+    {
+      "id": "e-resume-export",
+      "from": "resume",
+      "to": "handoff-export"
+    },
+    {
+      "id": "e-install-config",
+      "from": "install",
+      "to": "client-config"
+    },
+    {
+      "id": "e-doctor-output",
+      "from": "doctor",
+      "to": "doctor-output"
+    },
+    {
+      "id": "e-tests-cli",
+      "from": "tests",
+      "to": "cli"
+    },
+    {
+      "id": "e-tests-mcp",
+      "from": "tests",
+      "to": "mcp-server"
+    },
+    {
+      "id": "e-smoke-mcp",
+      "from": "smoke",
+      "to": "mcp-server"
+    },
+    {
+      "id": "e-release-tests",
+      "from": "release",
+      "to": "tests"
+    },
+    {
+      "id": "e-release-smoke",
+      "from": "release",
+      "to": "smoke"
+    }
+  ],
+  "flows": [
+    {
+      "id": "init",
+      "label": "init workspace",
+      "summary": "Create local task-state ledger and keep it out of git.",
+      "nodes": [
+        "human",
+        "agentpack-bin",
+        "cli",
+        "commands",
+        "store",
+        "state",
+        "events",
+        "sources",
+        "instructions"
+      ],
+      "edges": [
+        "e-human-bin",
+        "e-bin-cli",
+        "e-cli-commands",
+        "e-commands-store",
+        "e-store-state",
+        "e-store-events",
+        "e-store-sources"
+      ],
+      "steps": [
+        "Developer runs `agentpack init` in a repo.",
+        "CLI resolves the workspace and calls `initPack()` in core/store.ts.",
+        "store.ts creates `.agentpack/` and default state.json, events.jsonl, sources.json.",
+        "`ensurePackIgnored()` appends local-only ignore patterns to .gitignore without replacing existing rules."
+      ]
+    },
+    {
+      "id": "install",
+      "label": "install client",
+      "summary": "Generate client instructions + MCP launcher config for Codex / Claude / Cursor.",
+      "nodes": [
+        "human",
+        "agentpack-bin",
+        "cli",
+        "install",
+        "store",
+        "instructions",
+        "client-config"
+      ],
+      "edges": [
+        "e-human-bin",
+        "e-bin-cli",
+        "e-cli-install",
+        "e-install-store",
+        "e-install-instructions",
+        "e-install-config"
+      ],
+      "steps": [
+        "Developer runs `agentpack install codex|claude|claude-desktop|cursor --write`.",
+        "`installIntegration()` builds the per-client file plan (dry-run unless --write).",
+        "Generated workflow instructions are written under `.agentpack/instructions/`.",
+        "Project-local clients get config files (.codex, .mcp.json, .cursor/mcp.json); Claude Desktop gets a merge snippet."
+      ]
+    },
+    {
+      "id": "source-cache",
+      "label": "source cache",
+      "summary": "Record source conclusions by hash and detect staleness on the next session.",
+      "nodes": [
+        "agent",
+        "mcp-start",
+        "mcp-server",
+        "operations",
+        "hash",
+        "git",
+        "sources",
+        "events",
+        "resume-output"
+      ],
+      "edges": [
+        "e-agent-mcp",
+        "e-mcp-server",
+        "e-mcp-operations",
+        "e-operations-hash",
+        "e-operations-git",
+        "e-operations-sources",
+        "e-operations-events"
+      ],
+      "steps": [
+        "Agent inspects an important source file.",
+        "`record_source` (or `agentpack source add`) stores summary + snippet + path + sha256 via core/hash.ts.",
+        "`source_status` later compares recorded hashes against the working tree and git status.",
+        "Future resumes show unchanged sources as compact stubs and flag changed/missing files in full."
+      ]
+    },
+    {
+      "id": "checkpoint",
+      "label": "checkpoint",
+      "summary": "Persist meaningful progress into durable state and a recoverable snapshot.",
+      "nodes": [
+        "agent",
+        "mcp-start",
+        "mcp-server",
+        "checkpoints",
+        "store",
+        "state",
+        "events",
+        "checkpoint-store"
+      ],
+      "edges": [
+        "e-agent-mcp",
+        "e-mcp-server",
+        "e-mcp-checkpoints",
+        "e-checkpoints-store",
+        "e-checkpoints-state",
+        "e-checkpoints-events"
+      ],
+      "steps": [
+        "Agent reaches a coherent boundary and calls `checkpoint`.",
+        "`checkpoints.ts` writes a manifest + resume snapshot under the Agentpack write lock.",
+        "state.json is updated with status, next actions, and the current checkpoint id.",
+        "events.jsonl gets a `checkpoint` event for the timeline."
+      ]
+    },
+    {
+      "id": "resume",
+      "label": "resume context",
+      "summary": "Pack current task state into budgeted markdown for the next agent.",
+      "nodes": [
+        "agent",
+        "mcp-start",
+        "mcp-server",
+        "resume",
+        "git",
+        "budget",
+        "redaction",
+        "state",
+        "sources",
+        "events",
+        "resume-output",
+        "handoff-export"
+      ],
+      "edges": [
+        "e-agent-mcp",
+        "e-mcp-server",
+        "e-mcp-resume",
+        "e-resume-state",
+        "e-resume-sources",
+        "e-resume-events",
+        "e-resume-git",
+        "e-resume-budget",
+        "e-resume-redaction",
+        "e-resume-out",
+        "e-resume-export"
+      ],
+      "steps": [
+        "Agent calls `load_context` or `resume` with a preset, budget, and optional query.",
+        "core/resume.ts combines state + git + source cache + decisions + evidence + timeline.",
+        "core/budget.ts keeps required sections and reports truncated/omitted ones.",
+        "core/redaction.ts strips root paths + configured secrets before output leaves the ledger.",
+        "Result is returned via MCP, or written to `.agentpack/exports/` as a markdown fallback."
+      ]
+    },
+    {
+      "id": "doctor-ci",
+      "label": "doctor + CI",
+      "summary": "Catch broken setup, stale MCP roots, and release regressions.",
+      "nodes": [
+        "human",
+        "ci",
+        "agentpack-bin",
+        "cli",
+        "commands",
+        "doctor",
+        "doctor-output",
+        "tests",
+        "smoke",
+        "release",
+        "mcp-server"
+      ],
+      "edges": [
+        "e-human-bin",
+        "e-ci-bin",
+        "e-bin-cli",
+        "e-cli-commands",
+        "e-commands-doctor",
+        "e-doctor-output",
+        "e-release-tests",
+        "e-release-smoke",
+        "e-tests-cli",
+        "e-tests-mcp",
+        "e-smoke-mcp"
+      ],
+      "steps": [
+        "`agentpack doctor` reports pack health, ignore rules, launcher names, and stale roots.",
+        "Node tests cover CLI behavior, MCP tools, installs, source cache, redaction, budget packing.",
+        "`scripts/mcp-smoke.mjs` runs a JSON-RPC flow against the built server.",
+        "Release workflow publishes npm packages with provenance after build/test/smoke/pack checks."
+      ]
+    }
+  ]
+}