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:

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. 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:

• 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.

Step 4 — Write SPEC.md

Render assets/spec-template.md with the substituted variables:

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-<name>.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:

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 <id> -f      # tail any parcel's log
  rookery diff <id>         # 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:

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:

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):

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:

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:

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: <stop / auto-run / auto-run + auto-land>
  status: <pending review / running / landed / failed>

Conventions enforced

Files