archgen-skill 0.1.0 → 0.1.2

package/lib/node_modules/archgen-mcp/README.md

@@ -0,0 +1,131 @@
+# archgen-mcp
+
+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, two ways in:
+
+| Consumer | How it reaches the server |
+|---|---|
+| Coding agents | MCP over stdio — 8 domain tools + `archgen_help` |
+| `archgen-skill init` / `install` | `archgen-mcp bootstrap` |
+
+## 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_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.
+
+## License
+
+MIT

package/lib/node_modules/archgen-mcp/assets/briefs/investigate.md

@@ -0,0 +1,21 @@
+TASK: Investigate a recurring post-execution defect in this repository.
+TRIGGER: User reports repetitive/recurring issues AFTER implementation waves completed. This is NOT a patch-fix task.
+SCOPE: Read-only analysis and reporting (unless the brief explicitly authorizes edits).
+
+DELIVERABLE — all four sections are MANDATORY:
+1. ROOT CAUSE: One sentence identifying the underlying defect (never merely the symptom).
+2. EVIDENCE: Exact file paths, line numbers, and reproduction steps proving the root cause.
+3. BLAST RADIUS: Affected tasks and artifacts computed via `archgen_plan { action: 'impact', tasksYaml: <tasks.yaml>, target: <id-or-path> }`.
+4. REMEDIATION: Proposed fix tasks (new task IDs inheriting affected `file_ownership` globs) routed through normal Verifier, Review, and User gates.
+
+SIZING
+- SMALL: Main agent investigates directly.
+- MEDIUM / LARGE: 1 investigator by default. Dispatch a 2nd investigator ONLY when the suspected defect spans disjoint subsystems—split strictly by SUBSYSTEM with zero file overlap.
+
+DISCIPLINE
+- Read narrowly around evidence paths; avoid whole-repo sweeps.
+- Patch-fixing without a verified root-cause statement is FORBIDDEN.
+- Write working notes to `<slug dir>/.agent/notes/<topic>.md` and final report to `<slug dir>/.agent/reports/investigate-<round>.md`. Never create ad-hoc root directories.
+
+REUSE
+For any follow-up question, verification, or fix touching these files, CONTINUE THIS AGENT'S SESSION rather than spawning a new agent.

package/lib/node_modules/archgen-mcp/assets/briefs/review.md

@@ -0,0 +1,47 @@
+TASK: Review the plan in `<slug dir>` READ-ONLY.
+SCOPE: Read-only. NEVER edit files or code; output findings only.
+DELIVERABLE: ONE message in this exact format:
+
+```
+VERDICT: APPROVE
+COVERAGE:
+| area | status | reason |
+| --- | --- | --- |
+| edge cases per module | PASS | matrices cover empty, boundary, authz, concurrency, retry, and i18n states |
+| task ordering & parallelization | N/A | single sequential wave |
+| cross-module contracts | PASS | every shared interface has a single owning task |
+| enhancement opportunities | PASS | none material for this scope |
+| documentation completeness | PASS | every task has a matching plan section |
+```
+
+or
+
+```
+VERDICT: ISSUES
+COVERAGE:
+| area | status | reason |
+| --- | --- | --- |
+| ... all 5 areas above marked PASS, FAIL, or N/A ... |
+FINDINGS:
+1. plans/demo.md § API — response type named inconsistently — client/server contract mismatch — standardize on ApiResponse
+2. docs/prd.md § Grades — FR-GRADE-02 has no owning task — requirement will not be built — add task owning grade-read endpoint
+```
+
+EXAMINE ALL 5 AREAS EVERY RUN:
+1. `edge cases per module`
+2. `task ordering & parallelization` (waves vs real `depends_on` edges)
+3. `cross-module contracts` (interfaces, paths, `naming_conventions`)
+4. `enhancement opportunities`
+5. `documentation completeness`
+
+MANDATORY COVERAGE TABLE: Must appear in every report (even on `APPROVE`). Mark every area `PASS`, `FAIL`, or `N/A` with a 1-line reason. Omitting the table or any row makes the report INCOMPLETE.
+
+SIZING & CONTEXT
+- SMALL: Main-agent self-review permitted if no reviewer sub-agent exists.
+- MEDIUM: 1 holistic reviewer.
+- LARGE: 1 top-tier holistic reviewer (2nd allowed ONLY if context limits force splitting `plans/` vs `docs/`; never split by review area).
+- Use the pre-rendered dependency graph and doc-validation results in the `CONTEXT` block below—make zero `archgen_*` tool calls.
+
+BOUNDS
+- A user "more review" approval grants EXACTLY ONE additional pass. The stage exits only on zero findings or an explicit user waiver.
+- The ORCHESTRATOR applies all fixes and re-runs `validate` + Verifier Gate; reviewers never edit files.

package/lib/node_modules/archgen-mcp/assets/briefs/survey.md

