Getting Started · 05
Projects, PRDs, and the brainstorm-to-ship pipeline. Structure when you want it, freedom when you don't.
A project is a self-contained work package — a feature, a migration, a new service. It lives in a directory under your company, contains a prd.json (the source of truth), and tracks progress through user stories with pass/fail acceptance criteria.
Projects are created by /plan and executed by /run-project. They're optional — you can build anything in HQ without creating a project. But for multi-story features, they give you traceability: which stories are done, which workers ran, what decisions were made, and where the code landed.
Project Structure
What's in a PRD
User Stories
Each story has acceptance criteria, file targets, priority, worker assignments, and a pass/fail flag
Metadata
Company, repo path, branch name, quality gates (lint, test, typecheck, build)
Quality Gates
Run every 3 stories to catch regressions early. Configurable per project
E2E Tests
Optional per-story tests that verify the product works, not just the code
The full pipeline starts with a brainstorm, sharpens into a PRD, and executes with worker agents. Each stage is optional — jump in wherever your idea is ready.
The Development Pipeline
/brainstorm
Explore 2-3 approaches with effort estimates. Get a recommendation before committing.
optional
/plan
Discovery interview → structured PRD with stories, acceptance criteria, quality gates.
creates prd.json
/run-project
Execute stories with workers. Quality gates. Auto-commit. Back-pressure testing.
ships code
Each stage is optional. Jump straight to /plan if you know what you're building. Skip the pipeline entirely and code directly — HQ doesn't require projects for day-to-day work. The pipeline is there when you want structure and traceability.
Run /brainstorm [company] [idea] to explore approaches before committing to a plan. HQ generates 2-3 approaches with effort estimates (S/M/L/XL), states a recommendation, and saves to brainstorm.md in your project directory.
When you later run /plan on the same project, it detects the brainstorm file and pre-fills the interview questions — collapsing open-ended questions into confirmations. You answer faster and the PRD is better anchored.
2 approaches evaluated
Recommendation: B. WebSocket push — best effort/value tradeoff for your scale.
Run /plan [company] [description] to generate a structured PRD. HQ scans your company context (repos, policies, workers, existing projects), then runs a batched discovery interview — problem/success, users, scope, architecture, integrations, quality gates.
Output: prd.json with user stories, acceptance criteria, branch name, worker assignments, and quality gates. Each story is a discrete unit of work that can be executed independently.
Project acme-notifications created — 7 stories
Branch: feature/acme-notifications · Repo: repos/private/acme-app
Run /run-project [project-name] to execute the PRD. For each story: a worker agent is spawned, code is written and committed, back-pressure checks run (tests, lint, typecheck, build), and the story is marked passed or blocked.
Three execution modes let you choose the right level of control for the project.
/run-project Execution Modes
inline
(default)
Spawns worker agents per story phase in your current session. You see progress, can intervene.
interactive
--interactive
You make edits directly in the parent session. Pause between stories. Maximum control.
ralph
--ralph-mode
Unattended inline worker loop — auto-advances through every story without pausing. Best for big projects.
Story Execution Flow
Back-pressure
Tests, lint, typecheck, and build run after each story. Failures block the next story until fixed.
Quality Gates
Every 3 stories, a full quality gate runs to catch regressions across the project.
Projects, PRDs, and the pipeline are tools, not requirements. Plenty of HQ work is just opening a session, describing what you need, and building it directly. The pipeline exists for when you want structure — multi-story features, team coordination, or traceability on complex builds. Use what helps, skip what doesn't.