### Example Usage Source: https://forgeplan.dev/docs/cli/discover-start Examples showing how to start a session and the typical brownfield workflow. ```shell # Start a named session in the current workspace forgeplan discover start "Auth System Onboarding" # Typical brownfield flow forgeplan init -y forgeplan discover start "Legacy API Mapping" # agent now executes the printed protocol, calling discover_finding via MCP forgeplan discover show forgeplan discover complete ``` -------------------------------- ### forgeplan discover complete examples Source: https://forgeplan.dev/docs/cli/discover-complete Shows a basic completion example and a full onboarding loop. The loop runs init, start, show, complete, then creates proposed artifacts with `forgeplan new`. ```bash forgeplan discover complete disc-001 # Full onboarding loop forgeplan init -y forgeplan discover start # ... agent runs ... forgeplan discover show disc-001 forgeplan discover complete disc-001 # → proposals printed; create the ones you accept forgeplan new prob "Auth drift between docs and code" forgeplan new prd "Unified config loader" ``` -------------------------------- ### forgeplan fpf status examples Source: https://forgeplan.dev/docs/cli/fpf-status Shows two usage examples: a simple status check and a typical workflow for a fresh workspace. The workflow starts with init, verifies the KB is empty, ingests it, then confirms the section count. ```bash # Check KB status forgeplan fpf status # Common "empty workspace" flow forgeplan init -y forgeplan fpf status # → not ingested forgeplan fpf ingest forgeplan fpf status # → ingested, N sections ``` -------------------------------- ### forgeplan fpf ingest examples Source: https://forgeplan.dev/docs/cli/fpf-ingest Shows common usage examples: first-time setup, re-ingest after upgrade, and ingesting from an external directory. ```bash # First-time setup - uses bundled spec forgeplan init -y forgeplan fpf ingest # Re-ingest after upgrade forgeplan fpf ingest forgeplan fpf status # Ingest from an external FPF sections directory forgeplan fpf ingest --path ./fpf-sections/ ``` -------------------------------- ### forgeplan discover show examples Source: https://forgeplan.dev/docs/cli/discover-show Shows example invocations of discover show. The first two lines demonstrate basic usage and piping to less. The commented block shows a typical mid-run check: start a session, let the agent run, then show the session. ```bash forgeplan discover show disc-001 forgeplan discover show disc-001 | less # Typical mid-run check forgeplan discover start # ...agent runs for a while... forgeplan discover show disc-001 ``` -------------------------------- ### Examples: forgeplan fpf section Source: https://forgeplan.dev/docs/cli/fpf-section Shows several example invocations of `forgeplan fpf section`. The first retrieves the full B.3 section (trust calculus), the second uses `--summary` to get only the first 500 characters, and the remaining examples fetch the B.4 and C.1 sections. ```bash # Trust calculus (the FPF B.3 section that defines R_eff semantics) forgeplan fpf section B.3 # Just the first 500 chars when you only need the gist forgeplan fpf section B.3 --summary # Explore/exploit reasoning forgeplan fpf section B.4 # ADI cycle forgeplan fpf section C.1 ``` -------------------------------- ### forgeplan_discover_start example invocation Source: https://forgeplan.dev/docs/mcp/forgeplan_discover_start Example JSON input for forgeplan_discover_start, providing the project_name parameter. ```json { "project_name": "legacy-billing-service" } ``` -------------------------------- ### Pre-activation review example Source: https://forgeplan.dev/docs/cli/review Pre-activation check example. Run this before activating an artifact to see its review verdict. ```bash forgeplan review PRD-001 ``` -------------------------------- ### Example 1: Session start check with healthy output Source: https://forgeplan.dev/docs/cli/health Runs a basic health check and shows the typical healthy output. Use this to verify the workspace has no blind spots, orphans, stale, or at-risk artifacts. ```bash forgeplan health ``` ```text Project Health ============== Artifacts: 147 (PRD: 42, RFC: 18, ADR: 12, Evidence: 56, ...) Active: 98 Blind spots: 0 Orphans: 0 Stale: 0 At risk: 0 Project looks healthy! ``` -------------------------------- ### Example 3: Capture then promote to ADR when it matters Source: https://forgeplan.dev/docs/cli/capture Starts with a Note for minimal friction, then creates an ADR and links the Note if the decision proves load-bearing. Shows the full workflow of capture, new adr, and link. ```bash forgeplan capture "use LanceDB as derived index, markdown as source of truth" \ --context "ADR-003 principle: files are authoritative, lance/ is gitignored" # Later, if the decision proves load-bearing: forgeplan new adr "LanceDB as derived index" forgeplan link NOTE-NNN ADR-005 --relation informs ``` -------------------------------- ### Initialize Forgeplan workspace and verify MCP Source: https://forgeplan.dev/docs/guides/mcp-setup Run these commands after installing Forgeplan MCP. Restart your AI client first, then initialize a workspace with `forgeplan init -y`, and finally ask the agent to use the `forgeplan_health` tool to verify the setup. ```bash # 1. Restart your AI client to load the new config # (Claude Code, Cursor, Windsurf - fully quit and re-open) # 2. In your project directory, initialize a workspace forgeplan init -y # 3. Verify MCP is wired up # Ask the AI agent: "use forgeplan_health to check the project" ``` -------------------------------- ### Install Forgeplan CLI with Homebrew Source: https://forgeplan.dev/docs/getting-started/installation Install the Forgeplan CLI using Homebrew. ```bash brew install ForgePlan/tap/forgeplan ``` -------------------------------- ### Example invocation: session_id parameter Source: https://forgeplan.dev/docs/mcp/forgeplan_discover_complete Example JSON input for forgeplan_discover_complete, providing the session_id from forgeplan_discover_start. ```json { "session_id": "discover-legacy-billing-service-2026-04-11T10:15:00Z" } ``` -------------------------------- ### Install Forgeplan CLI with Cargo Source: https://forgeplan.dev/docs/getting-started/installation Install the Forgeplan CLI using Cargo. ```bash cargo install forgeplan-cli ``` -------------------------------- ### forgeplan_discover_finding response example Source: https://forgeplan.dev/docs/mcp/forgeplan_discover_finding Example response returned by forgeplan_discover_finding after creating an artifact. Shows the artifact ID, session ID, phase, tier, and a linked confirmation flag. ```json { "artifact_id": "NOTE-087", "session_id": "discover-legacy-billing-service-2026-04-11T10:15:00Z", "phase": "code", "tier": 1, "linked": true } ``` -------------------------------- ### Install /forge skill with forgeplan setup-skill Source: https://forgeplan.dev/docs/getting-started/installation Installs the /forge skill for Claude Code, Cursor, Codex, Gemini and 40+ AI agents. Writes ~/.claude/skills/forge/SKILL.md, no network required. ```bash forgeplan setup-skill # writes ~/.claude/skills/forge/SKILL.md, no network ``` -------------------------------- ### Examples: full dashboard and session-start combo Source: https://forgeplan.dev/docs/cli/fpf-dashboard Shows two example invocations. The first runs the full dashboard alone. The second shows a typical session-start combo that runs forgeplan health, then the dashboard, then forgeplan blocked. ```bash # Full dashboard forgeplan fpf dashboard # Typical session-start combo forgeplan health forgeplan fpf dashboard forgeplan blocked ``` -------------------------------- ### Example invocation for forgeplan_estimate Source: https://forgeplan.dev/docs/mcp/forgeplan_estimate Example JSON request to call forgeplan_estimate with my_grade set to true to get personal hours. ```json { "id": "PRD-039", "my_grade": true } ``` -------------------------------- ### forgeplan fpf examples Source: https://forgeplan.dev/docs/cli/fpf Shows common workflows: ingest after init, explore the KB, search for context, and apply rules to artifacts. ```bash # One-time setup after forgeplan init forgeplan fpf ingest # Explore the KB forgeplan fpf status forgeplan fpf list forgeplan fpf section B.3 # Pull first-principles context into your reasoning forgeplan fpf search "trust calculus" forgeplan fpf search "bounded context" # Apply FPF rules to the project and specific artifacts forgeplan fpf dashboard forgeplan fpf rules forgeplan fpf check PRD-019 ``` -------------------------------- ### Example rendered Mermaid graph Source: https://forgeplan.dev/docs/cli/graph Example Mermaid graph TD output showing nodes and edges. Active artifacts get solid outlines; superseded/deprecated ones get dashed outlines if the renderer supports the class definitions at the top. ```mermaid graph TD EPIC_003[EPIC-003
Search, Discovery] PRD_039[PRD-039
BM25 production] RFC_004[RFC-004
Layered search] EVID_018[EVID-018
Benchmark] EPIC_003 --> PRD_039 PRD_039 --> RFC_004 EVID_018 -.informs.-> PRD_039 ``` -------------------------------- ### Full-month rollup invocation Source: https://forgeplan.dev/docs/mcp/forgeplan_activity_stats Example invocation with since_hours set to 720 to get a 30-day rollup. ```json { "since_hours": 720 } ``` -------------------------------- ### Set up a fresh clone with forgeplan init and scan-import Source: https://forgeplan.dev/docs/getting-started/configuration Fresh clone workflow: clone the repository, initialize Forgeplan non-interactively, edit the generated config.yaml to set the LLM provider and API key environment variable, then rebuild the lance/ index from tracked markdown and verify with forgeplan list. ```bash git clone && cd forgeplan init -y # creates .forgeplan/config.yaml + empty lance/ $EDITOR .forgeplan/config.yaml # set llm.provider, model, api_key_env export GEMINI_API_KEY=... # or whichever provider you chose forgeplan scan-import # rebuilds lance/ from tracked markdown forgeplan list # verify artefacts are back ``` -------------------------------- ### Usage Syntax Source: https://forgeplan.dev/docs/cli/discover-start The basic syntax for the discover start command. ```shell forgeplan discover start ``` -------------------------------- ### forgeplan_activity invocation: last hour Source: https://forgeplan.dev/docs/mcp/forgeplan_activity Example invocation to get activity for the last hour using the since_hours parameter set to 1. ```json { "since_hours": 1 } ``` -------------------------------- ### Start MCP server: forgeplan mcp serve Source: https://forgeplan.dev/docs/cli/mcp-serve Shows the primary command and its equivalent alias. Both start the same MCP server (stdio transport, 73 tools, one workspace) and exit on Ctrl-C. Use the alias for consistency after running forgeplan mcp install. ```bash forgeplan mcp serve ``` ```bash forgeplan serve ``` -------------------------------- ### Example: build, embed, and semantic search Source: https://forgeplan.dev/docs/cli/embed Complete workflow: build with semantic search, generate embeddings, then run a semantic search. ```bash # Build with semantic search enabled cargo install --path crates/forgeplan-cli --features semantic-search # Generate embeddings for the whole workspace forgeplan embed # Now semantic search works forgeplan search "trust calculus" --semantic ``` -------------------------------- ### forgeplan_session return value (active session) Source: https://forgeplan.dev/docs/mcp/forgeplan_session Example return value when a session is active. Shows the current phase, active artifact, depth, enforcement flag, start time, and a history of phase transitions. ```json { "phase": "coding", "active_artifact": "PRD-042", "depth": "standard", "enforcement": "enabled", "started_at": "2026-04-11T09:17:00Z", "history": [ { "phase": "routing", "at": "2026-04-11T09:05:00Z" }, { "phase": "shaping", "at": "2026-04-11T09:10:00Z" }, { "phase": "coding", "at": "2026-04-11T09:17:00Z" } ] } ``` -------------------------------- ### Good hint: Next command with rationale Source: https://forgeplan.dev/docs/methodology/agent-protocol Shows a specific, full command with a real ID and rationale explaining why the action is recommended. ```text Next: forgeplan score PRD-001 R_eff is 0 - link evidence to enable activation ``` -------------------------------- ### Example 3: Brownfield onboarding with custom path Source: https://forgeplan.dev/docs/cli/scan-import Points the scanner at a non-standard directory. Useful when legacy docs live under docs/, architecture/, or decisions/ instead of .forgeplan/. ```bash forgeplan init -y forgeplan scan-import --path docs/architecture forgeplan list forgeplan health ``` -------------------------------- ### forgeplan watch - example session Source: https://forgeplan.dev/docs/cli/watch Start the watcher in one terminal, then edit a markdown file in another terminal and search immediately. The daemon logs sync events and picks up changes without manual reindex. ```bash # Start the watcher in one terminal $ forgeplan watch [watch] observing .forgeplan/ (Ctrl-C to stop) [watch] synced prds/prd-001-auth.md (1 artifact) [watch] synced evidence/evid-042-benchmark.md (1 artifact) # In another terminal, edit and save - the daemon picks it up $ vim .forgeplan/prds/prd-001-auth.md $ forgeplan search "auth" # sees the new content immediately ``` -------------------------------- ### Example 2: Health with debt and next actions Source: https://forgeplan.dev/docs/cli/health Shows the health output when the workspace has debt (blind spots, orphans, stale). The output lists next actions to fix each issue before starting new work. ```bash forgeplan health ``` ```text Project Health ============== Blind spots: 2 - PRD-019 (active, 0 evidence, R_eff=0.00) - RFC-007 (active, 0 evidence, R_eff=0.00) Orphans: 1 - NOTE-033 (no parent, no children, no links) Stale: 3 - ADR-004 (valid_until 2026-03-01, expired 41 days ago) At risk: 0 Next actions: 1. Create EvidencePack for PRD-019 and RFC-007 2. Link NOTE-033 to its parent or deprecate 3. Review and renew/supersede ADR-004 ``` -------------------------------- ### forgeplan git-sync example Source: https://forgeplan.dev/docs/cli/git-sync Examples of using git-sync: default (since last pull/merge), explicit diff base against origin/main, and checking what a PR branch brought in with --since dev. ```bash # Default - since last pull/merge forgeplan git-sync # Explicit diff base (e.g. against main) forgeplan git-sync --since origin/main # Check what a PR branch brought in git checkout feat/prd-050-discover forgeplan git-sync --since dev ``` -------------------------------- ### Full pipeline from idea to sprint plan Source: https://forgeplan.dev/docs/cli/decompose Example showing the complete workflow from routing an idea to creating and validating an RFC. ```bash forgeplan route "add OAuth2 login flow" # -> Standard, PRD -> RFC forgeplan new prd "OAuth2 login flow" # -> PRD-042 # ... fill MUST sections ... forgeplan validate PRD-042 # PASS forgeplan reason PRD-042 --fpf # ADI cycle forgeplan decompose PRD-042 # -> RFC-018 draft forgeplan validate RFC-018 # sanity check ``` -------------------------------- ### Example 1: Quick rule-based routing (default) Source: https://forgeplan.dev/docs/cli/route Runs the route command with default keyword-based routing. The output shows a Standard depth, PRD → RFC pipeline, 88% confidence, and alternatives. ```bash forgeplan route "add rate limiting to API" ``` ```text Depth: Standard Pipeline: PRD → RFC Confidence: 88% Rationale: new capability, multiple components, reversible within a sprint Alternatives: - Deep (if rate limiter is cross-service) - Tactical (if single middleware with existing library) ``` -------------------------------- ### forgeplan_list invocation with kind and status filters Source: https://forgeplan.dev/docs/mcp/forgeplan_list Example invocation of forgeplan_list with kind and status filters. Returns only PRDs with active status. Typical agent context: starting a session, wants a quick snapshot of active work before reading any bodies. ```json { "kind": "prd", "status": "active" } ``` -------------------------------- ### Preview install for Windsurf (dry-run) Source: https://forgeplan.dev/docs/cli/mcp-install Prints the merged JSON for the windsurf client without making any filesystem changes. Inspect the diff, then re-run without --dry-run once happy. ```bash forgeplan mcp install --client windsurf --dry-run ``` -------------------------------- ### /do command Source: https://forgeplan.dev/docs/marketplace/dev-toolkit Takes any task description and figures out the right approach: research, build, audit, or a combination. ```text /do "add rate limiting to the API gateway" ``` -------------------------------- ### forgeplan_list invocation with status filter only Source: https://forgeplan.dev/docs/mcp/forgeplan_list Example invocation of forgeplan_list with only the status filter set to active. Returns all active artifacts regardless of kind. Typical agent context: starting a session, wants a quick snapshot of active work before reading any bodies. ```json { "status": "active" } ``` -------------------------------- ### /fpf decompose command example Source: https://forgeplan.dev/docs/guides/fpf Use /fpf decompose to break down a complex system into its parts. Outputs a table of context, responsibilities, key roles, and interfaces, plus a Mermaid diagram and category error check. Ideal for starting new features, understanding existing systems, or planning architecture. ```text /fpf decompose our authentication system ``` -------------------------------- ### forgeplan discover list usage examples Source: https://forgeplan.dev/docs/cli/discover-list Shows two usage examples: listing all sessions, and a typical recovery flow that lists sessions, then shows and completes a specific session by ID. ```bash # All sessions forgeplan discover list # Typical "where was I" recovery flow forgeplan discover list forgeplan discover show disc-002 forgeplan discover complete disc-002 ``` -------------------------------- ### Verify Forgeplan installation Source: https://forgeplan.dev/docs/getting-started/installation Checks the installed version and runs a health check to confirm the installation is working. ```bash forgeplan --version forgeplan health ``` -------------------------------- ### Verify the skill installation Source: https://forgeplan.dev/docs/cli/setup-skill Verifies the installation by running setup-skill and listing the user-global Claude Code skills directory. The output shows the single skill file SKILL.md landed correctly. ```bash forgeplan setup-skill ls ~/.claude/skills/forge/ # -> SKILL.md ``` -------------------------------- ### Install FPF as Claude Code plugin and CLI Source: https://forgeplan.dev/docs/guides/fpf Install FPF as a Claude Code plugin via the marketplace, or use the built-in CLI command to search FPF concepts. The plugin installation requires the marketplace add and install commands. ```bash # As Claude Code plugin /plugin marketplace add ForgePlan/marketplace /plugin install fpf@ForgePlan-marketplace # Or use built-in CLI forgeplan fpf search "trust" ``` -------------------------------- ### forgeplan init options Source: https://forgeplan.dev/docs/cli/init Lists the options for forgeplan init. Use --force to reinitialize even if .forgeplan/ exists, -y for non-interactive mode, --scan to import existing documents, and -h/-V for help and version. ```bash --force Force reinitialize even if .forgeplan/ exists -y, --yes Non-interactive mode (skip prompts, use defaults) --scan Scan for existing documents and import them -h, --help Print help -V, --version Print version ``` -------------------------------- ### forgeplan init usage Source: https://forgeplan.dev/docs/cli/init Shows the command-line syntax for forgeplan init. Use this to see the available options and flags. ```bash forgeplan init [OPTIONS] ``` -------------------------------- ### forgeplan get workflow diagram Source: https://forgeplan.dev/docs/cli/get Illustrates the workflow where list finds the artifact, get reads it, and subsequent commands act on it. This shows how get fits into the overall toolchain. ```text list (find it) → get (read it) → validate / reason / link / score (act on it) ``` -------------------------------- ### Worked example of /forge with rate limiting Source: https://forgeplan.dev/docs/marketplace/forgeplan-workflow Shows a full worked example of the /forge command, including the agent's tool calls and outputs. Demonstrates the complete cycle from routing to activation. ```text User: /forge "add rate limiting to the API" Agent: [calls forgeplan_route("add rate limiting to the API")] -> Depth: Standard, Pipeline: PRD -> RFC Agent: [calls forgeplan_new(kind: "prd", title: "API Rate Limiting")] -> Created PRD-042 Agent: [fills Problem, Goals, Non-Goals, FR sections] Agent: [calls forgeplan_validate("PRD-042")] -> PASS (0 MUST errors) Agent: [implements rate limiting middleware + tests] Agent: [calls forgeplan_new(kind: "evidence", title: "Rate limit tests -- 8 pass")] -> Created EVID-089 Agent: [calls forgeplan_link("EVID-089", "PRD-042", "informs")] Agent: [calls forgeplan_activate("PRD-042")] -> draft -> active, R_eff = 1.00 ``` -------------------------------- ### forgeplan_calibrate example invocation Source: https://forgeplan.dev/docs/mcp/forgeplan_calibrate Example invocation of forgeplan_calibrate with an artifact ID. ```json { "id": "PRD-042" } ``` -------------------------------- ### Install a specific plugin via npx Source: https://forgeplan.dev/docs/marketplace/overview Run inside a Claude Code session to add a plugin from the marketplace and install a specific plugin. Also installs the forge skill offline. ```bash # Install a specific plugin (run inside a Claude Code session) /plugin marketplace add ForgePlan/marketplace /plugin install dev-toolkit@ForgePlan-marketplace # Install the forge skill (methodology) — offline, no marketplace needed forgeplan setup-skill ``` -------------------------------- ### Bootstrap a new project with forgeplan init and setup-skill Source: https://forgeplan.dev/docs/cli/setup-skill Typical bootstrap sequence for a new project: create the workspace with forgeplan init -y, then install the Claude Code skill so /forge is immediately available in the next chat session. ```bash forgeplan init -y forgeplan setup-skill ``` -------------------------------- ### forgeplan reindex example workflows Source: https://forgeplan.dev/docs/cli/reindex Two example workflows: bootstrapping a fresh clone and syncing after manual markdown edits. The first runs init -y then reindex; the second edits a PRD then reindexes and searches. ```bash # Fresh clone bootstrap git clone && cd myproject forgeplan init -y forgeplan reindex forgeplan list # verify # After editing a PRD in your text editor vim .forgeplan/prds/prd-001-auth.md forgeplan reindex forgeplan search "auth" ```