@@ -0,0 +1,19 @@
+TASK: Survey this repository to prepare a feature plan for: `<feature request>`
+SCOPE: Read-only exploration, writing ONLY `<slug dir>/codebase-map.md`.
+
+DELIVERABLE: Write `<slug dir>/codebase-map.md` containing EXACTLY these four non-empty sections:
+## Structure — Top 2 directory levels with 1-line purpose per folder
+## Modules — Table: `module | responsibility | key entry points`
+## Conventions — Observed file naming, error handling, and test placement patterns
+## Affected — Files/modules impacted by the feature, citing exact evidence paths
+
+NAVIGATION & VERIFICATION
+- Prefer CodeGraph MCP tools when `.codegraph/` is present (index is kept live by the watcher—never re-index); otherwise use systematic Glob + Grep.
+- Every architectural claim MUST cite a real repository file path. Never guess APIs.
+- Every section must be present and non-empty; document unresolved items as explicit unknowns rather than omitting sections.
+- Downstream rule: The orchestrator will ask the user ONLY what this map could not answer.
+
+SIZING & REUSE
+- SMALL: Main agent surveys in one pass.
+- MEDIUM / LARGE: 1–2 survey agents split strictly by disjoint SUBSYSTEM (zero file overlap).
+- Continue this agent's session for any follow-up questions covering the surveyed subsystem.

package/lib/node_modules/archgen-mcp/assets/briefs/verifier.md

@@ -0,0 +1,56 @@
+TASK: Verify the archgen plan in `<slug dir>` before execution.
+SCOPE: Read-only. NEVER edit files; report verdict, coverage table, and findings only.
+
+STEP 1 — RUN DETERMINISTIC CHECKS FIRST (both must pass):
+1. `archgen_plan { action: 'verify', tasksYaml: <tasks.yaml>, planDir: <plans dir> }` $\rightarrow$ must return `verdict: 'APPROVE'` (validates DAG, dangling refs, wave ownership disjointness, acceptance presence, and bidirectional plan$\leftrightarrow$task coverage).
+2. `archgen_docs { action: 'validate', slugDir: <slug dir> }` (if markdown artifacts exist) $\rightarrow$ must return `valid: true` (zero broken links or heading anchors).
+
+STEP 2 — AUDIT JUDGMENT & CONTRACT COMPLETENESS:
+- Wave boundaries match true dependencies without artificial serialization.
+- Acceptance criteria are objectively verifiable (runnable command or observable output).
+- Edge-case coverage satisfies the scope class (`SMALL` / `MEDIUM` / `LARGE`).
+- Planned structure and naming obey `references/code-standards.md`.
+- **CONTRACT-COMPLETENESS SWEEP** (evaluate every dimension; mark `N/A` only when the system genuinely lacks that surface):
+  1. `functional coverage`: Every requirement maps to a task + objective acceptance check.
+  2. `security & data protection`: Authn/authz flows, session/credential lifecycle, CSRF/replay defense, encryption/privacy boundaries, boundary input validation.
+  3. `data integrity`: Schemas, foreign keys/relations, validation rules, migrations & backward compatibility.
+  4. `state, lifecycle & recovery`: Checkpointing/resume, idempotency, cleanup/TTL, rollback/compensation for stateful or multi-step flows.
+  5. `resource limits & abuse`: Quotas, rate limiting, data retention/deletion, unauthenticated abuse controls.
+  6. `operational entrypoints`: Build, test, deploy, and bootstrap entrypoints are each owned by a task.
+  7. `metric traceability`: Every PRD success metric maps to a task acceptance check with a reproducible command, sample size, or data source.
+  8. `consistency`: Zero contradictions across PRD, `architecture.yaml`, `plans/*.md`, and `tasks.yaml`.
+
+DELIVERABLE — ONE message in this exact format:
+
+```
+VERDICT: APPROVE
+COVERAGE:
+| dimension | status | reason |
+| --- | --- | --- |
+| functional coverage | PASS | all FR IDs map to tasks with runnable checks |
+| security & data protection | N/A | internal CLI with no auth or sensitive data |
+| data integrity | PASS | schemas and migrations are fully typed and owned |
+| state, lifecycle & recovery | FAIL | TASK-07 mutates state without rollback or idempotency |
+| resource limits & abuse | N/A | no shared or public network surface |
+| operational entrypoints | PASS | build, test, and CLI entrypoints have owning tasks |
+| metric traceability | PASS | PRD latency target verified by benchmark acceptance command |
+| consistency | PASS | all contracts align across architecture.yaml and plans |
+```
+
+or
+
+```
+VERDICT: ISSUES
+COVERAGE:
+| dimension | status | reason |
+| --- | --- | --- |
+| ... all 8 dimensions above marked PASS, FAIL, or N/A ... |
+FINDINGS:
+1. tasks.yaml § SCAFFOLD — acceptance #2 has no observable check — worker cannot verify completion — replace with "npm run build exits 0"
+2. plans/demo.md § Risks — config-drift risk has no owning task — mitigation never built — assign mitigation to TASK-01
+```
+
+RULES
+- **MANDATORY COVERAGE TABLE:** Every report (even `APPROVE`) must include all 8 dimensions marked `PASS`, `FAIL`, or `N/A` with a 1-line reason. Missing rows = INCOMPLETE report (treated as `ISSUES`).
+- **Top-tier holistic agent:** Run on the strongest reasoning model available (never a quick/explore/cheap tier) as ONE holistic agent across the entire plan.
+- **Exhaustive single pass:** Report EVERY defect found in this pass with exact `file § section — defect — impact — fix`. Never hold findings back for a later round.

package/lib/node_modules/archgen-mcp/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
+  }
+}