Forge Init

MCP Server Provisioning

After detecting the environment, provision the Forge MCP server for cross-platform AI client access:

1. Check config gate: If mcp_server.enabled: false in forge-config.md, skip.

2. Check Python version:

   python3 --version 2>/dev/null
   

   Parse the output. If Python 3.10+ is available, proceed. Otherwise log: "ℹ️ Python 3.10+ not found. Forge MCP server skipped. Forge works without it." and skip steps 3-5.

3. Check mcp package:

   python3 -c "import mcp" 2>/dev/null
   

   If import fails, attempt install:

   • pip install --user mcp 2>/dev/null || pip3 install --user mcp 2>/dev/null || uv pip install mcp 2>/dev/null If all fail, log INFO and skip.

4. Write .mcp.json entry: Read existing .mcp.json at project root (create {} if absent). Merge the forge server entry:

   {
     "mcpServers": {
       "forge": {
         "command": "python3",
         "args": ["{CLAUDE_PLUGIN_ROOT}/shared/mcp-server/forge-mcp-server.py"],
         "env": {
           "FORGE_PROJECT_ROOT": "{project_root}"
         }
       }
     }
   }
   

   If forge entry already exists, update the args path (idempotent).

5. Display result:

   ✅ Forge MCP server provisioned in .mcp.json
      Any MCP-capable AI client can now query pipeline state, run history, and findings.
   

Idempotency: Running /forge-init again does not duplicate the entry. It updates the args path if the plugin location changed.

Instructions

Work through these phases in order. Do NOT skip ahead -- each phase builds on the previous one.

Phase 1: DETECT

Pre-Validation

Before scanning for stack markers, verify the environment is ready:

1. Git repository check: Run git rev-parse --show-toplevel
   • If it fails: ERROR — "Not a git repository. Initialize with git init first." Abort.
2. Config directory check: Verify .claude/ directory exists and is writable.
   • If it does not exist, it will be created in the CONFIGURE phase — this is fine, just note it.
   • If it exists but is not writable: ERROR — ".claude/ directory is not writable. Check permissions." Abort.
3. Existing config check: Check whether .claude/forge.local.md already exists.
   • If it exists: ASK via AskUserQuestion with header "Config", question "Found existing forge.local.md. What should I do?", options: "Overwrite" (description: "Replace existing config with freshly detected settings") and "Keep existing" (description: "Abort initialization and preserve current configuration").
   • If the user chooses "Keep existing": abort with message "Keeping existing configuration."
   • If the user chooses "Overwrite": proceed, and the CONFIGURE phase will overwrite the file.

Greenfield Detection

Before scanning for stack markers, check whether the project is empty or has no source code:

1. Check tracked files: Run git ls-files --cached --others --exclude-standard | head -5
   • If the command returns empty (no tracked or untracked files, ignoring .claude/ and .forge/): the project is greenfield.
   • If the only files present are configuration files (.gitignore, .editorconfig, README.md, LICENSE) with no source code: the project is greenfield.
2. Check for any language markers: Quickly scan for the existence of ANY build/manifest file (package.json, build.gradle.kts, build.gradle, Cargo.toml, go.mod, pyproject.toml, Package.swift, *.csproj, CMakeLists.txt, Makefile).
   • If none found: the project is greenfield.

If the project is greenfield, ASK via AskUserQuestion with header "New Project", question "This looks like a new project with no code yet. Would you like to scaffold a project from scratch?", options:

• "Bootstrap" (description: "Select a tech stack and scaffold a production-grade project structure with build system, CI/CD, and tooling")
• "Select stack manually" (description: "Just configure the pipeline — I'll tell you what tech stack I plan to use")
• "Skip" (description: "Proceed with detection anyway — I have code that wasn't detected")

If user chooses "Bootstrap":

1. Ask the user directly: "What would you like to build? Describe your project (e.g., 'Kotlin Spring Boot REST API with PostgreSQL', 'React Vite frontend with TypeScript')."
2. After receiving the description, dispatch fg-050-project-bootstrapper via the Agent tool with the user's description. The bootstrapper handles all scaffolding, validation, and auto-runs /forge-init at the end. Return the bootstrapper's output and stop — do not continue to Phase 2.

