A long parchment scroll unrolled on the forge workbench, glowing rune lines tracing a winding path between three milestone shapes (a flat plate, a curve, and a small archway), an antique brass compass set at the top of the scroll, hammers and tools scattered around, the forge fire glowing warmly in the background
Quickstart · Step 2 of 3

Your First Plan

Specify, harden, and execute a feature in 15 minutes.

This is the essential path through Steps 0–3. For the full walkthrough (sweep, review, ship, and everything in between) see Chapter 6: Your First Plan.

Before you start: Complete Step 1: Install, pforge smith should show all green. Have VS Code open with GitHub Copilot active.

What We're Building

A GET /health endpoint, deliberately simple so you can focus on the pipeline, not the code. You'll run three steps: specify → harden → execute. The endpoint takes about 15 minutes to build; the pipeline knowledge you gain applies to every feature after this.

Step 0: Specify the Feature

  1. Open Copilot Chat: Ctrl+Shift+I (Windows) · Cmd+Shift+I (Mac)
  2. Select Agent Mode at the bottom of the chat panel
  3. Click 📎 attach file → select .github/prompts/step0-specify-feature.prompt.md
  4. Replace <FEATURE-NAME> with health-endpoint and send

The specifier agent interviews you. Here are the answers for a health endpoint:

Example answers
Problem:    Load balancers need to verify the service is running.
Scenarios:  GET /health every 30s → 200 OK {"status":"healthy"}.
Criteria:   Returns 200 with JSON. Under 50ms. No auth required.
Edge cases: DB unreachable → 503 {"status":"degraded","reason":"database"}.
Out of scope: No deep checks (Redis, APIs). No metrics endpoint.

The agent creates docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md.

Shortcut: Select the Specifier agent from the agent picker dropdown instead of attaching the prompt file. Same interview, handoff buttons included.

Step 1: Pre-flight Check

Still in the same session, attach .github/prompts/step1-preflight-check.prompt.md, replace <YOUR-PLAN> with Phase-1-HEALTH-ENDPOINT-PLAN, and send. The agent verifies git state, guardrail files, and the roadmap. For a fresh install, everything passes.

Step 2: Harden the Plan

Attach .github/prompts/step2-harden-plan.prompt.md, replace <YOUR-PLAN>, and send. The hardener adds the mandatory blocks to your plan file:

What a hardened plan looks like
## Scope Contract        ← Files the AI may touch
## MUST Criteria         ← Non-negotiable requirements
## Execution Slices      ← 30–120 min checkpointed chunks
  ### Slice N
    Tasks:  …
    Gate:   dotnet build && dotnet test   ← Must pass before next slice
    Stop if: Gate fails

## Rollback Plan         ← How to undo safely

When the agent says "Plan hardened", Session 1 is complete.

Step 3: Execute

Three ways to run execution, choose one:

🤖 Automatic
pforge run-plan docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

Kick off and walk away. Watch at localhost:3100/dashboard.

🤝 Assisted
pforge run-plan --assisted docs/plans/Phase-1-HEALTH-ENDPOINT-PLAN.md

You code; orchestrator validates gates automatically.

📋 Manual

Start a new Copilot session. Attach step3-execute-slice.prompt.md. The AI reads the plan and executes slice by slice.

The executor builds the endpoint, runs build, runs test, and reports pass/fail at each gate. If a gate fails, execution stops, no silent failures.

What Just Happened

You've completed Sessions 1 and 2 of the 4-session pipeline:

Sessions so far
Session 1 (Specify & Plan)  ✓  Described what you wanted; AI structured it
Session 2 (Execute)         ✓  AI built it slice-by-slice with validation gates
Session 3 (Review)          …  Next step →
Session 4 (Ship)            …  Final step →
✓ Plan executed! Continue to Step 3: Review & Ship →