pi-topdown-kit

Scaffold-first, top-down layered workflow for AI coding agents. The skeleton IS the plan.

AI coding agents jump to code too fast. The shape of the system emerges by accident — over-engineered, misaligned, reviewed too late (if at all). pi-topdown-kit fixes that by forcing a scaffold-first workflow: before writing any behavior, the agent produces a reviewable skeleton of the whole system — real, compilable code, with stub() markers everywhere. You review the entire shape as a diff. Only then does it fill stubs, layer by layer.

Best for: new subsystems where you want the architecture right before logic lands. (Not sure? Compare it to the sibling pwk- kit.)

This is the classical discipline of stepwise refinement (Wirth, 1971) and "programming by wishful thinking" (SICP), driven by a cognitive-load argument: experts read code top-down by chunking familiar lines into high-level concepts. Top-down production matches that mental model — the agent writes code shaped the way you read it.

Why?

• AI agents skip design. Left unchecked, they jump to code and the shape emerges accidentally. This forces a think-shape-first workflow.
• The skeleton is reviewable. You read the whole system's shape — names, layers, boundaries — before any logic distracts you. Mistakes are one-line stub edits, cheap.
• Progress can't drift. The stub() frontier is grep. No status file to forget to update, no rows to go stale. The codebase's own grep-ability tracks where you are.
• You stay in control. Checkpoint gates at the skeleton review and at hazard stubs mean you approve the shape and the risky bits before they're committed.
• Enforced, not suggested. Hard blocks mean the agent can't accidentally ignore the rules.

Install

Requires pi, an AI coding agent harness.

pi install npm:@tianhai/pi-topdown-kit

No setup needed — skills and guard activate automatically. Try before committing:

pi -e npm:@tianhai/pi-topdown-kit

What You Get

🛡️ Workflow Guard (extension)

Enforces phase-appropriate tool access — hard blocks, not guidelines:

| Phase | write / edit | bash | |-------|:-:|:-:| | Brainstorm / Verify | 🔒 Blocked outside docs/plans/ | 🔒 Read-only only (grep, find, cat, git status, curl…) | | Scaffold / Execute / Finalize | ✅ Full access | ✅ Full access |

The agent can discuss design during brainstorm, but physically cannot modify source files until scaffold.

🧠 7 Workflow Skills

brainstorm ─┬→ scaffold → execute → [verify?] → finalize
 (why/what) │   (shape)    (behavior)  (review)    (ship)
            ├→ modify (change existing behavior: characterize → change → repin)
            └→ diagnose (anytime)