If user chooses "Select stack manually":

1. Present the available frameworks grouped by language:

   Language	Frameworks
   Kotlin/Java	spring, jetpack-compose, kotlin-multiplatform
   TypeScript	react, nextjs, angular, vue, svelte, sveltekit, express, nestjs
   Rust	axum
   Go	gin, go-stdlib
   Python	fastapi, django
   Swift	vapor, swiftui
   C#	aspnet
   C/C++	embedded
   Infrastructure	k8s

2. ASK via AskUserQuestion with header "Framework", question "Which framework will you use?", options: up to 4 most likely matches based on any context clues, plus "Other" (description: "I'll type the framework name").

3. Once the framework is selected, use it as the detected module and continue to Phase 1.5 (Code Quality Recommendations) and Phase 2 (CONFIGURE) normally. Skip the rest of Phase 1 detection since the user selected manually.

If user chooses "Skip": Continue with normal stack detection below.

Monorepo Detection

Before stack detection, check for monorepo tooling:

1. Scan for monorepo markers:

   • nx.json → Nx monorepo
   • turbo.json → Turborepo monorepo
   • pnpm-workspace.yaml → pnpm workspaces
   • lerna.json → Lerna monorepo
   • rush.json → Rush monorepo

2. If monorepo detected:

   • Parse workspace/package definitions to list all packages/apps

   • For each package, run the Stack Detection logic below independently

   • Present findings:

     Monorepo detected: {tool} ({N} packages)
     
     | Package          | Path              | Framework  | Language   |
     |------------------|-------------------|------------|------------|
     | web-app          | apps/web          | react      | typescript |
     | api-server       | apps/api          | express    | typescript |
     | shared-utils     | packages/utils    | —          | typescript |
     

   • ASK via AskUserQuestion with header "Monorepo", question "Which packages should the pipeline manage?", options:

     • "All" (description: "Configure all detected packages as pipeline components")
     • "Select" (description: "Choose which packages to include")
     • "Primary only" (description: "Pick one primary package, ignore the rest")

   • If "All" or "Select": generate components: entries with path: per package in forge.local.md. Set monorepo.tool in forge-config.md.

   • If "Primary only": proceed with single-module stack detection as normal.

3. If no monorepo detected: proceed to Stack Detection normally.

Stack Detection

Scan the project root and immediate subdirectories for stack markers. Check for the first match in this priority order:

Ambiguity Resolution

If module detection is ambiguous — for example, both build.gradle.kts and package.json exist in the project root or subdirectories, matching multiple modules — do NOT guess. Instead:

1. ASK via AskUserQuestion with header "Framework", question "Detected multiple frameworks. Which is the primary module for pipeline configuration?", options: one per detected framework (label: framework name, description: matched markers that triggered the detection). Max 4 options.
2. Use the user's answer as the primary module for all config generation.
3. Note the other detected frameworks in the config's related_modules field for future multi-module support.

If detection is unambiguous (only one module matches), proceed without asking.

Supplementary Detection

Also detect and note the presence of:

• Docker: docker-compose.yml, docker-compose.yaml, Dockerfile
• CI/CD: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, bitbucket-pipelines.yml
• Test framework: JUnit, Jest, Vitest, pytest, go test, cargo test, XCTest, etc.
• OpenAPI spec: openapi.yaml, openapi.json, swagger.yaml, swagger.json (search recursively)

Crosscutting Module Detection

Scan project files to detect which crosscutting infrastructure modules are in use. These map to modules/{layer}/{name}.md convention files that the composition engine loads at runtime.

Databases — detect from config files and dependencies:

• application.yml/application.properties with spring.datasource → parse driver class/URL for: postgresql, mysql, mariadb, oracle, mssql
• prisma/schema.prisma → parse provider field: postgresql, mysql, sqlite, mongodb
• docker-compose.yml service images: postgres → postgresql, mysql → mysql, mongo → mongodb, redis → redis
• knexfile.* or ormconfig.* → parse dialect
• sqlalchemy in requirements.txt/pyproject.toml → check DATABASE_URL in .env
• diesel.toml → Rust diesel, parse backend

Persistence/ORM — detect from dependencies:

