# Parcel Scaffold > Interactive 'what do you want to build?' flow that produces SPEC.md + a parcel chain ready to enqueue. Given 6 short questions, scaffold a complete parcel breakdown for a small CLI tool that pulls from a free no-key API (Hacker News, Wikipedia, GitHub public, PokeAPI). Optionally chain into a live build via rookery-daemon. Triggers on: scaffold a build, parcel-scaffold, build from spec, create parcels for, scaffold a parcel chain, generate parcels for a CLI, set up a new build, what do you want to build. - Skill: `0xdarkmatter/parcel-scaffold` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add 0xdarkmatter/parcel-scaffold` - Raw SKILL.md: https://api.skillmd.com/api/skills/0xdarkmatter/parcel-scaffold/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: 0xDarkMatter (https://skillmd.com/u/0xdarkmatter) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/0xdarkmatter/parcel-scaffold --- # Parcel Scaffold Bundled with **rookery** and works inside any rookery project. The upstream half of the parcel pipeline — turns a 6-question conversation into `SPEC.md` + a chain of 4 parcel files ready for `rookery enqueue`. Companion to `parcel-plan` (decomposes existing specs) and `parcel-generate` (renders prompts from a parcel breakdown). This skill differs by **starting from nothing**: no spec doc required. The reference example produces a **Hacker News top-stories CLI**. The same flow extends to other free no-key APIs (Wikipedia, GitHub public, PokeAPI) and other output styles (CLI rich tables, plain text, TUI, JSON). ## When to use - The user wants to demo or smoke-test rookery end-to-end and needs a build target - A new project is starting and you need a parcel chain to seed it - The user typed something like "scaffold a HN CLI" / "what do you want to build" / "set up a build for X" - You want to show "look, rookery builds real things" without an existing codebase ## When NOT to use - An existing spec doc already exists — use `parcel-plan` to decompose it, then `parcel-generate` for prompts - A parcel chain is already in `parcels/` and just needs running — skip straight to `rookery enqueue` - The user wants to add a feature to an existing codebase — use the regular `rookery parcel new` then hand-edit - The build target is bigger than ~4 parcels — this skill is sized for ~half-day demos, not multi-week features ## What this skill produces ``` parcels/ ├── SPEC.md # structured spec (the answers from Q1–Q5 in canonical form) ├── 01-scaffold.md # parcel: project skeleton (deps=[]) ├── 02-fetch.md # parcel: API client + tests (deps=[01-scaffold]) ├── 03-display.md # parcel: output formatter + tests (deps=[02-fetch]) └── 04-polish.md # parcel: README + docstrings + final QA (deps=[03-display]) ``` Each parcel is a runnable markdown prompt for a `claude -p` worker, with frontmatter, acceptance criteria, and the v0.3 verdict-helper invocation in the Verdict section. ## Workflow ### Step 1 — Verify project context Confirm we're inside a rookery project before generating files: ```bash test -f rookery.yaml && test -d parcels/ ``` If either is missing, tell the user to run `rookery init` first and stop. ### Step 2 — Ask the 6 questions Use `AskUserQuestion` once to ask all 6 at once (single call, multiple questions). The question set is defined in [references/question-flow.md](references/question-flow.md). **Read that file first** — it has the exact option lists, default-derivation rules, and the Q1-hint logic that pre-fills Q3 and Q4. Summary: 1. **What to build?** Pick from 4 example projects, or "Other". 2. **Project slug?** Derived defaults from Q1, or type your own. 3. **API / data source?** HN / Wikipedia / GitHub public / PokeAPI / Other (recommend HN for demos). 4. **Output / interface?** CLI rich / CLI plain / Rich TUI / JSON. 5. **Extras?** (multi-select) Defaults / GitHub Actions / caching / `--json` flag. 6. **Run mode?** Stop here / Auto-run / Auto-run + auto-land. ### Step 3 — Resolve the API + interface details Based on Q3, look up the API metadata in [references/api-catalog.md](references/api-catalog.md): - Base URL - Endpoints to use - Primary function signature - Response shape (pydantic model) Based on Q4, look up the output-style specifics in [references/output-styles.md](references/output-styles.md). ### Step 4 — Write SPEC.md Render `assets/spec-template.md` with the substituted variables: | Placeholder | Source | |---|---| | `{{slug}}` | Q2 | | `{{slug_snake}}` | Q2 with `-` → `_` | | `{{tagline}}` | Q1 (one-line summary) | | `{{description}}` | derived: 1 paragraph from Q1 + Q3 + Q4 | | `{{api_name}}` / `{{api_base_url}}` / `{{api_endpoints}}` / `{{api_response_shape}}` | api-catalog entry for Q3 | | `{{output_style}}` / `{{output_style_specifics}}` | output-styles entry for Q4 | | `{{extras_list}}` | Q5 selections, formatted as bullet list | | `{{date}}` | today's ISO date | Write to `parcels/SPEC.md` using `Write`. ### Step 5 — Render the 4 parcel files For each of `assets/parcel-01-scaffold.md`, `02-fetch.md`, `03-display.md`, `04-polish.md`: 1. Read the template 2. Substitute the same `{{...}}` placeholders 3. Write to `parcels/0N-.md` The substitution is mechanical. Don't paraphrase the template prose; just replace the braces. ### Step 6 — Validate `rookery parcel validate` takes one path at a time. Run a loop: ```bash for f in parcels/01-scaffold.md parcels/02-fetch.md parcels/03-display.md parcels/04-polish.md; do rookery parcel validate "$f" || exit 1 done ``` (SPEC.md is a documentation artifact, not a runnable parcel — don't validate it.) If any fail, surface the errors and stop. Don't proceed to Step 7. ### Step 7 — Branch on Q6 Three paths: #### 7a — Q6 = "Stop here" (default, recommended) Print the next-steps checklist: ``` ✓ Generated parcels/SPEC.md + 4 parcel files for {{slug}}. Review: cat parcels/SPEC.md rookery parcel validate parcels/*.md (already passed) bat parcels/01-scaffold.md (or however you read markdown) Run: for p in 01 02 03 04; do rookery enqueue $p-* done rookery-daemon # foreground; Ctrl-C to stop Watch: rookery summary # in another terminal rookery logs -f # tail any parcel's log rookery diff # review a parcel's diff before landing ``` Stop. Don't run anything. #### 7b — Q6 = "Auto-run" Run the **preflight** first — refuse to proceed on any FAIL: ```bash rookery doctor ``` If doctor exits non-zero, print the failures and stop. Tell the user how to fix and re-invoke the skill, OR re-answer Q6 as "Stop here" and they can fix it themselves. If doctor passes, show the cost estimate: ``` Auto-run will spawn 4 worker sessions: 01-scaffold → ~5–10k tokens 02-fetch → ~10–15k tokens 03-display → ~10–15k tokens 04-polish → ~5–10k tokens Total: ~30–50k tokens (≈ 5–10 cents at current pricing on Claude Max) Continue? [y/N] ``` Wait for explicit `y` / `yes` (use `AskUserQuestion` with a single confirm question if running inside a Claude Code session, or skip the prompt if running in headless mode). If confirmed, execute: ```bash rookery enqueue 01-scaffold rookery enqueue 02-fetch rookery enqueue 03-display rookery enqueue 04-polish rookery-daemon & DAEMON_PID=$! trap "rookery daemon-stop; wait $DAEMON_PID 2>/dev/null" EXIT INT TERM ``` Then tail progress per parcel (the chain runs serially because of the deps): ```bash for p in 01-scaffold 02-fetch 03-display 04-polish; do echo "=== watching $p ===" rookery logs "$p" --events --follow & TAIL_PID=$! # Wait for terminal status while true; do status=$(rookery status "$p" --json | jq -r '.status') case "$status" in done|failed|blocked|landed|merge-blocked) break ;; esac sleep 5 done kill $TAIL_PID 2>/dev/null echo " $p → $status" if [[ "$status" != "done" && "$status" != "landed" ]]; then echo " ABORT — $p did not reach a passing terminal state" break fi done rookery summary ``` Print a final summary table. #### 7c — Q6 = "Auto-run + auto-land" Same as 7b but **before** the `rookery enqueue` calls, edit each parcel's frontmatter to set `auto_land: true`: ```bash sd '^auto_land: false' 'auto_land: true' parcels/01-scaffold.md \ parcels/02-fetch.md \ parcels/03-display.md \ parcels/04-polish.md ``` (or `sed -i` if `sd` is unavailable). Then proceed with the same enqueue + daemon + watch loop. The `auto_land` flag makes the daemon merge each parcel branch into `main` after PASS. Note: this only works if the parent repo has a `main` branch and a clean working tree. Check before kicking off: ```bash git symbolic-ref --short HEAD # should be 'main' or default branch git status --porcelain | head -1 # should be empty ``` ### Step 8 — Final report Whatever path was taken, end with a one-line summary: ``` ✓ parcel-scaffold complete: {{slug}} ({{api_name}} → {{output_style}}) spec: parcels/SPEC.md parcels: 4 files (01-scaffold → 04-polish) run mode: status: ``` ## Conventions enforced | Convention | Source | |---|---| | Question flow | [references/question-flow.md](references/question-flow.md) | | API metadata | [references/api-catalog.md](references/api-catalog.md) | | Output styles | [references/output-styles.md](references/output-styles.md) | | 4-parcel CLI shape | [references/cli-template.md](references/cli-template.md) | | Parcel templates | `assets/parcel-0[1-4]-*.md` | | Spec template | `assets/spec-template.md` | | Verdict reporting | v0.3 `rookery parcel done` helper (in every parcel's Verdict section) | ## Files | File | Role | |---|---| | `SKILL.md` | This file — orchestrator | | `references/question-flow.md` | Full text of the 6 questions + default-derivation rules | | `references/api-catalog.md` | The 4 supported APIs (HN / Wikipedia / GitHub / PokeAPI) | | `references/output-styles.md` | Mapping Q4 answer → parcel-03 specifics | | `references/cli-template.md` | Why the 4-parcel chain decomposes the way it does | | `assets/spec-template.md` | SPEC.md template with `{{}}` placeholders | | `assets/parcel-01-scaffold.md` | Project-skeleton parcel template | | `assets/parcel-02-fetch.md` | API-client parcel template | | `assets/parcel-03-display.md` | Output-formatter parcel template | | `assets/parcel-04-polish.md` | Polish parcel template |