Pi Forge Command

the-forge is a local Pi package that adds /tdd: a ticket-driven TDD orchestration command for running one behavior slice at a time with explicit git checks, phase-specific agents, and prompt-injection boundaries around ticket text. It also adds /rolling for larger work that should be narrowed just in time with a fresh agent context for each ready item.

This README is the Diataxis-style orientation document for the project: it explains the mental model, the current package behavior, and where to find the reference and how-to details. Use the linked docs for exhaustive gate contracts, run-artifact proposals, and programmatic TDD instructions.

What Forge does

Forge turns a ticket, issue, pull request, URL, or current-branch context into a strict orchestration prompt for Pi. The extension itself gathers context and constructs the prompt; the receiving agent is then required to follow the Forge loop contract.

At a high level, a Forge run:

1. parses /tdd [ticket|issue|pr|url] [extra context], preserving any user context after the selector;
2. loads tolerant Forge settings from global and trusted project settings;
3. resolves phase agents from project/user overrides first, otherwise using the bundled local defaults without an install prompt;
4. gathers git context and available Linear/GitHub ticket evidence;
5. wraps external ticket text in an explicit untrusted-data boundary;
6. sends or queues a prompt that requires ticket-driven red/green/refactor work, deterministic git checks, and one final commit per behavior slice.

Forge is intentionally conservative: code-owned checks such as git status, file boundaries, command exit codes, and commit ancestry cannot be overridden by AI judgment. AI is used for semantic work such as requirement interpretation, behavior slicing, red-failure diagnosis, naming, and readability cleanup.

Quick start

1. Build the package

pnpm build

2. Test the built Pi package manifest

pi -e .

3. Install locally from this checkout

pi install /path/to/the-forge

For npm distribution, publish the package tarball after pnpm prepack. Pi discovers the package through the pi-package keyword and loads the compiled extension entry declared in package.json:

{
  "pi": {
    "extensions": ["./dist/extensions/forge.js"]
  }
}

4. Run Forge in a target repository

/tdd ABC-123 preserve this extra implementation context

If the session is idle, Forge sends the orchestration prompt immediately. If Pi is already running an agent, Forge queues the prompt as follow-up work and updates the Forge status line.

Command behavior

--local mode

When the --local flag is passed, Forge restricts all model selection to local providers only and tries the ordered local fallback list from ollama/ornith:35b downward:

