forge-server 0.1.0

package/docs/plans/2026-02-27-swarm-coordination/architecture.md

@@ -0,0 +1,203 @@
+# Swarm Coordination Activation — Architecture Plan
+
+## Overview
+
+Wire the existing swarm infrastructure (broadcasts, observations, memory) into the implementation phase so agents actually coordinate. Five modules of changes across server code and agent prompts.
+
+## Module A: Context Injection — Broadcasts + Sibling Awareness
+
+**Files:** `src/context/injector.ts`
+
+### Changes:
+
+1. **Extend `ModuleContext` interface** (line 90-94) — add two new fields:
+   ```typescript
+   export interface ModuleContext {
+     relevantCode: string;
+     gotchas: Array<{ title: string; content: string }>;
+     conventions: Array<{ title: string; content: string }>;
+     // NEW: swarm coordination
+     recentBroadcasts: Array<{ content: string; severity: string; created_at: number }>;
+     siblingModules: Array<{ name: string; agentType: string; description?: string }>;
+   }
+   ```
+
+2. **Update `injectImplementationContext()`** (line 347-407):
+   - Accept the full modules array (already does)
+   - Call `this.getRecentBroadcasts(projectId, 10)` once (not per-module)
+   - For each module, populate `recentBroadcasts` with project-wide broadcasts
+   - Populate `siblingModules` with ALL other modules in the dispatch (name + agentType + description), so each agent knows who else is working and on what
+   - Method signature gains optional `moduleDescriptions` parameter
+
+3. **Extend `getRecentBroadcasts()`** (line 184-209) — increase default limit from 5 to 10 for implementation phase, already handles empty gracefully.
+
+## Module B: Phase Tools — Broadcast Injection into start_implementation Response
+
+**Files:** `src/tools/phase-tools.ts`
+
+### Changes:
+
+1. **Update `startImplementation()`** (line 714-769):
+   - Pass module descriptions through to `injectImplementationContext()`
+   - Add `recent_broadcasts` and `sibling_modules` to each entry in `module_contexts`
+   - Response shape becomes:
+     ```typescript
+     module_contexts: {
+       [moduleName]: {
+         relevant_code: string;
+         gotchas: [...];
+         conventions: [...];
+         recent_broadcasts: [...];  // NEW
+         sibling_modules: [...];    // NEW
+       }
+     }
+     ```
+
+2. **Update `startImplementationSchema`** (line 115-122):
+   - The `description` field on modules is already optional — no schema change needed
+   - But agents should be encouraged to pass it (handled in prompts)
+
+3. **Update `submitImplementation()`** (line 774+):
+   - After `engine.completeClaim()`, auto-broadcast the module's completion summary so sibling agents can query it:
+     ```typescript
+     // Fire-and-forget: broadcast module completion for sibling awareness
+     broadcastHandler({
+       project_id: input.project_id,
+       content: `Module "${input.module}" completed. Files changed: ${(input.files_changed ?? []).join(', ')}. Summary: ${input.summary ?? 'no summary'}`,
+       severity: 'info',
+     }).catch(() => {});
+     ```
+   - This requires access to the broadcast handler — pass it through the factory or import directly
+
+## Module C: Inspector — Interface Compatibility Verification
+
+**Files:** `plugin/agents/inspector.md`, `src/context/injector.ts`
+
+### Changes to inspector.md:
+
+1. **Add new section "### 7. Interface Compatibility Verification"** after the existing section 6 (Security):
+   ```markdown
+   ### 7. Interface Compatibility Verification
+   
+   When multiple agents built modules in parallel, verify interface compatibility:
+   
+   **Cross-Module Interface Checklist:**
+   - [ ] Check `get_broadcasts` for all interface-related broadcasts from implementation agents
+   - [ ] For each producer module: verify exported types/interfaces match what consumer modules import
+   - [ ] For each API endpoint: verify request/response shapes match what frontend components expect
+   - [ ] For each shared component: verify prop interfaces match what consumers pass
+   - [ ] For each database schema: verify Drizzle schema types match what services expect
+   - [ ] Flag any module that was built without checking broadcasts from its dependencies
+   
+   **Process:**
+   1. Call `mcp__dk-forge__get_broadcasts` to get all implementation-phase broadcasts
+   2. Identify producer/consumer pairs from the broadcasts
+   3. For each pair, verify the producer's exported interface matches the consumer's import
+   4. Report mismatches as CRITICAL findings
+   ```
+
+2. **Update Phase 3: Cross-Reference Verification** to include:
+   ```markdown
+   5. Verify interface compatibility across parallel-built modules using broadcast history
+   ```
+
+### Changes to `src/context/injector.ts`:
+
+3. **Update `injectInspectionContext()`** (line 413-448):
+   - Add broadcast history to the inspection context so the Inspector can see what agents communicated:
+     ```typescript
+     const broadcasts = await this.getRecentBroadcasts(projectId, 20);
+     ```
+   - Add to return value: `broadcasts` field
+   - Update `InspectionContext` interface (line 100-111) to include `broadcasts`
+
+## Module D: Specialist Agent Prompts — Mandatory Broadcasting
+
+**Files:** All 4 specialist prompts:
+- `plugin/agents/backend-specialist.md`
+- `plugin/agents/frontend-specialist.md`
+- `plugin/agents/data-specialist.md`
+- `plugin/agents/platform-engineer.md`
+
+### Changes (same pattern for all 4):
+
+1. **Add "## Swarm Coordination Protocol" section** — placed BEFORE "Knowledge & Context Access" to ensure it's seen early. This replaces the vague "Cross-Agent Collaboration" section at the bottom:
+
+   ```markdown
+   ## Swarm Coordination Protocol
+
+   You work as part of a swarm. Other specialists are building modules IN PARALLEL with you right now. You MUST coordinate.
+
+   ### On Startup (MANDATORY — do this BEFORE writing any code):
+   1. Call `mcp__dk-forge__get_broadcasts` with your project_id
+   2. Review ALL broadcasts — especially critical/warning severity
+   3. Check if any broadcast affects your module's interfaces or dependencies
+   4. If a sibling module you depend on has broadcast interface changes, use their broadcast as your source of truth
+
+   ### During Implementation (MANDATORY — broadcast when these happen):
+   - **You create or modify an exported type/interface** → broadcast it with the full type signature
+   - **You create or modify an API endpoint** → broadcast the method, path, request/response shape
+   - **You create or modify a component's prop interface** → broadcast the component name and props
+   - **You create or modify a database schema** → broadcast the table name and column types  
+   - **You discover a blocker** (missing dependency, unresolved interface) → broadcast with severity=critical
+   - **You make a breaking change** to something another module might consume → broadcast with severity=critical
+
+   ### Broadcast Format:
+   Use `mcp__dk-forge__broadcast_finding` with structured content:
+   ```
+   INTERFACE: ComponentName
+   TYPE: export interface ComponentProps { ... }
+   MODULE: my-module-name
+   BREAKING: yes/no
+   ```
+
+   ### Breaking Change Protocol:
+   When you broadcast a breaking change (severity=critical), the Architect will be notified to assess impact. Continue your work — the Architect will coordinate any necessary adaptations across affected modules.
+   ```
+
+2. **Update existing "Cross-Agent Collaboration" section** — replace the weak "Usage:" paragraph with a reference to the Swarm Protocol:
+   ```markdown
+   ## Cross-Agent Collaboration
+   
+   See **Swarm Coordination Protocol** above. Broadcasting is MANDATORY, not optional.
+   ```
+
+## Module E: Architect Prompt — Breaking Change Escalation
+
+**Files:** `plugin/agents/architect.md`
+
+### Changes:
+
+1. **Add "## Breaking Change Escalation" section**:
+   ```markdown
+   ## Breaking Change Escalation
+
+   During implementation, specialists may broadcast critical findings about breaking changes. When reviewing implementation results or when called upon to assess impact:
+
+   1. Call `mcp__dk-forge__get_broadcasts` filtered by severity=critical
+   2. For each breaking change broadcast:
+      - Identify which sibling modules are affected
+      - Assess whether the affected modules can adapt or need to restart
+      - Broadcast your decision back with the resolution approach
+   3. If the breaking change fundamentally conflicts with the architecture, escalate to the user
+   ```
+
+## Dependency Graph
+
+```
+Module A (context injection) ← Module B (phase tools) depends on A's interface changes
+Module C (inspector) — independent
+Module D (specialist prompts) — independent  
+Module E (architect prompt) — independent
+```
+
+Modules C, D, E are pure documentation changes (markdown only). Modules A and B are code changes. A must be done before B.
+
+## What This Does NOT Change
+
+- No new MCP tools — we use `broadcast_finding` and `get_broadcasts` as-is
+- No new database tables or columns — broadcasts already stored in `pipeline_events`
+- No dependency ordering in claims — agents run fully parallel, coordination is via broadcasting
+- No persistent orchestrator loop — broadcasting is agent-initiated
+- No mid-implementation forced checkpoints — Inspector handles convergence at the end
+- State machine transitions unchanged

