tworkflow

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #go #machine-learning #rust #linux #nodejs #awesome #vue #pytorch #ios #openai

(★ 45)

A practical, no-hype workflow for AI coding agents: context, plan, implement, review, QA, ship, retro. Templates, two Claude Code skills, and a 40% context rule - every claim traced to official docs.

tworkflow 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](docs/00-principles.md).

## The loop

| Phase | What happens | Doc |
|---|---|---|
| Context | The agent gets a small, accurate project context file | [docs/01-context.md](docs/01-context.md) |
| Plan | Scope is pinned down in a plan document before code is written | [docs/02-planning.md](docs/02-planning.md) |
| Implement | Small diffs, frequent checkpoints, scoped tasks | [docs/03-implementation.md](docs/03-implementation.md) |
| Review | Three review lenses run as separate passes with checklists | [docs/04-review.md](docs/04-review.md) |
| QA | Functional checks plus a visual QA step with real screenshots | [docs/05-qa.md](docs/05-qa.md) |
| Ship | Tests, docs sync, PR | [docs/05-qa.md](docs/05-qa.md) (Ship section) |
| Retro | What the plan got wrong feeds the next plan | [docs/02-planning.md](docs/02-planning.md) |

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

- [docs/07-context-hygiene.md](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](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](docs/06-model-selection.md) (which
model and how much effort per phase) and
[docs/09-fable-5.md](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](docs/00-principles.md), or see the whole
loop run once on a small feature in [examples/](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](templates/CLAUDE.md.example) → `CLAUDE.md`
   - Codex CLI / Cursor / others: [templates/AGENTS.md.example](templates/AGENTS.md.example) → `AGENTS.md`

Fill it in. Keep it under a page (see
   [docs/01-context.md](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):

```bash
   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](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:

```bash
# 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/`:

```bash
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](skills/context-checkpoint/scripts/context_hook.py)
and the why in [docs/07-context-hygiene.md](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](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](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](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](LICENSE).

tworkflow

tworkflow 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

tworkflow

tworkflow 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README