specforge-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# SpecForge
+
+**Spec Driven Development for AI coding agents.**
+
+![Build](https://img.shields.io/badge/build-passing-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-blue)
+![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-green)
+
+## Installation
+
+### Claude Desktop / Claude Code
+
+Add to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "npx",
+      "args": ["-y", "specforge-mcp"]
+    }
+  }
+}
+```
+
+Requires **Node.js ≥ 22**. No API keys or accounts needed — all data is stored locally.
+
+---
+
+## What is SpecForge?
+
+SpecForge is an MCP (Model Context Protocol) server that brings Spec Driven Development to AI coding agents. It manages the full spec lifecycle -- from requirements clarification and spec creation to estimation, validation, and drift detection. It enforces a project Constitution (immutable architectural principles extracted from CLAUDE.md and .cursorrules), validates DoR/DoD at every lifecycle transition, generates PLAN.md execution files for implementing specs step-by-step, and detects spec versioning drift with cascading downstream impact analysis. Language and framework agnostic, it works with any stack and learns from your codebase over time.
+
+## SDD Lifecycle
+
+```
+clarify → create_spec → DoR check → implement (PLAN.md) → validate → drift detection → done
+```
+
+Each transition is gated by DoR (Definition of Ready) and DoD (Definition of Done) checklists.
+Constitution compliance is enforced automatically at `create_spec`, `audit`, and `detect_drift`.
+Spec versioning tracks every change and flags downstream spec impact when a dependency drifts.
+
+## Features
+
+### A -- Configuration
+
+| Tool | Description |
+|------|-------------|
+| `set_locale` | Change the active locale for messages and spec templates |
+| `init_project` | Initialize a project -- detects language, framework, architecture, and stores project knowledge; also detects AI-native architecture patterns (inference mode, orchestration frameworks), frontend performance setup (Core Web Vitals budgets, SSR frameworks), and K3s/Nomad workload orchestrators |
+| `init_constitution` | Generate the project constitution -- immutable architectural principles extracted from CLAUDE.md, .cursorrules; auto-enforced in create_spec, audit, and drift detection |
+
+### B -- Spec Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `clarify_requirements` | Generate targeted clarification questions before creating a spec |
+| `create_spec` | Create a full SDD spec with auto-generated sections: ADR hints, DB schema, UI contracts, test plan, execution plan, DoR checklist; generates AI-native architecture criteria (latency budgets, fallback chains, prompt versioning) and frontend performance criteria (Core Web Vitals, SSR hydration, MFE boundaries) when detected |
+| `list_specs` | List all specs for a project, optionally filtering by status |
+| `update_status` | Transition a spec through its lifecycle with DoR/DoD validation at each step |
+| `summarize_spec` | Generate a concise summary of a spec |
+| `generate_checklist` | Generate a quality checklist for a spec |
+| `reconcile_spec` | Reconcile spec with implementation changes, with per-change approval and Constitution compliance check |
+| `manage_scope` | Manage the project scope definition and backlog |
+| `detect_contradictions` | Analyze all specs in a project for semantic contradictions |
+| `check_readiness` | Evaluate if a spec is ready for implementation -- completeness, criteria quality, and dependency status |
+| `package_handoff` | Generate a structured handoff package for an AI agent to implement a spec, including objective, criteria, file list, and constraints |
+
+### C -- Analysis and Estimation
+
+| Tool | Description |
+|------|-------------|
+| `estimate` | Estimate effort, cost, and token usage for a spec using multi-agent analysis |
+| `reverse_engineer` | Analyze existing code and generate an SDD spec from it |
+| `validate` | Validate implementation against its spec -- coverage, drift, and quality |
+| `detect_drift` | Detect drift between spec and implementation -- includes Constitution compliance, downstream spec impact |
+| `audit` | Audit code for SOLID, clean code, architecture, and Constitution violations; generates quality score 0-100 |
+| `learn_pattern` | Teach the system a new pattern (architecture, convention, estimation, stack, quality) |
+| `security_check` | Analyze a spec against OWASP Top 10, scan code for insecure patterns, and generate a security score (A–F) with drift detection |
+| `capture_learning` | Capture a discovered pattern or lesson into the spec system with semantic deduplication |
+| `paradigm_report` | Detect and report the programming paradigms used in a project |
+| `reality_check` | Evaluate whether a set of requirements is feasible given the project context |
+
+### D -- Design and Planning
+
+| Tool | Description |
+|------|-------------|
+| `generate_adr` | Generate Architecture Decision Records for a spec |
+| `design_schema` | Design database schema from spec requirements |
+| `define_ui_contract` | Define UI component contracts, data flow, and state management |
+| `challenge_spec` | Stress-test a spec for failures, concurrency, scale, and edge cases |
+| `generate_execution_plan` | Generate a step-by-step PLAN.md for implementing a spec -- RED/GREEN/VERIFY cycle with parallelizable steps |
+| `generate_orchestration_script` | Generate a 3-layer parallel automation script (worktrees + claude -p) for running specs concurrently |
+| `event_contracts` | Manage event-driven architecture contracts -- generate JSON Schema event contracts for producer/consumer validation |
+
+### E -- Stack and Agents
+
+| Tool | Description |
+|------|-------------|
+| `suggest_stack` | Suggest a technology stack based on project requirements |
+| `check_versions` | Check dependency versions for updates, deprecations, and security issues |
+| `generate_skill` | Generate an agent skill file for a specific platform |
+| `detect_agent` | Detect the AI coding agent platform in use |
+| `generate_sub_agent` | Generate a sub-agent definition for multi-agent orchestration |
+| `generate_rules` | Generate agent rules files (.cursorrules, CLAUDE.md, etc.) |
+
+### F -- Dev Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `suggest_tooling` | Assess and suggest dev lifecycle tooling (CI/CD, testing, monitoring, etc.); includes AI-native tooling recommendations (LLM observability, semantic cache, prompt management, guardrails) and frontend performance tooling (Lighthouse CI, visual regression, component libraries) |
+| `generate_tests` | Generate test plan and test files from a spec |
+| `generate_docs` | Generate documentation from specs and code |
+| `integrate_pm` | Integrate with project management tools (Jira, Linear, GitHub Issues, etc.) |
+
+### G -- Infrastructure
+
+| Tool | Description |
+|------|-------------|
+| `manage_context` | Save, load, and manage persistent context notes across sessions |
+| `manage_git` | Git integration -- branches, PRs, changelogs, hooks linked to specs |
+| `orchestrate` | Multi-agent orchestration -- register agents, lock resources, distribute tasks |
+| `consult_docs` | Consult framework documentation for a specific topic |
+| `discover_mcps` | Discover MCP servers configured in the environment |
+| `suggest_mcps` | Suggest MCP servers that could benefit the project |
+| `migrate_tech` | Guide tech stack migration -- analyze source codebase, map equivalences, generate migration plan, validate functional parity, and plan DB migration |
+| `orchestrate_agents` | Declare agent capabilities, route tasks to the best agent, generate structured handoff contexts, and detect file-ownership conflicts before parallel execution |
+| `validate_workflow` | Validate developer workflow conventions: suggest the right AI model for a task, detect Git Flow violations, audit MCP tool conventions, or run a full workflow audit |
+| `log_decision` | Register, list, search, or supersede architectural and process decisions for a project |
+| `facilitate` | Entry point for users unfamiliar with SpecForge -- guides them through the SDD workflow interactively |
+| `request_context` | Generate a prompt that asks the user for reference documentation (README, PRD, architecture docs) |
+| `contribute_context` | Persist structured knowledge extracted from user-provided documents into the project knowledge base |
+
+### H -- Governance & Stack Health
+
+| Tool | Description |
+|------|-------------|
+| `data_governance` | Detect PII in specs, generate retention policies, draft privacy notices, and audit GDPR/CCPA/LGPD compliance |
+| `audit_stack` | Audit all project dependencies, classify as up_to_date/outdated/vulnerable/unmaintained, and generate a StackHealthScore (0–100) |
+| `plan_upgrade` | Generate a migration plan for upgrading a specific package -- breaking changes, estimated effort, and rollback procedure |
+| `detect_deprecations` | Scan project source files for deprecated API patterns (no network) and return a deprecation report with tech-debt estimate |
+
+## Quick Setup
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "specforge": {
+      "command": "node",
+      "args": ["/absolute/path/to/specforge/dist/index.js"],
+      "env": {
+        "SDD_DATA_DIR": "/absolute/path/to/specforge/data",
+        "SDD_HOURLY_RATE": "50",
+        "SDD_LOCALE": "en"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add specforge node /absolute/path/to/specforge/dist/index.js
+```
+
+## Architecture
+
+```
+src/
+├── index.ts          # MCP server entry point
+├── tools/            # MCP tool handlers (58 tools, 8 streams A-H)
+├── resources/        # MCP resources (read-only)
+├── engine/           # Business logic (estimator, analyzer, validator)
+├── storage/          # JSON persistence layer
+├── types/            # TypeScript interfaces (16 domain files)
+├── config/           # Extensible registries and signatures
+└── i18n/             # Internationalization (en, es, pt)
+```
+
+Data is stored as JSON files in `data/` (gitignored):
+
+```
+data/
+├── projects/{hash}/  # Per-project: specs, metrics, patterns, knowledge
+└── global/           # Shared: templates, pricing
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SDD_DATA_DIR` | Path to data storage directory | `./data` |
+| `SDD_HOURLY_RATE` | Developer hourly rate (USD) for cost estimation | `50` |
+| `SDD_LOCALE` | Default locale (`en`, `es`, `pt`) | `en` |
+
+## Control Panel
+
+SpecForge ships with a cross-platform interactive launcher and a parallel spec execution system.
+
+### Launchers
+
+| Platform | How to run |
+|----------|-----------|
+| macOS | Double-click `sdd.command` or `bash sdd.sh` |
+| Linux / WSL | `bash sdd.sh` |
+| Windows | Double-click `sdd.bat` (requires WSL or Git Bash) |
+| Makefile | `make watch` / `make status` / `make auto` / `make batch SPECS="..."` |
+
+The menu provides: real-time worker dashboard, system status, automatic batch detection, explicit spec batches, tests, lint, and cleanup.
+
+### Parallel Spec Execution
+
+Specs are implemented by autonomous `claude -p` workers running in isolated git worktrees. Resource allocation is dynamic -- computed at runtime from the machine's physical cores and available RAM.
+
+```bash
+bash scripts/parallel-specs.sh --status    # show spec readiness and worker state
+bash scripts/parallel-specs.sh --auto      # detect and launch next ready batch
+bash scripts/parallel-specs.sh SPEC-014a SPEC-021   # launch specific specs
+bash scripts/watch-workers.sh 10           # real-time dashboard, refresh every 10s
+```
+
+Worker limits are computed as `min(phys_cores / 2, (avail_ram - 3 GB) / 0.35 GB)` and capped at 10. A background health monitor warns on high swap and kills the highest-memory worker if swap exceeds 3 GB.
+
+## Development
+
+| Command | Description |
+|---------|-------------|
+| `pnpm build` | Compile TypeScript |
+| `pnpm dev` | Watch mode |
+| `pnpm lint` | Lint with ESLint (zero warnings) |
+| `pnpm lint:fix` | Lint and auto-fix |
+| `pnpm test` | Run tests with Vitest |
+| `pnpm format` | Format with Prettier |
+| `pnpm format:check` | Check formatting |
+| `pnpm typecheck` | Type-check without emitting |
+| `pnpm check` | Run typecheck + lint + format check |
+
+Pre-commit hooks (Husky + lint-staged) run automatically: typecheck, eslint, prettier, commitlint, and secretlint.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the GitFlow strategy, branch naming, commit conventions, and PR process.
+
+## License
+
+[MIT](LICENSE)

