chelch5/scaffold-kickoff

Scaffold Kickoff

This is the default entrypoint for project scaffolding. When a user asks to scaffold a project, start here.

Decision tree

Before starting, classify the run type:

1. Greenfield — No repo exists yet, or the repo contains only specs/plans/notes. Follow the full 10-step workflow below.
2. Retrofit — A repo with code already exists but needs the agent operating layer added. Run spec-pack-normalizer first if the project lacks a canonical brief, then skip to step 4 (agent team bootstrap), and continue from step 5.
3. Refinement — A scaffolded repo exists but needs its tickets, skills, or agents improved. Jump directly to the specific sibling skill needed.

Full greenfield workflow

Follow these steps in order. Each step references a sibling skill — read it at the relative path shown.

Step 1: Normalize the spec pack

Read ../spec-pack-normalizer/SKILL.md and follow its procedure.

Scan the workspace for project inputs:

• Look for *.md files, docs/, specs/, plans/, requirements/, notes/, design/ directories
• Look for pasted chats, informal notes, architecture docs, API specs
• Read everything you find

Produce a canonical brief at docs/spec/CANONICAL-BRIEF.md (or docs/BRIEF.md for non-OpenCode repos) with all required sections defined in the spec-pack-normalizer schema.

Gate: Canonical brief must exist with all required sections populated.

Step 2: Resolve ambiguities

Before proceeding, present the user with a batched decision packet for any blocking ambiguities:

• Project name, slug, destination path
• Agent configuration prefix (if applicable)
• Model provider and model choices (planner, implementer, utility)
• Stack/framework choices
• Any other materially divergent decisions

Do NOT guess at these. Ask the user explicitly. Do NOT proceed until blocking decisions are resolved.

Gate: All blocking decisions resolved or explicitly recorded.

Step 3: Generate the base scaffold

Read ../repo-scaffold-factory/SKILL.md and follow its procedure.

This produces the repository file tree:

• README.md, AGENTS.md, docs skeleton, .github templates
• Agent configuration directory (.opencode/, .copilot/, .codex/, or equivalent)
• Ticket directory structure

For clients that support script-assisted generation (e.g., OpenCode with Scafforge), this has two phases:

• Phase A: Run the scaffold script to generate template files with placeholder substitution
• Phase B: Customize generated files with project-specific content from the canonical brief

Gate: Repository structure exists with README.md, AGENTS.md, and docs skeleton.

Step 4: Design and customize the agent team

Read ../opencode-team-bootstrap/SKILL.md and follow its procedure.

Customize the agent team for this specific project:

• Rewrite agent prompts to be project-specific
• Add or remove agents based on project type
• Create multiple implementer-type agents if the project spans different domains
• Set appropriate permissions, tool access, and delegation boundaries

Gate: Agent definitions exist with project-specific prompts and permissions.

Step 5: Build the ticket backlog

Read ../ticket-pack-builder/SKILL.md and follow its procedure in bootstrap mode.

Create implementation-ready tickets from the canonical brief:

• Break work into implementation waves (foundation → core → secondary → polish)
• Each ticket small enough for one agent session
• Unresolved decisions become blocked/decision tickets, not guesses

Gate: Ticket manifest exists with at least one actionable ticket.

Step 6: Bootstrap project-local skills

Read ../project-skill-bootstrap/SKILL.md and follow its procedure.

• Foundation mode: populate baseline skills with actual project data
• Synthesis mode: create stack/domain-specific skills from project evidence and external research (reference only, never auto-install)

Gate: Project-local skills exist with real content, no placeholders.

Step 7: Harden agent prompts (if needed)

Read ../agent-prompt-engineering/SKILL.md and follow its procedure.

Apply when:

• The chosen models need specific prompting techniques
• Agent prompts need tighter scope or anti-doom-loop behavior
• Stage contracts need project-specific hardening

Skip if the agent team is already robust for the chosen models.

Step 8: Audit the generated repo

Read ../repo-process-doctor/SKILL.md and follow its procedure.

Run the audit against the freshly generated repo. Fix any safe-repair findings. Escalate intent-changing findings to the user.

Gate: Audit passes clean or all findings addressed.

Step 9: Write the handoff surface

Read ../handoff-brief/SKILL.md and follow its procedure.

Generate START-HERE.md with actual project state so the repo can be resumed by another agent or session.

Gate: START-HERE.md exists with all sections populated with real content.

Step 10: Done checklist

The scaffold is complete when ALL of these exist:

• Canonical brief with real project content (not template placeholders)
• Ticket manifest with implementation-ready tickets
• Board view showing the work queue
• Agent definitions with project-specific prompts and permissions
• Agent tools, plugins, and commands (if applicable to the client)
• Project-local skills with real content
• START-HERE.md with current project state
• A clean audit from repo-process-doctor

Output contract

• A canonical brief that separates facts, assumptions, and open questions
• A decision packet that records blocking vs non-blocking ambiguities
• A scaffolded repo with README.md, AGENTS.md, START-HERE.md, docs, and tickets
• A structured truth hierarchy with clear ownership for facts, queue state, transient workflow state, artifacts, provenance, and handoff
• The agent operating layer — customized for this specific project and client
• A process audit confirming the generated repo is clean
• A handoff surface that another machine or session can resume from

Rules

• Prefer this umbrella flow for greenfield work instead of manually starting with lower-level skills
• Keep generated docs and prompts weak-model friendly: short sections, explicit steps, obvious source-of-truth files
• If the repo already exists and only needs the agent layer, switch to the relevant team-bootstrap skill instead of forcing a full scaffold reset
• When the stack is still unknown, keep the scaffold framework-agnostic and record unresolved choices in the canonical brief
• Do not let ticket-pack-builder fabricate implementation detail for unresolved major decisions
• Preserve exact model/provider strings and project names when the source material specifies them
• Do not ship a repo-local workflow until a doctor pass confirms it is clean
• Leave review-audit-bridge for later implementation and QA cycles — it is not part of the initial scaffold flow

Failure handling

• Missing specs: Stop and request minimum viable input (problem statement + target users + rough scope)
• Ambiguous stack: Emit stack profile with confidence: low flag and list alternatives; proceed with most likely choice but document uncertainty
• Partial completion: Commit whatever was generated with WIP: prefix; log which phase failed
• Conflicting constraints: Surface as decision items in the canonical brief rather than making silent choices
• Gate failure at any step: Stop, report which gate failed and what's missing, do not proceed past a failed gate