Forgeplan

https://forgeplan.dev/docs
Admin
Forgeplan turns unstructured thinking into structured artifacts with quality scoring, evidence...
Tokens:243,146
Snippets:2,595
Trust Score:2.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 <session-id>
forgeplan discover complete <session-id>
```

--------------------------------

### 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<br/>Search, Discovery]
  PRD_039[PRD-039<br/>BM25 production]
  RFC_004[RFC-004<br/>Layered search]
  EVID_018[EVID-018<br/>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 <repo> && cd <repo>
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 <NAME>
```

--------------------------------

### 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 <repo> && 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"

```
Tokens:
Raw