package/dist/config/advanced-testing-tools.json

@@ -0,0 +1,210 @@
+{
+  "propertyBased": {
+    "javascript": {
+      "name": "fast-check",
+      "weeklyDownloads": 60000,
+      "install": "pnpm add -D fast-check",
+      "scaffoldImport": "import * as fc from 'fast-check';"
+    },
+    "typescript": {
+      "name": "fast-check",
+      "weeklyDownloads": 60000,
+      "install": "pnpm add -D fast-check",
+      "scaffoldImport": "import * as fc from 'fast-check';"
+    },
+    "python": {
+      "name": "hypothesis",
+      "dailyDownloads": 100000,
+      "install": "pip install hypothesis",
+      "scaffoldImport": "from hypothesis import given, settings\nfrom hypothesis import strategies as st"
+    },
+    "rust": {
+      "name": "proptest",
+      "install": "cargo add --dev proptest",
+      "scaffoldImport": "use proptest::prelude::*;"
+    },
+    "java": {
+      "name": "jqwik",
+      "install": "implementation(\"net.jqwik:jqwik:1.8.0\")",
+      "scaffoldImport": "import net.jqwik.api.*;"
+    },
+    "kotlin": {
+      "name": "jqwik",
+      "install": "implementation(\"net.jqwik:jqwik:1.8.0\")",
+      "scaffoldImport": "import net.jqwik.api.*"
+    },
+    "go": {
+      "name": "gopter",
+      "install": "go get github.com/leanovate/gopter",
+      "scaffoldImport": "\"github.com/leanovate/gopter\""
+    },
+    "haskell": {
+      "name": "QuickCheck",
+      "install": "cabal install QuickCheck",
+      "scaffoldImport": "import Test.QuickCheck"
+    },
+    "scala": {
+      "name": "ScalaCheck",
+      "install": "libraryDependencies += \"org.scalacheck\" %% \"scalacheck\" % \"1.17.0\" % Test",
+      "scaffoldImport": "import org.scalacheck.Prop.forAll"
+    }
+  },
+  "mutation": {
+    "javascript": {
+      "name": "stryker",
+      "stars": 5000,
+      "vitestPlugin": "@stryker-mutator/vitest-runner",
+      "jestPlugin": "@stryker-mutator/jest-runner",
+      "defaultThreshold": 80,
+      "install": "pnpm add -D @stryker-mutator/core @stryker-mutator/vitest-runner"
+    },
+    "typescript": {
+      "name": "stryker",
+      "stars": 5000,
+      "vitestPlugin": "@stryker-mutator/vitest-runner",
+      "jestPlugin": "@stryker-mutator/jest-runner",
+      "defaultThreshold": 80,
+      "install": "pnpm add -D @stryker-mutator/core @stryker-mutator/vitest-runner"
+    },
+    "python": {
+      "name": "mutmut",
+      "install": "pip install mutmut",
+      "alternative": "cosmic-ray",
+      "defaultThreshold": 80
+    },
+    "java": {
+      "name": "pitest",
+      "mavenGroup": "org.pitest",
+      "mavenArtifact": "pitest-maven",
+      "defaultThreshold": 80
+    },
+    "kotlin": {
+      "name": "pitest",
+      "mavenGroup": "org.pitest",
+      "mavenArtifact": "pitest-maven",
+      "defaultThreshold": 80
+    },
+    "rust": {
+      "name": "cargo-mutants",
+      "install": "cargo install cargo-mutants",
+      "defaultThreshold": 80
+    },
+    "go": {
+      "name": "gremlins",
+      "install": "go install github.com/go-gremlins/gremlins/cmd/gremlins@latest",
+      "defaultThreshold": 80
+    },
+    "scala": {
+      "name": "stryker4s",
+      "install": "addSbtPlugin(\"io.stryker-mutator\" % \"sbt-stryker4s\" % \"0.16.1\")",
+      "defaultThreshold": 80
+    },
+    "csharp": {
+      "name": "stryker-dotnet",
+      "install": "dotnet tool install -g dotnet-stryker",
+      "defaultThreshold": 80
+    }
+  },
+  "chaos": {
+    "kubernetes": {
+      "name": "LitmusChaos",
+      "cncf": true,
+      "dockerPulls": 30000000,
+      "install": "kubectl apply -f https://litmuschaos.github.io/litmus/litmus-operator-v3.0.0.yaml",
+      "docsUrl": "https://litmuschaos.io/docs"
+    },
+    "aws": {
+      "name": "AWS Fault Injection Simulator",
+      "managed": true,
+      "docsUrl": "https://docs.aws.amazon.com/fis/latest/userguide/what-is.html"
+    },
+    "azure": {
+      "name": "Azure Chaos Studio",
+      "managed": true,
+      "docsUrl": "https://learn.microsoft.com/en-us/azure/chaos-studio/"
+    },
+    "enterprise": {
+      "name": "Gremlin",
+      "saas": true,
+      "docsUrl": "https://www.gremlin.com/docs"
+    }
+  },
+  "accessibility": {
+    "playwright": {
+      "name": "axe-playwright",
+      "vendor": "Deque",
+      "wcagCoverage": "57%",
+      "install": "pnpm add -D axe-playwright",
+      "playwrightIntegration": "axe-playwright",
+      "docsUrl": "https://github.com/abhinaba-ghosh/axe-playwright"
+    },
+    "jest": {
+      "name": "jest-axe",
+      "install": "pnpm add -D jest-axe @types/jest-axe",
+      "docsUrl": "https://github.com/nickcolley/jest-axe"
+    },
+    "react": {
+      "name": "@axe-core/react",
+      "install": "pnpm add -D @axe-core/react",
+      "docsUrl": "https://github.com/dequelabs/axe-core-npm/tree/develop/packages/react"
+    },
+    "ci": {
+      "name": "pa11y-ci",
+      "install": "pnpm add -D pa11y-ci",
+      "docsUrl": "https://github.com/pa11y/pa11y-ci"
+    },
+    "lighthouse": {
+      "name": "lighthouse-ci",
+      "install": "pnpm add -D @lhci/cli",
+      "docsUrl": "https://github.com/GoogleChrome/lighthouse-ci"
+    }
+  },
+  "syntheticData": {
+    "javascript": {
+      "name": "@faker-js/faker",
+      "install": "pnpm add -D @faker-js/faker",
+      "docsUrl": "https://fakerjs.dev"
+    },
+    "typescript": {
+      "name": "@faker-js/faker",
+      "install": "pnpm add -D @faker-js/faker",
+      "docsUrl": "https://fakerjs.dev"
+    },
+    "python": {
+      "name": "Faker",
+      "install": "pip install faker",
+      "docsUrl": "https://faker.readthedocs.io",
+      "statistical": "SDV (Synthetic Data Vault) for ML-based generation"
+    },
+    "java": {
+      "name": "JavaFaker",
+      "install": "implementation(\"com.github.javafaker:javafaker:1.0.2\")",
+      "docsUrl": "https://github.com/DiUS/java-faker"
+    },
+    "go": {
+      "name": "gofakeit",
+      "install": "go get github.com/brianvoe/gofakeit/v6",
+      "docsUrl": "https://github.com/brianvoe/gofakeit"
+    }
+  },
+  "aiTesting": [
+    {
+      "name": "Keploy",
+      "description": "Captures real traffic and generates tests — Go/Java/Node/Python",
+      "docsUrl": "https://keploy.io/docs",
+      "recommended": true
+    },
+    {
+      "name": "CodiumAI",
+      "description": "AI unit test generation from existing code — VS Code / JetBrains",
+      "docsUrl": "https://www.codium.ai",
+      "recommended": false
+    },
+    {
+      "name": "Diffblue Cover",
+      "description": "Java enterprise AI test generation",
+      "docsUrl": "https://www.diffblue.com",
+      "recommended": false
+    }
+  ]
+}

package/dist/config/agent-capabilities-catalog.json

@@ -0,0 +1,30 @@
+{
+  "standardRoles": {
+    "researcher": {
+      "keywords": ["search", "explore", "find", "read", "analyze"],
+      "model": "haiku"
+    },
+    "implementer": {
+      "keywords": ["implement", "create", "write", "build", "add"],
+      "model": "sonnet"
+    },
+    "reviewer": {
+      "keywords": ["review", "validate", "check", "audit", "verify"],
+      "model": "sonnet"
+    },
+    "planner": {
+      "keywords": ["design", "architect", "plan", "decompose", "structure"],
+      "model": "opus"
+    },
+    "tester": {
+      "keywords": ["test", "coverage", "spec", "assert", "mock"],
+      "model": "sonnet"
+    }
+  },
+  "filePatternRoles": {
+    "src/engine/**": "implementer",
+    "tests/**": "tester",
+    "docs/**": "researcher",
+    "src/types/**": "implementer"
+  }
+}