• spring-boot-starter-data-jpa or hibernate → jpa-hibernate
• spring-boot-starter-data-r2dbc → r2dbc
• jooq in build files → jooq
• exposed in build files → exposed
• prisma in package.json → prisma
• typeorm in package.json → typeorm
• drizzle-orm in package.json → drizzle
• sequelize in package.json → sequelize
• sqlalchemy → sqlalchemy
• diesel → diesel
• gorm in go.mod → gorm
• ent in go.mod → ent

Migrations — detect from dependencies/files:

• flyway in build files or db/migration/V*.sql → flyway
• liquibase in build files or db/changelog → liquibase
• prisma/migrations/ → prisma (already detected above)
• alembic/ or alembic.ini → alembic
• knex migrate or migrations/ with knex → knex

API protocols — detect from files:

• openapi.yaml/openapi.json/swagger.* → openapi
• *.proto files or buf.yaml → grpc
• schema.graphql or graphql dependency → graphql
• trpc in package.json → trpc

Messaging — detect from dependencies/config:

• spring-kafka or kafka in docker-compose → kafka
• spring-amqp/spring-rabbit or rabbitmq in docker-compose → rabbitmq
• @nestjs/bull or bullmq in package.json → bullmq
• celery in requirements → celery
• nats in dependencies → nats
• pulsar-client → pulsar

Caching — detect from dependencies/config:

• spring-boot-starter-data-redis or redis service in docker-compose → redis
• ioredis or redis in package.json → redis
• spring-boot-starter-cache with caffeine → caffeine
• memcached → memcached

Search — detect from dependencies/config:

• elasticsearch or opensearch in dependencies/docker-compose → elasticsearch or opensearch
• meilisearch in dependencies → meilisearch
• typesense in dependencies → typesense

Storage — detect from dependencies:

• aws-sdk/@aws-sdk/client-s3 or s3 in config → s3
• @google-cloud/storage → gcs
• @azure/storage-blob → azure-blob
• minio in docker-compose → minio

Auth — detect from dependencies:

• spring-security → spring-security
• passport in package.json → passport
• next-auth or @auth/core → nextauth
• keycloak in config → keycloak
• auth0 in dependencies → auth0
• firebase-admin auth → firebase-auth
• JWT libraries (jsonwebtoken, jose) → note as JWT-based

Observability — detect from dependencies/config:

• opentelemetry or otel in dependencies → opentelemetry
• micrometer in build files → micrometer
• prometheus in docker-compose → prometheus
• datadog in dependencies → datadog
• sentry in dependencies → sentry
• pino or winston in package.json → note logging library

i18n — detect from dependencies:

• react-i18next or i18next in package.json → i18n: i18next
• vue-i18n → i18n: vue-i18n
• @ngx-translate/core → i18n: ngx-translate
• django.utils.translation in imports → i18n: django
• *.lproj directories or Localizable.strings → i18n: apple
• values-*/strings.xml → i18n: android

Feature flags — detect from dependencies:

