coding-lifecycle-engine

# AI Coding Lifecycle > A **stateful lifecycle engine** that forces an AI coding agent to walk a real product from *idea* to *shippable deliverable* — without cutting corners, faking green tests, or silently restarting. **English** | --- ## What is this? Most AI coding agents are *stateless sprinters*. They enthusiastically write code, declare "done", and forget everything the moment a session ends. Open a new window and the agent has no idea what it built yesterday, which decisions were made, or whether the tests it claimed to pass actually pass. **AI Coding Lifecycle** fixes this. It is a combination of: 1. **An MCP server** (`mcp-server/`) — a Model Context Protocol server exposing **52 tools** backed by a single SQLite database (`lifecycle.db`). This database is the *single source of truth*: every phase, decision, contract, task, cost record, and NFR coverage flag lives here, persisted across sessions and workspaces. 2. **A SKILL.md orchestration layer** — a detailed playbook that tells the AI agent *how* to drive the lifecycle: when to stop, when to ask the user, when it is forbidden to advance. 3. **42 reference files** (`references/`) — deep-dive guides the agent pulls in on demand (contract design, maturity scoping, NFR dimensions, parallel execution, adversarial acceptance, etc.). The core insight: **state must live in a database, not in the conversation.** Conversations get truncated, summarized, and forgotten. A database does not. When you switch tasks, close a window, or come back a week later, the lifecycle picks up exactly where it left off. --- ## Built on the work of others (important) **This project is not an invention of the AI's own "method". It is a workflow-orchestration layer built on top of open-source AI coding *skills* created by other people — primarily [Matt Pocock's `skills` collection](https://github.com/mattpocock/skills).** Those upstream skills are excellent at *what to do in a single conversation* (how to grill a plan, how to write tests first, how to review a diff), but they are **stateless**: every time you open a new window, the agent has no memory of what it did before, and nothing enforces that you actually finished one step before moving to the next. What this project adds is the **stateful engine around those skills**: - It wraps the upstream skills (grilling, TDD, code-review, research, handoff, …) into a **6-phase pipeline** driven by an MCP server. - It persists **every phase, decision, contract, and gate** to a SQLite database so the process survives across sessions. - It enforces **hard gates** (stop-after-each-phase, identity lock, NFR completeness) that the raw skills never had. - It makes the whole flow **resumable, auditable, and parallel-safe**. In short: **the upstream skills are the engine; this repo is the chassis, the fuel gauge, and the traffic lights.** Full credit for the underlying techniques belongs to their original authors — see [Acknowledgements](#acknowledgements). > If you see a phase named **"Grilling"** below: that is Matt Pocock's `grilling` skill (an adversarial plan-review technique) being invoked as Phase 0.5. It is *not* something home-grown here — we are standing on his shoulders. --- ## Why does it exist? (The problems it solves) | Problem with vanilla AI coding | How the lifecycle solves it | | --- | --- | | **Corner-cutting.** Agent writes a stub, calls it done. | Phase gates + adversarial acceptance force real implementation. | | **Faking green.** Agent claims tests pass without running them. | Phase 3 adversarial acceptance + explicit gate records. | | **Silent restart.** New session = agent forgets and rebuilds from scratch. | SQLite single source of truth + resume protocol. | | **Runaway agent.** Agent blasts through all phases in one shot, no human checkpoint. | Server-level two-step commit gate — stops after every phase. | | **Lost decisions.** Key architectural decisions vanish when the chat is summarized. | `record_decision` / `save_memory` persist to DB. | | **Parallel-project confusion.** Multiple projects in flight; "continue" is ambiguous. | `list_projects` enumeration + user selection. | | **Missing non-functional requirements.** Commercial product ships with no auth/logging/backup. | NFR completeness gate scaled by maturity. | --- ## The 6-phase lifecycle ``` Phase 0 Requirements + Solution design │ Phase 0.5 ★ Grilling Adversarial plan review (HARD GATE) │ Phase 1 Decomposition + Contract freeze │ Phase 2 Parallel development │ Phase 3 ★ Adversarial acceptance (HARD GATE) │ Phase 4 Failure rehearsal + Delivery ``` - **Phase 0 — Requirements & Solution.** Capture what is being built and the proposed approach. Maturity is scoped here (MVP / commercial / enterprise), which controls how strict later gates are. (Technique credit: `mattpocock/skills` `to-spec` / `research`.) - **Phase 0.5 — Grilling (★ hard gate).** The plan is stress-tested against exhaustive dimensions before a single line of production code is written. Weak plans are sent back. **This is Matt Pocock's `grilling` skill** — an adversarial, one-question-at-a-time plan review — wired in as a hard gate. - **Phase 1 — Decomposition & Contract freeze.** Work is split into tasks; interface contracts between tasks are **frozen**. Changing a frozen contract bumps its version and automatically blocks dependents until they re-align. (Technique credit: `implement` / `to-tickets` from `mattpocock/skills`.) - **Phase 2 — Parallel development.** Tasks execute (potentially in parallel), respecting the DAG and frozen contracts. File locks prevent collisions. (Technique credit: `tdd` drives per-task implementation + tests.) - **Phase 3 — Adversarial acceptance (★ hard gate).** Deliverables are attacked, not congratulated. Real tests, real edge cases. (Technique credit: `code-review` / `tdd` from `mattpocock/skills`.) - **Phase 4 — Failure rehearsal & delivery.** Rehearse how it breaks, then hand off. (Technique credit: `handoff` from `mattpocock/skills`.) --- ## Three hard disciplines (non-negotiable) 1. **Don't cut corners.** No stubs masquerading as features. 2. **Don't fake green.** A gate is only passed with recorded evidence. 3. **Don't restart.** Resume from DB state, never rebuild from zero. --- ## Server-level hard gates (enforced in code, not just prose) These are **real barriers baked into the MCP server**, not soft SOP suggestions the AI can ignore: - **Two-step commit on `advance_phase`.** The first call only *parks* the transition — it does not advance. The phase only moves forward when the user explicitly confirms (`confirmed_by_user=true` + `user_ack`). This forces a human checkpoint after every phase. - **Identity hard-lock before Phase 1.** `identity_confirmed=1` is required to enter Phase 1. This flag is set only by `rename_project` or `confirm_identity`. Without it, `advance_phase` fails. (Independent DB flag — a genuinely hard gate.) - **NFR completeness gate scaled by maturity.** For `commercial` / `enterprise` maturity, `pass_gate(phase_0_5)` requires every dimension in `nfr_coverage` to be marked `covered=1`. MVP is not forced (only advised). > **Honest boundary:** The two-step commit is a strong barrier but not absolute — an agent could theoretically call `advance_phase` twice in a single turn. The identity lock is genuinely hard (independent DB flag). We document this honestly rather than overselling. --- ## Multi-project & parallel support All projects share one `lifecycle.db`, isolated by `root_path` / `project_id`. - **`root_path` is the "household address"** — fixed at `init_project` time. It defines *where the code ultimately lands*, not *which window you are in*. You can switch tasks/workspaces freely; the household does not move. - **Resume protocol.** In a fresh session, saying "continue" triggers `list_projects()`: - **1 active project** → `get_state(project_id)` directly. - **Multiple projects** → enumerate them, ask the user which one to resume (structured selection), then `get_state`. - **Naming.** Start chaotic ideation with a placeholder name (`untitled-{keyword}`), then `rename_project` to the final name once the plan is locked. --- ## Installation & setup ### Prerequisites - Node.js **>= 18** - An MCP-capable client (e.g. WorkBuddy, Claude Desktop, or any MCP host) ### 1. Install the MCP server ```bash cd mcp-server npm install ``` This builds `better-sqlite3` and installs `@modelcontextprotocol/sdk`. ### 2. Register the server in your MCP config Add to your MCP host config (e.g. `~/.workbuddy/mcp.json`): ```json { "mcpServers": { "ai-coding-lifecycle": { "command": "node", "args": ["/absolute/path/to/ai-coding-lifecycle/mcp-server/src/index.js"] } } } ``` The database is created automatically on first run at the user-level data directory. Migrations (001, 002, 003) run idempotently on import — no manual `ALTER` needed. ### 3. Install the SKILL Copy or symlink `SKILL.md` into your agent's skills directory so the agent loads the orchestration playbook. The SKILL references files under `references/` on demand. ### 4. Run the tests (optional) ```bash cd mcp-server node --test test/smoke.test.mjs ``` Tests use a temporary DB (`AI_LIFECYCLE_DB` env override), so they never pollute your real `lifecycle.db`. Current suite: **22/22 passing, 52 tools**. --- ## Tool catalog (52 tools) Organized across layered modules under `mcp-server/src/tools/`: | Module | Responsibility | Example tools | | --- | --- | --- | | `project.js` | Project lifecycle, identity, state | `init_project`, `get_state`, `list_projects`, `rename_project`, `confirm_identity`, `reset_project`, `delete_project`, `bootstrap_existing` | | `dag.js` | Task graph, dependencies, contracts | `decompose`, `get_dag`, `freeze_contract`, `get_contracts`, `check_dependencies` | | `execution.js` | Task execution & phase control | `claim_task`, `start_task`, `complete_task`, `advance_phase`, `pass_gate`, `get_checklist` | | `increment.js` | Mid-stream change handling | `classify_change`, `integrate_changes` | | `conventions.js` | Coding conventions extraction | `get_conventions`, `set_convention` | | `memory.js` | Cross-session memory | `save_memory`, `search_memory`, `record_decision` | | `bug.js` | Bug tracking (sibling track) | `report_bug` | | `approval.js` | Human approvals | `request_approval`, `record_approval` | | `parallel.js` | File locks for parallel work | `acquire_file_lock`, `release_file_lock`, `check_file_lock` | | `cost.js` | Token / model cost accounting | `record_cost`, `get_cost`, `route_model` | | `nfr.js` | Non-functional requirements gate | `get_nfr_checklist`, `set_nfr_coverage` | | `misc.js` | Escalation & utilities | `escalate_to_human`, `detect_stale` | Run `list_projects` in any fresh session to see what is resumable. --- ## Project structure ``` ai-coding-lifecycle/ ├── SKILL.md # Orchestration playbook (the agent reads this) ├── README.md # This file ├── references/ # 42 deep-dive guides pulled in on demand ├── examples/ │ └── minimal-walkthrough.md ├── scripts/ │ └── extract-conventions.mjs └── mcp-server/ ├── src/ │ ├── index.js # MCP stdio server entry │ ├── db.js # SQLite + auto migrations │ └── tools/ # 12 layered tool modules ├── migrations/ # 001, 002, 003 (idempotent) ├── test/smoke.test.mjs └── package.json ``` --- ## License MIT --- ## Acknowledgements This project is a **derivative workflow built on top of open-source skills authored by others.** The underlying techniques belong to their original authors; this repo's contribution is the stateful orchestration, persistence, and gating around them. - **[Matt Pocock — `skills`](https://github.com/mattpocock/skills)** — the primary engine. The following skills from this collection are invoked directly by the lifecycle: - `grilling` — adversarial plan review → **Phase 0.5** (the "Grilling" hard gate) - `tdd` — test-driven development → **Phase 2 / 3** - `code-review` — adversarial diff review → **Phase 3** - `research` / `to-spec` — requirements & spec capture → **Phase 0** - `implement` / `to-tickets` — decomposition & ticketing → **Phase 1** - `handoff` — delivery & documentation → **Phase 4** - `diagnosing-bugs` — bug triage (sibling track) - **The MCP / SQLite state layer** is original to this project (the `mcp-server/` directory and the `references/` guides). If you like the *techniques*, go star and credit the upstream skills. If you like the *stateful pipeline that makes them survivable across sessions*, that is what this repo adds. --- --- <a name="English"></a> # AI Coding Lifecycle > A **stateful lifecycle engine**, forcing AI coding agents to walk a real product from *idea* all the way to *deliverable* — no faking, no pretending to pass, no secretly restarting. [English](#ai-coding-lifecycle) | [中文](#中文文档) --- ## What is this? Most AI coding agents are *stateless sprinters*: they enthusiastically write code, declare "done", and then forget everything the moment the session ends. Open a new window, and the agent has no memory of what was built yesterday, what decisions were made, or whether the tests they claimed to pass actually passed. **AI Coding Lifecycle** is here to fix that. It consists of three parts: 1. **An MCP server** (`mcp-server/`) — a Model Context Protocol server exposing **52 tools**, backed by a single SQLite database (`lifecycle.db`). This database is the *single source of truth*: every phase, decision, contract, task, cost record, and NFR coverage marker lives here, persisting across sessions and workspaces. 2. **A SKILL.md orchestration layer** — a detailed playbook telling AI *how* to drive the lifecycle: when to pause, when to ask users, when to be blocked. 3. **42 reference files** (`references/`) — on-demand pulled deep-dive guides (contract design, maturity grading, NFR dimensions, parallel execution, adversarial acceptance, etc.). Core insight: **State must live in the database, not in the conversation.** Conversations get truncated, summarized, and forgotten; databases don't. When you switch tasks, close the window, or return a week later, the lifecycle picks up exactly where it left off. --- ## Standing on the shoulders of others (important note) **This project isn't a workflow "invented" by AI itself, but an orchestration layer built on top of open-source AI coding *skills* — primarily from [Matt Pocock's `skills` collection](https://github.com/mattpocock/skills).** Those upstream skills excel at "what to do in a single conversation" (how to grill a plan, how to do test-driven development, how to review diffs), but they are **stateless**: every new window, the agent forgets what was done before, and there's no enforcement to ensure you complete one step before moving to the next. This project's value is to give those skills a **stateful engine**: - to sequence upstream skills (grilling, TDD, code-review, research, handoff…) into a **six-phase pipeline** driven by the MCP server; - to ground *each phase, decision, contract, and gate* in the SQLite database, making the process survivable across sessions; - to add **hard gates** not present in upstream skills (per-phase checkpoints, identity checkpoints, NFR completeness); - to make the entire process **resumable, auditable, and parallel-safe**. In short: **Upstream skills are the engine; this repo is the chassis, dashboard, and traffic lights.** All credit for underlying techniques goes to the original authors — see [Acknowledgements](#acknowledgements). > If you see a phase called **"Grilling"** below: that's Matt Pocock's `grilling` skill (an adversarial plan review technique) hooked up as Phase 0.5. **This isn't invented here; we're just using his shoulder.** --- ## Why do we need this? (The problem it solves) | Native AI coding issues | How Lifecycle solves it | | --- | --- | | **Faking it.** Writing stubs to pretend to be done. | Phase gating + adversarial acceptance enforce real implementation. | | **Pretending to pass.** Claiming to pass without actually running tests. | Phase 3 adversarial acceptance + explicit gate records. | | **Secretly restarting.** New session = forgetting everything. | SQLite single source of truth + resumability protocol. | | **Running wild.** Rushing through phases without human checkpoints. | Server-level two-step commits enforce checkpoints. | | **Lost decisions.** Key architecture decisions disappear after conversation summaries. | `record_decision` / `save_memory` grounding in DB. | | **Parallel project confusion.** Multiple projects in flight; unclear what to resume. | `list_projects` enumeration + structured choice. | | **Non-functional requirements missing.** Shipping products without auth/logging/backup. | Maturity-scaled NFR completeness gating. | --- ## The Six-Phase Lifecycle ``` Phase 0 Requirements + Planning │ Phase 0.5 ★ Grilling Adversarial plan review (hard gate) │ Phase 1 Decomposition + Contracting │ Phase 2 Parallel Development │ Phase 3 ★ Adversarial Acceptance (hard gate) │ Phase 4 Failure Rehearsal + Handoff ``` - **Phase 0 — Requirements & Planning.** Clarify what to build and how. Maturity level set here (MVP / Commercial / Enterprise), which determines how strict subsequent gates are. (Technique credits: `mattpocock/skills`'s `to-spec` / `research`.) - **Phase 0.5 — Grilling (★ hard gate).** Before writing a single line of production code, the plan gets stress-tested on exhaustive dimensions. Weak plans get rejected. **This is Matt Pocock's `grilling` skill** — an adversarial, question-by-question plan review — hooked up as a hard gate. - **Phase 1 — Decomposition & Contracting.** Work gets broken into tasks; task interfaces get **frozen**. Changes to frozen contracts increment the version and automatically block dependents until they re-align. (Technique credits: `mattpocock/skills`'s `implement` / `to-tickets`.) - **Phase 2 — Parallel Development.** Tasks execute (potentially in parallel), respecting DAG and frozen contracts. File locks prevent conflicts. (Technique credits: `tdd` drives single-task implementation + testing.) - **Phase 3 — Adversarial Acceptance (★ hard gate).** Deliverables get "attacked" rather than "praised". Real testing, real boundary cases. (Technique credits: `mattpocock/skills`'s `code-review` / `tdd`.) - **Phase 4 — Failure Rehearsal & Handoff.** Rehearse how it might fail, then hand off. (Technique credits: `mattpocock/skills`'s `handoff`.) --- ## Three Hard Disciplines (non-negotiable) 1. **No faking** — no stubs masquerading as functionality. 2. **No pretending to pass** — gates only pass with recorded evidence. 3. **No restarting** — resuming from database state, never rebuilding from scratch. --- ## Server-Level Hard Gates (baked into the code, not just talk) These are **actual barriers baked into the MCP server**, not soft SOP suggestions AI can ignore: - **`advance_phase` two-step commit.** First call only *pauses*, doesn't advance. Only after explicit user confirmation (`confirmed_by_user=true` + `user_ack`) does the phase advance. This enforces a checkpoint after each phase. - **Identity hard gate before Phase 1.** Entering Phase 1 requires `identity_confirmed=1`. This flag is only set by `rename_project` or `confirm_identity`. Without it, `advance_phase` fails outright. (Independent DB flag — a true hard gate.) - **Maturity-scaled NFR completeness gating.** For `commercial` / `enterprise` maturity, `pass_gate(phase_0_5)` requires every NFR dimension marked `covered=1`. MVP doesn't enforce (only suggests). > **Honesty boundary:** Two-step commits are a strong barrier but not absolute — theoretically, an agent could double-call `advance_phase` in one swoop. Identity hard gate is a true hard gate (independent DB flag). We record accurately, no exaggeration. --- ## Multi-Project & Parallel Support All projects share a single `lifecycle.db`, isolated by `root_path` / `project_id`. - **`root_path` is the "home address"`** — set during `init_project`, defining *where code lands*, not *which window you're in*. You can switch tasks/workspaces freely; home stays put. - **Resumability protocol.** Saying "continue" in a new session triggers `list_projects()`: - **1 active project** → directly `get_state(project_id)`. - **Multiple projects** → enumerated for structured choice; user picks which to resume, then `get_state`. - **Naming.** Use placeholder names during chaotic ideation (e.g., `untitled-{keyword}`), then rename to a proper name once planning solidifies. --- ## Installation & Configuration ### Prerequisites - Node.js **>= 18** - An MCP-compatible client (e.g., WorkBuddy, Claude Desktop, or any MCP host) ### 1. Install MCP Server ```bash cd mcp-server npm install ``` This compiles `better-sqlite3` and installs `@modelcontextprotocol/sdk`. ### 2. Register Server in MCP Config Add to your MCP host config (e.g., `~/.workbuddy/mcp.json`): ```json { "mcpServers": { "ai-coding-lifecycle": { "command": "node", "args": ["/absolute/path/to/ai-coding-lifecycle/mcp-server/src/index.js"] } } } ``` Database created automatically on first run in user-level data directory. Migrations (001, 002, 003) run idempotently on import — no manual `ALTER` needed. ### 3. Install SKILL Copy or symlink `SKILL.md` into your agent's skills directory so the agent loads the orchestration playbook. SKILL references files under `references/` on demand. ### 4. Run Tests (optional) ```bash cd mcp-server node --test test/smoke.test.mjs ``` Tests use a temporary DB (`AI_LIFECYCLE_DB` env override), so they never pollute your real `lifecycle.db`. Current suite: **22/22 passing, 52 tools**. ## Tool List Organized by layered modules under `mcp-server/src/tools/`: | Module | Responsibilities | Example Tools | | --- | --- | --- | | `project.js` | Project lifecycle, identity, state | `init_project`, `get_state`, `list_projects`, `rename_project`, `confirm_identity`, `reset_project`, `delete_project`, `bootstrap_existing` | | `dag.js` | Task graph, dependencies, contracts | `decompose`, `get_dag`, `freeze_contract`, `get_contracts`, `check_dependencies` | | `execution.js` | Task execution and phase control | `claim_task`, `start_task`, `complete_task`, `advance_phase`, `pass_gate`, `get_checklist` | | `increment.js` | Mid-course change handling | `classify_change`, `integrate_changes` | | `conventions.js` | Coding convention extraction | `get_conventions`, `set_convention` | | `memory.js` | Cross-session memory | `save_memory`, `search_memory`, `record_decision` | | `bug.js` | Bug tracking (sibling orbit) | `report_bug` | | `approval.js` | Human approval | `request_approval`, `record_approval` | | `parallel.js` | File locking for parallel work | `acquire_file_lock`, `release_file_lock`, `check_file_lock` | | `cost.js` | Token/model cost accounting | `record_cost`, `get_cost`, `route_model` | | `nfr.js` | Non-functional requirement gating | `get_nfr_checklist`, `set_nfr_coverage` | | `misc.js` | Escalation and tools | `escalate_to_human`, `detect_stale` | Run `list_projects` in any new session to see which projects are available to continue. --- ## Project Structure ``` ai-coding-lifecycle/ ├── SKILL.md # Orchestration manual (read by intelligent agents) ├── README.md # This file ├── references/ # 42 in-depth guides pulled as needed ├── examples/ │ └── minimal-walkthrough.md ├── scripts/ │ └── extract-conventions.mjs └── mcp-server/ ├── src/ │ ├── index.js # MCP stdio server entry │ ├── db.js # SQLite + automatic migration │ └── tools/ # 12 layered tool modules ├── migrations/ # 001, 002, 003 (idempotent) ├── test/smoke.test.mjs └── package.json ``` --- ## License MIT --- ## Acknowledgements This project is a **derivative process built on top of others' open-source skills**. The underlying technical merit goes to the original authors; this repository's contributions are stateful orchestration, persistence, and gating around these skills. - **[Matt Pocock — `skills`](https://github.com/mattpocock/skills)** — Main engine. Lifecycle directly invokes these skills: - `grilling` — Adversarial scheme review → **Phase 0.5** ("Grilling" hard gating) - `tdd` — Test-driven development → **Phase 2 / 3** - `code-review` — Adversarial diff review → **Phase 3** - `research` / `to-spec` — Requirement and specification capture → **Phase 0** - `implement` / `to-tickets` — Breakdown and ticketing → **Phase 1** - `handoff` — Delivery and documentation → **Phase 4** - `diagnosing-bugs` — Bug triage (sibling orbit) - **MCP / SQLite state layer** (`mcp-server/` directory and `references/` guides) is original to this project. If you like the *technical techniques*, go star and attribute the upstream skills; if you like the *stateful pipeline that makes them work across sessions*, that's what this repository adds.