hermes-sdlc

<p align="center"> <img src="extension/media/icon.png" alt="Hermes SDLC" width="120" /> </p> <h1 align="center">Hermes SDLC</h1> <p align="center"> <strong>AI-powered Software Development Lifecycle orchestrator</strong><br/> MCP server + IDE extension for autonomous, multi-agent development workflows </p> <p align="center"> <a href="#features">Features</a> • <a href="#architecture">Architecture</a> • <a href="#quick-start">Quick Start</a> • <a href="#usage">Usage</a> • <a href="#agents">Agents</a> • <a href="#engines">Engines</a> • <a href="#configuration">Configuration</a> • <a href="#license">License</a> </p> --- ## Overview Hermes SDLC is a **zero-click pipeline orchestrator** that drives your entire software development lifecycle through AI agents. Define an epic, click play, and watch as specialized agents autonomously execute each phase — from product planning through deployment. <p align="center"> <img src="docs/screenshots/dashboard.png" alt="Hermes Dashboard" width="800" /> <br/> <em>Dashboard view — pipeline progress at a glance with inline approve/reject controls</em> </p> It works with **multiple AI coding agents** simultaneously: | Agent | Dispatch Method | |-------|----------------| | **Antigravity** | `sendPromptToAgentPanel` — direct agent injection | | **Claude Code** | `terminal.sendSequence` — raw terminal keystroke dispatch | | **Codex** | CLI command via clipboard | ## Features - **🚀 One-Click Execution** — Click ▶️ on any phase in the sidebar to dispatch to your preferred AI agent - **📋 9-Phase Pipeline** — Plan → Design → Test Plan → Implement → Review → Execute Test → Release → Monitor → Doc Sync - **🤖 5 Agent Personas** — Product Owner, Tech Lead, QA Engineer, Developer, Release Manager - **✅ Quality Gates** — Inline approve/reject buttons with human review gates - **🔍 Automated Pre-Review** — Nyx shadow reviewer validates artifacts before human review - **📊 Spec Drift Detection** — Argos monitors alignment between PRD, design, and implementation - **🧠 Context Optimization** — Proteus compresses phase context to fit token budgets - **🏗️ Model Selection** — Athena assigns optimal AI models per role and phase - **💰 Token Tracking** — Cronus monitors API usage across the pipeline - **🔗 Integrations** — GitLab, Jira, YouTrack issue tracker connectors ## Architecture ``` hermes-sdlc/ ├── pipeline/ # MCP server — the brain │ ├── mcp.ts # Model Context Protocol server (Olympus) │ ├── orchestrator.ts # Phase lifecycle management │ ├── nyx.ts # Shadow pre-reviewer │ ├── argos.ts # Spec drift detector │ ├── proteus.ts # Context optimizer │ ├── athena.ts # Model selector │ ├── cronus.ts # Token tracker │ └── runner.ts # Autonomous Gemini API runner │ ├── extension/ # VS Code / Antigravity extension │ ├── extension.ts # Command registration + dispatch │ ├── providers/ # Sidebar tree views │ ├── panels/ # Dashboard webview │ └── integrations/ # GitLab, Jira, YouTrack │ ├── shared/ # Shared TypeScript types ├── agents/ # Agent persona definitions (markdown) └── config/ # Model registry + review matrix ``` ### How It Works ``` ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │ IDE Sidebar │───▶│ Agent Picker │───▶│ AI Agent │ │ Click ▶️ │ │ (QuickPick) │ │ (Antigravity/ │ │ │ │ │ │ Claude Code) │ └─────────────┘ └──────────────┘ └───────┬────────┘ │ ┌────────────────────▼──────────────────┐ │ MCP Server (Olympus) │ │ │ │ start_phase → phase_context → │ │ get_agent → [agent creates artifacts] │ │ → set_phase_status │ └───────────────────────────────────────┘ │ ┌────────────────────▼──────────────────┐ │ Filesystem (docs/sdlc/) │ │ │ │ epics/WEB-042/ │ │ ├── epic.json # Epic metadata │ │ ├── PRD.md # Plan artifact │ │ ├── TECH-DESIGN.md # Design artifact │ │ └── phases/ # Status tracking │ └───────────────────────────────────────┘ ``` ## Quick Start ### Prerequisites - **Node.js** ≥ 18 - **pnpm** ≥ 8 - **VS Code**, **Antigravity**, or compatible editor - One of: Antigravity, Claude Code, or Codex for AI agent execution ### Installation ```bash # Clone the repo git clone https://github.com/dustin9893/hermes-sdlc.git cd hermes-sdlc # Install dependencies pnpm install # Build all packages pnpm build # Install the VS Code extension cd extension pnpm exec vsce package --no-dependencies --allow-missing-repository code --install-extension hermes-sdlc-0.1.0.vsix ``` ### MCP Server Setup Register the MCP server in your project's `.mcp.json`: ```json { "mcpServers": { "hermes": { "command": "node", "args": ["/path/to/hermes-sdlc/pipeline/dist/index.js"], "env": {} } } } ``` For Claude Code, add to `~/.mcp.json` (global) or `.mcp.json` (project-level). ## Usage ### 1. Initialize an Epic ``` hermes.init_epic( workspace="/your/project", epic_id="WEB-042", project="my-app", brief="Build a responsive landing page with dark mode" ) ``` ### 2. Run Phases via Sidebar Open the **Hermes SDLC: Pipeline** sidebar panel. Each phase shows: | Icon | Status | Action | |------|--------|--------| | ⚪ | Pending | — | | ▶️ | Ready | Click to run | | 🔄 | In Progress | Running | | 🔍 | In Review | ✅ Approve / ❌ Reject | | ✅ | Passed | Complete | | 🔴 | Rejected | Click 💬 for feedback | ### 3. Approve / Reject When a phase reaches **In Review**, inline buttons appear: - **✅ Check** — Approves the phase, advances pipeline - **❌ X** — Prompts for rejection reason, sends back for rework ### 4. Run via MCP Tools Directly All operations are available as MCP tools: ``` start_phase — Begin a phase run phase_context — Get full context payload for a phase get_agent — Load agent persona instructions set_phase_status — Transition phase status epic_status — Full status report shadow_review — Automated pre-review screening (Nyx) detect_drift — Spec drift analysis (Argos) optimize_context — Token budget optimization (Proteus) select_model — Model selection per role (Athena) token_report — Usage tracking (Cronus) ``` ## Pipeline Phases | # | Phase | Worker | Artifact | Description | |---|-------|--------|----------|-------------| | 1 | **Plan** | Product Owner | `PRD.md` | Requirements, user stories, acceptance criteria | | 2 | **Design** | Tech Lead | `TECH-DESIGN.md` | Architecture, components, data flow, API contracts | | 3 | **Test Plan** | QA Engineer | `TEST-PLAN.md` | Test cases, coverage matrix, traceability | | 4 | **Implement** | Developer | Source code | Feature branch with implementation | | 5 | **Review** | Tech Lead | `APPROVAL.md` | Code review, architecture validation | | 6 | **Execute Test** | QA Engineer | `TEST-SCRIPT.md` | Test execution results | | 7 | **Release** | Release Manager | `RELEASE-NOTES.md` | Changelog, deployment checklist | | 8 | **Monitor** | SRE | Dashboards | Production health monitoring | | 9 | **Doc Sync** | Archivist | Documentation | Final documentation updates | ## Agents Agent personas are defined in `agents/*.md` and loaded dynamically: ### Product Owner (`po.md`) Creates PRDs with user stories, acceptance criteria, and scope definitions. Ensures business alignment and stakeholder requirements are captured. ### Tech Lead (`tech-lead.md`) Produces technical design documents covering architecture, component specs, API contracts, performance budgets, and risk mitigations. ### QA Engineer (`qa.md`) Writes test plans with full traceability to PRD acceptance criteria. Creates coverage matrices ensuring no requirement gaps. ### Developer (`developer.md`) Implements features following the technical design. Creates feature branches with proper commit hygiene referencing the epic key. ### Release Manager (`release-manager.md`) Manages release notes, deployment checklists, and go/no-go criteria for production releases. ## Engines The pipeline server includes specialized sub-systems (named after Greek mythology): | Engine | Role | Description | |--------|------|-------------| | **Olympus** | MCP Host | Main server exposing all pipeline tools via Model Context Protocol | | **Nyx** | Shadow Reviewer | Automated pre-review screening against quality checklists | | **Argos** | Drift Detector | Monitors alignment between PRD, design, and implementation | | **Proteus** | Context Optimizer | Compresses phase payloads to fit model token budgets | | **Athena** | Model Selector | Assigns optimal AI models per role based on capabilities | | **Cronus** | Token Tracker | Records and reports API token usage across pipeline runs | ## Configuration ### Model Registry (`config/model-registry.json`) Configure available AI models per provider: ```json { "anthropic": [ { "id": "claude-sonnet-4-20250514", "roles": ["developer", "qa"], "contextWindow": 200000 } ], "google": [ { "id": "gemini-2.5-pro", "roles": ["po", "tech-lead"], "contextWindow": 1000000 } ] } ``` ### Review Matrix (`config/review-matrix.json`) Configure which phases require human gates, auto-review, and quality checklists: ```json { "phases": { "plan": { "worker": "po", "humanGate": true, "autoReview": true }, "design": { "worker": "tech-lead", "humanGate": true }, "implement": { "worker": "developer", "humanGate": true } } } ``` ### Extension Settings | Setting | Description | Default | |---------|-------------|---------| | `hermes.geminiApiKey` | API key for autonomous runner | — | | `hermes.epicDir` | Epic storage directory | `docs/sdlc/epics` | ## File System Convention Hermes uses the filesystem as its state store — no database required: ``` your-project/ └── docs/sdlc/epics/ └── WEB-042/ ├── epic.json # Epic metadata ├── WEB-042.md # Epic description ├── PRD.md # Plan phase artifact ├── TECH-DESIGN.md # Design phase artifact ├── TEST-PLAN.md # Test plan artifact └── phases/ ├── plan/ │ └── status.json ├── design/ │ └── status.json └── implement/ └── status.json ``` Each `status.json` tracks: ```json { "status": "passed", "revision": 2, "startedAt": "2026-05-02T04:00:00Z", "completedAt": "2026-05-02T04:30:00Z", "lastReview": { "decision": "pass", "reviewer": "human", "reason": "Approved via sidebar" } } ``` ## Development ```bash # Install dependencies pnpm install # Build all packages pnpm build # Build in watch mode (extension) cd extension && pnpm exec esbuild src/extension.ts --bundle --outfile=dist/extension.js --platform=node --external:vscode --watch # Package extension cd extension && pnpm exec vsce package --no-dependencies --allow-missing-repository ``` ### Monorepo Structure | Package | Description | Build | |---------|-------------|-------| | `shared/` | TypeScript types | `tsc` | | `pipeline/` | MCP server | `esbuild` | | `extension/` | VS Code extension | `esbuild` | ## Contributing 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License MIT © [Dustin Le](https://github.com/dustin9893)