Agentic Coding Starter
Starter is a working template for building software with coding agents. It gives a project a written brief, a phased plan, reusable skills, independent product review, and executable checks. The operator controls consequential decisions and judges the resulting product.
Wolf McNally created and maintains Starter. His Encyclopedia of Agentic Coding Patterns explains the broader vocabulary and patterns behind agentic development.
Start with Get Started to create a project. Use Run a Phase for the everyday development loop. The skill reference and command reference help when you know the task you want to perform.
This manual describes the methodology as it works now. The repository's briefs and policies retain the full authority and detail. They are available in the source repository; operational records are outside this published manual.
A project derived from Starter documents its own users, features, setup, and operation. A brief acknowledgment and a link to this manual are enough to explain that it uses the Starter methodology.
Get Started
This tutorial creates a small project, checks its initial scaffold, and identifies the first phase. You need Git, a supported coding harness such as Claude Code or Codex, and the language toolchain selected for your project. Starter's own example uses managed Python 3.11 and uv.
Prepare Starter
Clone the Starter repository and open its directory in your coding harness. Run the setup command from a terminal in the checkout:
./bin/setup
Setup succeeds only after the pinned interpreter, locked dependencies, example package, and test tools load. If it refuses, fix the named prerequisite before continuing.
Describe a small project
Ask the agent to use stamp with a new directory and a description. In Claude Code:
/stamp ~/path/to/weather-cli "A Rust command-line app that reports the weather for a named city"
In Codex:
$stamp ~/path/to/weather-cli "A Rust command-line app that reports the weather for a named city"
For a serious project, write the brief first. A destination may already contain a Markdown brief, an optional Git directory, and a gitignore. stamp adopts the brief's body unchanged. It refuses a destination containing source code or unrelated files.
The skill adapts the project instructions, runtime and checks, skill mirrors, initial brief, and phase plan. It verifies the new scaffold and makes its initial local commit. You choose the remote separately.
Inspect the result
Open the new project in your harness. Read its entry-point brief, plan/INDEX.md, and the first phase file. Check the inferred name, language, surfaces, dependencies, and acceptance criteria. Correct assumptions before implementation begins.
Run kickoff in the new project. In Claude Code:
/kickoff
In Codex:
$kickoff
The agent selects the next marked phase, loads its authority, plans and implements it, obtains the selected independent advice, and runs the checks. A successful delivery leaves any human demo and product judgment explicit for you.
Check your understanding
You have completed this tutorial when the new project has an understandable brief, one next phase, working setup/test/check commands, and a clear statement of what the first phase will prove. A live model preflight may still refuse because of authentication, provider availability, or usage limits; that refusal is reported separately from the scaffold's checks.
For a small research folder or knowledge base, the mini-method scaffold offers briefs, policies, pinned references, and deterministic commands without the full phase workflow. Use teach later to assess an upgrade.
Run a Phase
Use a phase to deliver one coherent outcome with explicit acceptance criteria. A phase may touch several files or surfaces. Split it when a consequential decision, independently accepted prerequisite, deployment seam, or human judgment separates the outcomes.
Select and load the work
plan/INDEX.md is the sole status ledger. Its markers mean: ⏳ not started, ⬅️ next, 🚧 in progress, and ✅ completed. kickoff owns transitions. To resume active work, name that phase explicitly.
Invoke kickoff with no argument to select the next phase, or name a phase. In Claude Code:
/kickoff phase 2
In Codex:
$kickoff phase 2
The agent reads the index, target and parent when needed, cited briefs and pinned references, dependencies, preceding completed phase, applicable policies, and the execution resource for the current stage.
Plan, implement, and review
An eligible primary owns product planning, coding, and acceptance decisions. Independent advisers inspect the plan and implementation, preferably through a permitted different provider. A single-provider setup uses a fresh same-provider instance. Advisers supply evidence and severity; the primary resolves findings and records consequential dispositions.
Constrained primaries use delegated planner/coder roles and approval-gated reviewer/critic loops. The configured mode determines authority; a review lane determines which stages run. Ordinary product work defaults to the full lane. An explicit user invocation is required for the product one-shot lane.
Methodology improvements follow a different standing route: the primary assesses, implements, self-checks, validates, commits, and fast-forward-pushes authorized work. Independent role loops are not invoked. teach and learn still require the operator to approve their concrete transfer plan before recipient writes.
Prove and deliver the candidate
Use focused tests during implementation. The implementation-candidate sequence ends with changed-path test selection. After every tracked close write, run the full handoff gate on the exact tree being delivered. No tracked write follows a successful handoff gate.
./bin/test --changed-from '@{upstream}'
./bin/check all
Candidate identity binds product review. Full-tree identity binds the handoff gate and delivery. A changed candidate invalidates evidence that depended on its previous bytes. Unknown classifications or failed queries refuse; they never become a reassuring default.
When every executable gate passes, delivery stages explicit attributable paths, commits with hooks enabled, verifies the resulting commit and clean tree, and fast-forward-pushes to the existing upstream. Unexpected changes, divergence, ambiguous upstream, or unresolved hook refusal park delivery.
Passing checks proves the executable criteria that were actually run. It does not prove the product feels right, that a visual result is acceptable, or that a human demo has been completed. Those criteria remain the operator's.
Close or park truthfully
Record remaining work, evidence, lessons, and outcomes through the deterministic activity-log writer. Failed gates keep the phase open. Human-only actions belong in the action queue. A park says what blocks progress and what evidence or decision will unblock it.
Use the Skills
Skills are repository procedures that a harness can discover and load. Canonical definitions live under .claude/skills/; .agents/skills/ exposes directory symlinks for Codex. Invoke /name in Claude Code or $name in Codex.
| Skill | Use it when you want to… |
|---|---|
stamp | Create a new project from this template. It is available only in Starter. |
methodology | Scope a project, turn an idea into a brief, or organize a phased plan. |
kickoff | Execute or resume one phase with its selected review contract and checks. |
demo | Walk through an approved human demo one visible action at a time. |
docs | Build and open the project's manual, preview it, or deploy through an approved Pages workflow. |
roles | Inspect or change model and effort pins in kickoff.yaml. |
refactor | Improve code structure while preserving observable behavior. |
mutate | Survey whether the tests catch planted faults in disposable copies. It runs only on request. |
learn | Assess practices in another repository for adoption here. |
teach | Assess which practices here should move to another repository. |
sweep | Review accumulated rules, skills, briefs, and lessons for maintenance. |
sweep-planning | Analyze plan-review verdicts and propose improvements to the planning loop. |
sweep-coding | Analyze code-review verdicts and propose improvements to the coding loop. |
treatise | Produce a durable outward explanation from current repository evidence. |
ask | Surface all open operator decisions in one interaction. Only the operator invokes it. |
plain | Recompose a report so its consequence and required decision are clear. |
rule-one | Diagnose a failure or correction and persist reusable learning at its proper authority. |
learn, teach, and the sweep skills present their judgments before applying the changes their approval contracts require. The agent normally applies plain and Rule One without a separate user command.
Change role configuration
roles edits maintained model/effort pins while preserving unrelated configuration. It does not invoke a model. kickoff performs live preflight before product mutation and chooses an allowed review venue.
Review documentation
In Claude Code:
/docs
In Codex:
$docs
The skill checks the local configuration, provisions only missing pinned documentation tools, builds the curated manual, validates its internal links and assets, and opens the result in a local browser. See documentation publishing for preview and deployment modes.
Command Reference
Repository wrappers own runtime selection and checks. Run commands from the checkout; the core wrappers also resolve their own location when invoked elsewhere.
| Command | Result |
|---|---|
./bin/setup | Provisions the pinned runtime and locked dependencies and probes the real tools. |
./bin/python | Runs Python from the same environment used by the checks. |
./bin/test | Runs the example and methodology tests. Additional arguments select focused tests. |
./bin/test --vital | Runs the locally admitted fast proof families. |
./bin/test --changed-from REF | Selects proof families affected by the diff, widening to full when uncertain. |
./bin/check all | Runs lint, formatting verification, tests, and policy checks; captures a bound full-gate receipt. |
./bin/docs setup | Uses exact installed documentation tools or installs them under ignored repository-local runtime storage. |
./bin/docs build | Builds and validates the curated manual without opening a browser. |
./bin/docs check | Runs the same publication-input, build, output and link checks. |
./bin/docs | Builds and opens the local manual. |
./bin/docs serve | Builds, opens, and serves a loopback-only foreground preview. Ctrl-C stops it. |
./bin/docs deploy | Requests publication of the latest validated, clean, pushed release candidate through the approved workflow. |
./bin/docs deploy continuous on | Enables push deployment for the configured release branch using repository variables. |
./bin/docs deploy continuous off | Disables push deployment; manual deployment remains usable. |
./bin/docs verify | Probes the configured HTTPS site, deep pages, assets, search and private-path exclusions. |
./bin/kickoff-config show | Displays maintained orchestration settings. |
./bin/kickoff-tree-id | Identifies the current candidate. |
./bin/test-governance validate | Checks the local proof inventory and its evidence. |
./bin/lessons validate | Validates the lessons ledger. |
./bin/lessons candidates | Reports lessons ready for operator consideration. |
./bin/install-hooks | Opts the checkout into the tracked Git hooks. |
./bin/check-hooks-installed | Distinguishes not opted in from a broken hook installation. |
bin/README.md in the source repository is the complete deterministic-command catalog. Use a command's --help before selecting a less common operation.
Runtime overrides
TOOLCHAIN_PYTHON is an authoritative absolute interpreter-path override for deliberate runtime testing. Invalid or failed overrides refuse; the wrapper does not silently switch to another interpreter. Normal use follows the committed managed runtime pin.
Documentation pins
documentation.toml selects mdBook 0.4.50 and mdbook-admonish 1.19.0. Setup uses exact versions and Cargo's locked dependency graph. It leaves global tools unchanged. Missing Rust/Cargo is reported as a prerequisite rather than silently installing a global toolchain.
Repository Map
| Surface | Owns |
|---|---|
CLAUDE.md, with AGENTS.md pointing to it | Agent instructions, hard rules, project context, and authority catalogs. |
briefs/ | Intent, design rationale, research, and methodology explanations. |
policies/ | Binding rules. Policies override implementation and plans. |
docs/ | Third-party reference text, pinned with source, version/date, retrieval date and redistribution basis. |
manual/ | The curated first-party user manual and its mdBook configuration/theme. |
documentation.toml | Pinned documentation tools, local preview port, publication repository and release branch. |
plan/INDEX.md | The only phase-status ledger. |
plan/ phase files | Dependencies, scope, executable acceptance and user demos. |
project/ | The isolated example deliverable, runtime pin, manifest, lockfile and tests. |
lib/agentic_starter/ | Shared deterministic methodology machinery. |
bin/ | Setup, checks, evidence and other deterministic commands. |
.claude/skills/, .claude/agents/ | Canonical procedures and role definitions. |
.agents/skills/, .codex/agents/ | Thin harness discovery mirrors. |
tests/ | Independent proofs and recipient-local proof governance. |
LOG.md | Append-only activity history. |
user-actions/, lessons/ | Open human-only actions and provisional learning, with separate archive directories. |
.kickoff/ | Ignored runtime state, full-gate receipts, documentation tools and build output. |
Briefs explain decisions; policies prescribe behavior; plans refine the work. Pinned sources supply external authority. The manual is a reader-facing guide to the current system and does not replace those authorities.
Preserve the boundary
The example deliverable does not reach into the parent repository. Its own source, tests, dependency metadata and runtime form an isolated package. The methodology machinery lives outside that package.
The public site is built only from the manual's curated chapters and declared theme. Logs, evidence, internal planning queues, host configuration and third-party reference archives are outside its publication input.
Write and Publish Documentation
Write manuals in Markdown and build them with the versions in documentation.toml. Keep the documentation alongside the behavior it describes and update both in the same change.
Choose the reader's task
Use tutorials for guided learning, how-to guides for a concrete task, reference for exact facts, and explanation for understanding. Give each page a primary reader need. A short reason can sit in an admonition; longer reasoning belongs on an explanation page.
Use descriptive headings, meaningful link text, and text alternatives for informative images. Keep commands copyable and provide one command per shell fence. Test executable examples through the project's native runner; mdbook test tests Rust snippets only.
Edit the manual
Add a snake_case Markdown chapter under manual/src/, then list it in SUMMARY.md with a title-case label. Use two spaces to indent nested summary entries. Each prose paragraph stays on one physical line. Missing chapters fail the build instead of being created automatically.
The source boundary accepts only summary-listed chapters, SUMMARY.md, an optional 404.md, and assets explicitly listed in book.assets in documentation.toml. Review each declared asset for public use; JavaScript and JSON source assets are not admitted. Raw include directives, scripts, iframes, symlinks, and unlisted source files refuse before preprocessing. These restrictions prevent the manual from importing an operational file accidentally.
Build and check:
./bin/docs build
Open the built book without leaving a server running:
./bin/docs
For HTTP review, use the foreground loopback preview:
./bin/docs serve
The preview serves only the checked output. It does not create network routes. For an existing approved Tailnet proxy, pass its URL with serve --url; the listener remains on loopback. Stop the foreground command when review is complete. A browser-open acknowledgment proves only that the browser accepted the request; inspect the rendered result separately.
Prepare GitHub Pages
Starter installs its approved workflow at .github/workflows/docs-pages.yml, with read-only default permissions and Pages-write/OIDC-token permissions confined to the deployment job. Its github-pages environment allows only master. Continuous deployment stays off unless explicitly enabled. The generic recipient template remains at manual/github-pages.yml; installing it in another repository requires that owner's explicit approval of the permissions, publishing source and deployment environment. The command refuses until an approved workflow is installed. It never enables Pages or grants permissions itself.
The workflow uploads only fresh, validated book output. Continuous deployment defaults off. Configure deploy.repository, deploy.release_branch, deploy.workflow, and deploy.url in documentation.toml, and the corresponding site-url prefix in manual/book.toml. master is the default release branch; a project may configure main or another existing branch. Branch selection does not rename a repository's branch.
Deploy manually
Commit and push the documentation with the normal repository gates. Then invoke docs deploy through either harness, or run:
./bin/docs deploy
The command requires a clean checkout on the configured release branch, a matching GitHub origin, and a local commit equal to the branch's current remote commit. It validates locally and requests the installed workflow on that exact branch. A dispatch acknowledgment is not completed publication. Wait for the matching workflow run and inspect its terminal result before checking the site.
Control continuous deployment
After approval and workflow installation, enable deployment on release-branch pushes:
./bin/docs deploy continuous on
Disable it:
./bin/docs deploy continuous off
These commands set DOCS_RELEASE_BRANCH and DOCS_CONTINUOUS repository variables. They require GitHub variable-write authority. The off setting preserves manual deployment. A failure or absent variable is never reported as enabled or disabled successfully.
Verify publication
./bin/docs verify
Then inspect the live site in a browser: open a deep page, follow an anchor, search for a known term, navigate by keyboard, inspect the 404 page and assets, and check the README's actual live link. The HTTP probe checks excluded operational paths return 403 or 404. It cannot prove perceptual quality or search interaction.
Resolve Problems
Setup or runtime refuses
Read the complete diagnostic. Check the committed runtime pin, manifest, lockfile and real dependency probe together. A bad explicit runtime override is authoritative and must be corrected; adding a fallback would conceal the problem.
An agent sandbox may block an otherwise working host tool's cache, managed runtime or network access. Distinguish a permission refusal from a missing dependency. Use a supported authorized execution route; do not weaken the check or claim the dependency is broken from a failed sandbox probe alone.
A documentation tool version differs
Run ./bin/docs setup. It uses exact installed versions when available and otherwise installs the selected version locally. It does not upgrade other projects' global tools. Re-pin the renderer, plugin and generated plugin CSS together when deliberately changing versions, then rerun the manual's checks.
A chapter or link is missing
Read the named page and destination. Add the intended chapter to SUMMARY.md, or correct the link or anchor. The build does not silently create an empty page. The generated-output check includes print and search, where omitted or private text can otherwise survive unnoticed.
A gate fails
The phase remains open. Diagnose the earliest meaningful divergence, correct the cause, and renew evidence bound to the changed candidate. A hook refusal caused by a safe defect in the agent's own work is work to finish. An unresolved refusal parks delivery. Never disable the hook or retry unchanged input.
Another session changed the checkout
Treat unexpected paths as shared work. Stage only attributable paths. If a shared file's hunks cannot be assigned safely, park delivery. A pathspec on git commit uses working-tree content and can defeat a staged hunk partition; commit a partitioned index without a pathspec.
Pages is unavailable
A missing workflow or permission is a publication boundary, not evidence of successful deployment. Finish the local manual and prepare the exact requested change for approval. Keep continuous deployment off unless the operator enables it. Manual publication remains independent of that switch.
Human review is pending
Say exactly which criteria remain. A passing build is evidence of the automated checks, not a substitute for the operator's demo, visual judgment, or custody decision. Use demo for a visible step-by-step review and ask when the operator wants open decisions collected together.
Understand the Method
Starter turns intent into written authority, bounded work, evidence and human judgment. Its eleven-step method starts with an idea and insights, develops a brief and architecture, establishes repository policies, creates a phased plan, decomposes consequential prerequisites when needed, executes the selected development/review loop, records acceptance and lessons, supports human evaluation, and adjusts the remaining plan as evidence changes.
Put decisions in their owning surface
Rules that matter across sessions belong in repository authority rather than one agent's memory. Briefs explain the design; policies prescribe behavior; plans refine authorized work. Fix an ambiguity at its owner. Keep canonical sources and thin harness mirrors so the rule has one maintained home.
Ask evidence to prove the actual claim
A count, label or successful command is often a proxy for the property you care about. Name the property and the proxy, consider innocent triggers, and ask whether the proxy could reverse the conclusion. Re-read the original artifact before characterizing it. Unknown measurements remain unknown.
Candidate-bound review answers whether the inspected implementation satisfies its contract. The full handoff gate answers whether the exact delivered tree passes its executable checks. Neither replaces human evaluation.
Keep progress monotonic
Hold authorized scope fixed. Implement unblocked work and defer tangents explicitly. Prefer a deterministic script for exact repeatable work and contextual judgment for decisions. Introduce an abstraction for a present use, rather than for an imagined future consumer.
Learn from surprises
Rule One starts with the observed divergence and diagnoses before prescribing a rule. Separate containment, correction and prevention. Persist a reusable lesson at the narrowest existing cross-harness authority; keep unsettled learning provisional. The operator decides when lessons graduate into rules.
Before a stable external release, replace a wrong shape and update all callers, fixtures and documentation together. Transitional compatibility paths add a second system to maintain before the first has shipped.
Keep authority and judgment with the operator
Routine gate-proved delivery is authorized; destructive Git actions and consequential decisions remain the operator's. Availability does not create authority. Delegation can carry existing permission but cannot invent it. Clear reports lead with the consequence and preserve the evidence needed to assess it.
Glossary
| Term | Meaning |
|---|---|
| Acceptance | A decision that the specified criteria are met; human criteria remain with the operator. |
| Advisory review | Independent evidence and findings that inform the primary's acceptance decision. |
| Brief | The written intent, design context, rationale and scope. |
| Candidate | The exact implementation or full-tree bytes to which evidence is bound. |
| Delivery | A verified commit and fast-forward push after the required executable checks. |
| Gate | An executable check that must pass before the governed transition. |
| Handoff gate | The full check on the tree after all tracked close bookkeeping. |
| Methodology work | Changes to the development method, policies, skills or supporting machinery. |
| Operator | The person who owns decisions and product judgment for this checkout. |
| Park | A truthful hold stating the blocker and the evidence or decision needed to resume. |
| Phase | A coherent outcome with explicit dependencies, scope and acceptance. |
| Pin | An exact version or dated external reference deliberately selected for use. |
| Policy | A binding repository rule. |
| Primary | The instance accountable for orchestration and decisions in its selected authority mode. |
| Proof estate | The recipient-local inventory of executable checks and their governance evidence. |
| Skill | A discoverable procedure with instructions and any supporting resources. |
The methodology brief in the source repository owns the complete canonical glossary. Use its terms when editing plans and policies.