This diagram documents the end-to-end development process used by the EIB MCP-RAG platform, where Spec-Driven Development (SDD) governs the lifecycle from conceptual design through autonomous code implementation and back to human review. The process spans two execution modalities—IDE (human-in-the-loop) and CLI (autonomous)—unified by persistent session state.
| Step | Actor | Activity | Key Tools / Artifacts |
|---|---|---|---|
| 1. Discover | Human + AI | Run health checks and smoke tests to validate system state. Identify gaps, stale documentation, parameter mismatches. | mcp_health_check(), get_knowledge_base_status(), search_documentation(), GraphRAG validation |
| 2. Spec Design | Human + AI | Author the SDD workflow specification in markdown. Define steps, success criteria, dependencies, and open questions. "If it's not in the SDD, it doesn't get coded." | sdd_framework/workflows/phaseNN_feature.md |
| 3. Resolve Decisions | MCP-assisted | Investigate open questions using MCP tools (code analysis, architecture search). Make architectural decisions and update the spec with resolutions. | get_code_context(), search_architecture(), spec updates committed to git |
| 4. Prep Handoff | MCP-assisted | Push all changes to origin. Ensure instruction files are synchronized (generate-tool-docs.js --check). Verify the spec is self-contained for the CLI agent. |
git push origin develop, instruction file sync, CHANGELOG |
| 5. /plan Decompose | CLI Agent | The Copilot CLI reads the SDD spec, .github/copilot-instructions.md, and existing source code. Generates its own implementation plan from the spec. |
copilot --model claude-opus-4.6 --yolo --additional-mcp-config @.copilot/mcp-config.json |
| 6. Start Session | CLI Agent | Calls start_sdd_session() to activate tracking. Creates active_session.json and first history.jsonl entry. From this point, all progress is durable. |
start_sdd_session({ phase, totalSteps }) |
| 7. Implement + Record | CLI Agent | Iterative loop: edit code, then call record_sdd_step() after each milestone. Session state updates on every step. Calls complete_sdd_session() when done. |
record_sdd_step({ step, name, tag, notes }), complete_sdd_session({ summary }) |
| 8. Monitor + Review | Human + AI | The IDE session monitors CLI progress in real-time via get_sdd_session() or tail -f history.jsonl. After completion: review changes, run validation gates, merge. |
get_sdd_session(), get_sdd_execution_history(), git diff, code review |
Before any CLI-produced code is merged, it passes through five automated checks:
| Gate | What It Checks | Pass Criteria |
|---|---|---|
generate-tool-docs.js --check | All MCP tools documented in instruction files with correct required params | 44/44 tools, 0 warnings |
npm test | Unit + integration test suite | All pass |
mcp_health_check(deep) | Server + ChromaDB + Neo4j + all components | 7/7 healthy |
| Docker rebuild | Image builds with new code baked in | docker build succeeds |
| Gateway smoke test | New tools callable via Streamable HTTP gateway | Tools respond correctly |
All state is filesystem-based (no Redis, no SQLite), following the Phase 31 session model decision:
| File | Purpose | Lifecycle |
|---|---|---|
active_session.json | Current session: phase, completedSteps[], modifications[], examined[], checkpoints[] | Created on start_sdd_session, deleted on complete_sdd_session |
history.jsonl | Append-only event log for audit trail | Grows forever, one JSON line per event |
checkpoints/*.json | Named snapshots of session state (Phase 24H-3 extension) | Created by checkpoint_state, read by restore_checkpoint |
workflows/*.md | SDD specifications — Single Point of Truth for each feature | Authored in Steps 2-3, read by CLI in Step 5 |
CHANGELOG.md | Semantic versioning with dated headers | Updated at every version change |
The same session model serves both modalities. In IDE mode (Steps 1-4, 8), the chat window is the
approval mechanism—every tool call requires a human turn. In CLI mode (Steps 5-7, --yolo),
the agent runs autonomously with the SDD spec as its guardrail. The persistent state layer bridges the gap:
the CLI writes to the same active_session.json and history.jsonl that the IDE reads.
This enables true cross-modality session handoff.
When Phase 4C USD delivers the ISD approval infrastructure for CLI mode, the same file-based state will gain enforcement semantics—step types will gate tool permissions rather than just describe intent. Until then, the SDD spec itself is the control plane.