Getting Started Checklist

This page is a single-page checklist. Work through it top to bottom. Each item is a concrete action you can complete in under two minutes. Links point to the full reference for each topic.

By the end you will have PACE installed, configured, a sprint plan written, and Day 1 running.

Pre-flight

Complete these before touching PACE.

Python 3.11 or 3.12 installed — confirm with python --version
A git repository with at least one commit — PACE needs a git history to operate
An Anthropic API key (or the key for your chosen LLM provider)
Your test suite runs locally and exits 0 — confirm with pytest, go test ./..., npm test, etc.
You know the exact command that runs your tests — this becomes tech.test_command in your config

Step 1 — Install PACE

Clone PACE into a pace/ subdirectory at your repo root:

git clone https://github.com/pace-framework-org/pace-framework-starter pace

Create and activate a virtual environment:

python -m venv pace/.venv
source pace/.venv/bin/activate

Install dependencies:

pip install PyYAML jsonschema anthropic

Verify the install:

python pace/pace/orchestrator.py --help

You should see the PACE usage message. If you get a ModuleNotFoundError, the virtualenv is not active — re-run the source command above.

Step 2 — Configure

Copy the example config to the expected location:

cp pace/pace.config.yaml.example pace/pace.config.yaml

Open pace/pace.config.yaml and fill in these required fields:

Field	What to set
`product.name`	Your product’s name
`product.description`	One paragraph describing what your product does
`source.dirs`	List of directories FORGE is allowed to read and write (e.g., `[src, tests]`)
`tech.test_command`	The exact command that runs your test suite (e.g., `pytest -q`)
`tech.primary_language`	e.g., `python`, `go`, `typescript`, `java`
`platform.ci`	Start with `local`; switch to `github` once verified locally

Optional: set llm.analysis_model: claude-haiku-4-5-20251001 for 40–50% cost savings on analysis steps

# pace/pace.config.yaml — minimum viable config
product:
  name: "My Product"
  description: "A service that does X for Y users."

source:
  dirs:
    - src
    - tests

tech:
  test_command: "pytest -q"
  primary_language: python

platform:
  ci: local

llm:
  analysis_model: claude-haiku-4-5-20251001   # optional cost saving

See Configure Your Project for every available field.

Step 3 — Set credentials

Export your API key in the same shell session where you will run PACE:

export ANTHROPIC_API_KEY="sk-ant-..."

Verify the key is importable:

python -c "import anthropic; print('OK')"

If you see OK, the library loaded and the key is present. If you see AuthenticationError, the key value is wrong.

See Environment Variables for all supported provider keys and optional variables.

Step 4 — Write plan.yaml

Create plan.yaml at your repo root (not inside pace/):

# plan.yaml — lives at your repo root
release: v1.0

stories:
  - id: story-1
    title: "Your first story title"
    status: pending
    acceptance_criteria:
      - "Feature behaves as described"
      - "pytest -q exits 0"

  - id: story-2
    title: "Your second story title"
    status: pending
    acceptance_criteria:
      - "Second feature works end to end"
      - "pytest -q exits 0"

Each story has: id: story-N, title, status: pending, and acceptance_criteria
Every story’s final acceptance criterion includes your test command (e.g., pytest -q exits 0)
Write at least 2 stories to start — you can add more later

See Write a Sprint Plan for full schema reference, story scoping guidance, and examples.

Step 5 — Run Day 0 (optional but recommended)

Day 0 runs the planner only — it does not write any code. It generates per-story cost estimates and pre-populates PROGRESS.md.

Run Day 0:

python pace/pace/orchestrator.py --day 0

Review the planner output:

cat .pace/day-0/planner.md

Review cost estimates in PROGRESS.md:

cat PROGRESS.md

If the estimates look reasonable, proceed to Day 1. If a story’s estimate is very high, it may be too large — consider splitting it before running FORGE.

See Day 0 — Sprint Planning for a walkthrough of the planner output.

Step 6 — Run Day 1

Run Day 1:

python pace/pace/orchestrator.py --day 1

Watch for [FORGE] output — FORGE reads your codebase, writes changes, and runs your tests
Wait for the pipeline to complete — the full run (PRIME → FORGE → GATE → SENTINEL → CONDUIT → SCRIBE) takes 2–10 minutes depending on story size and model

If GATE issues SHIP:

Review the PR summary in .pace/day-1/review-pr.md
Review the full artifact set in .pace/day-1/

If GATE issues HOLD:

Read the hold_reason printed in the terminal
See What to Do When PACE Issues a HOLD for step-by-step diagnosis and fix instructions
Review all Day 1 artifacts:

ls .pace/day-1/
cat .pace/day-1/gate-report.yaml
cat .pace/day-1/sentinel-report.yaml

After Day 1 ships — ongoing sprint

Review PROGRESS.md for actual vs estimated cost and retry count for Day 1
Advance to Day 2:

python pace/pace/orchestrator.py --day 2

For CI/CD integration: set platform.ci: github in pace/pace.config.yaml, then follow the GitHub Actions tutorial
If you want PACE to run on a schedule, see Scheduling

Common first-run failures

Error	Cause	Fix
`ModuleNotFoundError: pace`	Virtualenv not active	Run `source pace/.venv/bin/activate`
`ANTHROPIC_API_KEY not set`	Key not exported in current shell	Run `export ANTHROPIC_API_KEY="sk-ant-..."`
`plan.yaml not found`	`plan.yaml` created inside `pace/` instead of repo root	Move it: `mv pace/plan.yaml ./plan.yaml`
`GATE: HOLD — test_command failed`	Test suite was already failing before PACE ran	Run your test command manually and fix failures first
`FORGE: max_iterations reached`	Story scope too large for FORGE to complete	Add `out_of_scope` items or split into two stories
`platform adapter not found`	`platform.type` used instead of `platform.ci`	Replace `type:` with `ci:` in the `platform:` section