• ollama/* (Ollama local models, starting with ollama/ornith:35b)
• lmstudio/* (LM Studio local models)
• local/* (other local provider adapters)

This ensures no data leaves the local machine, useful for air-gapped environments or when working with sensitive proprietary code.

Example:

/tdd ABC-123 --local implement user authentication flow

/tdd [ticket|issue|pr|url]

Starts a ticket-driven TDD orchestration prompt. The first token is treated as the selector; remaining text is preserved as additional user context.

Selectors that start with - are rejected before any external lookup command is called. This prevents user input such as --help from being passed to gh or linear as command flags.

When a selector is provided, Forge attempts to gather evidence from:

• GitHub pull request lookup;
• GitHub issue lookup;
• Linear issue lookup.

When no selector is provided, Forge attempts current-branch lookups instead:

• Linear branch issue id;
• Linear branch issue details;
• current-branch GitHub pull request.

Lookup failures are captured as evidence rather than treated as prompt instructions. The generated prompt labels lookup output as untrusted data:

<<<BEGIN UNTRUSTED TICKET DATA>>>
...external lookup output...
<<<END UNTRUSTED TICKET DATA>>>
Trusted Forge instructions resume after the end marker above.

/specmap [feature-path]

Runs the traceability preflight before Rolling Forge. When no path is provided, /specmap defaults to features, scans Gherkin scenarios, ensures stable Rule/Scenario tags, finds matching executable tests, and adds only high-confidence coverage tags. It prefers the lowest useful test level: unit when possible, integration when behavior crosses module boundaries, and e2e only when lower-level tests cannot prove the behavior.

Uncovered or ambiguous scenarios become candidate items for /rolling instead of silently creating false coverage links.

/specmap also updates the committed development trace registry under .bdd/trace/ before it sends the agent prompt. The same deterministic builder is available from package scripts:

pnpm trace:generate
pnpm trace:check

Trace files are generated from feature tags and test comments. Keep @covers comments next to the executable test they describe, and add repeatable @source comments for repository-relative files whose behavior that test protects:

// @covers @scenario-specmap-defaults-to-feature-files
// @source src/forge.ts
// @source src/specmap-trace.ts
test("/specmap defaults to feature files", async () => {
  // ...
});

The generated JSONL links scenarios to tests and source paths so contributors can find affected scenarios and tests when a source file changes. .bdd/trace/ is committed for development traceability but is not included in the published package files.

/rolling [ticket|issue|pr|url]

Starts Rolling Forge, a just-in-time variant for larger work where the future shape may change after each completed slice. /rolling shares Forge lookup, settings, agent availability, git context, model guidance, and deterministic safety rules with /tdd, but changes the planning contract:

• do not fully decompose the entire ticket up front;
• deeply plan only the next definitely useful, validated behavior item;
• run each ready item with a fresh agent context;
• carry forward only curated summaries and compact item packets;
• reassess the current code reality before promoting the next item.

See docs/rolling-forge.md for the planning contract.

How the Forge loop works

flowchart TD
    A[Intake] --> B[Grill Requirements]
    B --> C[Decompose]
    C --> D[Red: Failing Test]
    D --> E[Verify-Red]
    E --> F[Green: Production Fix]
    F --> G[Refactor]
    G --> H[Final-Verify]
    H --> I{All Slices Done?}
    I -->|No| D
    I -->|Yes| J[Cleanup & Commit]

The generated prompt requires the receiving agent to use the configured skills, phase agents, git checks, and validation commands. The core loop is:

1. Intake the ticket, branch context, linked docs, and repository evidence.
2. Grill requirements and edge cases until the behavior target is clear.
3. Decompose into the smallest behavior/test slices.
4. For each slice:
   • run git status and commit-range checks before any phase;
   • add one red behavior test with test-only changes;
   • verify the red failure is for the intended missing behavior;
   • create a temporary red checkpoint commit;
   • make the smallest production-only green change;
   • run cleanup/refactor only for production readability and duplication;
   • run final verification, including every configured validation command, with retries and connectedness classification for wider-suite failures;
   • squash red/green/cleanup into one final conventional commit whose parent is the recorded slice start commit.
5. Repeat until all ticket requirements and accepted edge cases are covered.
6. Clean up temporary branches, worktrees, checkpoint commits, and scratch files.

The package currently implements the Pi command, prompt construction, settings loading, context lookup, phase-agent packaging, and behavior tests for those surfaces. The detailed executable gate model is documented as the intended v1 safety contract in docs/deterministic-gates.md and docs/design-decisions.md.

Smart model profiles

Forge routes phase-agent dispatch through smart-model-run profiles instead of a single fixed model. Each phase gets optimized budget and capability settings:

| Phase | Budget | Thinking Level | Tools Required | |-------|--------|---------------|----------------| | intake | cheap | low | correctness, tools | | decompose | cheap | low | correctness, tools | | red | mid | medium | reliable-tools, correctness | | verify-red | mid | medium | correctness, tools | | green | mid | medium | reliable-tools, correctness | | refactor | cheap | low | tools | | final-verify | cheap | low | tools |

When --local is passed, these profiles call smart-model-run with local: true and the local fallback selectors, restrict to local providers (ollama/*, lmstudio/*, local/*), and try ollama/ornith:35b before moving down the local fallback list.

Phase agent tool access

Each phase agent receives a specific tool subset to enforce safety boundaries:

| Phase | Read-only tools | Editing tools | |-------|----------------|---------------| | intake | read, grep, find, ls, bash | read, grep, find, ls, bash | | decompose | read, grep, find, ls, bash | read, grep, find, ls, bash | | red | read, grep, find, ls, bash | read, grep, find, ls, bash, edit | | verify-red | read, grep, find, ls, bash | read, grep, find, ls, bash | | green | read, grep, find, ls, bash | read, grep, find, ls, bash, edit | | refactor | read, grep, find, ls, bash | read, grep, find, ls, bash, edit | | final-verify | read, grep, find, ls, bash | read, grep, find, ls, bash |

Phase agents

Forge bundles default Pi subagent prompts in agents/. They can be copied into a target repository's .pi/agents/ directory for customization.

• forge-intake: understands ticket evidence, edge cases, assumptions, and open questions. It is read-only unless explicitly asked to draft notes.
• forge-decompose: splits understood requirements into ordered one-behavior slices. It is read-only.
• forge-red: adds exactly one failing behavior test for the selected slice. It may edit tests, specs, or approved fixtures only.
• forge-verify-red: proves the red failure matches the intended missing behavior. It is read-only.
• forge-green: makes the smallest production change that passes the verified red test. It may edit production code only.
• forge-refactor: improves production readability after green without changing behavior. It is production-readability only.
• forge-final-verify: runs final checks, retries wider-suite failures, classifies whether failures are connected to the slice, and confirms git, file, and commit boundaries. It is read-only.

When /forge starts, it checks override locations first:

• project-local .pi/agents/;
• user-global ~/.pi/agent/agents/.

If an override exists for a Forge phase agent, the prompt reports that override. Otherwise Forge uses the bundled local default from agents/ directly and does not ask to install or copy agent files.

Forge's orchestration prompt routes phase-agent dispatch through smart-model-run profiles instead of one fixed model. Red and green use higher correctness/tool-reliability profiles; read-only planning and verification use cheaper profiles unless selection needs to escalate. When the user passes --local, those profiles pass local: true plus the local fallback selectors to smart-model-run, starting with ollama/ornith:35b before lower fallbacks.

Settings

Forge reads an optional forge section from Pi settings.

• Global settings: ~/.pi/agent/settings.json, read whenever present.
• Project settings: .pi/settings.json, read only when the project is trusted; valid values override global values.
• Test/debug override: PI_FORGE_GLOBAL_SETTINGS_PATH, which replaces the global settings path.
• Test/debug override: PI_FORGE_USER_AGENTS_DIR, which replaces the user agent directory.

Environment Variables

| Variable | Purpose | Default | | -------- | ------- | ------- | | PI_FORGE_GLOBAL_SETTINGS_PATH | Overrides global settings | ~/.pi/agent/settings.json | | PI_FORGE_USER_AGENTS_DIR | Overrides user agents | ~/.pi/agent/agents/ |

Supported settings are defined in src/forge-config.ts and the generated sample lives at docs/data/forge-settings.sample.json. Regenerate it after default changes:

pnpm generate:forge-settings

• retries defaults to 0 and controls external lookup command retries.

• timeoutMs defaults to 30000 and controls external lookup command timeouts.

• testCommands defaults to ["pnpm typecheck", "pnpm test"]. It is the ordered validation command list passed to the prompt. Final verification must run the full list before the final green commit. Wider-suite failures are retried and classified: connected failures block and return to green/refactor, unrelated or pre-existing failures are reported as watch items, and ambiguous failures become follow-up questions or near-final side investigations.

• skills defaults per Forge step. These skill names are required in the prompt for intake, decomposition, red, verify-red, green, refactor, and final verification. Legacy aliases are accepted with warnings:

• timeout is treated as timeoutMs;

• testCommand is normalized to testCommands: [testCommand].

Forge loads settings tolerantly. Missing files, missing forge, and omitted optional fields are quiet. Malformed JSON, untrusted project settings, legacy keys, unknown keys, and invalid values produce one warning notification plus a # Forge settings warnings prompt section that explains the source, key, outcome, and fix without echoing raw unsafe values.

Safety defaults

Forge's prompt contract requires these safeguards:

• Git CLI checks before and after every agent phase.
• Red agents may only change tests, specs, or approved fixtures.
• Green agents may only change production code.
• Verify agents must prove failures happen for the intended ticket reason, not syntax, imports, setup, timing, snapshots, leaked state, or unrelated breakage.
• Cleanup focuses on production readability, naming, simpler control flow, and duplication removal.
• Temporary red checkpoint commits must be squashed into one final commit per behavior slice.
• Final verification must run all configured validation commands, including the full unit test suite, before that final commit is created; retried wider-suite failures only stop coding when they are connected to the current slice or remain ambiguous without a recorded follow-up.
• Ticket lookup output is explicitly marked as untrusted before any agent reads it.

For the full gate list, see docs/deterministic-gates.md. For the detailed programmatic loop, see docs/tdd-microcycle-programmatic-guide.md.

Feature specifications

The repository uses Gherkin feature files as behavior contracts for how Forge functions. Existing feature coverage includes:

• features/verified-tdd-microcycle.feature: observable TDD micro-cycle behavior from slice selection through final verification.
• features/forge-keeps-user-context.feature: extra context after a ticket selector is preserved in the agent prompt.
• features/forge-labels-ticket-text-untrusted.feature: external ticket text is fenced as untrusted before trusted instructions resume.
• features/forge-settings-stay-synchronized.feature: documented settings samples stay synchronized with generated defaults.
• features/forge-settings-warnings.feature: invalid, legacy, malformed, or untrusted settings warn and fall back safely.
• features/forge-resolves-ticket-context.feature: ticket evidence lookup for explicit selectors and current-branch context.
• features/forge-blocks-unsafe-selectors.feature: dash-prefixed selectors are rejected before external commands are called.
• features/forge-dispatches-or-queues-orchestration.feature: idle sessions receive the prompt immediately; busy sessions queue follow-up work.
• features/forge-installs-phase-agents.feature: bundled local phase agents are used by default unless project or user overrides exist.
• features/forge-loads-settings-overrides.feature: global and trusted project settings are loaded, adapted, or warned safely.
• features/forge-captures-git-context.feature: initial working tree, branch, head, and upstream context are included when available.
• features/forge-validates-trusted-contributions.feature: CI validation runs for mainline and trusted contributor changes.

Known spec gaps are tracked in docs/documentation-backlog.md. In particular, planned run-artifact behavior under .tmp/.forge/runs/<slug>/ is documented in docs/run-artifacts.md but is not presented here as an implemented feature.

Development commands

pnpm build          # compile TypeScript into dist/
pnpm typecheck     # run TypeScript without emitting
pnpm test          # build, then run node --test test/*.test.mjs
pnpm prepack       # build before packing/publishing

The test suite checks prompt construction, settings loading, feature-spec alignment, bundled agent contracts, CI workflow expectations, and extension entrypoint delegation.

Requirements

• Pi with extension support.
• Git CLI in the target repository.
• Linear CLI (linear) when working from Linear issues.
• GitHub CLI (gh) when working from GitHub issues or pull requests.
• pnpm for local development of this package.

Current boundaries and roadmap

Accepted planning decisions live in docs/design-decisions.md. Important current boundaries:

• Forge's extension implementation constructs the orchestration prompt; it does not yet implement every deterministic gate as executable code.
• .tmp/.forge/runs/<slug>/ run artifacts are planned and documented, but remain a proposal until implemented.
• The public package includes bundled agents, docs, features, compiled output, README, and license.
• The GitHub wiki is exploratory and non-normative; accepted behavior belongs in committed docs/ and features/ files.

Documentation map

| Need | Start here | | --- | --- | | Understand the safety model | docs/design-decisions.md | | Follow the programmatic TDD loop | docs/tdd-microcycle-programmatic-guide.md | | Look up deterministic gates | docs/deterministic-gates.md | | Understand planned run artifacts | docs/run-artifacts.md | | Audit feature coverage | features/ | | Review bundled phase prompts | agents/ | | Track documentation gaps | docs/documentation-backlog.md |

License

MIT