workflow-agent

Give your AI coding agent a memory for real project work.

A single wf skill that manages the full ticket lifecycle — context, tickets, phased plans, reviews, and progress — stored as plain files in your repo so work survives across sessions.

Get Started View Presentation View on GitHub
1 · New
CONTEXT.mdCreate a persistent workspace for the change.
2 · Discover
INTERVIEWTurn raw ideas into clear project context.
3 · Breakdown
TICKET.mdSplit work into deployable tickets you confirm.
4 · Plan
PLAN.mdGround phased implementation in actual code.
5 · Implement
PHASE 2/3Execute and verify one focused phase at a time.
6 · Complete
VERIFIEDArchive verified work and select what comes next.

Why

AI agents are great at writing code and bad at running projects. They forget context between sessions, skip steps, lose track of multi-ticket work, and can't resume where they left off.

🗂

Persistent by design

Everything lives in .workflow/ inside your repo — markdown files and folders. Close the session, come back tomorrow, the agent picks up exactly where it stopped.

🧭

Structured, not rigid

A clear path from idea to shipped code: context → tickets → phased plan → implementation → done. Reviews are optional. Single-PR fixes and multi-ticket epics both fit.

🔌

No hosted tools

No Jira, no database, no server. Ticket directories moving between numbered folders are the source of truth. Optional isolated worktrees use local Git.

Why Not Just Ask the Agent for a PLAN.md?

You can — once. The problem is everything after that: the second session, the fifth ticket, the phase you left half-finished on Friday.

Situation Ad-hoc prompting workflow-agent
New session You re-explain the goal, constraints, and what's already done. wf status PYE-1123 reconstructs it from files in seconds.
Context window fills up Compaction silently drops decisions; the agent re-litigates them. Decisions live in CONTEXT.md and PLAN.md, re-read on demand.
Multi-ticket work One giant plan that drifts from reality after ticket two. Ticket directories move draft → todo → in-progress → done.
Half-finished work "Where did we stop?" is a guess. wf implement PYE-1123 001 phase 3 resumes exactly there.
Status truth A status field in a doc that nobody updates. Folder location is the status; summaries auto-repair on drift.
Setup cost None, but repeated every session. One npx install. No server, database, or hosted service.

Swipe the table sideways to compare all three columns.

Resume Without Reconstructing Everything

Return after an hour, a week, or a fresh agent session. One command tells you where work stopped and what to do next.

wf status <change id>

Your project handoff, available instantly.

No rereading every diff, ticket, plan, or conversation. wf status PYE-1123 inspects persisted workflow state and gives you a concise, trustworthy view of the selected change.

Shows every ticket grouped by in progress, todo, and done.
Distinguishes planned tickets from those still needing a plan.
Reconciles STATUS.md against ticket folders when summaries drift.
Ends with the exact recommended wf command to run next.
PYE-1123-auth-refactor — 2/5 done

In Progress
  → 003  Replace auth middleware
    Phase 2/3 complete

Todo
  ○ 004  Add integration tests planned
  ○ 005  Remove legacy paths  needs plan

Done
  ✓ 001  Extract auth service
  ✓ 002  Add token validation

Next: run wf implement PYE-1123 003 phase 3

Quickstart

Install once, then drive everything through wf commands — or just describe what you want in natural language.

1

Install the skill

Requires Node.js 18+ (for npx) and an agent that supports Agent Skills.

npx skills add zetdotcom/workflow-agent --skill wf # add -g for global

Prefer a local checkout? Clone the repo and run ./install.sh — it symlinks skills/wf into ~/.agents/skills/, so your edits apply immediately. Override the destination with AGENTS_SKILLS_DIR.

2

Start a change — wf new

Creates the change folder with CONTEXT.md, STATUS.md, and the four status folders. Then run wf discover — a short interview that turns your raw notes into structured context.

wf new # scaffold PYE-1123-auth-refactor wf discover # interview → complete CONTEXT.md

Don't want to memorise commands? Run bare wf for an interactive menu, or just describe what you want — “break this epic into tickets” routes to the right command.

Need isolation? Add --worktree to any command or ask naturally. Choose a new branch, available branch, or detached snapshot. The agent validates refs and collisions, confirms reuse, then runs every operation in the selected sibling worktree.

3

Break it into tickets — wf breakdown

Proposes independently deployable tickets (1–3 days each) with goals, risk, and dependencies. Nothing is created until you confirm.

wf breakdown # propose tickets, create after confirmation
4

Plan a ticket — wf plan

The agent explores your actual codebase, validates assumptions, and writes a detailed phased PLAN.md plus a concise PLAN-BRIEF.md for human review.

wf plan PYE-1123 001 wf plan-review PYE-1123 001 # optional sanity check
5

Implement, phase by phase — wf implement

Executes one verifiable phase at a time, runs tests, and records results in PROGRESS.md. Resume any phase later.

wf implement PYE-1123 001 phase 1 wf impl-review PYE-1123 001 # optional code review vs plan
6

Finish and track — wf complete / wf status

Complete verifies readiness before moving the ticket to done. Status shows scoped progress and always recommends the exact next command.

wf complete PYE-1123 001 wf status PYE-1123

The Lifecycle

One entry point, nine commands. Reviews are optional gates — use them for risky work, skip them for small fixes.

What Gets Created

workflow-agent stores everything as readable Markdown inside your repository. Files appear only when needed, and ticket folders move to represent real lifecycle state.

Repository structure
  • .workflow/
    • changes/
      • PYE-1123-auth-refactor/
        • CONTEXT.md change definition
        • STATUS.md progress summary
        • 1.draft/
        • 2.todo/
          • 001-token-validation/
            • TICKET.md
            • PLAN.md
            • PLAN-BRIEF.md
        • 3.in-progress/
        • 4.done/
