workflow-agent
Frontend team walkthrough
From request to verified code

Give your coding agent project memory.

One practical walkthrough: adding a new payment method without losing context, scope, or progress.

30 minutesreal commands · real files
workflow-agent
01 / Why
Daily engineering workflow

What changes when work spans sessions?

Start→Write goal and constraints once
Plan→Validate assumptions against current code
Build→Implement and verify one phase at a time
Resume→Read persisted state instead of reconstructing chat
repo/
├── src/                 # product code
├── tests/               # verification
└── .workflow/          # agent state
    └── changes/
        └── ABC-123-.../
            ├── CONTEXT.md
            ├── STATUS.md
            └── ...
workflow-agent
01 / Why
Core idea

Workflow state lives beside code.

Plain Markdown in .workflow/. No server. No database. Ticket directory location is lifecycle status.

wf newopen workspace
wf discoverclarify intent
wf breakdowncreate tickets
wf specifyconfirm behavior
wf planground in code
wf implementbuild by phase
wf completeverify and finish
wf archivepreserve the why
workflow-agent
02 / Walkthrough · start
Step 1 · Open workspace

wf new

wf new ABC-123 add paypal checkout

Provide change ID and short description. Agent resolves them to stable slug ABC-123-add-paypal-checkout and scaffolds workflow state.

ABC-123-add-paypal-checkout/
├── CONTEXT.md
├── STATUS.md
├── 1.draft/
├── 2.todo/
├── 3.in-progress/
└── 4.done/
workflow-agent
02 / Walkthrough · clarify
Step 2 · Turn idea into constraints

wf discover ABC-123

Agent reads raw context, then interviews only missing areas: behavior, scope, dependencies, risk, rollout.

You confirm synthesis. Application code stays untouched.
ABC-123-add-paypal-checkout/
├── CONTEXT.md     modified
├── STATUS.md          0/0 done
├── 1.draft/
├── 2.todo/
├── 3.in-progress/
└── 4.done/

src/                    unchanged
tests/                  unchanged
workflow-agent
02 / Walkthrough · scope
Step 3 · Define deployable units

wf breakdown ABC-123

Provider contract + feature flagShared types, API adapter, configuration
medium
PayPal checkout UISelector, provider flow, states, analytics
medium
Checkout integration coverageRegression and provider-flow tests
low
ABC-123-add-paypal-checkout/
├── CONTEXT.md
├── STATUS.md      modified
└── 1.draft/
    ├── 001-provider-contract/
    │   └── TICKET.md
    ├── 002-paypal-checkout-ui/
    │   └── TICKET.md
    └── 003-integration-coverage/
        └── TICKET.md

Created only after confirmation
workflow-agent
02 / Walkthrough · filesystem
After confirmation

Only ticket definitions appear.

No speculative plans. No empty progress or review files.

ABC-123-add-paypal-checkout/
├── CONTEXT.md
├── STATUS.md
├── 1.draft/
│   ├── 001-provider-contract/
│   │   └── TICKET.md
│   ├── 002-paypal-checkout-ui/
│   │   └── TICKET.md
│   └── 003-integration-coverage/
│       └── TICKET.md
├── 2.todo/
├── 3.in-progress/
└── 4.done/
workflow-agent
02 / Walkthrough · plan
Step 4 · Ticket 001 done; plan frontend ticket

wf plan ABC-123 002

Explore→Components, hooks, API clients, analytics, tests
Validate→Correct assumptions from TICKET.md and optional SPEC.md
Design→Phases, affected files, specification verification mapping
ABC-123-add-paypal-checkout/
├── 1.draft/
├── 2.todo/
│   └── 002-paypal-checkout-ui/
│       ├── TICKET.md
│       ├── SPEC.md
│       ├── PLAN.md
│       └── PLAN-BRIEF.md
├── 3.in-progress/
└── 4.done/
    └── 001-provider-contract/

src/                    unchanged
workflow-agent
02 / Walkthrough · phases
Example plan for ticket 002

Three independently verifiable phases.

Phase 1

Payment selection

Add PayPal option behind flag. Preserve current default and accessibility behavior.

Phase 2

Provider flow

Launch redirect, process return state, and prevent duplicate submission.

Phase 3

Feedback + telemetry

Pending/error UI, analytics events, focused component tests.

Each phase names affected files, tests, and observable completion criteria.
workflow-agent
02 / Walkthrough · build
Step 5 · Execute one phase

wf implement ABC-123 002 phase 1

