archgen-mcp 0.0.0-stage → 0.0.7

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# archgen-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server for [archgen](https://github.com/akashmaurya99/archgen) — it
+owns **every** deterministic capability in the archgen workflow.
+
+The archgen skill is orchestration guidance for an agent; this server is the
+runtime it drives. One implementation, three ways in:
+
+| Consumer | How it reaches the server |
+|---|---|
+| Coding agents | MCP over stdio — 10 domain tools |
+| `archgen-skill init` / `install` | `archgen-mcp bootstrap` |
+| The VS Code extension | `archgen-mcp exec <tool> '<json>'` |
+
+## Install
+
+The archgen installer wires this server into every detected harness for you:
+
+```bash
+npx archgen-skill init
+```
+
+That installs the skill, writes the `archgen` MCP entry into each detected
+harness's own config (with the correct per-platform file and top-level key),
+and ensures CodeGraph.
+
+To run it by hand:
+
+```bash
+npx archgen-mcp            # serve MCP over stdio
+npx archgen-mcp --list     # list the tools
+npx archgen-mcp doctor     # health report
+```
+
+Requires **Node.js >= 20** (the official MCP SDK v2 floor).
+
+## The tools
+
+| Tool | Use it for |
+|---|---|
+| `archgen_plan` | validate · verifier gate · dependency graph · blast radius · coverage · **scaffold** (the artifact set for a scope class) · **brief** (a dispatch brief) |
+| `archgen_tasks` | next wave · set status · list · resume snapshot · **contract** (the assembled worker prompt) |
+| `archgen_docs` | navigate markdown artifacts: section index, one section, token map, reference integrity |
+| `archgen_registry` | refresh / read the AGENTS.md features registry |
+| `archgen_codegraph` | install CodeGraph if it is missing · wire its MCP · index the project |
+| `archgen_setup` | doctor · bootstrap servers · install/remove the MCP · list harnesses · **harness_info** (a platform's capabilities) |
+| `archgen_ui` | drive the VS Code extension in real time |
+| `archgen_skills` | match / install / load external capability skills |
+| `archgen_refs` | load archgen's own protocol documents — section by section |
+| `archgen_help` | the full briefing for one domain |
+
+Every tool returns the same envelope:
+
+```json
+{ "ok": true, "data": { }, "error": null, "meta": { "serverVersion": "…", "skillVersion": "…", "projectRoot": "…" } }
+```
+
+`ok` says whether the **call** succeeded. A failed call carries a typed
+`error.code`:
+
+`INVALID_INPUT` · `NOT_FOUND` · `CYCLE` · `OWNERSHIP_CONFLICT` · `CONFLICT` ·
+`PERMISSION_DENIED` · `UNAVAILABLE` · `TIMEOUT` · `INTERNAL`
+
+Call `archgen_help { topic: "<domain>" }` for the full briefing on any tool —
+including when to call it, every action, and its gotchas.
+
+### The judgment / output split
+
+The archgen **skill** carries the judgment (policy, rules, when-to-use). This
+server carries the **deterministic output** — the artifact sets, the skeletons,
+the dispatch briefs, the assembled worker prompt, the harness capability tables.
+
+The five orchestrator-facing protocol documents also live **here**, in
+`assets/references/`, and are served section-by-section by `archgen_refs`:
+
+```
+archgen_refs { action: 'index', topic: 'orchestration' }
+archgen_refs { action: 'read', topic: 'orchestration', section: 'dispatch--wave-execution' }
+```
+
+They live here so they are always the same version as the tools they describe.
+One exception stays in the skill as a plain file: `code-standards.md`, because
+WORKER sub-agents read it with their native file tools and may have no MCP
+server at all.
+
+### The capability contract
+
+The skill declares the server version it needs:
+
+```yaml
+metadata:
+  requires:
+    archgen_mcp: ">=x.y.z"
+```
+
+`archgen_setup { action: 'doctor' }` reports a mismatch, `bootstrap` warns
+before wiring, and CI refuses to ship a skill whose declared minimum exceeds
+this package's version.
+
+## The CLI facade
+
+```bash
+archgen-mcp exec archgen_plan '{"action":"validate","tasksYaml":"/abs/tasks.yaml"}'
+archgen-mcp exec archgen_tasks '{"action":"next","tasksYaml":"/abs/tasks.yaml"}'
+archgen-mcp bootstrap --project . --location both --yes
+archgen-mcp doctor --project . --json
+archgen-mcp uninstall-mcp --project . --yes
+```
+
+`exec` runs the **same handlers** the MCP tools expose — there is no second
+implementation of any capability, only a second way to reach it.
+
+## Safety
+
+- The server owns a **boundary**: the directory it was started in. A tool's
+  `projectRoot` argument selects a directory *inside* that boundary — it
+  cannot redefine it, so a model cannot move the edge by naming a different
+  root.
+- Every path argument is resolved against the project root and refused if it
+  escapes; symlinked targets are never written through, and a symlinked
+  *parent* is caught by comparing real paths.
+- The artifact space is anchored to the project: a `.archgen` directory
+  elsewhere on the machine is not this project's artifacts.
+- MCP-config writes are approval-gated (`approve: true` / `--yes`); without
+  approval the tool reports its **plan** and writes nothing.
+- A config file that cannot be parsed is reported, never rewritten.
+- Writes are atomic (temp file + rename): readers see old-or-new, never a
+  partial file. A read-modify-write — a status update, a config merge — runs
+  under an exclusive lock, so two workers cannot lose each other's change.
+- UI commands are allowlisted, workspace-scoped, expiring, and idempotent;
+  the command queue is pruned, so it cannot grow without bound.
+
+## License
+
+MIT

package/assets/briefs/investigate.md

@@ -0,0 +1,22 @@
+TASK: Investigate a recurring issue in this repository.
+TRIGGER: the user reports repetitive/recurring issues AFTER implementation waves
+completed. This is NOT a patch-fix task.
+
+DELIVERABLE: all four, or the investigation is incomplete:
+1. ROOT CAUSE — one sentence naming the actual defect (not the symptom).
+2. EVIDENCE — files / lines / repro steps that prove it.
+3. BLAST RADIUS — which tasks and artifacts are affected.
+   Use `archgen_plan { action: 'impact', tasksYaml: <tasks.yaml>, target: <id-or-path> }`.
+4. REMEDIATION — routed through the NORMAL gates: new fix tasks get fresh ids
+   inheriting the affected task's ownership globs.
+
+SIZING
+- SMALL scope: the main agent investigates directly.
+- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+
+DISCIPLINE
+- Read narrowly around the evidence — no whole-repo sweeps.
+- A patch-fix WITHOUT a root-cause statement is FORBIDDEN under this protocol.
+- Write your notes under .archgen/<slug>/.agent/notes/<topic>.md and your
+  findings under .archgen/<slug>/.agent/reports/investigate-<round>.md.
+  NEVER create ad-hoc folders at the repo root.

package/assets/briefs/review.md

@@ -0,0 +1,35 @@
+TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
+DELIVERABLE: a numbered findings list; each finding = what + where + why.
+You NEVER edit files. You report only.
+
+EXAMINE
+- edge cases per module
+- task ordering / parallelization sanity (waves vs real dependencies)
+- cross-module contract mismatches (interfaces, paths, naming)
+- enhancement recommendations
+- documentation completeness
+
+CONTEXT TO ATTACH
+- `archgen_plan { action: 'graph', tasksYaml: <tasks.yaml>, format: 'mermaid', status: true }`
+  — the wave-progress render; reviewer reads it to sanity-check ordering.
+- `archgen_docs { action: 'validate', slugDir: <slug dir> }` — the reference
+  integrity result; broken references are findings, not noise.
+
+SIZING
+- SMALL: the main agent's self-review is acceptable when the harness has no
+  reviewer mechanism.
+- MEDIUM: 1 reviewer.
+- LARGE: 1 holistic reviewer on the strongest reasoning tier. A 2nd reviewer
+  ONLY if the plan is genuinely too large for one reviewer's context — split by
+  ARTIFACT/VOLUME (e.g. plans vs docs), never by concern.
+
+ONE holistic reviewer analyzes ALL issues together: cross-issue reasoning catches
+contradictions a narrow per-concern slice misses, and one reviewer costs far
+fewer tokens than several. NEVER dispatch one sub-agent per individual issue.
+
+BOUNDS
+- A "more review" approval authorizes EXACTLY ONE additional pass — never a
+  fresh loop, never more reviewers. The stage ends ONLY at zero findings or an
+  explicit user waiver on record.
+- The ORCHESTRATOR fixes the artifacts, re-runs validate + the verifier gate
+  after every change, and re-dispatches. Reviewers never fix.

package/assets/briefs/survey.md

@@ -0,0 +1,22 @@
+TASK: Survey this repository to prepare a feature plan for: <feature request>
+DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
+sections:
+  ## Structure      — top-2-levels folder tree w/ one-line purpose each
+  ## Modules        — table: module | responsibility | key entry points
+  ## Conventions    — naming, error-handling, test layout actually observed
+  ## Affected       — files/modules the feature will touch, with evidence paths
+SCOPE: read-only.
+NAVIGATE: use the CodeGraph MCP tools when available — the index is built once
+at bootstrap and kept live by the server's watcher, so never re-index.
+Otherwise Glob+Grep systematically.
+VERIFY: every claim cites a real path; no guessed APIs. A claim without an
+evidence path is a defect, not a detail.
+
+ACCEPTANCE
+The map is accepted only if every section is present and NON-EMPTY. Anything the
+survey could not determine is written down as an explicit unknown, not omitted —
+an omitted section is indistinguishable from an un-surveyed one.
+
+THEN: the orchestrator asks ONLY what the survey could not answer. Never
+interrogate the user with what a file already answers — quote the file and ask
+for confirmation instead.

package/assets/briefs/verifier.md

@@ -0,0 +1,44 @@
+TASK: Verify this archgen plan before any execution.
+DELIVERABLE: exactly one line — `APPROVE` or `ISSUES:` followed by a numbered list.
+SCOPE: read-only. You NEVER edit files. You report findings only.
+
+RUN THESE FIRST (the deterministic floor — every one must pass):
+1. `archgen_plan { action: 'verify', tasksYaml: <tasks.yaml>, planDir: <plans dir> }`
+   — must return verdict APPROVE. It checks cycles, dangling refs, same-wave
+   ownership overlap, missing acceptance criteria and plan<->task coverage.
+2. `archgen_docs { action: 'validate', slugDir: <slug dir> }` (when markdown
+   artifacts exist) — must return valid:true. Broken references BLOCK approval.
+
+THEN judge what the tools cannot:
+- Are wave boundaries sensible (no artificial serialization)?
+- Do acceptance criteria objectively verify (a command or an observable)?
+- Is edge-case coverage adequate for the scope class of each task?
+- Is code-standards compliance plausible for the planned structure?
+- CONTRACT-COMPLETENESS sweep — round 1 must confirm OR flag-as-missing every
+  APPLICABLE dimension. Apply a dimension only where the system actually has
+  that concern, but NEVER skip a dimension the system touches:
+  - Functional coverage: every stated requirement has a task + objectively
+    verifiable acceptance.
+  - Security & data protection (if it authenticates, authorizes, encrypts or
+    handles sensitive data): authn/authz flows, session & credential lifecycle,
+    replay/CSRF protection, encryption & privacy boundaries, input validation.
+  - Data integrity: schemas, relationships, validation, migration / back-compat.
+  - State, lifecycle & recovery (if any operation is stateful, long-running or
+    multi-step): checkpointing/resume, idempotency, cleanup, expiry,
+    compensation/rollback semantics.
+  - Resource limits & abuse (if it exposes shared or anonymous resources):
+    quotas, rate limits, retention/deletion, anonymous-abuse controls.
+  - Operational entrypoints: every stack-required build/deploy/test/bootstrap
+    entrypoint is OWNED by some task.
+  - Metric traceability: every PRD success metric maps to a task acceptance
+    criterion with a reproducible command / sample size / data source.
+  - Consistency: cross-contract claims must not contradict each other.
+  These failure classes are the TOP cause of multi-round loops — round 1 MUST
+  sweep the applicable dimensions exhaustively.
+
+RULES
+- Run on the STRONGEST reasoning agent the harness offers. NEVER an explore /
+  research / quick / cheap tier: a weak verifier misses real defects AND raises
+  false positives, costing MORE rounds, not fewer.
+- Every finding names the file and the reason. No vague findings.
+- If everything passes, return exactly `APPROVE` and nothing else.

package/assets/depth-ladder.json

@@ -0,0 +1,90 @@
+{
+  "version": 1,
+  "_readme": [
+    "Canonical depth ladder: scope class -> the artifact set a plan MUST have.",
+    "",
+    "This is the machine-readable twin of references/artifact-templates.md § Plan",
+    "depth by scope class. The reference keeps the AUTHORING RULES; this file",
+    "owns the ARTIFACT SET, so the orchestrator never guesses which files a",
+    "SMALL/MEDIUM/LARGE plan needs. `archgen_plan{action:'scaffold'}` serves it.",
+    "",
+    "A drift test (packages/mcp/test/core/depth-ladder.test.mjs) pins this file",
+    "against the reference's stated minimums."
+  ],
+  "classes": {
+    "SMALL": {
+      "label": "SMALL — add or touch a few things",
+      "intentDefaults": ["BROWNFIELD-CHANGE"],
+      "roundCap": 3,
+      "artifacts": [
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>-note.md", "required": true, "purpose": "a lean plan note" }
+      ],
+      "planSections": ["Intent", "Tasks", "Risks"],
+      "minEdgeCasesPerTask": 0,
+      "requires": [],
+      "forbids": ["docs/prd.md", "architecture.yaml", "decisions/"],
+      "notes": [
+        "Every task entry STILL carries repo-root-relative paths verbatim in file_ownership, in each step, and in verification commands.",
+        "No Context section, no diagrams, no PRD."
+      ]
+    },
+    "MEDIUM": {
+      "label": "MEDIUM — a real feature with real risk",
+      "intentDefaults": ["GREENFIELD-MODULE", "BROWNFIELD-FEATURE"],
+      "roundCap": 3,
+      "artifacts": [
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>.md", "required": true, "purpose": "the full plan" }
+      ],
+      "planSections": ["Context", "Per-task sections", "Verification steps"],
+      "minEdgeCasesPerTask": 3,
+      "requires": ["plan context of 2-4 paragraphs", "per-task sections with approach + edge cases + out-of-scope", "ordered runnable verification steps"],
+      "forbids": ["docs/prd.md", "architecture.yaml"],
+      "notes": [
+        "One `<id> — <title>` heading per task, in dependency order.",
+        "Verification steps are repo-root-relative (no `../`, no `--plan .`), exact, and runnable."
+      ]
+    },
+    "LARGE": {
+      "label": "LARGE — a full professional stack (greenfield from scratch)",
+      "intentDefaults": ["GREENFIELD-SYSTEM"],
+      "roundCap": 6,
+      "artifacts": [
+        { "path": ".archgen/<slug>/answers.yaml", "required": true, "purpose": "the captured requirements" },
+        { "path": ".archgen/<slug>/docs/prd.md", "required": true, "purpose": "the product requirements — FR ids tasks cite" },
+        { "path": ".archgen/<slug>/architecture.yaml", "required": true, "purpose": "the contract source of truth" },
+        { "path": ".archgen/<slug>/tasks.yaml", "required": true, "purpose": "the task contract" },
+        { "path": ".archgen/<slug>/plans/<slug>.md", "required": true, "purpose": "the full plan" },
+        { "path": ".archgen/<slug>/decisions/NNNN-<title>.md", "required": false, "purpose": "formal ADRs (one per decision)" },
+        { "path": ".archgen/<slug>/docs/<module>.md", "required": false, "purpose": "per-module diagrams (≤15 nodes each)" }
+      ],
+      "planSections": ["Context", "Per-task sections", "Edge-case matrices", "Verification steps"],
+      "minEdgeCasesPerTask": 3,
+      "requires": [
+        "docs/prd.md written BEFORE tasks.yaml (~1 page per major module)",
+        "architecture.yaml with naming_conventions, data_contracts, api_contracts and environment_matrix",
+        "an edge-case matrix per task (every row maps to an acceptance bullet)",
+        "per-module diagrams (≤15 nodes each) plus one integration diagram",
+        "MEDIUM-grade plan sections"
+      ],
+      "forbids": [],
+      "notes": [
+        "Requirement ids (FR-<MODULE>-nn) are defined in docs/prd.md and cited from tasks.yaml acceptance lines.",
+        "architecture.yaml is the anti-hallucination source of truth: tasks cite its keys instead of restating shapes from memory."
+      ]
+    }
+  },
+  "edgeCaseClasses": [
+    "empty/null",
+    "boundary values",
+    "authz denied",
+    "concurrent/conflicting write",
+    "failure/retry path",
+    "i18n/formatting edge"
+  ],
+  "edgeCaseExtras": {
+    "infra": ["partial-failure recovery", "rollback story"],
+    "maxRowsPerMatrix": 10
+  }
+}