Get started.md
Concepts
| Concept | What it is |
|---|---|
| Company | The customer. It has members, projects, GitHub installations and its own harness. A person can belong to several companies. |
| Project | What is being built. It groups repos, specs, backlog, harness and autonomy level. |
| Repository | A code folder of the project on GitHub (front, back, infra…). It has an integration branch (develop) and a production branch (main). |
| Spec home | The repo where SpecKit's specs/ lives for that project. |
| Spec | A SpecKit feature: spec.md (what and why), plan.md (how) and tasks.md (tasks). |
| Harness | The rules your agents follow in a project: standards (AGENTS.md), commands and which decisions require a person. |
| Agent | Claude Code, Codex or another agent with CLI access, running on a developer's machine with their own subscription. |
| Phase / wave | A phase is a milestone with value (MVP, v1…). A wave is a group of tasks that share no files and can run in parallel. |
| Task classification | Every task has an area (docs, ui, api, core, data, infra, security), a size (XS–XL) and a risk (R0–R3). Risk decides how much documentation, review and approval it needs. |
| Subagent | A short-lived helper an agent launches: explorer (reads), verifier (runs checks), reviewer and challenger (adversarial review). |
| Report | Structured output an agent sends to ZPX Forge (spec, plan, progress, review, blocker, delivery). People read it as a view, not as a file. |
| Approval | A decision that requires a person: spec, architecture, risky action or production release. |
The life of a feature
Scope → spec.md → approval (PM/PO) → plan.md + tasks.md → backlog
→ a developer picks a task → their agent works in a worktree and a branch
→ PR to develop → review → approved release → main = production
Branches
| Branch | Purpose | Who changes it |
|---|---|---|
main | Production | Only through an approved release PR |
develop | Integration / staging | Through PRs from task branches |
feat/<task>-… | One task, short-lived | The developer and their agent |
Evidence and decisions
Declared evidence comes from the team. Observed evidence includes the result Forge reads from GitHub for the commit and agreed test. Accepted risks identify the reason and owner. The release owner decides whether to share the sheet. The customer decides whether to accept that version.