forge-server 0.1.0

package/.claude/hooks/worktree-create.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# WorktreeCreate hook for Claude Code agent isolation.
+# Receives JSON on stdin with a "name" field.
+# Must print the absolute path to the created worktree on stdout.
+# All other output must go to stderr to avoid corrupting the path.
+#
+# This hook is necessary because Claude Code's internal git repo detection
+# can fail on Windows (reports "not in a git repository" even when .git exists
+# and git commands work). By providing explicit WorktreeCreate/WorktreeRemove
+# hooks, we bypass the detection issue entirely.
+
+set -euo pipefail
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract fields using node (jq is not available on all Windows systems)
+NAME=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).name||'')}catch(e){console.log('')}})")
+CWD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).cwd||'')}catch(e){console.log('')}})")
+
+if [ -z "$NAME" ]; then
+  echo "Error: no 'name' field in WorktreeCreate input" >&2
+  exit 1
+fi
+
+if [ -z "$CWD" ]; then
+  CWD="$(pwd)"
+fi
+
+# Resolve the git toplevel from the cwd
+REPO_ROOT=$(cd "$CWD" && git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO_ROOT" ]; then
+  echo "Error: could not find git repo root from cwd=$CWD" >&2
+  exit 1
+fi
+
+# Create the worktree directory under .claude/worktrees/
+WORKTREE_DIR="$REPO_ROOT/.claude/worktrees/$NAME"
+
+# Create a new branch for this worktree based on HEAD
+BRANCH_NAME="worktree/$NAME"
+
+# Clean up any stale worktree or branch with the same name
+if [ -d "$WORKTREE_DIR" ]; then
+  echo "Cleaning up stale worktree at $WORKTREE_DIR" >&2
+  cd "$REPO_ROOT"
+  git worktree remove --force "$WORKTREE_DIR" 2>/dev/null || rm -rf "$WORKTREE_DIR"
+fi
+
+# Remove stale branch if it exists (from a previous failed run)
+cd "$REPO_ROOT"
+if git rev-parse --verify "$BRANCH_NAME" >/dev/null 2>&1; then
+  git branch -D "$BRANCH_NAME" >&2 2>/dev/null || true
+fi
+
+# Prune stale worktree entries
+git worktree prune >&2 2>/dev/null || true
+
+# Create the worktree with a new branch
+echo "Creating worktree: $WORKTREE_DIR (branch: $BRANCH_NAME)" >&2
+git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" HEAD >&2
+
+# Print the absolute path to stdout (this is what Claude Code reads)
+echo "$WORKTREE_DIR"

package/.claude/hooks/worktree-remove.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# WorktreeRemove hook for Claude Code agent isolation.
+# Receives JSON on stdin with a "worktree_path" field (the path that
+# WorktreeCreate printed on stdout).
+# No output is required. Failures are logged in debug mode only.
+
+set -euo pipefail
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract fields using node (jq is not available on all Windows systems)
+WORKTREE_PATH=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).worktree_path||'')}catch(e){console.log('')}})")
+CWD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).cwd||'')}catch(e){console.log('')}})")
+
+if [ -z "$WORKTREE_PATH" ]; then
+  echo "Warning: no 'worktree_path' in WorktreeRemove input" >&2
+  exit 0
+fi
+
+# Check if the worktree directory exists
+if [ ! -d "$WORKTREE_PATH" ]; then
+  echo "Worktree directory does not exist, nothing to remove: $WORKTREE_PATH" >&2
+  exit 0
+fi
+
+# Extract the worktree name from the path to derive the branch name
+NAME=$(basename "$WORKTREE_PATH")
+BRANCH_NAME="worktree/$NAME"
+
+# Find the main repo root from cwd or by walking up from worktree path
+if [ -n "$CWD" ]; then
+  REPO_ROOT=$(cd "$CWD" && git rev-parse --show-toplevel 2>/dev/null || echo "$CWD")
+else
+  # Worktree is at REPO_ROOT/.claude/worktrees/NAME
+  REPO_ROOT=$(dirname "$(dirname "$(dirname "$WORKTREE_PATH")")")
+fi
+
+echo "Removing worktree: $WORKTREE_PATH" >&2
+
+# Remove the worktree using git
+cd "$REPO_ROOT" 2>/dev/null || true
+git worktree remove --force "$WORKTREE_PATH" 2>&2 || {
+  echo "git worktree remove failed, falling back to rm -rf" >&2
+  rm -rf "$WORKTREE_PATH"
+}
+
+# Prune stale worktree entries
+git worktree prune 2>&2 || true
+
+# Clean up the branch
+if git rev-parse --verify "$BRANCH_NAME" >/dev/null 2>&1; then
+  echo "Removing branch: $BRANCH_NAME" >&2
+  git branch -D "$BRANCH_NAME" 2>&2 || true
+fi
+
+echo "Worktree removed successfully: $WORKTREE_PATH" >&2

