name: workflow-management description: Use PROACTIVELY when discovering, creating, renaming, or removing workflow definitions. MUST BE USED when adding a new user-facing flow that needs testing, or when the user asks for workflow changes. Owns the four-file workflow contract (registry + spec + bug file + fix-loop binding). last_updated: 2026-04-18

Workflow Management

Workflows are the unit of testable user-facing behavior. Each workflow touches four files that together form one system; this skill owns the rules for creating, maintaining, and retiring them.

The four-file workflow contract

All four live inside the vault-synced allowlist (see docs-governance), so vault/Obsidian always sees the full state.

When to create a workflow

Signals that something should become a workflow:

1. User-facing flows — sign up, log in, create/edit/delete, checkout, upload.
2. Integration points — API calls, webhook handlers, third-party service interactions.
3. Background processes — job queues, scheduled tasks, sync operations.
4. Admin operations — user management, configuration, deployments.
5. Critical paths — anything where failure means the user can't complete their goal.

Rule of thumb: if it broke, would a user notice? If yes, it's a workflow.

Creating a workflow — three steps

1. Add an entry to .claude/workflows.md

## <workflow-name>

- **Description:** One-line user-facing summary.
- **Test methods:** chrome-mcp | playwright | curl | bash | test-suite
- **URL:** (if browser-based)
- **Steps:**
  1. First thing that happens
  2. Next thing
  3. Expected result
- **What to check:**
  - Expected behavior A
  - Expected behavior B
  - No errors in console/logs
- **Test actions:**
  - Specific commands or UI actions to exercise the flow
- **Verification command:** `npm test` or a workflow-specific command
- **Baseline success:** What "passing" looks like, one sentence
- **Skip if:** When this test isn't relevant (e.g. "dev server not running")
- **Escalate if:** When to stop and ask the user (e.g. "auth provider changed")

2. Create the behavioral spec at docs/system/<workflow-name>.md

# Workflow: <Name>

## What it does
Describe the flow from the user's perspective.

## Steps
1. User does X
2. System responds with Y
3. User sees Z

## Rules
- Must complete within <time>
- Invalid input shows inline errors, doesn't clear form
- Requires authentication

## Edge cases
- What happens with empty input?
- What happens with very large input?
- What happens if a dependency is down?

## Last verified
YYYY-MM-DD — passed / failed (link to session log)

3. Create the empty bug file at .claude/bugs/workflows/<workflow-name>.md

# Bugs: <workflow-name>

Per-workflow view of bugs. Entries also live in the root bug files
(`.claude/bugs/{agent-reported,user-reported,resolved}.md`).

*No bugs tracked yet.*

The bug-fixer agent and fix-loop skill both read this file as part of their loop.

Naming rules

• Lowercase, hyphens, no spaces: checkout-flow, user-signup, background-jobs.
• Short enough to be memorable: ≤3 words where possible.
• Same slug across all four files.
• Don't prefix with the project name — the repo context is implicit.

Maintaining workflows

After each fix-loop run or significant change:

1. Update Last verified in docs/system/<workflow>.md.
2. Add any newly discovered bugs to the matching bugs/workflows/<name>.md.
3. Keep root bug files (agent-reported.md, user-reported.md, resolved.md) and the per-workflow file in sync — fix-loop enforces this.
4. Split large workflows if they cover more than ~7 steps or multiple personas. Each workflow should exercise one coherent slice.
5. Retire stale workflows when a feature is removed — delete all four artifacts in one commit, grep for references first.

Connecting workflows to other skills

• fix-loop reads .claude/workflows.md to pick targets. Delegates the bug-fix rhythm to test-first.
• bug-fixer agent reads the per-workflow bug file before any fix.
• docs-governance ensures all four file locations stay in the synced allowlist.
• writing-skills owns frontmatter rules for any new skills related to workflows.

When to skip creating a workflow

• The code is exploratory/throwaway and you don't plan to keep it.
• It's pure refactoring with no user-visible behavior change.
• It's a one-off script (cron, migration) — those belong in docs/runbooks/, not as a workflow.