package/docs/plans/2026-02-27-swarm-coordination/vision.md

@@ -0,0 +1,57 @@
+# Swarm Coordination Activation — Vision
+
+## Problem Statement
+
+The Forge pipeline's swarm infrastructure (broadcasts, observations, memory, collaboration tools) exists but is completely unwired during the implementation phase — the only phase where multiple agents work in parallel and need coordination. Agents build against the baseline codebase independently, producing interface mismatches that are only discovered after all work is done. The broadcast tools exist but no agent calls them, context injection skips broadcasts for implementation, claims have no dependency tracking, and agent prompts treat broadcasting as optional.
+
+## Coordination Model
+
+**Fully parallel + mandatory broadcasting (Option B)**. All specialist agents start simultaneously for maximum parallelism. Agents MUST broadcast interface changes (exported types, prop interfaces, API contracts) as they produce them. Consumer agents check broadcasts before building against any shared interface. This relies on explicit prompt instructions making broadcasting non-optional.
+
+## Interface Contract Granularity
+
+Broadcasts should include whatever level of detail makes most sense for the change — exported type signatures, prop interfaces, API endpoint contracts, schema changes. The system should make it easy for agents to broadcast structured interface data, not just free-text.
+
+## Convergence Checking
+
+Mid-implementation convergence happens at the end via the Inspector. No forced checkpoints during implementation — agents run to completion, Inspector validates interface compatibility across all modules.
+
+## Breaking Change Handling
+
+When Agent A broadcasts a breaking change that affects Agent B, escalate to the Architect. The Architect assesses impact and decides how to proceed (adapt, restart, or accept the mismatch for Inspector to catch).
+
+## User Stories
+
+1. As a specialist agent, when I create or modify a shared interface (exported types, API endpoints, component props), I MUST broadcast the interface contract so sibling agents can build against it.
+2. As a specialist agent, before I consume any shared interface, I MUST check broadcasts to see if a sibling agent has published an updated contract.
+3. As a specialist agent starting implementation, I receive context that includes all existing broadcasts from sibling agents on this project.
+4. As the implementation phase dispatcher, I inject broadcast history and sibling module awareness into each specialist's context.
+5. As the Inspector, I verify interface compatibility across all modules — checking that producer interfaces match consumer expectations, using broadcast history to identify mismatches.
+6. As the Supervisor/Architect, when a specialist broadcasts a breaking change (severity=critical), I am notified and can assess impact on dependent modules.
+7. As a claim in the parallel dispatch system, I track which modules I depend on and which depend on me, enabling the system to detect blocked claims.
+
+## Success Criteria
+
+1. `injectImplementationContext()` includes recent broadcasts and sibling module info in returned context
+2. All specialist agent prompts (backend, frontend, data, platform) contain MANDATORY broadcast instructions — not "can" but "MUST"
+3. Claims track `dependsOn` relationships derived from the architecture plan
+4. Specialist prompts include an "Initialization Checklist" requiring agents to check broadcasts before starting work
+5. Specialist prompts include "Mandatory Broadcast Triggers" — specific events that require broadcasting (interface creation, schema changes, API contract changes, breaking changes)
+6. Inspector checklist includes interface compatibility verification using broadcast history
+7. Breaking changes (severity=critical) trigger escalation to Architect
+8. The `start_implementation` response includes sibling module list with dependency relationships
+
+## Out of Scope (V1)
+
+- Persistent background orchestrator agent (Option C) — too heavy for V1
+- Mid-implementation forced convergence checkpoints — Inspector handles this at the end
+- Automatic agent restart/adaptation on breaking changes — escalate to Architect instead
+- Real-time WebSocket-style broadcast subscriptions — polling via get_broadcasts is sufficient
+- Changes to the state machine or phase transitions (already fixed separately)
+
+## Known Risks
+
+1. Agent discipline — even with MUST language, LLM agents may not reliably call broadcast tools every time. Mitigation: make the prompts extremely explicit with checklists.
+2. Broadcast noise — too many broadcasts could overwhelm agent context. Mitigation: severity levels + recency filtering.
+3. Dependency tracking accuracy — Architect may not declare all dependencies correctly. Mitigation: Inspector catches mismatches at the end.
+4. Token budget — injecting broadcasts + sibling info increases context size. Mitigation: limit broadcast count, summarize older broadcasts.

