workflow-state
Read and update workflow state when planning, executing, completing, pausing or resuming project work.
- License 许可
- MIT
- 所属仓库
- 1aGh/maude
- 最近更新
- 2026-11-13
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- workflow-state
- type
- skill
- keywords
- [ "state", "workflow", "phase", "handoff", "continuity", "session" ]
- description
- Read and update workflow state when planning, executing, completing, pausing or resuming project work.
03 SKILL.md 正文
Workflow State
Follow host conventions for Claude Code or Codex.
.ai/state/STATE.md is the single source of truth for "what's happening right now." It's read by /status, /resume, /done, and any future agent that joins mid-feature. Keep it accurate.
This skill complements workflow-orchestration (which covers the protocol of phases & gates). This skill focuses on the STATE.md schema and lifecycle.
Backend: file vs. knowledge graph (kgai-aware)
Load flow:kgai-backend and check maude kg resolve --json before treating STATE.md as authoritative:
active: false(default — most repos) → the schema below is the source of truth. Everything in this skill applies unchanged. No regression.active: true→ the knowledge graph is the history authority, and.ai/state/STATE.mdis a thin human-readable pointer-stub (written bymaude init --kg): status line + "history lives in kgai —kg history/kg context". History rows, the Decisions section, and pause/resume state live as graph events (seeflow:kgai-backendfor theplan:/session:recipes;/flow:run --pauserecords apausedevent,/flow:run --resumereconstructs from it,/flow:run --statusoverlayskg history/kg context). Do NOT append full History rows to the stub — write the movement to the graph instead. The narrative files STATE.md never owned (PRD, design-system, plans) stay on disk as prose.
This is behind the active gate — an inactive repo keeps the full STATE.md below, untouched (slim, never gut).
STATE.md schema
# Workflow State
**Workflow:** ad-hoc
**Phase:** intake | discovery | design | planning | execution | verification | done | paused | blocked
**Status:** ready | in-progress | paused | blocked | done
**Started:** <YYYY-MM-DD>
**Updated:** <YYYY-MM-DD HH:MM>
**Active task:** <one-liner from the plan or "—">
**Active plan:** <.ai/plans/<x>.plan.md, or `plan:<slug>` when the plan lives in orbit, or "—">
## Decisions
<bullet list — short summaries; full DDRs live in .ai/decisions/>
## Blockers
<bullet list — what is in the way, who must decide it>
## History
| When | Phase | Note |
| ---- | ----- | ---- |
| <YYYY-MM-DD HH:MM> | <phase> | <one-liner> |
Rules
- Every phase change → a new history row. History is append-only — no row gets rewritten, removed, or reordered.
- Update the Updated field on every edit.
/statusand/resumeuse it to detect stale state. - Pause path: Phase →
paused, Status →paused, keep the currentActive task(do not clear it). Details go in.ai/state/HANDOFF.md. - Done path: Phase →
done, Status →done, Active task →—, Active plan →—. The plan moves to.ai/plans/archive/— unlessintegrations.tracker.artifacts.storeisorbit, where there is no local archive and the Active plan line holds the orbit slug (plan:<slug>) instead of a path, so/flow:run --resumeand/flow:run --statusknow to pull it (flow:orbit-backendguide 06). - Blocked: Phase stays the same, Status →
blocked, the Blockers section gets a bullet with the specifics.
HANDOFF.md (only while paused)
A transient file. Created on /pause, removed on /resume. Never committed standalone — it lives in .gitignore. If it appears in git, that is a leak.
Use .ai/templates/HANDOFF.md as the base. Key sections:
- Active feature
- Last task (with status)
- Next step (concrete command / file / line)
- Open questions / blockers
- Files touched (uncommitted)
- Recent thinking (1–2 paragraphs — trail of thought)
Anti-patterns
- ❌ Hand-editing History without a phase change.
- ❌ Deleting History rows to "clean up" — that is institutional amnesia.
- ❌ STATE.md committed with status
in-progresson the main branch — either work isdone, or it lives in a PR. - ❌ HANDOFF.md committed — it is gitignored for a reason.
- ❌ Multiple active plans at once without an explicit reason — if you want to drive two things in parallel, use branches, not one state.
Integration
| Command | What it does with STATE.md |
|---|---|
/plan |
Phase → planning, Active plan → <path>, history row |
/execute |
Phase → execution, Active task per task, history row per completed task |
/done |
Phase + Status → done, plan archived, final history row |
/pause |
Status → paused, Active task kept, creates HANDOFF.md |
/resume |
Status → in-progress, removes HANDOFF.md, history row |
/status |
Read-only — returns summary |
/flow:record-ddr |
Appends to ## Decisions (summary only, full DDR in .ai/decisions/) |
04 同仓库更多 Skills
ui-rules
UI hard-stop rules and audit method: WCAG 2.1 AA accessibility, responsive layout and motion.
testing-rules
Apply test quality rules during implementation and review: meaningful assertions, isolation and coverage.
security-rules
Apply application and AI security checks to code reviews, implementation and threat-driven validation.
scenario
Author or run cross-platform UI scenarios with selectors, screenshots, platform coverage and result reports.
question-protocol
Batch necessary questions from workflow participants, collect user answers and route them to the requester.
quality-gates
Resolve project quality commands, scoped checks, gate failures and validation fallbacks from workflow config.