docs · workflow

Workflow Lifecycle.

The durable lifecycle path from initial exploration to validated handoff, and the lightweight reduced modes for bounded changes.

Lifecycle Architecture.

The workflow lifecycle requires no running daemon or database binary. AGENTS.md serves as the entry point, defining the shared workflow boundaries. Each stage delegates to a dedicated markdown playbook in docs/playbooks/, executing directly against the repository code and committed markdown plans.

1. Explore trade-offs & lock requirements→/brainstorm
2. Structure phases, tasks & checks→/to-plan
3. Execute wave-by-wave with verified proof→/work
4. Fail-closed review & proof re-execution→/check
5. Conventional commit, push & PR→/git
6. Persist session state & next actions→/handoff

The 6 Playbooks.

The core lifecycle is governed by six projected playbooks located under docs/playbooks/:

1. brainstorm

playbook

Explores options, analyzes feasibility, and clarifies intent. In lock mode, creates the active initiative file at docs/plans/active/{slug}.md and verifies repository identity in docs/PROJECT.md.

docs/playbooks/brainstorm.md

2. to-plan

playbook

Transforms locked specifications into executable implementation blueprints: defines technical approach, decomposition into phases (waves only on the high-risk lane), and concrete verification checks.

docs/playbooks/to-plan.md

3. work

playbook

Executes the next phase of the active plan (full) or a direct change (bounded). Runs tasks in waves on the high-risk lane, captures observable evidence, appends task results to ## Log, and ends every phase with a check gate.

docs/playbooks/work.md

4. check

playbook

Quality gate in three modes: bounded (response-only evidence), gate (automated phase gate, appends to ## Validation), and full (gate plus the complete Security, Performance, Architecture, and Code Quality review, once, on the final phase). full and high-risk entries require judge: independent.

docs/playbooks/check.md

5. handoff

playbook

Session close-out. Records blockers and the exact next action in ## Current State and Next Action. On final close, appends one absorb: decision (none, or an ADR, guard, or memory) and git mvs the plan to docs/plans/completed/.

docs/playbooks/handoff.md

6. watzup

playbook

Cold session recap. Reads current git branch state, uncommitted changes, active plan progress, and recent handoff notes to recommend the precise next command without modifying any files.

docs/playbooks/watzup.md

Reduced Modes for Bounded Tasks.

Not every change warrants a full multi-wave initiative ledger. Reduced modes provide fast execution while maintaining rigor:

Command
Scope
Behavior & Persistence
01
/brainstorm explore
Research
Response-only analysis. Evaluates trade-offs without writing a plan file to disk.
02
/work simple <task>
Small Change
Direct execution and verification without creating active plan files or multi-wave ledger rows.
03
/check bounded
Targeted
Runs the relevant tests and linters for a direct change and returns evidence in the response only. Never writes to a plan.
04
/watzup
Inspection
Read-only inspection of git status, active plan, and handoff notes. Zero side effects.

Execution Boundary & State Model.

A plan has exactly five sections: ## Goal, ## Phases and Verification, ## Log, ## Validation, and ## Current State and Next Action. At most one plan may be active. Execution state is append-only and file-driven:

  • Log: Task results, blockers, and decisions with their rationale append directly to ## Log in docs/plans/active/{slug}.md.
  • Validation: Quality gates, proof command outputs, and approval verdicts append to ## Validation.

Every proof claim must cite concrete command outputs or observable runtime evidence. Pre-commit hooks re-execute validation proofs fail-closed, ensuring that committed plans reflect reality.

markdown — active plan structure markdown 
# Plan: auth-token-refresh — Sliding Expiration Window

## Goal
- outcome: refresh tokens rotate on a sliding expiration window
- success_signal: a token used after 15 idle minutes is rejected
- actors: API clients holding refresh tokens
- requirements:
  - R1: each refresh issues a new token and revokes the old one | acceptance: auth tests | source: owner

## Phases and Verification
- approach: rotate in the token service; middleware only reads
- phase_slug: `token-refresh`
  status: checked
  - goal: R1 | depends_on: none
  - T1 token generator — output: rotating tokens — check: `go test ./pkg/auth/...` — stop_if: old token still valid
  - T2 HTTP middleware — output: reads only — check: `go test ./pkg/http/...` — stop_if: middleware writes tokens

## Log
- 2026-08-28T04:00Z — token-refresh/T1 — done — `go test ./pkg/auth/...` passed (14 tests).
- 2026-08-28T04:30Z — token-refresh — decision — 15-minute sliding window, 7-day absolute max.

## Validation
- 2026-08-28T05:00Z — phase `token-refresh` — verdict: APPROVED — mode: gate
  - `go test -race ./...` — exit 0
  - `golangci-lint run` — exit 0
  - scope: on target — token service and middleware only
  - requirements: R1 met (`go test ./pkg/auth/...`)
  - rollback_point: a1b2c3d
  - requests: none
  - judge: independent
  - judge_model: claude-opus-5

## Current State and Next Action
- active_phase: token-refresh
- lifecycle_status: checked
- blockers: none
- open_items: none
- exact_next_action: check full on token-refresh (final phase), then handoff
Ready to learn more about the underlying architecture or install the harness?
Read Architecture Install Guide