package/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cp:*)"
+    ]
+  },
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/worktree-create.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/worktree-remove.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.forge/knowledge/conventions.yaml

@@ -0,0 +1 @@
+[]

package/.forge/knowledge/decisions.yaml

@@ -0,0 +1 @@
+[]

package/.forge/knowledge/gotchas.yaml

@@ -0,0 +1 @@
+[]

package/.forge/knowledge/patterns.yaml

@@ -0,0 +1 @@
+[]

package/.forge/manifest.yaml

@@ -0,0 +1,6 @@
+name: dk-forge-server
+stack:
+  - typescript
+  - node
+sharing: public
+repo_id_override: null

package/CLAUDE.md

@@ -0,0 +1,144 @@
+# dominKnow | Forge — dk-forge-server
+
+## Identity
+
+| Context | Value |
+|---------|-------|
+| Display | dominKnow \| Forge |
+| Kebab/Package | dk-forge-server |
+| MCP server name | dk-forge |
+| MCP tool prefix | mcp\_\_dk-forge\_\_* |
+| Chunk marker | [dk-forge] |
+| Plugin name | dk-forge |
+| CLI binary | forge |
+| DB path | ~/.forge/pipeline.db |
+
+## Architecture
+
+- **MCP server** (TypeScript, ESM) — 34 MCP tools: pipeline, knowledge, context, memory, graph, collaboration, ingestion, git context
+- **2-way query engine**: agents pull context (semantic search, impact graphs, git hotspots) AND push learnings back (observations, broadcasts, confidence boosts)
+- **Claude Code plugin** (`plugin/`) — 16 agents, 20+ skills, /forge and /brainstorm commands, auto-starts MCP server
+- **VS Code extension** (`vscode-extension/`) — forge-lsp-bridge, feeds type-resolved call/reference edges from TS language server into forge graph
+- **Atlassian integration** (optional, plugin-level) — mcp-atlassian server declared in `.mcp.json`, 7 agent prompts have optional Jira context sections
+- **5-signal scoring**: vector similarity + graph centrality + recency decay + hotspot frequency + observation count (intent-dependent weights)
+- **Storage**: SQLite (pipeline state), Qdrant (vectors + git_commits), FalkorDB (graph, optional)
+- Server entry: `src/server.ts` → `SERVER_NAME = 'dk-forge'`
+- Plugin MCP config: `plugin/.mcp.json` → key `"dk-forge"`
+- Plugin metadata: `plugin/.claude-plugin/plugin.json` → name `"dk-forge"`
+
+## Key Directories
+
+- `src/pipeline/` — Pipeline engine and state machine
+- `src/tools/` — MCP tool handlers (registration, pipeline, knowledge, context, memory, graph, collaboration, ingestion)
+- `src/knowledge/` — Knowledge base (registry, search, hydration)
+- `src/ingestion/` — Indexing, chunking, embedding
+- `src/storage/` — Qdrant, FalkorDB, SQLite, file cache
+- `plugin/agents/` — 16 specialized agent prompts (see Agent Roster below)
+- `plugin/skills/` — 20+ forge-specific skills
+- `plugin/commands/` — /forge and /brainstorm slash commands
+- `plugin/docs/` — Workflow documentation
+- `vscode-extension/` — forge-lsp-bridge VS Code extension (LSP edge ingestion)
+- `docs/plans/` — Plan documents (active plans at root, archived in `completed/`)
+
+## Tool Categories (34 total)
+
+| Category | Tools | File |
+|----------|-------|------|
+| Registration | register, init, list_repos, get_manifest, index_repo, get_index_status | registration-tools.ts |
+| Pipeline | create_project, get_state, start_*/submit_* phase tools | pipeline-tools.ts, phase-tools.ts |
+| Knowledge | search_knowledge, get_patterns, get_gotchas | learning-tools.ts |
+| Context | get_codebase_context, get_git_context | context-tools.ts |
+| Memory | save_observation, search_memory, get_session_context | memory-tools.ts |
+| Graph | get_impact_graph, search_logic_flow | graph-tools.ts |
+| Collaboration | broadcast_finding, get_broadcasts | collaboration-tools.ts |
+| Ingestion | submit_lsp_edges | ingestion-tools.ts |
+| Confidence | boost_knowledge, decay_knowledge | learning-tools.ts |
+
+## Tool Routing — MANDATORY for Indexed Repos
+
+When working in a repo that has been registered and indexed with Forge (`register` + `index_repo`), **ALWAYS prefer Forge tools over built-in Claude Code tools**:
+
+| Instead of... | Use Forge tool | Why |
+|---------------|---------------|-----|
+| `Grep` / `Glob` for code search | `get_codebase_context` | 5-signal ranked results (vector + graph + recency + hotspot + observations) vs raw text match |
+| `Grep` for "who uses X" | `get_impact_graph` | Traverses actual call/import graph, not just string occurrences |
+| `git log` for history | `get_git_context` | Semantic search over commit messages, hotspot analysis, file change velocity |
+| Searching CLAUDE.md for past learnings | `search_memory` | Searches all persisted observations across sessions with vector similarity |
+| Guessing at patterns | `get_patterns` / `get_gotchas` | Curated, confidence-scored knowledge from past pipeline runs |
+| Ad-hoc file reading for context | `search_knowledge` | Searches curated knowledge items (gotchas, patterns, decisions, conventions) |
+
+**When to still use built-in tools**: Reading a specific known file path (`Read`), writing/editing files (`Edit`/`Write`), running shell commands (`Bash`), or when the repo is NOT indexed.
+
+## Agent Roster (16 agents)
+
+| Agent | Role | Model | Phase |
+|-------|------|-------|-------|
+| brainstormer | Pre-pipeline creative exploration | opus | Pre-pipeline |
+| strategist | Vision holder, user advocate | opus | Interview |
+| product-manager | Structured requirements | sonnet | Requirements |
+| architect | System design, tech decisions | opus | Architecture |
+| designer | XD/UX, design system, component contracts | opus | Design |
+| qa-strategist | Test plan, Playwright E2E strategy | sonnet | QA Strategy |
+| backend-specialist | NestJS modules, API implementation | sonnet | Implementation |
+| frontend-specialist | React/MUI UI implementation | sonnet | Implementation |
+| data-specialist | Schema, migrations, seed data | sonnet | Implementation |
+| platform-engineer | IaC, CI/CD, Docker, K8s | sonnet | Implementation |
+| inspector | Code verification, anti-stub, security | opus | Inspection |
+| product-owner | Run product (curl + Playwright), generate tests | sonnet | Acceptance |
+| pulse-checker | Lightweight drift detection | haiku | Advisory checkpoint |
+| supervisor | Dynamic orchestration, routing | sonnet | All phases |
+| knowledge-keeper | Persist project learnings to CLAUDE.md / docs | sonnet | Exit debrief + on-demand |
+| self-improver | Introspect and improve Forge itself | opus | Exit debrief + on-demand |
+
+## Mesh Intelligence Architecture (2026-02-28)
+
+The pipeline operates as a **mesh intelligence system**, not a linear conveyor belt:
+
+- **Advisory Context Injection**: Vision/architecture/design summaries auto-injected into every downstream phase via `src/context/injector.ts`
+- **Tiered Advisory Checkpoints**: Haiku pulse check (cheap) → Full Opus review (only on drift). Managed by Supervisor.
+- **Consult Protocol**: Specialists broadcast with `target_agents` when hitting decisions outside their authority
+- **Auto Knowledge Extraction**: Server-side regex in `src/tools/phase-tools.ts` extracts gotchas/patterns/decisions from phase outputs — zero LLM tokens
+- **Session Context Index**: `src/context/session-index.ts` — virtual memory for LLM context, offloads to Qdrant via session-scoped semantic search
+- **Code-Over-Prose Protocol**: All agents use TypeScript interfaces instead of prose descriptions (55-87% token reduction)
+- **Collaborative Exit Debrief**: After Product Owner acceptance testing, 6 agents review in parallel: 4 advisory agents (Strategist, Architect, Designer, QA Strategist) + Knowledge Keeper (project learnings) + Self-Improver (Forge system learnings)
+- **Self-Improvement Loop**: Knowledge Keeper detects recurring patterns → triggers Self-Improver → Self-Improver modifies agent prompts, writes skills, proposes pipeline changes → Forge gets smarter over time
+
+### Full Pipeline Flow
+
+```
+Brainstormer (optional) → Strategist → Architect + Designer (parallel)
+  → QA Strategist → Implementation Specialists (parallel)
+  → Advisory Checkpoint (pulse check) → Inspector
+  → Product Owner (acceptance testing)
+  → Collaborative Exit Debrief (6 agents parallel:
+      Strategist + Architect + Designer + QA Strategist
+      + Knowledge Keeper + Self-Improver)
+```
+
+## Parallel Dispatch — MANDATORY for Pipeline
+
+When the Forge pipeline reaches implementation phase with multiple modules:
+1. **Dispatch ALL specialist agents simultaneously** using parallel `Task` tool calls in a single message
+2. **Never serialize independent modules** — if modules A, B, C have no dependencies, launch all 3 at once
+3. **Architect + Designer run in parallel** — they are parallel phase pairs, dispatch both simultaneously
+4. After parallel agents complete, merge results, then dispatch Inspector
+5. After Inspector passes, dispatch Product Owner for acceptance testing
+6. After Product Owner completes, dispatch all 6 exit debrief agents in parallel (4 advisors + Knowledge Keeper + Self-Improver)
+
+## Rebrand History
+
+- **2026-02-27**: Renamed from `forge-pipeline-server` / `mcp__forge__*` to `dk-forge-server` / `mcp__dk-forge__*`. See `docs/plans/completed/` for historical docs that still reference old names.
+
+## Build
+
+```bash
+npm run build   # tsc → dist/
+npm run dev     # tsx watch
+npm test        # vitest
+```
+
+`dist/` is committed to git for zero-build plugin install.
+
+## Worktree Hooks (Windows)
+
+Claude Code's git repo detection fails on Windows for freshly-initialized repos, breaking `isolation: worktree`. Fix: add WorktreeCreate/WorktreeRemove hooks in `.claude/settings.local.json` pointing to `.claude/hooks/worktree-create.sh` and `.claude/hooks/worktree-remove.sh`. Restart session after adding hooks. Use `general-purpose` agent type to bypass auto-worktree when needed.

