Structured Agentic Development

A practical workflow for everyday developers using AI coding agents on one to three repositories. Not a fleet-orchestration system — a repeatable loop you can run on the project in front of you:

Context → Plan → Implement → Review → QA → Ship → Retro

What's in the box:

• 9 short docs — one per phase, plus two cross-cutting guides on context hygiene and agent failure modes.
• 6 copy-paste templates — context file (two flavors), plan document, review checklists, QA report, session handoff.
• 2 installable Claude Code skills — dev-workflow walks the loop; context-checkpoint watches your context budget.
• A worked example — one small feature carried through the whole loop.

Works with any coding agent that reads project context files (Claude Code, Codex CLI, Cursor, and others). Claude Code–specific material — model selection, plan mode, subagents, the skills — is clearly marked and skippable if you use a different tool.

Why this exists

I use AI coding agents every day on a small number of real repos. Most of the advice I found was either hype or theater — "act as a senior engineer" prompts, agent "companies" staffed with CEO and CTO personas, threads promising 10x results. What actually improved my output was boring: write the scope down before the code, keep diffs small, review with fresh context, look at real screenshots, and reset the session before the context window degrades.

This repo is that workflow, written down so you can copy it. Two rules keep it honest: every tool-specific claim traces to official documentation, and nothing depends on a pinned model version or price — so it should age better than a screenshot thread. The reasoning behind each piece is in docs/00-principles.md.

The loop

Cross-cutting, because agents fail the same ways in every phase:

• docs/07-context-hygiene.md — the 40% rule: treat the context window as a budget and reset deliberately, before quality degrades.
• docs/08-failure-modes.md — the failure-mode map: test gaming, hallucinated packages, sycophantic self-review, overconfident "done" claims, and which mechanism in this repo catches each.

Start with docs/00-principles.md, or see the whole loop run once on a small feature in examples/.

Quick start

Commands below work in bash and Windows PowerShell as-is.

1. Get the files: git clone https://github.com/clarity-digital-development/tworkflow.git (or Download ZIP).

2. Copy a context file template into your repo root:

   • Claude Code: templates/CLAUDE.md.example → CLAUDE.md
   • Codex CLI / Cursor / others: templates/AGENTS.md.example → AGENTS.md

   Fill it in. Keep it under a page (see docs/01-context.md for why).

3. Copy the templates folder into your repo so the context file's references resolve (run from your project root):

   hljs language-bash

   Copy

   mkdir -p docs/templates
   cp path/to/tworkflow/templates/*.md docs/templates/
   

4. For your next non-trivial change, copy docs/templates/PLAN.md to docs/plans/<date>-<slug>.md and fill it in before prompting — see docs/02-planning.md.

5. Before merging, run the review checklists in docs/templates/REVIEW-CHECKLIST.md (fresh context, one lens at a time), then QA with docs/templates/QA-REPORT.md.

Claude Code users: install the skills

Run from your clone of this repo:

# personal (all projects)
mkdir -p ~/.claude/skills
cp -r skills/dev-workflow ~/.claude/skills/
cp -r skills/context-checkpoint ~/.claude/skills/

For a project-scoped install (committed with your repo), run from your project root instead, copying into .claude/skills/:

mkdir -p .claude/skills
cp -r path/to/tworkflow/skills/dev-workflow .claude/skills/
cp -r path/to/tworkflow/skills/context-checkpoint .claude/skills/

Then /dev-workflow walks the loop and /context-checkpoint checks your context budget — or Claude invokes them automatically when the request matches. Both bundle their templates and scripts, so they work even in repos where you haven't vendored anything. Skill locations per the official docs: https://code.claude.com/docs/en/skills

The context-checkpoint skill ships an optional hook that nudges the agent automatically when context usage crosses 40% — setup instructions in skills/context-checkpoint/scripts/context_hook.py and the why in docs/07-context-hygiene.md.

Using it day to day

What the loop looks like once it's set up:

1. Once per repo: fill in the context file. Exact commands, real boundaries, nothing aspirational.
2. Trivial change? Just do it — the workflow says so. Non-trivial? Plan document first, and make the agent verify the plan's premises against the actual code before it writes anything. Wrong premises are where most agent work falls apart.
3. Implement in plan-step commits. Watch context usage; past 40%, reset at the next clean boundary instead of pushing a degraded session (docs/07-context-hygiene.md).
4. Before merge: three review passes in fresh context, then QA with real screenshots — code review can't see a broken layout.
5. Five minutes after shipping: note what the plan got wrong. Wrong premises become context-file lines; blind spots become plan-template lines. This is the part that compounds.

What's different about this approach

Most agent-workflow repos assign personas to the agent: a "CEO" reviews scope, a "CTO" reviews architecture, a "QA lead" tests. The persona is decoration. What actually changes agent behavior is what each pass is scoped to look for, what it's allowed to touch, and whether it runs with fresh context. This repo keeps those mechanisms and drops the costumes: each phase is defined by an explicit checklist, not a job title.

The second difference is scope. This is written for a developer running one agent on one to three repos — the common case — not 10–15 parallel sessions. Everything here works in a single terminal.

FAQ

Isn't a ten-section plan overkill for small changes? Yes — and the workflow says so. Trivial changes skip the loop entirely; single-file fixes get a one-paragraph plan. The full loop is for multi-file, behavior-changing work. See the triage split in docs/02-planning.md.

Do I need Claude Code? No. Docs 00–05, 07, and 08 plus all templates are tool-agnostic. Claude Code gets two extras: the model-selection doc and the installable skills.

Does this work on Windows? Yes. The quick-start commands run as-is in PowerShell, and the bundled scripts are plain Python and Node.

Why no personas? Telling a model it's a "senior engineer" has negligible effect on accuracy. Checklists, scoped passes, and fresh context are what work — docs/00-principles.md.

Doesn't all this planning cost more tokens? It moves spend from rework to thinking. A wrong premise caught in a plan costs a sentence to fix; the same mistake caught after implementation costs the whole diff.

Contributing

Issues and PRs welcome — especially corrections where tool behavior has drifted from what these docs claim. Tool-specific claims should trace to official documentation (see Sources).

Sources

Tool-specific claims in these docs trace to official documentation:

• Claude Code docs — https://code.claude.com/docs
• Agent Skills format — https://agentskills.io and the Anthropic skills docs
• AGENTS.md convention — https://agents.md

Where behavior may have changed since writing, the docs say so and link out rather than asserting.

License

MIT — see LICENSE.