forge-server 0.1.0 → 0.1.1

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

@@ -1,300 +0,0 @@
-# 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 |