| name | forgeplan-cookbook |
| description | Live reference for the 66 mcp__forgeplan__* MCP tools and the 82 forgeplan CLI subcommands shipped in forgeplan 0.32.1. Agents and humans consult this skill when they know what they want to do (create an artifact, score a graph, dispatch sub-agents, detect anomalies) but don't yet know which tool name to call. Organised by use-case (lifecycle / discovery / quality / health / AI-driven / multi-agent / brownfield / activity / FPF / playbooks / plugins / release / safety) rather than alphabetically. Each section maps tools to canonical use-cases + which Profile A / B / C / D agent or which skill should call them. Includes known safety warnings (forgeplan#350 MCP body literal-string-only, forgeplan#348 score-all hint typo, forgeplan#351 plugins doctor install syntax).
Triggers: "forgeplan tool reference", "which forgeplan command", "forgeplan-cookbook", "/forgeplan-cookbook", "what mcp tool", "how do I create artifact via mcp", "forgeplan cli vs mcp", "forgeplan capabilities"
|
| origin | forgeplan |
forgeplan-cookbook — tool reference for agents and humans
A working agent often knows what it wants to do (create a PRD, score the graph, find blind spots) but not which forgeplan tool name to call. This cookbook is the router. It is loaded lazily — start with this index, then read one section deeper when you have a use-case match.
What is and isn't here
- Is: every
mcp__forgeplan__* MCP tool + every forgeplan CLI subcommand in forgeplan 0.32.1. Mapped to use-case, owner profile, and canonical example.
- Is not: detailed schema for each tool. Schema lives in the MCP tool description itself (via
ToolSearch for deferred MCP tools, or forgeplan <cmd> --help for CLI). This cookbook tells you which tool to call; the tool itself tells you the exact arguments.
Surface picker — MCP vs CLI
For artifact lifecycle work — prefer MCP (mcp__forgeplan__*). MCP returns typed dicts with _next_action hints, is observed by the activity log automatically, and integrates with agent-frontmatter disallowedTools denylists.
For shell scripting, CI, or human exploration — CLI is fine. Behaviour is symmetric except where noted in section 14-mcp-safety.
If neither is available (no MCP wiring, no forgeplan on $PATH) — escalate to the user. Do not invent intermediate state.
Section index
| Section | Coverage | Tool count |
|---|
01-lifecycle | CRUD + lifecycle transitions (new / get / update / delete / activate / supersede / deprecate / link / unlink / restore / undo_last) | 11 |
02-discovery-and-search | Find existing artifacts (list / search / graph / order / journal) | 5 |
03-quality-gates | Validate, score, review, calibrate depth, estimate effort | 5 |
04-pipeline-health | Anomalies, blind spots, blocked, orphans, contradictions, coverage, decay, drift, stale, health, status | 11 |
05-session-and-phase | Methodology session phase (idle/routing/.../pr) + artifact lifecycle phase (shape/.../done) | 4 |
06-ai-driven-commands | Commands that require an LLM provider (reason / generate / decompose / capture / route) | 5 |
07-multi-agent-coordination | Claim / release locks + parallel-safe dispatch (claim / claims / release / dispatch) | 4 |
08-brownfield-discovery | Brownfield protocol (discover_, hypothesis_, interview_packet_*) | 7 |
09-activity-and-audit | Activity log query + workspace init / export / import / ingest | 6 |
10-fpf-knowledge-base | FPF (First Principles Framework) KB query + rule introspection | 5 |
11-playbooks | Declarative YAML orchestration (PRD-065 / SPEC-003) | 4 |
12-plugins-registry | Installed plugin detection + doctor health-check + info | 3 |
13-release-notes | Generate Keep-a-Changelog notes from git refs | 1 |
14-mcp-safety-warnings | Known bugs + safe patterns + filed upstream issues | n/a |
Quick router — by intent
Ownership matrix — who calls what
The CRUD-R-A profile system (see plugins/fpl-skills/AGENT-AUTHORING-GUIDE.md) constrains which agent profile is allowed to call which mutation. The cookbook respects that. When a section maps a tool to "owner: Profile A", it means Profile B / C / D agents physically cannot call it because their disallowedTools denies it.
| Operation | Owner profile | Tool examples |
|---|
| CREATE (new artifact) | Profile A | forgeplan_new, forgeplan_generate |
| READ (any) | Any | forgeplan_get, forgeplan_list, forgeplan_search |
| UPDATE (body / metadata) | Profile A (own kind), Profile D (cross-kind metadata) | forgeplan_update |
| LINK | Profile A | forgeplan_link, forgeplan_unlink |
| ACTIVATE / SUPERSEDE / DEPRECATE | Orchestrator (not agents) | forgeplan_activate, forgeplan_supersede, forgeplan_deprecate |
| REVIEW (read + emit EVID) | Profile B | forgeplan_validate, forgeplan_score, forgeplan_review |
| GATE | Profile B-gate (guardian) | reads everything, mutates nothing |
| RESEARCH | Profile C | read-only set: forgeplan_search, forgeplan_get, forgeplan_graph |
| SOURCE MUTATION | Profile C-coder | Write / Edit on source files; never calls forgeplan tools |
Reference docs
forgeplan --help — canonical CLI subcommand list (82 in 0.32.1).ToolSearch query="mcp__forgeplan" — canonical MCP tool surface (66 in 0.32.1).plugins/fpl-skills/AGENT-AUTHORING-GUIDE.md — Profile A / B / C / D / D-orchestrator definitions + disallowedTools patterns.AGENTS.md ## Cross-CLI compatibility — MCP registration + canonical wiring command.forgeplan reason --help — explicit list of which commands need LLM (only reason, generate, decompose, capture, route LLM-mode).
When NOT to use this cookbook
- You already know the tool name and only need the argument schema → call the tool directly; its description carries the schema.
- You are writing source code in the user's project → that is Profile C-coder territory; forgeplan tools are not relevant.
- You are debugging a forgeplan bug → file upstream at ForgePlan/forgeplan/issues. Three filed 2026-05-27: #348, #350, #351.
Anti-patterns
- ❌ Reading every section "to be thorough" — load only the section matching your intent. Agentic RAG, not exhaustive recall.
- ❌ Re-implementing what a forgeplan tool already does (e.g., manually parsing artifact frontmatter when
forgeplan_get returns typed dict).
- ❌ Treating MCP and CLI as identical surfaces. Section
14 lists 3 documented asymmetries; expect more to surface over time.
- ❌ Skipping the
14-mcp-safety section before writing artifact bodies. The @filepath data-loss bug is silent and consequential.
Last verified: forgeplan 0.32.1, marketplace catalog 1.78.1, fpl-skills 1.37.1 (2026-05-27).