Agent reads ticket, optional specification, and plan; checks dependencies; moves the ticket to in-progress; then implements and verifies only the selected behavior slice.

If code contradicts confirmed behavior or the plan materially, the agent stops instead of improvising.
1.draft/
2.todo/
3.in-progress/
└── 002-paypal-checkout-ui/
    ├── TICKET.md
    ├── SPEC.md
    ├── PLAN.md
    ├── PLAN-BRIEF.md
    └── PROGRESS.md

# Application files now change too
src/checkout/...
tests/checkout/...
workflow-agent
02 / Walkthrough · record
After each phase

Results survive session boundaries.

PROGRESS.md records changed files, verification results, deviations, and phase status. Verified completion boxes update in PLAN.md.

### Phase 1 Implementation - 2026-08-06

Changes made:
- PaymentMethodSelector.tsx
- usePaymentMethods.ts
- PaymentMethodSelector.test.tsx

Deviations: none

Verification:
- pnpm test PaymentMethodSelector PASS

Phase status: completed
workflow-agent
02 / Walkthrough · gates
Optional review gates

Use rigor where risk warrants it.

wf plan-review ABC-123 002

  • Feasibility and codebase fit
  • Scenario coverage and missing edge cases
  • Risk, rollout, and test quality
OPTIONAL

wf impl-review ABC-123 002

  • Diff against plan and ticket
  • Acceptance criteria, specification, and tests
  • Regressions and unresolved findings
First review creates REVIEWS.md; later reviews append dated findings.
workflow-agent
02 / Walkthrough · finish
Step 6 · Verify, then finish

wf complete ABC-123 002

Readiness checks

Phases, final verification, acceptance criteria, optional specification coverage, unresolved review items.

PROGRESS.md

Completion record appended.

STATUS.md

Progress counter and next actionable ticket updated.

ABC-123-add-paypal-checkout/
├── 1.draft/
├── 2.todo/
├── 3.in-progress/
└── 4.done/
    ├── 001-provider-contract/
    └── 002-paypal-checkout-ui/
        ├── TICKET.md
        ├── SPEC.md
        ├── PLAN.md
        ├── PLAN-BRIEF.md
        ├── PROGRESS.md
        └── REVIEWS.md
workflow-agent
02 / Walkthrough · preserve
Step 7 · Preserve the why

wf archive ABC-123

Distills any terminal change into one dated SUMMARY.md: outcome, lasting decisions, invariants, limits, evidence, and references. Preview the complete summary and removal manifest before confirming.

Outcomes are explicit: completed, cancelled, superseded, or closed-incomplete.
.workflow/archive/
  └── 2026-10-13-ABC-123-add-paypal-checkout/
      └── SUMMARY.md
workflow-agent
03 / Resume
Tomorrow. New session.

No “where were we?” archaeology.

wf status ABC-123

Reconciles folders, reports progress, and gives exact next action.

ABC-123-add-paypal-checkout - 2/3 done

Todo
  003 Integration coverage needs plan

Done
  ✓ 001 Provider contract
  ✓ 002 PayPal checkout UI

Recommended next action:
wf plan ABC-123 003
workflow-agent
03 / Benefits
What this buys you

Benefits

  • Work resumes across sessions from files in the repo, not from chat memory.
  • Plans come from actual codebase exploration and get verified one phase at a time.
  • Ticket folder location is the status — nothing to update, nothing to go stale.
  • Teams working in the same area can ask the agent whether planned work already exists in another team's changes.
workflow-agent
04 / Reference
Command → repository effect

What touches your codebase?

--worktree→Optional sibling worktree; branch/ref, reuse, and installs stay confirmed
new / discover→Change-level CONTEXT.md + STATUS.md
breakdown→Draft ticket directories + TICKET.md
specify→Optional confirmed ticket-level SPEC.md; lifecycle state unchanged
plan→PLAN.md + PLAN-BRIEF.md; ticket moves to todo
implement→Application code + tests + PROGRESS.md; ticket moves in-progress
reviews / complete→REVIEWS.md; verified ticket moves to done
archive→Dated SUMMARY.md; active change removed after confirmation
status→Read-only, except repairing derived STATUS.md drift
workflow-agent
End
Questions

Less re-prompting.
More continuity.

Project installnpx skills add zetdotcom/workflow-agent --skill wf
Global installnpx skills add zetdotcom/workflow-agent --skill wf -g

github.com/zetdotcom/workflow-agent

← → navigate · Home/End jump · swipe on touch