package/bin/setup-forge.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# dominKnow | Forge — Plugin Setup
+#
+# 1. Copies plugin files (markdown) to ~/.claude/plugins/forge/
+# 2. Installs MCP server (npm global or local fallback)
+#
+# Works on macOS, Linux, and Windows (Git Bash / MSYS2).
+#
+# Usage:  ./bin/setup-forge.sh          # install or update
+#         ./bin/setup-forge.sh --remove  # uninstall
+# ──────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+PLUGIN_SRC="$REPO_DIR/plugin"
+INSTALL_DIR="$HOME/.claude/plugins/forge"
+PKG_NAME="dk-forge-server"
+
+# ── Preflight ────────────────────────────────────────────────
+
+if ! command -v node &>/dev/null; then
+  echo "ERROR: Node.js is required but not installed."
+  echo ""
+  echo "Install Node.js:"
+  echo "  macOS:   brew install node"
+  echo "  Linux:   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - && sudo apt install -y nodejs"
+  echo "  Windows: https://nodejs.org/en/download"
+  echo ""
+  echo "Then re-run this script."
+  exit 1
+fi
+
+if ! command -v npm &>/dev/null; then
+  echo "ERROR: npm is required but not installed."
+  echo "npm comes with Node.js — reinstall Node.js from https://nodejs.org"
+  exit 1
+fi
+
+# ── Helpers ──────────────────────────────────────────────────
+
+remove_dir() {
+  local dir="$1"
+  if [[ -L "$dir" ]] || [[ -d "$dir" ]]; then
+    rm -rf "$dir" 2>/dev/null || {
+      if command -v cmd.exe &>/dev/null; then
+        cmd.exe /c "rmdir /s /q \"$(cygpath -w "$dir")\"" 2>/dev/null || true
+      fi
+    }
+  fi
+}
+
+# ── Uninstall ────────────────────────────────────────────────
+
+if [[ "${1:-}" == "--remove" ]]; then
+  echo "Removing Forge plugin..."
+  remove_dir "$INSTALL_DIR"
+  npm uninstall -g "$PKG_NAME" 2>/dev/null || true
+  echo "Done. Restart Claude Code."
+  exit 0
+fi
+
+# ── Install / Update ─────────────────────────────────────────
+
+echo "Installing Forge plugin..."
+
+# 1. Copy plugin files (agents, skills, commands — all markdown)
+mkdir -p "$HOME/.claude/plugins"
+remove_dir "$INSTALL_DIR"
+cp -r "$PLUGIN_SRC" "$INSTALL_DIR"
+echo "  Plugin files copied"
+
+# 2. Install MCP server
+echo "  Installing MCP server..."
+if npm view "$PKG_NAME" version &>/dev/null; then
+  # Published on npm — install from registry
+  npm install -g "$PKG_NAME" 2>&1 | tail -1
+  echo "  Installed $PKG_NAME from npm"
+else
+  # Not on npm yet — install from local repo
+  if [[ -f "$REPO_DIR/package.json" ]]; then
+    # Build if dist/ is missing
+    if [[ ! -f "$REPO_DIR/dist/index.js" ]]; then
+      echo "  Building from source..."
+      (cd "$REPO_DIR" && npm install && npm run build)
+    fi
+    (cd "$REPO_DIR" && npm install -g . 2>&1 | tail -1)
+    echo "  Installed $PKG_NAME from local repo"
+  else
+    echo "  WARNING: $PKG_NAME not on npm and no local repo found"
+    echo "  MCP server not installed — tools won't work"
+  fi
+fi
+
+# ── Verify ───────────────────────────────────────────────────
+
+ERRORS=0
+
+if [[ ! -f "$INSTALL_DIR/.claude-plugin/plugin.json" ]]; then
+  echo ""
+  echo "ERROR: Plugin files missing — plugin.json not found"
+  ERRORS=1
+fi
+
+if ! command -v "$PKG_NAME" &>/dev/null; then
+  echo ""
+  echo "WARNING: $PKG_NAME not found in PATH"
+  echo "  MCP tools won't work until the server is installed."
+  echo "  Try: cd $REPO_DIR && npm install -g ."
+  ERRORS=1
+fi
+
+if [[ "$ERRORS" -eq 0 ]]; then
+  echo ""
+  echo "Forge installed successfully"
+  echo ""
+  echo "Restart Claude Code to activate. Skills:"
+  echo "  /forge       Start a development pipeline"
+  echo "  /search      AI-ranked code search"
+  echo "  /impact      Dependency & call graph analysis"
+  echo "  /history     Git intelligence & hotspots"
+  echo "  /gotchas     Known pitfalls & patterns"
+  echo "  /learn       Save or search project learnings"
+  echo "  /fix         Auto-fix current changes"
+  echo "  /brainstorm  Creative exploration"
+  echo "  /index-repo  Register & index a repo"
+  echo ""
+  echo "To update: re-run this script"
+  echo "To remove: ./bin/setup-forge.sh --remove"
+fi

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}