Brainstorm is the triage point: it routes new shape to scaffold, behavior changes to modify, broken code to diagnose, and whole-subsystem replacements to scaffold (the old subsystem is removed during finalize's swap step). Six of the seven skills are user-invoked — you start each with /skill:ptk-…. Only ptk-diagnose also auto-fires (when a bug surfaces mid-workflow), so it's the one description that stays loaded in the agent's context.

| Phase | Trigger | What Happens | |-------|---------|--------------| | Brainstorm | /skill:ptk-brainstorming | Ask questions, explore approaches, record decisions, sketch the module outline. Output: *-decisions.md (problem, approaches, decisions, module outline). | | Scaffold | /skill:ptk-scaffold | Read decisions doc → emit the layered skeleton: full types, stub() stubs, it.todo tests, .ptk-scaffold sentinels. Runs a production-hazard check. Pauses at CHECKPOINT: skeleton for you to review the whole shape. | | Execute | /skill:ptk-execute | Grep the frontier → fill one stub + its unit test per increment (red→green). Recursively re-stubs when a fill is too complex. Tree stays green at every commit. | | Verify | /skill:ptk-verify | Three expert review passes (security, optimization, traceability) on the filled code. | | Finalize | /skill:ptk-finalizing | Remove .ptk-scaffold sentinels + stub() helper, archive decisions doc, update README/CHANGELOG, create PR. Includes a swap step for replacing a whole live subsystem. | | Modify | /skill:ptk-modify | Change behavior of existing working code: pin current behavior with characterization tests (green), make the change (intentional red), repin to the new contract (green). Localized changes (1–3 functions) only. | | Diagnose | /skill:ptk-diagnose | 6-phase debugging discipline: build feedback loop → reproduce → hypothesise → instrument → fix → cleanup. Utility skill, any time. |

There is no writing-plans skill. The skeleton is the plan — real, compilable code, not markdown prose.

Quick Start

# Install the kit
pi install npm:@tianhai/pi-topdown-kit

# Start a new feature
# (in pi TUI):
> /skill:ptk-brainstorming
> I want to add a job-scheduling subsystem to our worker pool

# Agent asks questions, explores approaches,
# writes *-decisions.md — no source writes yet.
# You approve the shape.

> /skill:ptk-scaffold

# Agent emits the layered skeleton:
#   scheduler/dispatcher.ts, scheduler/queue.ts, scheduler/repo.ts
# All stub() bodies, it.todo tests, .ptk-scaffold sentinels.
# Pauses at CHECKPOINT: skeleton — you review the whole shape as a diff.

# ...you approve the skeleton...

> /skill:ptk-execute

# Agent greps stub() call sites via sentinel patterns.
# Fills dispatcher first, recursively re-stubbing anything too complex.
# Tree green at every commit.

> /skill:ptk-verify
> /skill:ptk-finalizing

How It Works

Three ideas do the work:

1. Shape before behavior. Scaffold emits the whole skeleton as stub() placeholders — it compiles, tests are it.todo (skipped, not failing), but nothing runs. You review the map before any territory is written.
2. Drift-free progress. What's left to fill (the "frontier") is found by grepping stub() call sites — no progress file to forget to update. The codebase's own searchability tracks where you are.
3. Green at every commit. Filled stubs have passing tests; unfilled stubs skip. The tree compiles throughout, so you can stop, /new, and resume any time.

For the full internals — the marker protocol, sentinel mechanics, recursive re-stubbing, hazard gates, and key invariants — see docs/WORKFLOW.md.

vs pi-workflow-kit (pwk-)

This kit is the philosophical inverse of @tianhai/pi-workflow-kit, maintained alongside it. Both are valid — pick per task.

| | pi-workflow-kit (pwk-) | pi-topdown-kit (ptk-) | |---|---|---| | The plan is… | markdown prose (*-implementation.md) | real code (the skeleton) | | Task shape | vertical slices (signup = model+endpoint+UI) | layered fill (all handlers, then all services…) | | Progress tracking | a *-progress.md status table | grep the stub() frontier | | Readability bias | per-increment runnability (each task ships a working slice) | top-down shape review (review the whole skeleton first) | | Trade-off | loses whole-system shape review | loses per-step end-to-end runnability | | Best for | features where correctness per slice matters most | subsystems where architecture/shape matters most |

They coexist. Install both — no skill-prefix or extension conflicts (each guard tracks its own phase variable). Use pwk- for a CRUD endpoint you want working end-to-end today; use ptk- for a new subsystem whose shape you want to get right before any logic lands.

Project

pi-topdown-kit/
├── extensions/
│   └── workflow-guard.ts      # Write blocker during brainstorm/verify
├── skills/
│   ├── ptk-brainstorming/SKILL.md   # Decisions doc, module outline
│   ├── ptk-scaffold/SKILL.md        # Skeleton + hazard check
│   │   └── references/HAZARDS.md   # Production-hazard checklist (on-demand)
│   ├── ptk-execute/SKILL.md         # Fill stubs layer by layer
│   ├── ptk-verify/SKILL.md          # Security/optimization/traceability
│   ├── ptk-finalizing/SKILL.md      # Strip sentinels + helper, archive, ship
│   │   └── references/MERGE-STRATEGIES.md  # Git merge recipes (on-demand)
│   ├── ptk-modify/SKILL.md          # Change existing behavior (characterize→change→repin)
│   └── ptk-diagnose/SKILL.md        # 6-phase debug loop
├── tests/
│   └── workflow-guard.test.ts
├── docs/
│   ├── WORKFLOW.md                  # Internals reference (marker protocol, frontier, gates)
│   ├── lessons.md                   # Generic rules for future sessions
│   └── plans/
│       ├── PUBLISH.md               # Publishing runbook
│       └── completed/               # Archived decision docs
├── package.json
└── README.md

Development

npm test
npx biome check .

Publishing

See docs/plans/PUBLISH.md for the full runbook. (Docs must be updated before npm version — see the runbook.)

npm version patch   # bump
npm run check       # final gate
npm publish         # ship

License

MIT