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:

• 10 short docs — a principles intro, the loop phases, a model & effort
  guide, two cross-cutting guides (context hygiene, agent failure modes),
  and a prompting guide for Claude Fable 5.
• 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 and
effort selection, plan mode, subagents, Fable 5 prompting, 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.

On Claude Code with Anthropic's models, two more docs cover the tool
specifics: docs/06-model-selection.md (which
model and how much effort per phase) and
docs/09-fable-5.md (prompting tuned to Claude Fable 5
— relax the nagging, keep the structure). Both are skippable on other
tools.

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):

   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 the extras: the model & effort doc
(06), the Fable 5 prompting guide (09), and the installable skills.

Is this updated for Claude Fable 5? Yes. The model & effort doc and
the Fable 5 prompting guide cover the new effort dial, the safety-classifier
fallback, and how to prompt Fable specifically (it self-verifies, so you
nag it less). Availability of any given model shifts — run /model to see
what your account has today rather than trusting a number in a README.

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.