Projects

Overview

Projects in HQ are structured task definitions that workers execute autonomously. The workflow:

/prd "Build X"  →  /run-project {project}  →  /execute-task (per story)

Starting from a brainstorm

/brainstorm "idea" explores approaches before you commit to a plan. It ends with three choices: Plan it now (writes prd.json in the same session, reusing your brainstorm answers), Upgrade to deep-plan, or Stop here.

Project glossary: GLOSSARY.md

Project and repo glossaries used by the tdd, diagnose, and wayfinder skills are named GLOSSARY.md. The old name, CONTEXT.md, is no longer read. Rename existing files with:

git mv CONTEXT.md GLOSSARY.md

Creating Projects with /prd

/prd "Build a REST API for user management"

/prd asks which company the project belongs to, then writes prd.json and a README.md to companies/{co}/projects/{name}/. Personal projects go under personal/projects/. A shortened prd.json:

{
  "name": "user-management-api",
  "description": "REST API for user CRUD operations",
  "branchName": "feature/user-api",
  "userStories": [
    {
      "id": "US-001",
      "title": "User registration endpoint",
      "description": "As a new user, I want to register with email and password so that I can sign in",
      "acceptanceCriteria": [
        "Returns 201 with user object",
        "Validates email format",
        "Hashes password before storage"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    }
  ],
  "metadata": {
    "goal": "Ship a user management API",
    "repoPath": "repos/private/my-api",
    "baseBranch": "main"
  }
}

After it writes the files, /prd saves a checkpoint so you can start execution in a fresh session.

The Ralph Loop

Projects execute via the Ralph methodology — an iterative loop of planning, execution, and validation:

1. Load PRD — Read project definition and current state
2. Pick Story — Select highest-priority pending story
3. Route to Workers — Architect → Developer → QA → Reviewer
4. Execute — Worker implements the story
5. Validate — Run tests, check acceptance criteria
6. Capture Learnings — /learn records insights
7. Repeat — Next story until project complete

Running a Project

/run-project {project}

The orchestrator:

• Reads the PRD
• Tracks state in workspace/orchestrator/{project}/
• Routes stories to appropriate workers through HQ worker lanes
• Validates completion
• Updates PRD status

Task Execution

Individual tasks execute through /execute-task:

/execute-task {project}/US-001

This runs a single story through the worker pipeline:

1. Analyze — Task executor examines the story requirements
2. Plan — Architect designs the approach
3. Implement — Developer(s) write code
4. Test — QA writes and runs tests
5. Review — Code reviewer validates
6. Complete — Mark story as done, capture learnings

Project State

Project execution state is tracked in workspace/orchestrator/{project}/:

• Current story being executed
• Worker assignments
• Completion status
• Errors and retries