• launchdarkly-node-server-sdk or @launchdarkly/* → feature_flags: launchdarkly
• unleash-client or @unleash/* → feature_flags: unleash
• @growthbook/growthbook → feature_flags: growthbook
• flagsmith → feature_flags: flagsmith

ML/Ops — detect from dependencies/files:

• mlflow in requirements → ml_ops: mlflow
• dvc.yaml or .dvc/ → ml_ops: dvc
• wandb in requirements → ml_ops: wandb
• sagemaker in requirements → ml_ops: sagemaker

Property-based testing — detect from dependencies:

• jqwik in build files → property_testing: jqwik
• fast-check in package.json → property_testing: fast-check
• hypothesis in requirements → property_testing: hypothesis
• proptest in Cargo.toml → property_testing: proptest

Deployment infrastructure — detect from files:

• argocd/Application CRD in YAML files → deployment: argocd
• Chart.yaml → deployment: helm
• kustomization.yaml → deployment: kustomize
• terraform/ or *.tf files → deployment: terraform
• pulumi/ or Pulumi.yaml → deployment: pulumi

Collect all detected crosscutting modules. They will be presented in the summary table and configured in Phase 2.

Code Quality Tool Detection

Scan for configured code quality tools by checking for config files:

Linting/Analysis: .detekt.yml → detekt, .editorconfig with ktlint_* → ktlint, eslint.config.* or .eslintrc.* or eslintConfig in package.json → eslint, biome.json or biome.jsonc → biome, ruff.toml or [tool.ruff] in pyproject.toml → ruff, .golangci.yml → golangci-lint, clippy.toml → clippy, .swiftlint.yml → swiftlint, .credo.exs → credo, .rubocop.yml → rubocop, phpstan.neon → phpstan, analysis_options.yaml → dart-analyzer, .scalafmt.conf → scalafmt, .scalafix.conf → scalafix, roslyn analyzer packages in .csproj → roslyn-analyzers, checkstyle.xml → checkstyle, pmd.xml or ruleset.xml → pmd, spotbugs-exclude.xml → spotbugs, errorprone in build.gradle.kts → errorprone, .pylintrc or pylintrc → pylint, mypy.ini or .mypy.ini → mypy

Formatting: .prettierrc.* or prettier key in package.json → prettier, [tool.black] in pyproject.toml → black, spotless in build.gradle.kts → spotless, rustfmt.toml → rustfmt

Coverage: jacoco in build files → jacoco, nyc or c8 config → istanbul, [tool.coverage] in pyproject.toml or .coveragerc → coverage-py, coverlet in .csproj → coverlet

Security: dependencyCheck in build files → owasp-dependency-check, .snyk → snyk, .trivy.yaml → trivy

Present detected tools in the summary table.

Documentation Detection

Scan for documentation files beyond OpenAPI:

• Markdown docs: Count .md files in docs/, documentation/, wiki/, guides/ directories
• ADRs: Check for adr/, docs/adr/, docs/decisions/ directories; count files matching NNN-*.md or ADR-*.md
• Runbooks: Check for files/dirs named runbook, playbook, operations
• Changelogs: Check for CHANGELOG.md, CHANGES.md, HISTORY.md
• Architecture docs: Check for files named architecture.md, design.md, technical.md
• External references: Scan top-level markdown files for URLs pointing to Confluence, Notion, or wiki platforms

Add to the summary table:

Documentation:      {N} files ({breakdown by type})
External docs:      {list or "none detected"}

Present findings in a clear summary table:

Detected stack:     react
Module:             modules/frameworks/react
Package manager:    pnpm
Monorepo:           — (none detected)
Test framework:     Vitest
Code quality:       ESLint (lint), Prettier (format), istanbul (coverage)
Docker:             docker-compose.yml (3 services)
CI/CD:              GitHub Actions (2 workflows)
OpenAPI:            docs/openapi.yaml
Documentation:      14 files (3 ADRs, 1 OpenAPI, 2 runbooks, 8 guides)
External docs:      Confluence (2 spaces referenced)

Crosscutting:
  Database:         postgresql (via docker-compose)
  Persistence:      prisma
  Migrations:       prisma
  Caching:          redis (via docker-compose)
  Auth:             next-auth
  Observability:    sentry
  i18n:             react-i18next
  Feature flags:    — (none detected)
  ML/Ops:           — (none detected)
  Messaging:        — (none detected)
  Search:           — (none detected)
  Storage:          s3 (via @aws-sdk/client-s3)
  Deployment:       — (none detected)

Only show crosscutting modules that were detected or are commonly expected for the framework. Omit categories with no detections if the list would be too long (show max 8 lines; use "— (none detected)" for commonly expected but missing ones).

ASK via AskUserQuestion with header "Confirm", question "Does this detected stack look correct? Should I proceed with the {module} module?", options: "Proceed" (description: "Stack detection looks correct, continue to configuration") and "Adjust" (description: "Something is wrong — I'll provide corrections").

Wait for confirmation before continuing. If the user chooses "Adjust", ask what needs to change and adjust accordingly.

If detection returned unknown/null (non-greenfield project with code but unrecognized stack): Present the available frameworks table (same as the "Select stack manually" flow in Greenfield Detection) and ask the user to select manually. Do NOT proceed with a null module — every project needs a resolved framework module for configuration generation.

Documentation Sources Prompt

After stack confirmation, if any documentation files were detected, ask:

"Found {N} documentation files. Are there additional docs I should know about? (external wikis, Confluence spaces, Notion pages, shared drives) You can also add these later — the pipeline picks up new docs automatically on each run."

If the user provides URLs or paths:

• Store them for inclusion in the documentation.external_sources array during Phase 2 configuration.
• Accept any format: URLs, file paths, or just descriptions.

If the user says no or skips: proceed without additional sources.

Phase 1.5 — Smart Code Quality Recommendations

Input: Framework's code_quality_recommended list from local-template.md + project's existing tool configs detected in Phase 1.

Algorithm:

1. Load recommendations: Read the framework's code_quality_recommended list from local-template.md

2. Read frontmatter: For each recommended tool, read its modules/code-quality/{tool}.md YAML frontmatter to extract: exclusive_group, recommendation_score, detection_files, categories

3. Detect existing tools: For each tool, check if ANY of its detection_files exist in the project root. Mark as "already configured" if found.

4. Group by exclusive_group: Partition tools into groups. Tools with exclusive_group: none (security scanners) go into a "complementary" bucket — no deduplication needed.

5. Deduplicate per group: a. If the project already has a tool from this group (detected via detection_files) → keep it, hide alternatives b. If no tool detected in the group → pre-select the one with highest recommendation_score c. Mark remaining tools in the group as "alternatives (not selected)"

6. Present to user via AskUserQuestion:

   Header: "Code Quality Tools"
   Question: "Recommended tools for your {framework} + {language} project:"
   Options:
     A) Accept recommendations:
        ✅ {tool1} — {description from overview} (recommended)
        ✅ {tool2} — {description} (recommended)
           ↳ Alternatives: {alt1}, {alt2} (same category: {exclusive_group})
        ✅ {tool3} — {description} (recommended)
        ...
     B) Customize selection (per-group choices)
     C) Skip code quality setup
   

7. If user selects (B) — Customize: For each exclusive group with multiple members, present via AskUserQuestion:

   For exclusive groups (radio — pick one):

   Header: "{Language} {Category}"
   Question: "Pick one (or none):"
   Options:
     A) {tool1} — {brief desc} (recommended, score: {N})
     B) {tool2} — {brief desc} (score: {N})
     C) {tool3} — {brief desc} (score: {N})
     D) None — skip this category
   

   For complementary groups (checkboxes — pick any):

Phase 2: CONFIGURE

Once confirmed, generate the configuration files:

1. Read the module template: Read ${CLAUDE_PLUGIN_ROOT}/modules/frameworks/{detected_module}/local-template.md to get the template content.

2. Fill in detected values: Replace template placeholders with detected project-specific values:

   • Build command (e.g., ./gradlew build -x test, pnpm build, cargo build)
   • Test command (e.g., ./gradlew test, pnpm test, cargo test)
   • Lint command (if linters detected)
   • Format command (if formatter detected)
   • Adjust module paths if the project uses a monorepo structure

3. Write config files:

   • Copy filled template to .claude/forge.local.md
   • If ${CLAUDE_PLUGIN_ROOT}/modules/frameworks/{detected_module}/forge-config-template.md exists, copy it to .claude/forge-config.md
   • Create .claude/forge-log.md with this content:

     # Forge Log
     
     Accumulated learnings from forge runs. Updated automatically by the retrospective agent.
     

4. Code Quality Scaffolding: For each accepted tool from Phase 1.5:

   • Project setup: Add build dependency, generate baseline config, wire into build commands
   • CI/CD setup (if accepted): Add pipeline steps for linting, coverage reports, threshold enforcement
   • Config patterns sourced from modules/code-quality/{tool}.md → Installation & Setup and CI Integration sections
   • Do NOT modify existing configs, force declined tools, or scaffold conflicting tools without resolution
   • Record accepted tools in the code_quality list in forge.local.md (simple string form - jacoco or object form with external ruleset - tool: detekt\n ruleset:\n type: external\n source: "...")

5. Documentation config: If the module's local-template.md includes a documentation: section (all modules now do), populate detected values:

   • Set external_sources from any URLs the user provided in the documentation prompt
   • The auto_generate defaults come from the template — no detection-based overrides needed

Show the user what files were created and their key settings. ASK via AskUserQuestion with header "Validate", question "Config files written. Want me to validate the setup?", options: "Validate" (description: "Run build, test, and engine checks to verify everything works (Recommended)"), "Skip" (description: "Skip validation — I'll test it myself later").

Phase 2a — Git Conventions Detection

1. Scan for existing hooks in the project:

   • .husky/ → Husky detected
   • .git/hooks/commit-msg (exists with content, not default sample) → Native git hook
   • .pre-commit-config.yaml → pre-commit framework
   • lefthook.yml → Lefthook
   • commitlint.config.* (js, json, yaml, yml, ts, cjs, mjs) → commitlint
   • .czrc or .cz.json → Commitizen

2. If any convention tool detected:

   • If commitlint: parse rules to extract allowed types and scopes
   • Write to forge.local.md git: section with commit_format: project and detected rules
   • Set git.commit_enforcement: external
   • Tell user: "Detected {tool}. Adopting your project's commit conventions."

3. If NO convention tool detected:

   • Ask user via AskUserQuestion:

     Header: "Git Conventions"
     Question: "No commit conventions detected. Would you like to set up Conventional Commits?"
     Options:
       A) Yes, set up Conventional Commits (recommended)
       B) No, I'll configure my own later
     

   • If (A): Write defaults to forge.local.md git: section with commit_format: conventional
   • If (B): Write git: section with commit_format: none

4. Branch naming:

   • Write git.branch_template: "{type}/{ticket}-{slug}" to forge.local.md
   • If a custom branch naming hook is detected, parse its pattern and use it instead

Phase 2b — Kanban Tracking Setup

1. Check if .forge/tracking/counter.json already exists
2. If not, ask user via AskUserQuestion:

   Header: "Kanban Tracking"
   Question: "Set up file-based kanban tracking for this project?"
   Options:
     A) Yes, with default prefix "FG"
     B) Yes, with custom prefix
     C) No, skip tracking
   

3. If (A): Source shared/tracking/tracking-ops.sh, call init_counter ".forge/tracking"
4. If (B): Ask for prefix via AskUserQuestion, then init_counter ".forge/tracking" "$prefix"
5. If (C): Skip
6. If (A) or (B): Create directory structure: mkdir -p .forge/tracking/{backlog,in-progress,review,done}
7. If (A) or (B): Generate initial empty board: generate_board ".forge/tracking"

Phase 2c — Output Compression Setup

Ask the user whether to enable caveman mode (terse output compression) for pipeline sessions:

ASK via AskUserQuestion with header "Output Compression", question "Forge can compress its output to save tokens and reduce noise. Pick a compression level:", options:

• "Ultra" (description: "Maximum compression. Abbreviations, arrows, no conjunctions. ~65% prose reduction, ~7-10% session savings")
• "Full" (description: "Drop articles, fragments OK, short synonyms. ~45% prose reduction, ~4-7% session savings")
• "Lite" (description: "Drop filler/hedging, keep grammar and articles. ~20% prose reduction, ~2-4% session savings")
• "Off" (description: "Standard verbose output, no compression")

Based on the user's choice:

1. If Ultra/Full/Lite: Add to forge-config.md:

   caveman:
     enabled: true
     default_mode: {chosen_mode}   # ultra | full | lite
   

   Create .forge/caveman-mode with the chosen mode value.

2. If Off: Do not add a caveman: section (omitting = disabled). If .forge/caveman-mode exists, delete it.

Tell the user: "Output compression set to {mode}. Change anytime with /forge-compress output [mode]."

Phase 2d — Crosscutting Module Configuration

Present the crosscutting modules detected in Phase 1 and let the user confirm or adjust.

ASK via AskUserQuestion with header "Infrastructure", question "Detected these infrastructure modules. Confirm or adjust:", options:

• "Accept all" (description: "Use all detected modules as-is: {comma-separated list of detected modules}")
• "Customize" (description: "Review each category and adjust selections")
• "Skip" (description: "Don't configure crosscutting modules — I'll add them manually later")

If user chooses "Customize": For each detected category, show detected value and allow override. Also present undetected categories that are common for the framework and ask if any should be added.

If user chooses "Accept all" or after customization: Write to forge.local.md under the appropriate config keys: