archgen-skill
v0.1.7
Published
Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskill
Maintainers
Readme
archgen-skill
Conversational architecture generation & autonomous task execution for coding agents.
Describe what you want to build. archgen interviews you (or surveys your existing codebase), produces an architecture contract plus a dependency-ordered task graph, verifies the plan, then executes it wave-by-wave through sub-agents.
Works as an agent skill for Claude Code · OpenCode · Cursor · Codex · Gemini CLI · Antigravity — and any agentskills.io-compatible harness.
Install
Prepare a project (recommended) — installs ONE canonical skill copy plus harness bridges so every agent auto-discovers it:
npx archgen-skill initWhat init writes (nothing is ever duplicated):
| Path | What |
| --- | --- |
| .agents/skills/archgen/ | The only real copy — the agentskills.io standard location, read natively by OpenCode, Cursor, Codex, Gemini CLI, Copilot, and Antigravity |
| .claude/skills/archgen → ../../.agents/skills/archgen | Relative symlink for Claude Code (the one harness that needs it); skipped gracefully where symlinks require privileges |
| AGENTS.md | Managed hub block: skill pointer, quick triggers, and a features registry that stays current as you add features |
| CLAUDE.md | One-line bridge: @AGENTS.md (existing content is preserved; nothing is written if it already imports AGENTS.md) |
Existing projects are safe: managed blocks upsert between markers, modified skill
copies are backed up to .archgen/.backup/<timestamp>/ before refresh, and legacy
dual-copy layouts are migrated to symlinks automatically. Verify anytime with
archgen-skill doctor.
Every destructive step is behind a rail: the project root is asserted before
anything is written or deleted, a symlinked target is never written through, the
store swap is atomic (the old store is moved aside, not deleted, and restored if
the swap fails), and a restore puts back exactly the paths the snapshot recorded
— never a sibling skill. archgen-skill uninstall <dir> removes that project;
the global uninstall happens only when no project is named.
Or install globally into every detected harness:
npx archgen-skill installIt links the skill into every detected harness directory; --copy makes real
copies instead of symlinks.
Prefer shell? Clone the repo and run ./install.sh (same behavior, plus
--init, --project, --uninstall). Requires Node.js ≥ 20 — the official MCP
SDK v2 floor.
What init actually does: installs the skill (guidance only — no code),
wires the archgen-mcp MCP server into every detected harness, and ensures
CodeGraph (its CLI — installed only when it is MISSING, never upgraded — its
MCP entry, and the project index). The CLI itself is
zero-dependency; the MCP server it installs depends on the official MCP SDK.
Quick start
After npx archgen-skill init, open your project in any supported agent and talk
naturally:
| You say | What runs | | --- | --- | | "generate architecture for a booking platform" | Interview → artifacts → both gates | | "add rate-limiting to my API server" | Survey existing code first, then plan + gates | | "start work" | Autonomous wave execution until done or blocked | | "roll back the auth changes" | Impact analysis → reverse-order revert plan → approval |
Everything archgen produces lives in one reviewable .archgen/<slug>/ folder —
architecture contract, docs, ADRs, plans, and a tasks.yaml task graph — versioned
by git.
Commands
| Command | What it does |
| --- | --- |
| npx archgen-skill init [dir] | Prepare a project: canonical skill store at .agents/skills/archgen, Claude symlink adapter, AGENTS.md hub + CLAUDE.md bridge |
| npx archgen-skill install [--copy] | Install into global harness skill dirs (symlinks by default, real copies with --copy) |
| npx archgen-skill uninstall | Remove globally-installed copies (manifest-recorded, safe removal) |
| npx archgen-skill uninstall [dir] | Remove a project install (same as --project [dir]): strips managed blocks, symlink, the store only if unmodified, and the dead .archgen/.runtime/ extension state — .archgen/ feature folders and all user content are preserved |
| npx archgen-skill doctor [dir] [--check] | Verify and auto-repair an installation: store integrity, version stamp, Claude link, managed blocks, manifest (--check reports without fixing) |
| npx archgen-skill update [dir] | Check npm for a newer archgen-skill, upgrade the global install if outdated, then re-init the project and run doctor against the new version |
| npx archgen-skill restore | List backup snapshots; --snapshot <ts> restores one (current state is backed up first) |
| npx archgen-skill migrate [dir] [--apply] | Evolve generated-artifact formats in place (--check by default; every touched file is backed up) |
| npx archgen-skill mcp list | The MCP wiring admin surface: the detected harnesses and their config paths |
| npx archgen-skill mcp add --yes | Wire the archgen-mcp server into the detected harnesses (prints the plan without --yes) |
| npx archgen-skill mcp remove --yes | Remove the archgen MCP entries this server wrote |
| npx archgen-skill codegraph status | The CodeGraph admin surface: install, wiring and index state (read-only) |
| npx archgen-skill codegraph ensure --yes | Install the CodeGraph CLI if it is MISSING, wire its MCP entry, build the index |
| npx archgen-skill codegraph wire --yes | Wire the CodeGraph MCP entry into the detected harnesses only |
| npx archgen-skill --version / --help | Print the CLI version / show help |
Why archgen
AI coding agents fail at scale for predictable reasons: plans with hidden cycles, workers editing the same files, tasks without objective acceptance criteria, and no human checkpoint before execution. archgen makes each of these a structural guarantee:
| Guarantee | Mechanism |
| --- | --- |
| Plans are valid before work starts | Verifier gate — cycles, dangling refs, ownership overlaps, plan↔task coverage |
| You approve before code is written | Explicit user gate after verifier approval |
| Parallel workers never collide | Disjoint file_ownership globs enforced per wave |
| Task order is always correct | Topological waves from depends_on; chains stay sequential |
| Failures never cascade silently | Failed tasks exclude downstream into blockedByFailure, surfaced to you |
| Every artifact is reviewable | Everything in one .archgen/<slug>/ folder, versioned by git |
interview (greenfield) · survey (brownfield)
│
▼
.archgen/<slug>/ ── architecture.yaml · docs · ADRs · plans · tasks.yaml
│
▼
VERIFIER GATE ──issues──► fix & re-verify
│ APPROVE
▼
USER GATE ────reject───► revise
│ approve
▼
WAVES ── topological order · one sub-agent per task · disjoint ownership
│
▼
final report: done / failed / blocked · commits · follow-upsSupported harnesses
Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Antigravity — and any
agentskills.io-compatible harness. Both global install and project-local init
are supported for all of them.
Documentation
| Doc | Contents | | --- | --- | | Architecture walkthrough | Dual-mode design, gates, wave mechanics, platform detection | | The skill contract | The full skill specification agents execute | | Changelog | Release history |
Contributing
See CONTRIBUTING.md. Skill suite and CLI tests run with zero dependencies:
node --test packages/mcp/test/**/*.test.mjs
cd packages/cli && npm testThe first is the MCP server suite; the second is the CLI suite.
License
MIT © ArchGen contributors
