From Idea to Shipped

Match the tool to the size of the thought

HQ turns ideas into shipped work through a planning ladder, four rungs from a ten-second note to a deep strategic plan, followed by execution commands that do the building. The most common mistake is starting on the wrong rung: over-planning a tiny idea, or under-planning a big one. This article gives you the sizing guide.

The planning ladder#

Rung 1: /idea, capture a one-liner (10 seconds)

Got a thought you don't want to lose? Capture it:

/idea customers keep asking for a self-serve pricing calculator

That's it. HQ writes the idea to your company's board (a company is an isolated workspace for one business or team, and its knowledge never mixes with other companies'). No plan, no questions, no commitment. You can add --company acme if HQ can't tell which company it belongs to.

Use when: you want to remember it, not work on it yet.

Rung 2: /brainstorm, explore a fuzzy idea (a few minutes)

When you have an idea but aren't sure how (or whether) to build it:

/brainstorm acme self-serve pricing calculator

HQ researches what your company already knows about the topic, challenges the premise ("is this even the right problem? what's the 80% solution?"), asks you at most one batch of questions, and writes a brainstorm.md comparing 2 to 3 approaches with tradeoffs and a clear recommendation. If you later promote it with /prd, the brainstorm pre-fills most of the interview.

Use when: the idea is fuzzy, there are multiple ways to do it, or you're not sure it's worth doing at all.

Rung 3: /prd, the standard plan (right for ~90% of projects)

/prd acme self-serve pricing calculator

This is the workhorse. HQ scans what it already knows (existing projects, relevant knowledge, your company's rules), then interviews you in short batches about the problem, who it's for, what's in and out of scope, quality checks, and how you'll know it works. It's the lightweight flow: a quick set of batched questions, faster still if a brainstorm already exists. For large or strategically important work, the heavier /deep-plan flow runs a longer, research-backed interview.

The output is a PRD. In plain English, that's a Product Requirements Document, the written plan HQ executes from. In HQ it's two files: prd.json (the machine-readable source of truth) and README.md (the human-readable view). Importantly, /prd only plans. It never starts building. Execution happens in a fresh session, on purpose.

Use when: you know what you want and it's more than a quick tweak. When in doubt, use /prd.

Rung 4: /deep-plan, big strategic work only

/deep-plan acme replace the billing system

Everything /prd does, plus parallel research agents that study your codebase and company context first, and a deeper three-tier interview (strategic, architecture, quality, up to 15 questions). It costs more of your time up front, which is exactly right for work that's large, strategically important, or touches unfamiliar territory, and wrong for everything else.

Use when: getting it wrong would be expensive. Otherwise, /prd.

Sizing guide at a glance

What's inside a PRD: stories and acceptance criteria#

A PRD breaks the project into user stories: small pieces of work, each completable in one session, with IDs like US-001, US-002. Each story has acceptance criteria: the specific, checkable statements that define done, like "the calculator shows a price after selecting a plan and seat count."

Acceptance criteria are how HQ knows it's actually done. Vague criteria produce vague work. "Works correctly" is not a criterion; "submitting the form with an empty email shows a validation error" is. This checking pressure is what keeps autonomous execution honest, so it's worth being picky during the /prd interview.

Execution: one story or the whole plan#

Once the PRD exists, start a fresh session (the plan even reminds you) and choose:

One story at a time with /execute-task:

/execute-task pricing-calculator/US-001

Executes exactly one story: specialized workers (persistent AI specialists, like a backend builder, a reviewer, and so on) each handle their part, automated checks (tests, linting) verify the work, and the story is marked passed only when its acceptance criteria hold. Good when you want to review between steps.

The whole PRD on its own with /run-project:

/run-project pricing-calculator

Runs story after story on its own: shows you the plan, gets your approval, then works through every incomplete story with a fresh worker per story. This story-by-story rhythm (pick a task, plan, execute, verify, commit, next) is the Ralph Loop, HQ's core execution pattern. Add --dry-run to preview the story order without executing, or --status to check progress.

A worked example, end to end#

Monday, in a meeting: someone mentions customers want a pricing calculator.

/idea customers keep asking for a self-serve pricing calculator

Tuesday, you have 20 minutes. You're not sure if it should live on the website or in the app:

/brainstorm acme self-serve pricing calculator

HQ compares "embed on marketing site" vs "build into the app," recommends the marketing site as the narrower first step, and flags one unknown (where the price list lives). Looks right.

/prd acme pricing calculator on the marketing site

The interview is quick because the brainstorm pre-filled most answers. You confirm scope, name the non-goals ("no currency conversion"), and tighten the acceptance criteria. Out comes a PRD with five stories, US-001 through US-005.

Wednesday, fresh session:

/run-project pricing-calculator

You approve the plan; HQ works through the stories, verifying each against its criteria. Story US-004 fails its check the first time (the validation error didn't show), so it's fixed before moving on. When it's done: /deploy for a live link to share with the team (Sharing your work), and /handoff to close out (The daily loop).

Common questions#

If you get stuck#

If /run-project or /execute-task says the command isn't available, your install may be missing the engineering pack. The /prd output prints the one-line install command. For anything else, see The "I'm stuck" guide or file /hq-bug.