Ticket directory location is source of truth: draft → todo → in-progress → done. The whole directory moves, keeping every plan, review, and progress note together.
Created by each command
wf new
Creates change folder, four lifecycle folders, CONTEXT.md, and STATUS.md.
wf discover
Rewrites CONTEXT.md with structured goals, scope, constraints, risks, and rollout.
wf breakdown
Creates each NNN-ticket/ directory in 1.draft/ with its stable TICKET.md.
wf plan
Adds detailed PLAN.md and human-readable PLAN-BRIEF.md, then moves ticket to 2.todo/.
wf implement
Moves ticket to 3.in-progress/ and creates PROGRESS.md when first recording phase results.
wf reviews
Optional. plan-review or impl-review creates and appends dated findings to REVIEWS.md.
wf complete
Adds completion record, moves whole ticket directory to 4.done/, and updates STATUS.md.
wf status
Reads folder state; only updates STATUS.md when reconciling detected drift.

Digging Deeper

How workflow-agent stores and reasons about your work.

Storage model — folders are the source of truth

Each ticket is a directory that moves between numbered status folders. No status field can drift from reality — the location is the status. STATUS.md is a derived summary and gets auto-repaired if it drifts.

.workflow/ └── changes/ └── PYE-1123-auth-refactor/ ├── CONTEXT.md # change definition ├── STATUS.md # derived progress summary ├── 1.draft/ # new / unplanned │ └── 001-remove-old-deposit/ │ └── TICKET.md ├── 2.todo/ # planned, ready to implement ├── 3.in-progress/ # being implemented └── 4.done/ # implementation complete
Ticket files — created only when needed

Breakdown creates only TICKET.md. Planning adds PLAN.md and PLAN-BRIEF.md. Progress and review files appear lazily. Empty placeholder files are never created.

  • TICKET.md Goal, scope, acceptance criteria, risk, dependencies, technical context
  • PLAN.md Detailed, phased implementation plan — the implementation source of truth
  • PLAN-BRIEF.md Concise human summary: main changes, data flow, decisions, risks, review questions
  • PROGRESS.md Phase results, verification, deviations, PR-feedback work
  • REVIEWS.md Dated plan and implementation reviews
Phased implementation — verify as you go

Plans are split into coherent, independently verifiable phases. Implementation runs one phase at a time, each verified before moving on. You can execute or resume any single phase:

wf implement PYE-1123 001 phase 3

If the codebase contradicts the plan, the agent stops and tells you instead of improvising.

Addressing — change first, then ticket

Ticket-scoped commands take <change> <ticket>. A unique ID prefix like PYE-1123 resolves to PYE-1123-auth-refactor. When anything is ambiguous or omitted, the agent asks instead of guessing.

wf plan PYE-1123 001 wf status PYE-1123 001
Done isn't frozen — PR feedback and reopening

done means implementation completed — the PR may still be in review, merging, or receiving feedback. PR-feedback changes can update code and notes while the ticket stays in 4.done/. Explicit reopening moves it back to in-progress with a recorded reason. Follow-up work beyond the original scope becomes a new ticket.

All commands
  • wf new Create a change and its workflow structure
  • wf discover Interview to turn raw context into a structured change definition
  • wf breakdown Propose and create independently deployable tickets
  • wf plan Explore code, write phased PLAN.md + PLAN-BRIEF.md
  • wf plan-review optional Review a plan before coding
  • wf implement Execute and verify one implementation phase at a time
  • wf impl-review optional Review code against plan and acceptance criteria
  • wf complete Verify readiness, move ticket to done
  • wf status Scoped progress and exact next action

FAQ

The questions developers ask before installing.

Should I commit .workflow/?

Your call, and both work. Commit it when you want teammates and CI-adjacent reviewers to see the plan and progress alongside the diff. Add it to .gitignore when you treat it as a personal scratchpad. Nothing in the skill depends on it being tracked.

Will it bloat my repo?

It's plain Markdown — typically a few KB per ticket. No binaries, no lockfiles, no generated artifacts. A large epic with a dozen planned tickets is still smaller than a single screenshot.

Does it burn extra tokens?

Files are read on demand, not preloaded. A command loads its own reference plus the specific ticket it touches. Overall it usually costs fewer tokens than re-explaining a project from scratch each session.

Do I need Jira or a ticket tracker?

No. Tickets are directories. If you already use an external tracker, reuse its IDs as change prefixes — PYE-1123 addresses PYE-1123-auth-refactor — so the two stay readable side by side.

What about multiple developers?

Ticket directories are separate files, so parallel work rarely collides. STATUS.md is derived, not authoritative — if it conflicts or drifts, wf status reconciles it from the folder layout.

Can I use it for a one-line fix?

Yes, and you should skip most of it. Use wf new plus a single ticket, skip both review gates, and go straight to wf implement. The reviews and breakdown exist for work that actually warrants them.

How do I remove it?

Delete the skill and .workflow/. If you opted into worktree mode, remove any created worktrees or branches separately with normal Git commands; workflow-agent never deletes them automatically.

What if the plan is wrong?

When the codebase contradicts the plan, the agent stops and reports the mismatch instead of improvising. Deviations that you accept are recorded in PROGRESS.md, so the trail stays honest.

Compatibility

Agents need Agent Skills, filesystem tools, question/choice prompts, Git execution, and explicit command working directories. Optional package installation also needs selected package-manager executable.

OpenCode Claude Code Any skills-capable agent

Built and exercised on OpenCode and Claude Code. Other skills-capable agents should work; if yours doesn't, open an issue.