Scaffolding the Sprint
How to set up clean workspace governance, initialize sprint manifests, and anchor AI context before a single line of code is written.
29 July 2026
The Gap Without Workspace Governance
When developers start an AI coding session, the instinct is to jump straight to the prompt: "Build me a user registration service in TypeScript." The AI obliges, placing files wherever it guesses they should go, assuming naming conventions, and creating code that works in isolation but violates every tacit rule of your codebase.
Without upfront workspace governance, three structural failures occur immediately:
- Context Leakage & Drift. The AI pulls in arbitrary files or creates loose scripts in random directories. There is no single source of truth for what feature is actually being worked on.
- Untracked Decisions. Architecture boundaries, dependency choices, and scope limits exist only in the temporary chat buffer. When the session closes or the window overflows, those decisions vanish.
- Unrepeatable Environment Setup. Teammates or execution agents attempting to build on the work cannot reproduce the session context because no manifest records the initial scope, branch anchors, or phase state.
Jumping straight to code generation is like starting construction before laying out the site blueprints or establishing safety boundaries. Scaffolding the sprint anchors the AI into a structured sandbox before any work begins.
Never let an AI agent write production code in an un-scaffolded workspace. If the sprint lacks a manifest, directory anchor, and defined boundaries, any code generated is technical debt in disguise.
The Skill: /sprint-new
In the sprint-workflow operating system, every sprint begins with a single command:
/sprint-new <slug>
Where <slug> is a short, kebab-case identifier for the feature or initiative (e.g., user-auth-v2 or invoice-middleware).
Executing /sprint-new performs a deterministic workspace initialization:
- Creates the Sprint Directory Structure: Scaffolds
.sprint/<slug>/containing dedicated subdirectories for design docs, story breakdowns, task logs, and memory scratchpads. - Initializes
sprint-manifest.json: Establishes the authoritative state machine for the sprint, tracking the current phase, model policies, created artefacts, and completion status. - Anchors Project Rules & Governance: Injects workspace-level coding standards, target directory bounds, and git branch rules into the agent context.
- Verifies Workspace Cleanliness: Ensures git working directory state is clean or properly isolated before initiating phase transitions.
Walkthrough: Skill Excerpt & Manifest Schema
Below is a real excerpt from the /sprint-new skill definition used in the sprint-workflow plugin, demonstrating how the scaffolding agent sets up the manifest and directory layout:
{
"name": "sprint-new",
"description": "Initialize a new sprint workspace with manifest, directory structure, and governance anchors",
"parameters": {
"slug": {
"type": "string",
"description": "Kebab-case sprint identifier (e.g. auth-refactor)"
}
},
"initialization_steps": [
"Ensure git working directory is clean or create feature branch sprint/<slug>",
"Create directory layout: .sprint/<slug>/{docs,tasks,logs,memory}",
"Write initial .sprint/<slug>/sprint-manifest.json",
"Announce model switch policy and hand off to /sprint-brainstorm"
],
"manifest_template": {
"sprint_id": "<slug>",
"created_at": "<ISO-timestamp>",
"current_phase": "INITIATION",
"active_model_policy": "standard",
"artefacts": {
"brainstorm": null,
"design_doc": null,
"stories_tasks": null,
"code_review": null,
"security_scan": null
},
"status": "IN_PROGRESS"
}
}The `sprint-manifest.json` file is the source of truth for both human engineers and downstream AI agents. Every phase update mutates this manifest, ensuring complete auditability across the lifecycle.
Model Choice & Why
Scaffolding a sprint is primarily a mechanical execution task. It involves checking file systems, creating directories, and populating standard JSON templates.
| Task | Recommended Model | Rationale |
|---|---|---|
| Workspace checks & folder creation | Haiku / Flash | Fast, low-latency, and zero waste of high-reasoning tokens for file system operations. |
| Initial governance rule validation | Sonnet / Pro | Structured validation to ensure parameters and repository paths meet policy constraints. |
Using a high-reasoning model (like Opus) to create empty directories or write a JSON template is an expensive mistake. Save high-reasoning models for phases that demand adversarial debate and complex trade-off analysis — like requirements brainstorming and architectural planning.
Pitfalls to Avoid
When implementing workspace scaffolding in your AI workflow, beware of these common traps:
- 1. Polluting the Root Directory: Never let AI write sprint notes, temporary scratch files, or partial code directly into the root folder. Enforce isolated subdirectories (e.g.,
.sprint/<slug>/). - 2. Skipping Git Baseline Checks: Creating a new sprint in a dirty git working tree risks mixing uncommitted changes from prior tasks into the new sprint manifest.
- 3. Hardcoding Absolute Paths: Ensure all manifest references and script hooks use relative workspace paths so the sprint can be inspected across local machines and CI runners.
- 4. Over-engineering the Manifest: Keep the manifest schema minimalist. Track phase states, artefact paths, and completion flags — avoid duplicating git commit histories or full file diffs.
How It Hands Off to Discovery
Once /sprint-new finishes scaffolding the environment, it returns a clean status summary and automatically prompts for the next lifecycle phase:
Sprint 'user-auth-v2' scaffolded successfully.
Manifest: .sprint/user-auth-v2/sprint-manifest.json
Phase: INITIATION -> Ready for requirements discovery.
Model switch: Switch to Opus for adversarial product discovery.
Next step: Run /sprint-brainstorm
By anchoring context and creating the manifest upfront, the workspace is ready for Part 3: Brainstorming Requirements (/sprint-brainstorm), where we transition from mechanical scaffolding to high-reasoning product discovery.