package/docs/plans/completed/2026-02-26-forge-plugin-bundling/architecture.md

@@ -0,0 +1 @@
+Architecture plan for Forge Plugin Bundling. Covers 6 modules: Tool Rename (25 tools, 7 server files), Plugin Directory Structure (plugin.json + .mcp.json), Agent Migration (13 agents, external MCP refs replaced with forge-native tools), Skill Migration (14 skills, direct copy), Command & Docs (/forge command, workflow.md, README), Build Artifacts (remove dist/ from .gitignore, commit dist/). Full plan at docs/plans/2026-02-26-forge-plugin-bundling/architecture.md

package/docs/plans/completed/2026-02-26-forge-plugin-bundling/vision.md

@@ -0,0 +1,300 @@
+# Vision: Forge Plugin Bundling
+
+**Date**: 2026-02-26
+**Status**: Implemented (plugin bundling complete; rebranded 2026-02-27)
+**Author**: Strategist (on behalf of Adam Reynolds)
+
+> **Note (2026-02-27):** This vision was implemented. The project was subsequently rebranded from `forge-pipeline-server` / `mcp__forge__*` to `dk-forge-server` / `mcp__dk-forge__*`. References below reflect the original naming at time of writing. See project CLAUDE.md for current naming convention.
+
+## Problem Statement
+
+The Forge agent pipeline currently exists as two disconnected pieces: a forge-pipeline-server MCP server (TypeScript, distributed as a package) and a collection of 12 agent prompts, 14+ skills, and orchestration documentation that live in Adam's personal `~/.claude/` directory. Anyone who installs the forge-pipeline-server MCP server gets the tools (pipeline phases, knowledge search, codebase context) but NOT the agents, skills, or workflow documentation that make those tools useful.
+
+This means:
+1. **No one else can use Forge.** Another developer installing the MCP server would have `forge_create_project` and `forge_start_interview` tools available, but no agent system prompt telling Claude when or how to use them. The tools are inert without the orchestration layer.
+2. **Version drift between agents and server.** The personal `~/.claude/agents/` directory has already diverged from the early `~/.claude/plugins/forge/agents/` directory -- the personal versions reference the Supervisor agent and dynamic routing, while the plugin versions still describe the older linear handoff model.
+3. **Manual sync is fragile.** When Adam updates an agent prompt (e.g., adding MCP tool references, changing the workflow), those changes stay local. The existing plugin copy was a manual snapshot that immediately went stale.
+4. **No single source of truth.** Agent prompts reference MCP tools by name (e.g., `mcp__forge-pipeline__forge_create_project`), but there is no mechanism to validate that the tools referenced in prompts actually exist in the server, or that the server's tools are documented in the agent prompts.
+
+The Claude Code plugin system provides exactly the distribution mechanism needed: a `.claude-plugin/plugin.json` manifest, auto-discovered `agents/`, `skills/`, `commands/`, `hooks/` directories, and critically, a `.mcp.json` file that can auto-start the forge-pipeline-server when the plugin is enabled.
+
+## Goals
+
+- Bundle all forge agents, skills, workflow docs, and MCP server configuration into a single distributable Claude Code plugin that lives inside the forge-pipeline-server repository.
+- Make the plugin the single source of truth for agent prompts and skills -- the personal `~/.claude/agents/` and `~/.claude/skills/` directories should no longer contain forge-specific content.
+- Auto-start the forge-pipeline-server MCP server when the plugin is enabled, using the `.mcp.json` mechanism with `${CLAUDE_PLUGIN_ROOT}` for portable path references.
+- Include the Supervisor agent (currently only in personal `~/.claude/agents/supervisor.md`, missing from the existing plugin).
+- Include a `/forge` slash command that serves as the entry point for new users.
+- Ensure agents reference the correct MCP tool names (prefixed as `mcp__forge-pipeline__*`) and that the tool references in agent prompts match the actual tools registered by the server.
+- Separate personal/user-specific content (NestJS stack preferences, Synapse naming conventions, IaC repo paths, gotchas learned) from the distributable forge workflow content.
+- Support both local development installation (`isLocal: true` pointing at the repo) and future marketplace/npm distribution.
+
+## Non-Goals (Explicitly Out of Scope)
+
+- **Publishing to a marketplace.** This iteration produces a plugin that works as a local install or git-based install. Marketplace packaging (registry metadata, review process, listing) is a future iteration.
+- **Rewriting agent prompts.** The existing agent prompts are mature and battle-tested. This iteration moves them into the plugin structure and updates tool references to use the correct MCP prefix. It does NOT rewrite the agent system prompts from scratch.
+- **Hooks for pipeline enforcement.** While the plugin system supports hooks (e.g., a `PreToolUse` hook that checks whether a pipeline project exists before allowing code writes), designing and implementing enforcement hooks is a future iteration. This iteration focuses on distribution.
+- **Automated testing of agent prompts.** Validating that agent prompts correctly reference available MCP tools could be automated, but building that test infrastructure is out of scope. Manual verification during this iteration.
+- **Multi-user concurrent pipeline support.** The forge-pipeline-server stores state in a per-user SQLite database. Multi-user or team-shared pipeline state is out of scope.
+- **Docker Compose / infrastructure bundling.** The forge server depends on Qdrant and FalkorDB for full functionality. Bundling docker-compose configs or helm charts for these dependencies is out of scope -- users must set up the backing services themselves.
+
+## Success Criteria
+
+- A developer who runs `claude plugins install --local /path/to/forge-pipeline-server/plugin` (or equivalent git-based install) gets:
+  - All 12 agents loaded and available for dispatch (strategist, architect, supervisor, product-manager, designer, qa-strategist, backend-specialist, frontend-specialist, data-specialist, platform-engineer, inspector, knowledge-keeper).
+  - All 14 forge-specific skills loaded and invocable (interviewing, terminal-presentation, project-discovery, implementation-execution, verification-protocol, test-strategy, parallel-dispatch, agent-handoff, knowledge-curation, tdd, debugging, anti-stub, security-audit, graph-orchestrator).
+  - The forge-pipeline-server MCP server auto-started and its tools (forge_create_project, forge_start_interview, forge_submit_vision, etc.) available without manual MCP configuration.
+  - A `/forge` command that explains the workflow and starts a new pipeline.
+- The plugin works on Windows, macOS, and Linux (portable paths via `${CLAUDE_PLUGIN_ROOT}`).
+- The forge-pipeline-server repository is the single source of truth -- no forge-specific agent or skill content remains in Adam's personal `~/.claude/agents/` or `~/.claude/skills/` directories after migration.
+- The personal `~/.claude/CLAUDE.md` retains user-specific preferences (stack, naming conventions, gotchas) that are NOT part of the distributable plugin.
+
+## What Moves vs. What Stays
+
+### Moves INTO the Plugin (distributable)
+
+| Content | Source Location | Plugin Location |
+|---------|----------------|-----------------|
+| 12 agent prompts | `~/.claude/agents/*.md` | `plugin/agents/*.md` |
+| Supervisor agent | `~/.claude/agents/supervisor.md` | `plugin/agents/supervisor.md` |
+| 14 forge-specific skills | `~/.claude/skills/{name}/SKILL.md` | `plugin/skills/{name}/SKILL.md` |
+| Workflow documentation | `~/.claude/plugins/forge/docs/workflow.md` | `plugin/docs/workflow.md` |
+| Plugin manifest | `~/.claude/plugins/forge/.claude-plugin/plugin.json` | `plugin/.claude-plugin/plugin.json` |
+| README | `~/.claude/plugins/forge/README.md` | `plugin/README.md` |
+| MCP server config | (new) | `plugin/.mcp.json` |
+| Forge command | (new) | `plugin/commands/forge.md` |
+
+### Stays PERSONAL (not distributed)
+
+| Content | Location | Reason |
+|---------|----------|--------|
+| NestJS + Drizzle preferences | `~/.claude/CLAUDE.md` | Stack-specific, not forge-generic |
+| Synapse naming conventions | `~/.claude/CLAUDE.md` | Project-specific |
+| IaC repo paths | `~/.claude/CLAUDE.md` | User-specific local paths |
+| Gotchas learned | `~/.claude/CLAUDE.md` | Personal institutional memory |
+| Non-forge skills (nestjs, frontend-design, visual-explainer, etc.) | `~/.claude/skills/` | General-purpose, not forge-specific |
+| .claude-flow daemon state | `~/.claude/.claude-flow/` | Runtime state |
+| .swarm memory | `~/.claude/.swarm/` | Runtime state |
+| Session history | `~/.claude/history.jsonl` | Personal |
+
+### Skills Classification
+
+**Forge-specific (move to plugin):**
+- interviewing
+- terminal-presentation
+- project-discovery
+- implementation-execution
+- verification-protocol
+- test-strategy
+- parallel-dispatch
+- agent-handoff
+- knowledge-curation
+- tdd
+- debugging
+- anti-stub
+- security-audit
+- graph-orchestrator
+
+**Personal / general-purpose (stay in `~/.claude/skills/`):**
+- nestjs (stack-specific)
+- frontend-design (general)
+- visual-explainer (general, third-party)
+- agent-development (meta, for creating agents)
+- skill-development (meta, for creating skills)
+- mcp-integration (meta)
+- analyzing-financial-statements (domain-specific)
+- applying-brand-guidelines (domain-specific)
+- creating-financial-models (domain-specific)
+- writing-rules (general)
+- optimize-claude-md (meta)
+- record-claude-md (meta)
+- self-improving-agent (meta)
+- fix (general)
+- vector-memory (deprecated, replaced by forge MCP server)
+
+## Plugin Directory Structure
+
+```
+forge-pipeline-server/
+  src/                          # MCP server source (existing)
+  dist/                         # Compiled MCP server (existing)
+  plugin/                       # Claude Code plugin root
+    .claude-plugin/
+      plugin.json               # Plugin manifest
+    .mcp.json                   # Auto-start forge MCP server
+    agents/
+      strategist.md
+      architect.md
+      supervisor.md
+      product-manager.md
+      designer.md
+      qa-strategist.md
+      backend-specialist.md
+      frontend-specialist.md
+      data-specialist.md
+      platform-engineer.md
+      inspector.md
+      knowledge-keeper.md
+    skills/
+      interviewing/
+        SKILL.md
+      terminal-presentation/
+        SKILL.md
+      project-discovery/
+        SKILL.md
+      implementation-execution/
+        SKILL.md
+      verification-protocol/
+        SKILL.md
+      test-strategy/
+        SKILL.md
+      parallel-dispatch/
+        SKILL.md
+      agent-handoff/
+        SKILL.md
+      knowledge-curation/
+        SKILL.md
+      tdd/
+        SKILL.md
+      debugging/
+        SKILL.md
+      anti-stub/
+        SKILL.md
+      security-audit/
+        SKILL.md
+      graph-orchestrator/
+        SKILL.md
+    commands/
+      forge.md                  # /forge entry point command
+    docs/
+      workflow.md               # Full orchestration documentation
+    README.md                   # Plugin overview and installation guide
+```
+
+## MCP Server Auto-Start Configuration
+
+The `.mcp.json` at plugin root will auto-start the forge-pipeline-server:
+
+```json
+{
+  "forge": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/../dist/index.js"],
+    "env": {
+      "QDRANT_URL": "${QDRANT_URL}",
+      "FALKORDB_HOST": "${FALKORDB_HOST}",
+      "FALKORDB_PORT": "${FALKORDB_PORT}",
+      "FORGE_DB_PATH": "${FORGE_DB_PATH}"
+    }
+  }
+}
+```
+
+The `${CLAUDE_PLUGIN_ROOT}` resolves to the `plugin/` directory, so `../dist/index.js` reaches the compiled server. Environment variables with `${}` fallback to the user's shell environment or the server's internal defaults (e.g., Qdrant defaults to `localhost:6333`).
+
+**Key design decision**: The plugin directory is a subdirectory of the server repo (`forge-pipeline-server/plugin/`), NOT a separate repo. This keeps agent prompts, server code, and tool registrations in the same repository, enabling atomic changes when a new tool requires a new agent prompt update.
+
+## How Agents Reference MCP Tools
+
+When the forge MCP server is started via the plugin's `.mcp.json` with server name `forge`, Claude Code exposes its tools with the prefix `mcp__forge__`. Tool method names drop the `forge_` prefix to avoid double-forge. Agent prompts reference tools like:
+
+- `mcp__forge__create_project`
+- `mcp__forge__start_interview`
+- `mcp__forge__submit_vision`
+- `mcp__forge__start_architecture`
+- `mcp__forge__submit_plan`
+- `mcp__forge__start_implementation`
+- `mcp__forge__submit_implementation`
+- `mcp__forge__start_inspection`
+- `mcp__forge__submit_verdict`
+- `mcp__forge__collect_knowledge`
+- `mcp__forge__search_knowledge`
+- `mcp__forge__get_codebase_context`
+- `mcp__forge__register`
+- `mcp__forge__get_state`
+
+Each agent prompt must include a "## MCP Tools" section listing the specific tools that agent uses, with brief descriptions. This serves as both documentation and a prompt-level contract.
+
+**Tool naming note**: The server name in `.mcp.json` is `forge`, producing the prefix `mcp__forge__`. Tool method names are short (e.g. `create_project` not `forge_create_project`). This must be consistent across all agent prompts and the server's tool registrations.
+
+## User Stories
+
+- **As a developer installing Forge for the first time**, I want to install one plugin and have the full agent pipeline working immediately, so that I do not need to manually copy agent files, configure MCP servers, or understand the internal structure.
+
+- **As Adam migrating from the personal setup**, I want to delete forge-specific agents and skills from my `~/.claude/` directories and point to the plugin in the forge-pipeline-server repo, so that I have a single source of truth and can contribute improvements back to the repo.
+
+- **As a developer starting a new project with Forge**, I want to type `/forge` and be guided through the Strategist interview, so that I do not need to know which agent to invoke or what the pipeline phases are.
+
+- **As a developer resuming a Forge project**, I want the agents to call `forge_get_state` and pick up where I left off, so that session interruptions do not lose progress.
+
+- **As a contributor to the forge-pipeline-server**, I want to update an agent prompt and the MCP server code in the same commit, so that tool changes and prompt changes stay in sync.
+
+## Constraints
+
+- **Claude Code plugin format is the constraint.** The plugin must follow the exact directory structure: `.claude-plugin/plugin.json` at root, `agents/` with `.md` files, `skills/` with subdirectories containing `SKILL.md`, `commands/` with `.md` files, `.mcp.json` at root.
+- **The MCP server must be pre-built.** The `.mcp.json` uses `node dist/index.js`, meaning the TypeScript must be compiled before the plugin works. This is acceptable for local dev (run `npm run build`), but will need consideration for distribution.
+- **Environment variables for backing services.** The forge server gracefully degrades without Qdrant/FalkorDB, but full functionality requires them. The plugin cannot bundle these services -- they must be externally available.
+- **Tool name prefix is determined by .mcp.json server name.** If the server name in `.mcp.json` is `forge-pipeline`, all tool references in agent prompts must use `mcp__forge-pipeline__` prefix. Changing this name would require updating every agent prompt.
+- **Windows path compatibility.** The `${CLAUDE_PLUGIN_ROOT}/../dist/index.js` path traversal must work on Windows. Claude Code handles `${CLAUDE_PLUGIN_ROOT}` expansion, and Node.js resolves forward slashes on Windows, so this should work.
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| `${CLAUDE_PLUGIN_ROOT}/../dist/` path traversal may not work in plugin sandbox | Medium | High | Test on all three platforms. If blocked, move plugin to repo root instead of subdirectory, or use a wrapper script. |
+| MCP tool prefix changes if server name in .mcp.json changes | Low | High | Document the naming contract prominently. Add a build-time check that agent prompts reference valid tool names. |
+| Agent prompts reference tools from OTHER MCP servers (e.g., `mcp__ruflo__memory_search`) that users may not have | High | Medium | Document optional MCP server dependencies in README. Make agent prompts gracefully handle missing tools by using conditional language ("if available, use..."). |
+| Plugin auto-discovery loads stale agents from both plugin and personal `~/.claude/agents/` | Medium | Medium | Migration guide instructs users to remove forge agents from personal directory. Agent `name` field prevents duplicates (Claude Code deduplicates by name). |
+| forge-pipeline-server `dist/` not built when plugin is first enabled | High | High | Add `postinstall` or `prepare` script. Document that `npm run build` is required. Consider pre-building in CI. |
+| Large prompt sizes (some agents are 15-18KB) may hit context limits when multiple agents are loaded | Low | Medium | Claude Code loads agent prompts on-demand, not all at once. Monitor and trim if needed. |
+
+## Open Questions — RESOLVED
+
+All open questions have been resolved by the user:
+
+1. **Plugin root**: `plugin/` subdirectory. Keeps plugin cleanly separated from server source.
+2. **Build step**: Commit `dist/` to git. Works immediately after clone, no build step needed.
+3. **External MCP refs**: Remove all external MCP references (ruflo, vexp). Agents only reference forge tools. Other integrations are additive, documented separately.
+4. **Tool prefix**: Server name is `forge` (not `forge-pipeline`). Tool METHOD names drop the `forge_` prefix to avoid double-forge. e.g. `create_project` not `forge_create_project`, yielding `mcp__forge__create_project`.
+
+### Tool Rename Map
+
+| Old Name | New Name | MCP Full Name |
+|----------|----------|---------------|
+| `forge.register` | `register` | `mcp__forge__register` |
+| `forge.init` | `init` | `mcp__forge__init` |
+| `forge.list_repos` | `list_repos` | `mcp__forge__list_repos` |
+| `forge.get_manifest` | `get_manifest` | `mcp__forge__get_manifest` |
+| `forge.index_repo` | `index_repo` | `mcp__forge__index_repo` |
+| `forge_create_project` | `create_project` | `mcp__forge__create_project` |
+| `forge_get_state` | `get_state` | `mcp__forge__get_state` |
+| `forge_start_interview` | `start_interview` | `mcp__forge__start_interview` |
+| `forge_submit_vision` | `submit_vision` | `mcp__forge__submit_vision` |
+| `forge_start_architecture` | `start_architecture` | `mcp__forge__start_architecture` |
+| `forge_submit_plan` | `submit_plan` | `mcp__forge__submit_plan` |
+| `forge_start_design` | `start_design` | `mcp__forge__start_design` |
+| `forge_submit_design` | `submit_design` | `mcp__forge__submit_design` |
+| `forge_start_qa_strategy` | `start_qa_strategy` | `mcp__forge__start_qa_strategy` |
+| `forge_submit_test_plan` | `submit_test_plan` | `mcp__forge__submit_test_plan` |
+| `forge_start_implementation` | `start_implementation` | `mcp__forge__start_implementation` |
+| `forge_submit_implementation` | `submit_implementation` | `mcp__forge__submit_implementation` |
+| `forge_start_inspection` | `start_inspection` | `mcp__forge__start_inspection` |
+| `forge_submit_verdict` | `submit_verdict` | `mcp__forge__submit_verdict` |
+| `forge_collect_knowledge` | `collect_knowledge` | `mcp__forge__collect_knowledge` |
+| `forge_search_knowledge` | `search_knowledge` | `mcp__forge__search_knowledge` |
+| `forge_get_codebase_context` | `get_codebase_context` | `mcp__forge__get_codebase_context` |
+| `forge_get_project_history` | `get_project_history` | `mcp__forge__get_project_history` |
+| `forge_get_patterns` | `get_patterns` | `mcp__forge__get_patterns` |
+| `forge_get_gotchas` | `get_gotchas` | `mcp__forge__get_gotchas` |
+
+## Decision Log
+
+| Date | Decision | Rationale | Decided By |
+|------|----------|-----------|------------|
+| 2026-02-26 | Plugin lives in `plugin/` subdirectory of forge-pipeline-server repo | Keeps plugin content separate from server source while enabling atomic commits. Single repo = single source of truth. | Strategist |
+| 2026-02-26 | Use latest agent prompts from `~/.claude/agents/` (with Supervisor), not the stale plugin copy | The personal agents have been updated to reference the Supervisor and dynamic routing. The existing plugin copy is outdated. | Strategist |
+| 2026-02-26 | graph-orchestrator skill included in plugin | Referenced by Supervisor agent for workflow graph execution. Part of the forge orchestration system. | Strategist |
+| 2026-02-26 | vector-memory skill excluded from plugin | Deprecated in favor of the forge-pipeline-server's native Qdrant-based vector search. Supervisor agent prompt already marks it as deprecated. | Strategist |
+| 2026-02-26 | Commit dist/ to git | Works immediately after clone with no build step. Slight repo size increase is acceptable for frictionless onboarding. | User |
+| 2026-02-26 | Remove all external MCP references from agents | Agents only reference forge tools. Other integrations (ruflo, vexp) are additive and documented separately. Clean slate for new users. | User |
+| 2026-02-26 | Server name is `forge`, tool methods drop `forge_` prefix | Avoids double-forge in full MCP names. `mcp__forge__create_project` is cleaner than `mcp__forge__forge_create_project`. Requires renaming all tool registrations in server code. | User |