# workflow-agent

> Filesystem-based ticket lifecycle skill for AI coding agents. One `wf` skill manages work from idea to completed implementation — context, tickets, phased plans, reviews, and progress persist as markdown files in the repository, so work resumes across sessions. No servers or databases.

Site: https://michalzet.com/workflow-agent
Repository: https://github.com/zetdotcom/workflow-agent
Author: zetdotcom (https://github.com/zetdotcom)
License: MIT

## What it is

workflow-agent is an Agent Skill (installed via `npx skills add zetdotcom/workflow-agent --skill wf`). It gives an AI coding agent structured project management: single-PR features and multi-ticket epics through one `wf` entry point.

Lifecycle: new -> discover -> breakdown -> plan -> implement -> complete, with optional plan-review and impl-review gates.

## Commands

- `wf` — interactive menu
- `wf new` — create a change and its workflow structure
- `wf discover` — interview to turn raw notes into a structured CONTEXT.md
- `wf breakdown` — propose and create independently deployable tickets (1-3 days each, user-confirmed, dependencies form a DAG)
- `wf plan <change> <ticket>` — explore codebase, write detailed phased PLAN.md plus concise human-readable PLAN-BRIEF.md
- `wf plan-review <change> <ticket>` — optional plan review before coding
- `wf implement <change> <ticket> [phase N]` — execute and verify one implementation phase at a time; results logged in PROGRESS.md
- `wf impl-review <change> <ticket>` — optional review of code against plan and acceptance criteria
- `wf complete <change> <ticket>` — verify readiness, move ticket to done
- `wf status [change] [ticket]` — scoped progress plus exact recommended next action

Ticket-scoped commands resolve change first, then ticket. Unique ID prefix such as `PYE-1123` addresses change `PYE-1123-auth-refactor`. Example: `wf implement PYE-1123 001 phase 3`.

## Optional worktrees

Add global `--worktree` to any invocation, such as `wf plan PYE-1123 001 --worktree`, or request a worktree naturally. Before normal command dispatch, agent can create a new branch from current/local `main`/another validated ref, select an available existing branch, or create a detached snapshot. Detached mode warns that commits have no branch. New paths are siblings named from repository plus sanitized branch/ref; reuse requires a registered identity match and confirmation. Occupied branches, invalid refs, and path collisions are never forced or overwritten. All later operations explicitly target selected root; missing workflow metadata stops non-`new` commands without caller-tree fallback.

After selection, optional dependency installation detects root lockfiles. Commands are `npm ci`, `pnpm install --frozen-lockfile`, Yarn frozen/immutable based on declared major, or `bun install --frozen-lockfile`. Multiple managers require exact choice. Exact command/path and lifecycle-script risk are shown before separate confirmation. No lockfile or decline skips install; failure requires explicit continue/stop choice.

## Storage model

All data lives in `.workflow/changes/<slug>/` in the managed project:

```
.workflow/changes/PROJ-123-auth-refactor/
├── CONTEXT.md          # change definition
├── STATUS.md           # derived progress summary
├── 1.draft/            # new / unplanned tickets
│   └── 001-ticket-slug/
│       └── TICKET.md
├── 2.todo/             # planned, ready to implement
├── 3.in-progress/      # being implemented
└── 4.done/             # implementation complete
```

Each ticket is a directory that moves whole between numbered status folders. Directory location is the source of truth; STATUS.md is derived and auto-repaired if drifted.

Ticket files (created lazily, never as empty placeholders):
- TICKET.md — goal, scope, acceptance criteria, risk, dependencies, technical context (created by breakdown)
- PLAN.md — detailed phased implementation plan; implementation source of truth (created by plan)
- PLAN-BRIEF.md — concise human summary: changes, data flow, decisions, risks, review questions (created by plan)
- PROGRESS.md — phase results, verification, deviations, PR-feedback work
- REVIEWS.md — dated plan and implementation reviews

## Key semantics

- Plans are grounded in actual codebase exploration and split into independently verifiable phases.
- Reviews are optional; agent warns before bypassing but permits explicit override.
- `done` means implementation completed — the PR may still be in review, merging, or receiving feedback. PR-feedback changes may update code and notes while the ticket stays in 4.done/. Explicit reopening moves it back to in-progress with a recorded reason. Out-of-scope follow-up becomes a new ticket.
- All dates are real YYYY-MM-DD in YAML frontmatter.

## Install

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

## Compatibility

Any AI agent supporting Agent Skills, filesystem tools, question/choice prompts, Git command execution, and explicit command working directories (e.g., OpenCode, Claude Code, Cursor). Package-manager tools are optional.