scaffold-project

Scaffold a Project

Bootstrap a greenfield repository to a verified baseline: a skeleton where every quality tool is wired and demonstrably working, so the first feature starts from green.

Do not skip ahead to feature code. The deliverable is the harness, proven by one passing example test — nothing more.

Track progress

Create a todo for each step below (0–4) and complete them in order, checking each off only when its Done when is met. Step 0 is a gate: if it stops you (not greenfield), abandon the list and redirect. Otherwise the failure this guards against is a skipped step — the baseline never verified, or the setup-repo hand-off forgotten.

0. Confirm the target is greenfield — GATE

Scaffolding writes a project root (git repo, root manifest, root README, root CI, root pre-commit hook). Doing that on top of an existing project collides with or overwrites real config. So before anything else, resolve where you are scaffolding and prove it is empty. This gate is not optional and it is not a judgment call you make by feel — run the check.

Resolve the target directory. Default to the current working directory. If the user named a destination ("scaffold a bot package under packages/"), the target is that path. If the cwd is itself a populated repo root but the user asked for a new subpackage, resolve the target to that new subdirectory and classify that — do not stop at the root's verdict.

Inspect it yourself (never ask the user what is in the directory — look):

• ls -A <target> — does it exist, and is it empty?
• git -C <target> rev-parse --is-inside-work-tree and git -C <target> ls-files | wc -l — is it inside a git repo, and how many files are tracked?
• Is there a package manifest at the target (package.json, Cargo.toml, pyproject.toml, go.mod, …)?

Classify and branch:

Target state	Meaning	Action
Does not exist, or exists and is empty / only holds .git, README, LICENSE — and no manifest	Greenfield	Proceed to Step 1.
A new/empty subdirectory inside an existing git repo (e.g. packages/bot in a monorepo)	Subpackage	Proceed to Step 1 with the subdirectory as the target, and set inside-existing-repo = true (Step 2 skips the root-touching parts).
Exists and holds a manifest or many tracked files — a real project	Not greenfield — STOP	Do not scaffold. Redirect (below).

When you must stop, redirect — do not improvise a menu:

• If the user wants to use this skill set in the existing repo (configure tracker, verify commands, docs) → that is setup-repo, not scaffolding. Tell them to run it.
• If the user wants a new package inside this repo → confirm the new subdirectory path, then re-run this gate against that subdirectory (it should land in the Subpackage row).
• If they landed here by mistake → stop and let them reconsider.

State which case you detected and which redirect applies. Done when: the target is classified greenfield or subpackage and its resolved path is confirmed with the user, OR you have stopped and named the redirect.

1. Grill the stack

REQUIRED SUB-SKILL: use grilling to settle the stack and layout decisions for the resolved target — full question cards (inline only), each with options, consequences, and a recommended default:

• Project name (used in the manifest and README)
• Language and runtime
• Framework (or "none — plain library/CLI")
• Test runner
• Formatter and linter
• Package manager
• Repo layout (single package vs workspace/monorepo; source and test directory shape)
• License
• Commit or stage the result for review first

Look up facts yourself (what tools the user has installed, what the parent repo already uses in subpackage mode); bring only judgment calls to the user.

Done when: every decision above is explicitly confirmed and restated in one summary block — including the resolved target path — that the user approves.

2. Scaffold

Build the skeleton with the confirmed choices, at the resolved target. In subpackage mode (inside-existing-repo = true), skip the steps marked (root only) — the parent repo already owns them — and inherit the parent's shared config instead of creating competing copies.

1. Git (root only) — git init if the directory is not already a repo; write a sensible .gitignore for the stack. In subpackage mode, do not init and do not touch the root .gitignore; add a package-local ignore only if needed.
2. Project skeleton — manifest, source directory, minimal entry point. In subpackage mode, extend the workspace's shared toolchain config (e.g. a tsconfig that extends the root) and register the package with the workspace.
3. Test harness — install and configure the runner, plus exactly one passing example test. Its job is to prove the wiring (imports resolve, runner finds files, assertions execute), not to test real behavior.
4. Formatter + linter config — committed config, with format, lint, and typecheck (where applicable) runnable as single commands. In subpackage mode, inherit root config and add only package-level overrides.
5. Pre-commit hook (root only) — on every commit: format staged files, then lint, typecheck, and test. Use the stack's idiomatic hook mechanism. In subpackage mode, integrate with the parent repo's existing hook (scoped to the package) rather than installing a competing root hook.
6. CI stub (root only) — one workflow that runs the same verify commands on push and pull request. In subpackage mode, append a package-filtered job to the existing CI rather than authoring a new pipeline.
7. README skeleton — project name, one-paragraph description placeholder, and the install and verify commands. Place it at the target (in subpackage mode: <target>/README.md, never the repo root).
8. Docs seeds — CONTEXT.md (from the skill set's templates/CONTEXT.md), docs/specs/INDEX.md (from templates/specs-INDEX.md), and an empty docs/adr/ directory, all relative to the target. Optional project-docs layer: offer it once (a greenfield, multi-feature project benefits; a small one can skip and add it later via /establish-project). If the user opts in, also seed docs/product/vision.md, docs/architecture/INDEX.md, and docs/product/guidelines.md from templates/product-vision.md, templates/architecture-INDEX.md, and templates/product-guidelines.md. If declined, seed none of these — the setup-repo handoff can still enable the layer.

Done when: every applicable item exists and is committed (or staged, per the user's Step 1 choice).

3. Verify the baseline

REQUIRED SUB-SKILL: use verify — run the full verify suite (typecheck, lint, test) fresh and read the output. In root mode, also prove the pre-commit hook actually fires and passes (a throwaway commit or dry run).

A scaffold that hands off with a failing or unproven check is not done. Fix or remove the offending piece before proceeding.

Done when: every verify command passes, and you have shown the user the passing output.

4. Hand off

Tell the user the scaffold is complete and that the next step is to run setup-repo to write the agent-facing config (docs/agents/*.md — verify commands, tracker, labels, release steps). Do not write docs/agents/ yourself; that wizard owns it.

Completion criterion for the whole skill: from the repo root, one command installs dependencies and one command runs the target's verify suite green — state both commands explicitly in your final summary (in subpackage mode, scope the verify command to the new package).