What is ForgeHiveAI?

forgehive (fh) is a CLI that permanently equips Claude Code with your codebase context — and actively checks generated code for security issues.

Claude loses all project knowledge between sessions. forgehive solves this by writing a .forgehive/ directory into your target project that Claude reads automatically at every session start.

Core capabilities:

• Stack Scanner — detects tech stack, dependencies, and project structure automatically
• Persistent Memory — context and session notes survive every restart
• Story & Epic Tracking — lightweight agile backlog inside .forgehive/memory/
• Velocity Tracking — sprint velocity history, rolling average, and capacity hints
• Party Mode — 9 specialized agents (Kai, Sam, Eli, Vera + Felix, Mira, Aria, Leo, Hugo, Zara); fh auto --orchestrate dynamically composes the right team from detected stack capabilities
• Autonomous Loop — fh auto runs a story through plan → implement → test → PR with minimal human intervention
• Outcome Tracking — unified JSONL log of all runs; per-agent performance aggregates feed fh next
• Intelligence Layer — fh next detects your lifecycle phase and recommends the single most valuable action
• MCP Wiring — preconfigured connectors for 10 services, API keys stored securely in ~/.forgehive/
• Security Suite — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
• CI Integration — CI health report and GitHub Actions template generator
• Codebase Map — file/line/import table + semantic graph (hotspots, cycles, dependency stats)
• GitHub Integration — sync open Issues as Stories, fetch PR context, interactive token setup
• Intelligent Routing — fh ask "<task>" recommends the right agent or party set with a start command
• Product Workflow — PRD → Epic → Story pipeline with roadmap generation
• Team Sync — share memory across the team via a dedicated git branch
• AGENTS.md — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)

Design principle: writes exclusively to .forgehive/ in the target project. No globbing outside the project root. Never overwrites files it didn't create.

Status: v1.3.0 — Stable

497 passing tests back the commands listed below. The v1.0 feature set has been validated end-to-end.

Stable — use with confidence:

| Feature | State | |---|---| | fh init — stack scan + .forgehive/ setup | stable | | fh confirm / fh rollback | stable | | CLAUDE.md block merge (idempotent, 3 cases) | stable | | fh security scan — secrets + SAST | stable | | fh security deps — CVE check | stable | | fh security report — compliance reports | stable | | fh memory — show, clean, export, snapshot | stable | | MCP credential store (fh mcp auth) | stable | | fh ci — CI health report + GitHub Actions template | stable | | fh map — codebase structure map + semantic graph | stable | | fh map --semantic — semantic graph only (hotspots, cycles) | stable | | fh github setup — interactive token + repo configuration | stable | | fh github sync — sync open GitHub Issues as Story cards | stable | | fh github pr <N> — fetch PR metadata + changed files | stable | | fh ask "<task>" — intelligent agent/party routing | stable | | fh run <freetext> — route freetext tasks to best agent | stable | | fh product prd — create/list/show PRDs | stable | | fh product status — PRD → Epic → Story pipeline tree | stable | | fh product roadmap — generate ROADMAP.md | stable | | fh epic create --prd PRD-N — link epic to a PRD | stable | | fh status — daily driver dashboard (sprint · code health · watch events · next) | stable | | fh watch --smart — file watcher with test runner + agent routing | stable | | fh auto — autonomous development loop (plan → implement → test → PR) | stable | | fh auto --auto — fully automated mode (skips gate-1 and gate-2 checkpoints) | stable | | fh auto resume / status / list — run management | stable | | fh outcomes — unified outcome store (auto + party runs, per-agent aggregates) | stable | | fh next — intelligence layer (phase detection + next-step recommendation) | stable | | Smart Party Mode — review/security parties use real subagents (independent opinions) | stable | | fh onboard — generates ONBOARDING.md | stable | | fh changelog — semantic changelog from git | stable | | fh metrics — developer metrics by author/type | stable | | fh sync — team memory sharing via git branch | stable | | fh run — background agent execution via claude -p | stable | | fh story — story card create/list/show/done | stable | | fh epic — epic create/list/show | stable | | fh velocity — show history + record sprint data | stable | | fh upgrade — update CLAUDE.md block to latest template | stable |

Experimental — works in tests, not yet live-validated:

| Feature | State | |---|---| | fh party run — multi-agent worktree sessions | experimental | | fh skills regen — AI-assisted skill generation | experimental | | fh cost — session cost parsing from ~/.claude/ | experimental | | Guardrails bash hook in live Claude Code sessions | experimental |

If you run into issues, please open an issue on GitHub. The most valuable feedback right now is a real fh init run on your project — does Claude actually pick up the context?

Prerequisites

• Node.js ≥ 18 — check with node --version
• Claude Code installed and configured (claude CLI available)
• git — required for Party Mode worktrees, fh sync, and the guardrails hook

Documentation

| Document | Description | |---|---| | User Guide | Installation, quick start, all commands with examples, troubleshooting | | TUTORIAL.md | Step-by-step walkthrough of a real session |

Installation

From npm (recommended)

npm install -g forgehive

This makes both fh and forgehive available globally.

From source (for development)

git clone https://github.com/matharnica/forgehive
cd forgehive
npm install
npm run build      # compiles to dist/cli.js (~259 KB)
npm link           # makes 'fh' available globally

Verify the installation:

fh --version       # should print 1.0.0
fh --help          # lists all available commands

Quick Start

Step 1: Initialize your project

Navigate to any project you want Claude to understand, then run:

cd my-project
fh init

fh init does the following in order:

1. Scans your project — detects language, framework, dependencies, directory structure
2. Creates .forgehive/ with the full harness (capabilities, memory, skills, permissions)
3. Merges a context block into CLAUDE.md (creates it if it doesn't exist, never overwrites existing content)
4. Writes AGENTS.md to the project root (cross-tool agent standard)
5. Installs 16 expert skill files into .forgehive/skills/expert/

The scan result is displayed as a categorized capability table with brand colors:

🔍  ForgeHiveᴬᴵ  ·  Stack Intelligence
   my-project  ·  6 Signale  ·  18 Capabilities
───────────────────────────────────────────────────────────────

  ✦  Sprache    TypeScript
  ✦  Runtime    Node.js
  ✦  Framework  Next.js · React
  ✦  ORM / DB   Prisma · PostgreSQL
  ✦  Testing    Jest · Playwright
  ✦  CI/CD      GitHub Actions

  Bestätigen und loslegen? [Y/n]

Capabilities are grouped by category (Language, Runtime, Framework, ORM/DB, Auth, Testing, AI/ML, Build, CI/CD, Infra, Hosting, Messaging, Observability) and displayed with proper names — C# instead of csharp, .NET instead of dotnet, GitHub Actions instead of github-actions.

Step 2: Confirm the detected stack

fh confirm

This changes capabilities.yaml from status: draft to status: confirmed. Claude won't use the context as authoritative until it's confirmed — this gives you a chance to review what was detected before committing to it.

Answering Y at the fh init prompt confirms inline — no separate fh confirm needed. Use fh init --yes to skip the prompt entirely (CI/scripts).

After confirmation, open a new Claude Code session in the project. Claude will automatically read .forgehive/ and know your stack, constraints, and memory.

Step 3: Run a security audit (recommended)

fh security scan          # finds secrets and SAST vulnerabilities
fh security deps          # checks npm dependencies for known CVEs
fh security report gdpr   # generates a CISO-ready compliance report

Commands Reference

Setup & Lifecycle

| Command | Description | |---|---| | fh --help | Show full command reference | | fh -h | Same as --help | | fh init | Set up forgehive in the current project. Use --force to re-initialize an existing setup | | fh confirm | Confirm capabilities.yaml — activates context for Claude | | fh rollback | Remove .forgehive/ and the CLAUDE.md block cleanly | | fh status | Daily driver dashboard — sprint, code health, watch events |

Running fh init on a project that already has .forgehive/ prints a warning and exits. Use fh init --force to re-initialize (overwrites capabilities.yaml and scans again). To update only the scan, use fh scan --update.

When to use fh rollback: If you want to remove forgehive from a project entirely. It removes exactly the block it inserted into CLAUDE.md (nothing else) and deletes .forgehive/.

Scan

| Command | Description | |---|---| | fh scan --update | Re-scan the project (run after adding new dependencies) | | fh scan --check | Hash check — is the snapshot still current? | | fh upgrade | Update the CLAUDE.md block to the current forgehive template version |

The scan stores a hash of the project state. fh scan --check compares the current state against the stored hash and warns if dependencies or structure have changed significantly since the last scan.

Status & Cost Tracking

| Command | Description | |---|---| | fh status | Daily driver dashboard — sprint progress, code health, and last 5 watch events | | fh cost | Show Claude session costs from ~/.claude/ (all time) | | fh cost today | Costs for today only | | fh cost week | Costs for the current week | | fh cost --limit 20 | Set a hard spend limit of $20 | | fh cost --alert 15 | Set an alert threshold at $15 | | fh cost --limit 20 --alert 15 | Set both at once |

How spend limits work: Once set, fh cost checks your current spend against the configured limits every time it runs. When the alert threshold is reached, it prints a warning. When the hard limit is reached, it exits with a non-zero code — you can use this in CI or hooks to stop work automatically.

Daily Driver Dashboard

fh status

Opens the Daily Driver Dashboard — a three-section overview designed for the start of every session:

Sprint — lists all in-sprint stories and active epics from .forgehive/memory/.

Code Health — working-tree cleanliness (git status), days since last security scan (.forgehive/security-last-scan.txt), and number of open GitHub PRs (.forgehive/github-pr-cache.json).

Watch Events — the last 5 events from .forgehive/watch-events.jsonl (test runs, failures, agent prompts logged by fh watch --smart).

fh status is automatically called by Claude at session start when the forgehive CLAUDE.md block is present.

Smart File Watcher

fh watch --smart

Watches src/ and test/ directories. On every save:

1. Runs your project's test command (detected from capabilities.yaml)
2. On failure: classifies the error type and prompts to start the right agent:
   • Security/vulnerability/CVE keywords → Vera (security analyst)
   • Type/interface/logic errors → Kai (senior engineer)
   • Test/assertion/coverage failures → Sam (QA architect)
3. Appends a structured event to .forgehive/watch-events.jsonl (visible in fh status)

The event log rotates automatically at 500 entries (~25 KB).

fh watch             # standard watch mode (no routing)
fh watch --smart     # watch + test runner + agent routing

Autonomous Development Loop

fh auto US-3                    # plan + implement + test + open PR for story US-3
fh auto --auto US-3             # same, but skip both human checkpoints
fh auto "fix the login timeout" # freetext — creates a story card, then runs
fh auto resume <run-id>         # resume a paused or interrupted run
fh auto status                  # show all active runs with current phase
fh auto list                    # list all runs (active + completed)

fh auto runs a story through an 8-phase state machine and exits at each checkpoint for human review. The phases:

| Phase | What happens | |---|---| | analyzing | Reads the story card and project context | | planning | Generates an implementation plan (saved to runs/<id>/plan.md) | | gate-1 | Human checkpoint — review the plan before implementation starts | | implementing | Claude implements the plan on a new branch (feat/US-N) | | testing | Runs the test suite; records testsPassed in outcomes.jsonl | | escalating | Tests failed — Claude attempts a fix (up to 3 attempts) | | gate-2 | Human checkpoint — review the diff before PR is opened | | gate-stuck | All 3 attempts failed — always escalates to human, never skippable | | pr-creating | Opens a PR via gh pr create | | done | Run complete; outcome recorded |

With --auto, gate-1 and gate-2 are skipped automatically. gate-stuck is never skipped regardless of flags. Run state is persisted to .forgehive/runs/<run-id>/state.yaml — runs survive session restarts and can be resumed with fh auto resume.

Outcome Tracking

fh outcomes                     # summary table: last 10 runs, per-agent averages

fh outcomes shows a summary of all runs logged to .forgehive/outcomes.jsonl. Both fh auto runs and review/security party runs write to this store.

Auto run signals: testsPassed, attempts (up to 3), prMerged (updated lazily on next status check)

Party run signals: findingsCount, blockingCount (Kai), testGaps (Sam), docGaps (Eli)

Rating: After each review party, ForgeHive asks [1-5 oder Enter zum Überspringen]. The rating is stored in the run's outcome entry and feeds fh next recommendations.

The store rotates automatically at 500 entries (keeps last 400) — same pattern as watch-events.jsonl.

Intelligence Layer

fh next                         # show current phase and primary recommendation

fh next tells you exactly what to do next — which lifecycle phase you're in and the single most valuable action. It also appears as a compact Section 4 in fh status.

Phase detection (8 rules, priority order):

| Phase | Condition | |---|---| | health-check | Security scan age > 7 days | | implementing | Stories in-sprint + active fh auto run or no open PRs | | review | Stories in-sprint + open PRs with no recent review party | | closing-sprint | Done stories not yet in velocity record | | planning | Stories in backlog, none in-sprint | | kickoff | No stories at all | | solutioning | Epics exist with no linked stories |

Recommendations include outcome refinement when ≥ 3 historical data points exist for an agent + task type:

Phase: Implementation

  2 Stories in Sprint:
    US-3: Add rate limiting to auth endpoints
    US-5: Fix session timeout bug

Empfehlung:
  → fh auto US-3
    Kai löst deine Bug-Fixes im Schnitt 8 Min (40% schneller als Ø)

Auch fällig:
  → fh security scan  (letzter Scan vor 9 Tagen)

At most one secondary recommendation is ever shown — highest priority wins when multiple hygiene items apply.

Security Suite

The security suite consists of five commands:

fh security scan

fh security scan

Runs two scanners in sequence:

1. Secret Scanner — searches all source files for exposed credentials using 8 regex patterns:

   • Anthropic API keys (sk-ant-...)
   • OpenAI API keys (sk-... non-Anthropic)
   • GitHub tokens (ghp_...)
   • AWS Access Key IDs (AKIA...)
   • Slack bot tokens (xoxb-...)
   • PEM private keys (-----BEGIN ... PRIVATE KEY)
   • Generic password assignments (password = "...")
   • Generic token assignments (token = "...")

2. SAST Scanner — static analysis for 6 vulnerability classes:

   • SQL Injection (HIGH)
   • XSS / unescaped output (HIGH)
   • eval() usage (HIGH)
   • Path traversal (../ in file operations) (MEDIUM)
   • Weak random numbers (Math.random() in security contexts) (LOW)
   • Hardcoded credentials in source (CRITICAL)

Exit codes: exits 1 if CRITICAL or HIGH findings exist — safe to use in CI pipelines.

Secrets are never stored verbatim. Findings show only the first 6 characters followed by ***.

fh security deps

fh security deps

Runs npm audit and formats the output. Shows vulnerable packages grouped by severity (critical, high, moderate, low) with CVE identifiers and fix recommendations.

fh security report

fh security report          # no compliance framework
fh security report gdpr     # GDPR-specific checks and recommendations
fh security report soc2     # SOC 2 Type II relevant controls
fh security report hipaa    # HIPAA technical safeguard checklist

Generates a Markdown CISO report at .forgehive/security-report.md. The report includes:

• Overall risk score (CLEAN / LOW / MEDIUM / HIGH / CRITICAL)
• Secret scan results
• SAST findings with file paths and line numbers
• Dependency vulnerabilities
• Compliance-mode-specific recommendations and gaps
• Timestamp and project metadata

fh security audit

fh security audit

Displays the audit trail — every fh security command execution is logged in JSONL format to .forgehive/audit.log. Shows timestamp, command, user, and outcome. Useful for compliance documentation.

fh security permissions

fh security permissions

Shows permissions.yaml — the file access control list for each agent. Each agent (Nora, Eli, Remy, Suki, Viktor, Kai, Sam, Vera) has explicit read, write, and deny lists. This prevents agents from accidentally touching files outside their scope.

CI

fh ci                          # run CI health report (text output)
fh ci --format json            # output report as JSON
fh ci --format markdown        # output report as Markdown
fh ci --fail-on critical       # exit 1 only on CRITICAL findings
fh ci --fail-on high           # exit 1 on HIGH or CRITICAL
fh ci --fail-on any            # exit 1 on any finding
fh ci --init                   # generate a GitHub Actions workflow template

fh ci aggregates security scan, dependency audit, and test results into a single CI health report. Use --init to scaffold a .github/workflows/forgehive.yml file that runs the full check on every pull request. The --fail-on flag controls which severity level causes a non-zero exit code, giving you fine-grained control over what blocks a merge.

Codebase Map

fh map                  # full map + semantic graph (written to map.md)
fh map --semantic       # print only the semantic graph to stdout

fh map writes a structured table of your codebase — file paths, line counts, and import relationships — to map.md. It also runs a full semantic analysis and appends a ## Semantic Graph section to the file.

The semantic graph shows:

• Hotspots — files imported by 3+ others (sorted by import count), indicating high-impact modules
• Cycles — circular dependency chains detected via DFS
• Dependency summary — total files, edges, and average fanout

fh map --semantic prints only the ## Semantic Graph block to stdout — useful for piping directly into a Claude session as focused context.

Onboarding

fh onboard                     # generate ONBOARDING.md (stdout)
fh onboard --output ./ONBOARDING.md   # write to file

Generates a human-readable ONBOARDING.md from three sources: the detected stack in capabilities.yaml, the persistent memory in .forgehive/memory/, and the recent git log. The result is a self-contained document a new team member can read to understand the project architecture, conventions, and current state.

Changelog

fh changelog                        # full changelog from all commits
fh changelog --since v0.6.0         # changes since a specific tag
fh changelog --output CHANGELOG.md  # write to file

Parses conventional commits (feat:, fix:, chore:, docs:, etc.) and groups them into a semantic changelog. Breaking changes are surfaced separately. Requires conventional commit messages — standard for projects that use fh git-conventions.

Docs

fh docs                                        # list existing documentation
fh docs user [--output path]                   # generate user guide → docs/user-guide.md
fh docs api  [--output path]                   # generate API reference → docs/api.md
fh docs onboard [--output path]                # generate onboarding doc → ONBOARDING.md
fh docs changelog [--since tag] [--output path] # generate changelog → CHANGELOG.md
fh docs adr "<title>"                          # create Architecture Decision Record

Generates documentation from your project's stack, memory, and git history. Each subcommand writes to a default path inside docs/ (created if missing) or to the path given via --output. fh docs user and fh docs api write to docs/user-guide.md and docs/api.md respectively. fh docs adr creates a numbered ADR file in .forgehive/memory/adrs/.

fh docs onboard and fh onboard both generate onboarding documentation — they share the same generator. fh docs onboard allows specifying a custom --output path; fh onboard writes to stdout by default.

Developer Metrics

fh metrics                          # all-time developer metrics
fh metrics --since 2025-01-01       # metrics since a date

Shows commit activity broken down by author and commit type (feat, fix, chore, docs, test, refactor). Also shows rolling statistics: commit frequency, most active contributors, and type distribution. Useful for retrospectives and identifying contribution patterns.

Team Memory Sync

fh sync push                                           # push memory to default remote/branch
fh sync push --remote origin --branch forgehive-memory  # push to a specific remote branch
fh sync pull                                           # pull memory from remote
fh sync pull --remote origin --branch forgehive-memory  # pull from specific branch

fh sync shares .forgehive/memory/ across the team by pushing to (or pulling from) a dedicated git branch. This is an alternative to committing the memory directory into the main branch. On pull, existing local files are not overwritten — only new files are added, the same idempotent behavior as fh memory snapshot import.

Background Agent Execution

fh run <issue-url>                         # run agent on a GitHub/Linear issue URL
fh run <issue-url> --agent kai             # use a specific agent
fh run <issue-url> --label ready-for-ai   # filter by label
fh run "fix the login bug in auth.ts"      # freetext → routed to best agent automatically

fh run launches a background agent via claude -p, passes the issue content as context, and returns immediately. The agent reads the issue, applies forgehive context from .forgehive/, and works on the task in the background. Useful for automating repetitive issues or running agents overnight. Agent output is streamed to stdout and also written to .forgehive/runs/.

When the argument is not a URL, fh run delegates to the same routing logic as fh ask and recommends the right agent or party set with a concrete start command.

Intelligent Routing

fh ask "fix the login timeout bug"
fh ask "write integration tests for the payment service"
fh ask "design the new onboarding flow"

fh ask analyzes the task description and recommends the right agent or party set. It returns:

• Which agent or party to use (with confidence level: high / medium / low)
• Why — which keywords triggered the match
• Exact command to start — either cd <worktree> && claude for a single agent or fh party run <set> for a party

Routing table:

| Keywords | Routes to | |---|---| | security, vulnerability, auth, OWASP | Vera (security analyst) | | test, coverage, spec, assertion | Sam (QA architect) | | design, UI, UX, figma, wireframe | Suki (UX designer) | | architecture, scalability, refactor structure | Viktor (system architect) | | docs, README, onboarding, tutorial | Eli (documentation) | | research, compare, analyze, investigate | Nora (research analyst) | | product, roadmap, PRD, user story | Remy (product strategist) | | bug, fix, crash, error, regression | Kai (senior engineer) | | 3+ domains | full party | | security + review | security party | | architecture + QA | refactor party | | architecture + engineering | build party | | database, migration, ORM, prisma, query | db-party | | API, endpoint, route, REST, fastapi, express | api-party | | docker, kubernetes, terraform, infra, deploy | infra-party | | test coverage, jest, vitest, playwright | quality-party |

Memory

Memory files live in .forgehive/memory/ and are read by Claude at session start via the CLAUDE.md block.

| Command | Description | |---|---| | fh memory | Show all memory file contents | | fh memory show | Same as above | | fh memory clean | Delete state files older than 30 days | | fh memory export | Export all memory to a single Markdown file (stdout) | | fh memory export ./backup.md | Export to a specific path | | fh memory prune 60 | List memory files not updated in 60 days | | fh memory prune 60 --remove | Same, but delete them | | fh memory snapshot export | Export memory as a JSON bundle (for team sharing) | | fh memory snapshot export ./team-memory.json | Export to path | | fh memory snapshot import ./team-memory.json | Import bundle (skips existing files) | | fh memory adr list | List all Architecture Decision Records | | fh memory adr "Use Postgres over MongoDB" | Create a new ADR |

Memory files created by fh init:

| File | Purpose | |---|---| | MEMORY.md | Index file — lists all other memory files | | project.md | Project context, open decisions, goals | | feedback.md | Corrections and confirmed approaches from Claude sessions | | stack.md | Stack details the scanner can't detect (auth patterns, deploy targets) | | adrs/ | Architecture Decision Records |

Team snapshots: fh memory snapshot export bundles all memory files into a single JSON file you can commit or share. fh memory snapshot import imports it idempotently — existing files are never overwritten, only new files are added.

Story Cards

Story cards are lightweight user stories stored in .forgehive/memory/stories/. They integrate with /fh-sprint for velocity-based sprint planning.

fh story create "As a user I want to log in"            # create a story (auto-numbered US-N)
fh story create "As a user I want to log in" --epic EPC-1 --points 3   # with epic + points
fh story list                                            # list all backlog stories
fh story list --epic EPC-1                              # filter by epic
fh story show US-1                                       # show full story card with acceptance criteria
fh story sprint US-1                                     # mark story as in-sprint (pulled into current sprint)
fh story done US-1                                       # mark story as done
fh story done US-1 --points 5                           # mark done and record actual points

Each story card is a Markdown file at .forgehive/memory/stories/US-N.md. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (backlog | in-sprint | done). Stories move through backlog → in-sprint → done. When you run /fh-sprint in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.

Epics

Epics group related stories and are stored in .forgehive/memory/epics/.

fh epic create "User Authentication"                              # create an epic (auto-numbered EPC-N)
fh epic create "User Authentication" --goal "Users can log in securely"  # with a goal statement
fh epic create "User Authentication" --prd PRD-1                  # link to a PRD at creation time
fh epic list                                                       # list all epics
fh epic show EPC-1                                                 # show epic with linked stories and point total

Each epic card is a Markdown file at .forgehive/memory/epics/EPC-N.md. fh epic show aggregates all stories linked to the epic and displays their status and point totals.

Product Workflow

fh product manages the full PRD → Epic → Story pipeline.

PRDs (Product Requirements Documents)

fh product prd "User Authentication"       # create PRD-N (auto-incremented)
fh product list                            # list all PRDs with status and date
fh product show PRD-1                      # print full PRD content

PRDs are stored in .forgehive/memory/prds/ as YYYY-MM-DD-<slug>.md with a standard template (Overview, Goals, Non-Goals, User Stories, Success Metrics, Open Questions).

Pipeline Overview

fh product status                          # tree view: PRDs → Epics → Stories
fh product roadmap                         # generate ROADMAP.md from all PRDs + Epics + Stories

fh product status prints a tree of all PRDs, linked epics, and their stories with status indicators. Epics without a PRD are shown at the bottom as orphans.

fh product roadmap writes a ROADMAP.md to the project root with a section per PRD, linked epic tables, and story counts.

Typical product workflow:

fh product prd "Onboarding Redesign"
fh epic create "Welcome Flow" --prd PRD-1 --goal "Users complete setup in < 5 min"
fh story create "As a new user I want to see a setup checklist" --epic EPC-1 --points 3
fh product status                          # see full pipeline
fh product roadmap                         # generate ROADMAP.md

GitHub Integration

fh github setup                            # interactive: token + owner/repo; writes ~/.forgehive/credentials.json
fh github sync                             # fetch open Issues → create Story cards (idempotent)
fh github pr 42                            # fetch PR #42 metadata + changed files → .forgehive/github-pr-42.md

Setup

fh github setup prompts for a GitHub personal access token (saved to ~/.forgehive/credentials.json) and the repository in owner/repo format (saved to .forgehive/github.yaml). Run once; subsequent commands read the stored config.

Issue Sync

fh github sync fetches all open GitHub Issues (not PRs) and creates a Story card for each one. It's idempotent — issues already synced (detected by GitHub: #N in the story file) are skipped.

✓ Synced: #12 "Add OAuth login"     → US-4
✓ Synced: #15 "Fix session timeout" → US-5
→ Skipped: #10 "Refactor auth module" (already synced)

PR Context

fh github pr 42 fetches the PR title, body, author, and full list of changed files, writing a .forgehive/github-pr-42.md context file. Share this with a Review Party for structured code review:

fh github pr 42
fh party run review    # Kai + Sam + Eli each see the PR context

Velocity

fh velocity show                                              # velocity history + rolling average + recommendation
fh velocity record sprint-3 --committed 21 --delivered 18    # record sprint data

fh velocity show reads the velocity history from .forgehive/memory/velocity.md and prints:

• A table of past sprints (committed vs. delivered points)
• A rolling average (last 3 sprints)
• A capacity recommendation for the next sprint

fh velocity record appends a new entry to the velocity history. The /fh-sprint slash command reads this data automatically and uses it to calibrate the sprint scope it suggests.

Party Mode

Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.

fh party                    # show current party configuration
fh party --set build        # set default party to 'build'
fh party run                # start the default party
fh party run security       # start the security party specifically
fh party status             # show active party session
fh party cleanup            # remove finished worktrees

Available party sets:

| Set | Agents | Claude Code trigger | |---|---|---| | build | Viktor + Kai + Sam | /party | | design | Suki + Viktor | /design-party | | review | Kai + Sam + Eli | /review-party | | security | Felix + Vera | /security-party | | db-party | Mira + Sam | — | | api-party | Aria + Kai | — | | infra-party | Hugo + Vera | — | | quality-party | Zara + Sam | — | | full | All agents | /full-party |

Multi-model routing — defaults.yaml supports a models: key per agent set. Override via CLI:

fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"

Party execution modes:

| Set | Mode | Reason | |---|---|---| | build (Viktor + Kai + Sam) | Worktrees | Write code in parallel — filesystem isolation required | | design (Suki + Viktor) | Worktrees | Design artifacts + code — isolation required | | review (Kai + Sam + Eli) | Subagents | Review only — real independent opinions matter more than isolation | | security (Vera + Sam) | Subagents | Security review + test gap analysis — no code writing |

Specialist Agents (v1.3.0):

| Agent | Role | Triggers | |---|---|---| | Felix | Security Architect | jwt, auth, oauth2, bcrypt, next-auth | | Mira | Database Architect | prisma, typeorm, drizzle, sequelize | | Aria | API Architect | express, fastify, nestjs, hono, rails | | Leo | Performance Architect | react, vue, next, nodejs, angular | | Hugo | Infrastructure Architect | docker, kubernetes, terraform, helm | | Zara | Test Architect | jest, vitest, pytest, rspec, cypress |

How worktree isolation works: fh party run creates one git worktree per agent under .forgehive/worktrees/<agent-name>/. Each agent works in its own branch and filesystem copy. Worktrees are cleaned up with fh party cleanup or automatically when the session ends cleanly.

How subagent parties work: Review and security parties spawn independent claude -p subprocesses with focused context (diff only — no full project history). Each agent responds independently and cannot see the other agents' output. ForgeHive synthesizes the three reviews into a final verdict.

MCP (Model Context Protocol)

Quick wiring for common services

fh wire linear       # configure Linear MCP server in .mcp.json
fh wire slack        # configure Slack MCP server
fh wire github       # configure GitHub MCP server

Supported services for fh wire: linear, slack, github, sentry, notion, postgres, jira, pagerduty, datadog, figma

This writes the correct MCP server configuration to .mcp.json in the project root. Claude Code picks up .mcp.json automatically.

Credential management

API keys are stored encrypted at ~/.forgehive/credentials.json (chmod 600, user-only access):

fh mcp auth add github GITHUB_TOKEN=ghp_yourtoken
fh mcp auth add linear LINEAR_API_KEY=lin_api_key
fh mcp auth add slack SLACK_BOT_TOKEN=xoxb-... SLACK_TEAM_ID=T123

fh mcp auth list             # show which services have stored credentials
fh mcp auth remove github    # delete credentials for a service

Registry search and install

fh mcp search "database"              # search Smithery registry
fh mcp add @modelcontextprotocol/server-postgres
fh mcp add @smithery/some-server --env API_KEY SECRET_KEY

Trust Layer: fh mcp add checks the npm scope before installing. Trusted scopes:

• @modelcontextprotocol — official MCP servers
• @anthropic — Anthropic packages
• @smithery — Smithery registry
• @github — GitHub packages
• @microsoft — Microsoft packages

Unscoped packages or unknown scopes trigger a warning before installation proceeds.

Skills

Skills are Markdown instruction files that Claude reads when you reference them in a session.

fh skills list              # show all available skills
fh skills regen             # regenerate skills from templates (AI-assisted)
fh skills pull <git-url>    # pull expert skills from a team git repo

Pulling team skills:

fh skills pull https://github.com/my-team/ai-skills.git

Clones the repo with --depth=1, copies all .md files from the skills/expert/ subdirectory (or root if no skills/expert/ exists) into .forgehive/skills/expert/. Existing files are not overwritten.

Expert Skills installed by fh init (16 files):

| Skill | Coverage | |---|---| | typescript-patterns | Type-safe patterns, generics, discriminated unions | | testing-strategies | TDD, test design, coverage strategies | | api-design | REST, versioning, error responses | | git-conventions | Commit messages, branching, PR hygiene | | error-handling | Error hierarchies, recovery patterns | | security-checklist | Pre-deploy security review | | performance-patterns | Profiling, caching, async patterns | | code-review | Review checklist and feedback patterns | | clean-architecture | Dependency rules, layering, boundaries | | database-patterns | Query optimization, migrations, indexing | | monorepo-patterns | Workspace setup, shared packages, tooling | | observability | Logging, tracing, metrics | | owasp-top10 | A01–A10 with TypeScript examples | | auth-security | bcrypt, JWT, session security, MFA | | gdpr-compliance | PII classification, consent, right to erasure | | security-checklist | SAST integration, secret management |

Slash Commands

The following slash commands are available inside Claude Code sessions:

| Command | Description | |---|---| | /fh-sprint | Sprint planning — reads backlog, velocity, and capacity; suggests scope using Fibonacci points (1/2/3/5/8/13); records velocity at end of sprint | | /fh-deploy | Pre-deploy checklist — security scan, dependency audit, test run, final confirmation | | /fh-test-this | Generate tests for the current file or selection — uses testing-strategies skill | | /fh-docs | Generate documentation for the current file or module | | /party | Start the build party (Viktor + Kai + Sam) | | /design-party | Start the design party (Suki + Viktor) | | /review-party | Start the review party (Kai + Sam + Eli) | | /security-party | Start the security party (Vera + Sam) | | /full-party | Start all 8 agents |

/fh-sprint in detail: Reads .forgehive/memory/stories/ for backlog items, .forgehive/memory/velocity.md for historical capacity, and .forgehive/memory/epics/ for epic context. Suggests a sprint scope as a list of story cards with Fibonacci point estimates. When you close the sprint, it prompts you to record delivered points so velocity history stays up to date. If Linear or GitHub MCP servers are connected, it can pull issues directly from those services.

What fh init Creates

my-project/
  .forgehive/
    capabilities.yaml          <- detected stack (status: draft -> confirmed)
    scan-result.yaml           <- raw scanner output
    .scan-hash                 <- checksum for fh scan --check
    harness/
      architecture.md          <- codebase overview for Claude
      constraints.yaml         <- max_lines, require_tests, style rules
      permissions.yaml         <- per-agent file access control (read/write/deny)
    memory/
      MEMORY.md                <- index of all memory files
      project.md               <- project context and open decisions
      feedback.md              <- corrections + confirmed approaches
      stack.md                 <- stack details the scanner can't detect
      adrs/                    <- architecture decision records
      stories/                 <- story cards (US-N.md)
      epics/                   <- epic cards (EPC-N.md)
      prds/                    <- Product Requirements Documents (PRD-N.md)
      velocity.md              <- sprint velocity history
    skills/
      generated/               <- AI-generated skills (fh skills regen)
      expert/                  <- 16 preinstalled expert skills
      workflows/               <- MCP workflow skills
    worktrees/                 <- isolated git worktrees (fh party run)
    runs/                      <- background agent output (fh run)
    audit.log                  <- JSONL audit trail (fh security commands)
    cost-config.yaml           <- spend limits (fh cost --limit/--alert)
  AGENTS.md                    <- cross-tool agent standard
  CLAUDE.md                    <- forgehive block inserted, rest preserved

CLAUDE.md Merge Behavior

fh init never overwrites CLAUDE.md. Three cases:

| State | Action | |---|---| | No CLAUDE.md exists | Create new file with forgehive block | | CLAUDE.md exists, no forgehive block | Append block at the end | | CLAUDE.md exists, block already present | Replace only the block |

The block is delimited by <!-- forgehive:start --> and <!-- forgehive:end --> markers. fh rollback removes exactly this block and nothing else.

AGENTS.md — Cross-Tool Standard

fh init generates AGENTS.md in the project root following the Linux Foundation / AAIF standard. This file is read automatically by:

• Cursor — agent behavior configuration
• GitHub Copilot — workspace instructions
• Gemini CLI — project context
• OpenAI Codex — coding guidelines
• Windsurf — agent policies

You only maintain one file; all tools benefit.

Agents

| Agent | Role | Party Sets | |---|---|---| | Nora | Senior Research Analyst | full | | Eli | Technical Writer | review, full | | Remy | Creative Strategist | full | | Suki | UX Designer | design, full | | Viktor | System Architect | build, design, full | | Kai | Senior Engineer | build, review, full | | Sam | QA & Test Architect | build, review, security, full | | Vera | Security Analyst (OWASP, GDPR, Auth) | security, full |

Guardrails

fh init installs a Bash hook at .claude/settings.json that blocks:

Secrets in staged git files:

• Anthropic API keys (sk-ant-...)
• GitHub tokens (ghp_...)
• AWS Access Key IDs (AKIA...)
• Slack bot tokens (xoxb-...)
• PEM private keys

Dangerous commands:

• git push --force
• git reset --hard
• rm -rf /
• DROP TABLE

The hook fires on every bash command execution in Claude Code and exits 1 if a match is found.

Typical Workflows

New project setup

cd my-project
fh init
fh confirm
# Open Claude Code -> Claude now has full context

After adding new dependencies

npm install new-package
fh scan --update    # re-scan to pick up new dependency
fh confirm          # re-confirm the updated capabilities

Weekly security check

fh security scan            # check for secrets and SAST issues
fh security deps            # check for new CVEs in dependencies
fh security report gdpr     # update compliance report

CI integration

fh ci --init                  # scaffold .github/workflows/forgehive.yml
fh ci --format markdown --fail-on high   # use in existing CI scripts

Generating onboarding documentation

fh map                        # review codebase structure
fh onboard --output ONBOARDING.md   # generate onboarding document
git add ONBOARDING.md
git commit -m "docs: add forgehive-generated onboarding"

Generating a changelog

fh changelog --since v0.6.0 --output CHANGELOG.md

Sprint planning

# Set up your backlog
fh epic create "User Authentication" --goal "Users can log in securely"
fh story create "As a user I want to log in" --epic EPC-1 --points 3
fh story create "As a user I want to reset my password" --epic EPC-1 --points 2

# Check current velocity
fh velocity show

# Open Claude Code and run:
# /fh-sprint
# Claude reads velocity + backlog and suggests scope

# At end of sprint
fh velocity record sprint-1 --committed 13 --delivered 11
fh story done US-1
fh story done US-2

Sharing context with the team

fh memory snapshot export ./team-context.json
git add team-context.json
git commit -m "chore: update shared forgehive context"

# On another machine:
fh memory snapshot import ./team-context.json

# Or use the sync approach (no committed file):
fh sync push --remote origin --branch forgehive-memory
# teammate runs:
fh sync pull --remote origin --branch forgehive-memory

Starting a multi-agent build session

fh party --set build
fh party run
# -> Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
# -> Each Claude Code session opens in its own isolated worktree

fh party status     # check what's running
fh party cleanup    # clean up after the session

Connecting Linear and GitHub

fh wire linear
fh mcp auth add linear LINEAR_API_KEY=lin_api_...

fh wire github
fh mcp auth add github GITHUB_TOKEN=ghp_...

# Credentials stored at ~/.forgehive/credentials.json (chmod 600)
fh mcp auth list    # verify both services are stored

Running a background agent on an issue

fh run https://github.com/my-org/my-repo/issues/42 --agent kai
# Kai reads the issue, applies forgehive context, works in background
# Output streamed to stdout and saved to .forgehive/runs/

Configuration Files

.forgehive/capabilities.yaml

Auto-generated by fh init, confirmed by fh confirm. Contains:

• status: draft | confirmed
• Detected language, framework, package manager
• Key directories and entry points
• Test configuration

Edit this file manually to correct anything the scanner got wrong, then run fh confirm again.

.forgehive/harness/constraints.yaml

Defines Claude's behavior rules for this project:

• max_lines_per_file: soft limit for file size
• require_tests: whether to require tests for new code
• test_framework: which test runner to use
• Style and formatting preferences

.forgehive/harness/permissions.yaml

Per-agent file access control. Default permissions are conservative — agents can only read/write files relevant to their role. Edit to expand or restrict access.

~/.forgehive/credentials.json

Global credential store (chmod 600). Managed exclusively via fh mcp auth commands — do not edit manually.

Tech Stack

| | | |---|---| | Runtime | Node.js ≥ 18, ESM | | Language | TypeScript | | Build | esbuild -> dist/cli.js (~302.3 KB, single bundle) | | Type check | tsc --noEmit | | Tests | node:test (native) + tsx ESM loader, 398 tests | | Dependencies | js-yaml (sole runtime dependency) |

npm run build       # esbuild -> dist/cli.js
npm run typecheck   # tsc --noEmit
npm test            # node --import tsx/esm --test test/*.test.ts

Changelog

| Version | What's new | |---|---| | 1.0.0 | Autonomous Loop (fh auto), Outcome Tracking (fh outcomes), Smart Party Mode (subagent-based review/security), Intelligence Layer (fh next) | | 0.9.0 | Daily Driver: fh status dashboard (sprint · code health · watch events), fh watch --smart (test runner + agent routing), session-start auto-status | | 0.8.0 | GitHub Integration (fh github setup/sync/pr), Semantic Repo-Map (fh map --semantic), Intelligent Routing (fh ask), Product Workflow (fh product prd/status/roadmap) | | 0.7.7 | User Guide (docs/user-guide.md) included in npm package; Documentation table in README | | 0.7.6 | YAML shape fix in fh docs user; frontmatter regex fix; 8 new tests for HIGH RISK paths | | 0.7.5 | fh --version reads from package.json (no longer hardcoded) | | 0.7.4 | Party slash commands installed by fh init (/party, /review-party, /design-party, /full-party, /security-party) | | 0.7.3 | User Docs generation (fh docs user, fh docs api, fh docs list) | | 0.7.2 | fh --help, fh init --force, fh story sprint, fh velocity show fixes | | 0.7.1 | Story Cards, Epics, Velocity tracking | | 0.7.0 | CI, Map, Onboard, Changelog, Metrics, Sync, Background agents |

License

Elastic License 2.0 (ELv2) — kostenlos selbst hosten für den eigenen Betrieb. Weiterverkauf als Managed Service nicht erlaubt.