1 · Architecture
The whole puzzle
Modules, interfaces, data flow, technology choices, extension points, and the current build boundary.
Planning for AI-assisted software development · Version 0.4.0 (Draft)
Plan broadly.
Build one useful slice.
Scaffold Kit is a planning interview for AI coding projects. Turn a rough idea or an existing codebase into architecture, engineering rules, recorded decisions, and one active slice brief.
Design where the whole product is going. Approve a small, valuable section to build now. Test what matters, then expand deliberately.
The kit writes planning documents. Product code starts only after the owner approves the active Slice Brief.
Four documents the next coding session can use
2 · Engineering
The rules for building
Requirements, data model, security, verification, and the definition of done.
3 · Decisions
The reasoning stays
Significant choices, their status, alternatives, and the trigger that reopens each decision.
4 · Active slice
One build boundary
What to build now, what to defer, acceptance criteria, evidence, and owner approval.
Start without assuming a plugin has loaded
- Review the source and FSL-1.1-MIT license. Choose a source revision you have reviewed. Version 0.4 is a draft.
- Give your assistant
skills/scaffold-kit/references/conductor.mdand the four templates underskills/scaffold-kit/assets/templates/. Load a template when its phase starts. If a named file cannot be read, stop and resolve that prerequisite. - Describe the project in a paragraph. The interview starts with intake and triage; answers, accepted defaults, and flagged assumptions shape the documents.
- Review the first slice and its audit. Record owner approval in the active Slice Brief before product code is built.
For skill installation, copy the skill directory into your host's documented discovery location after reviewing the source. Confirm discovery in that host before relying on it. See the installation notes and Codex verification record; that record includes failed discovery and file-resolution checks.
Instructions need no runtime. The optional document-audit script uses the Python standard library and needs Python 3.9 or newer. A packaged skill is not proof of compatibility with every host.
Example: a small reading-list app
This is an illustrative starter, not a measured trial or a completed project plan.
Use Scaffold Kit 0.4 to plan a small reading-list app. Start with triage and questions. Write planning documents only; do not build product code.
The interview might make “save one book” the first slice, with title and author fields and a way to see the saved book. Accounts, recommendations, and sharing could remain outside that slice. Those are proposals to discuss, not choices the kit should silently make.
Use the four documents to record the accepted scope, unknowns, and acceptance evidence. The decision log carries the reasoning into the next session; the slice brief keeps implementation bounded.
Use the amount of planning the project needs
- A new project
- Triage the kind of build, experience, team, and risks. The same protocol adapts to apps, services, CLIs, libraries, data systems, games, automations, and sites.
- An existing codebase
- Anti-Dark-Code maps the code and exposes evidence and unknowns. Scaffold Kit uses that evidence to form planning decisions and a slice brief. They serve distinct jobs.
- The next feature
- Revisit decisions when their triggers fire, prepare the next slice, review it, and approve its build boundary.
- A disposable experiment
- A throwaway spike that answers one question and is then deleted may need much less planning. If it survives, bring it through triage.
Review the evidence, including the limits
The repository retains version history, behavioral evaluations, failures, and host limitations. Existing evaluations do not establish performance on every project or host. No generated plan can replace owner decisions, implementation checks, or user research.
Changelog · Evaluation records · Search discovery and publication notes