name	manage-work
description	Register work items, create feature branches, track and advance stages, close work items in the VibeFlow docs-first development workflow
metadata	{"triggers":["start vibeflow","begin workflow","new feature","workflow status","where am I","what stage","what track","select track","register work item","advance work item"]}

manage-work

Register work items, create feature branches, track and advance stages, close work items in the VibeFlow docs-first development workflow.

Purpose

This skill tracks multiple work items through the VibeFlow workflow by:

Registering work items with their workflow track and creating feat/<slug> branches
Tracking each work item's current stage independently
Advancing work items through stages and routing to the appropriate skill
Closing work items as DONE after Checkpoint #4 (release is optional)
Providing a dashboard view of all in-flight work items

Workflow

Register Work Item
    │
    ├── Assign ID, generate slug from description, and assign track
    ├── Create entry in docs/workflow-state.yaml (with branch field)
    ├── Create git branch: feat/<slug>
    └── Determine starting stage from track
    │
    ▼
Track Progress
    │
    ├── Show status dashboard (all work items)
    ├── Show detailed status (single work item)
    └── Cross-check manifest against artifacts
    │
    ▼
Advance & Route
    │
    ├── Mark work item as advancing to next stage
    ├── Recommend the appropriate skill command
    └── Update manifest with new stage
    │
    ▼
Close Work Item (after Checkpoint #4)
    │
    ├── Validate CP#4, set stage: DONE in manifest
    ├── Commit all changes on feat/<slug>
    ├── Push branch, create PR (or find existing)
    ├── Present PR URL — ask user to review
    │
    ├─► User accepts  → Merge PR, delete branch, checkout main
    └─► User declines → Leave PR open, stay on branch

Usage

Register a New Work Item

/manage-work register "<description>" <ID> <track>

Registers a work item in docs/workflow-state.yaml, determines the starting stage, and creates a git branch feat/<slug>.

Steps:

Generate kebab-case slug from description
Add entry to manifest with branch: feat/<slug>
Create and checkout git branch: git checkout -b feat/<slug>

Example:

/manage-work register "Add anti-hallucination guardrails" 030 medium
# Creates branch: feat/add-anti-hallucination-guardrails

/manage-work register "Export data to CSV" 031 small
# Creates branch: feat/export-data-to-csv

Status Dashboard

/manage-work status

Shows all registered work items with their current stage, track, and last checkpoint.

Example output:

Work Item                          Track    Stage  Checkpoint  Started
add-anti-hallucination-guardrails  Medium   G      3           2025-02-20
export-data-to-csv                 Small    E      2           2025-02-22

Detailed Work Item Status

/manage-work status <ID>

Shows detailed status for one work item including:

Current stage and description
Completed and remaining stages for its track
Last checkpoint passed
Artifact verification (cross-check with detect_track.py --workitem <ID>)

Advance a Work Item

/manage-work advance <ID>

Marks a work item as advancing to the next stage in its track:

Validates checkpoint if at a checkpoint boundary (blocks if failed)
Updates stage in docs/workflow-state.yaml
Updates checkpoint if a checkpoint boundary was crossed
Updates docs paths with any documents produced at the completed stage
Shows what the next stage requires
After Checkpoint #4 (Stage H): Offers two paths:
- advance → proceed to Stage I (release track)
- close → mark as DONE (see Close command below)

Close a Work Item

/manage-work close <ID>

Closes a work item with an interactive PR review and merge flow. Blocked if Checkpoint #4 validation fails.

Step 1 — Validate & mark DONE

Validate Checkpoint #4 if not yet passed (runs validate_checkpoint.py 4 --json --project-root <root>)
Requires work item to be at stage H or later with checkpoint >= 4
Set stage: DONE in docs/workflow-state.yaml

Step 2 — Commit all changes

Run git status to check for uncommitted changes on feat/<slug>
If there are changes: git add -A && git commit -m "chore(workflow): close <slug> (#ft-<ID>)"
If working tree is clean: skip commit

Step 3 — Push & create PR

Check for an existing PR: gh pr list --head feat/<slug> --state open --json url

If no PR exists: push and create one:

git push -u origin feat/<slug>
gh pr create --title "[ft-<ID>] <Description>" --body "## Summary

Closes work item #ft-<ID>: <Description>

Track: <track>
Stages completed: <stages>"

If PR already exists: use the existing PR URL

Step 4 — Ask user to review

Present the PR URL to the user
Ask: "Please review the PR. Would you like to merge it now, or keep it open?"
Wait for the user's response before proceeding

Step 5 — Merge or keep open

User accepts → merge, clean up, and switch to main:
```
gh pr merge --merge --delete-branch
git checkout main
git pull
```
Delete the local branch if it still exists: git branch -d feat/<slug>
User declines → leave the PR open, stay on feat/<slug>, inform the user the manifest is already DONE

Example:

/manage-work close 030
# Validates CP#4 → commits → creates PR → asks for review → merges on approval

Next Steps for a Work Item

/manage-work next <ID>

Shows the recommended next action for a work item:

What the current stage requires
Which skill command to run
Whether a checkpoint validation is needed first

Workflow Tracks

Track	Scope	Stages	Release	Example
Micro	Bug fix, typo, small refactor	F → G → DONE	No	Fix typo, update config
Small	Single feature, no contracts	E → F → G → H → DONE	Optional (I-L)	Add form field, UI polish
Medium	Multi-component, no new services	B → C → D → E → F → G → H → DONE	Optional (I-L)	New API endpoint
Large	System change, new contracts/services	A → B → C → D → E → F → G → H → DONE	Optional (I-L)	New LLM integration

Stage Overview

Planning Stages (A-D)

A — Initiate: Create/update PRD
B — Discovery: Analyze codebase (Medium/Large)
C — Specify: Create/update Tech Specs
D — Decide: Create ADRs for decisions

Checkpoint #1: Planning Complete

Design Stage (E)

E — Plan: Create Feature Spec with API Design

Checkpoint #2: Design Complete

Implementation Stages (F-H)

F — RED: Write failing unit tests + stubs
G — GREEN: Implement to pass tests
H — REFACTOR: Integration tests + quality validation

Checkpoint #3: Tests Complete (after F) Checkpoint #4: Implementation Complete (after H)

Release Stages (I-L)

I — Reconcile: Update specs if implementation deviated
J — Prepare: Write OP-NOTE
K — Deploy: Follow OP-NOTE, verify
L — Close: Update indices, tag release

Checkpoint #5: Release Ready (after J) Checkpoint #6: Deployed (after L)

Manifest Format

The manifest file docs/workflow-state.yaml is the single source of truth for work item lifecycle state:

workitems:
  add-anti-hallucination-guardrails:
    id: 030
    description: "Add anti-hallucination guardrails"
    track: medium        # micro | small | medium | large
    stage: G             # current stage letter (A-L) or DONE
    branch: feat/add-anti-hallucination-guardrails  # git branch
    started: 2025-02-20  # date work item was registered
    checkpoint: 3        # last checkpoint passed (1-6)
    docs:
      prd: docs/prds/prd.md
      discovery: docs/discovery/disco-030.md
      specs:
        - docs/specs/spec-llm.md
      adrs:
        - docs/adrs/adr-030-prompt-strategy.md
      feature: docs/features/ft-030-anti-hallucination.md
      opnote: null
  export-data-to-csv:
    id: 031
    description: "Export data to CSV"
    track: small
    stage: E
    branch: feat/export-data-to-csv  # git branch
    started: 2025-02-22
    checkpoint: 2
    docs:
      prd: null
      discovery: null
      specs: []
      adrs: []
      feature: docs/features/ft-031-export-csv.md
      opnote: null

When registering a new work item:

Create docs/workflow-state.yaml if it doesn't exist (use assets/workflow-state-template.yaml)
Generate a kebab-case slug from the description (e.g., "Add anti-hallucination guardrails" → add-anti-hallucination-guardrails)
Add the work item entry with id, description, track, stage (first stage for the track), branch (feat/<slug>), started (today), checkpoint: 0, and empty docs hierarchy
Create and checkout git branch: git checkout -b feat/<slug>

When advancing a work item:

Read docs/workflow-state.yaml
Check if current stage is a checkpoint boundary (D→E=CP#1, E→F=CP#2, F→G=CP#3, H→I=CP#4, J→K=CP#5, L→done=CP#6)
If checkpoint boundary: run uv run --no-project .claude/skills/validate-checkpoint/scripts/validate_checkpoint.py <N> --json --project-root <root>
- If exit code 1 (failed): STOP. Report errors. Do NOT update manifest.
- If exit code 0 or 2 (passed/warnings): proceed
Update stage field to the next stage in the track
Update checkpoint if a checkpoint boundary was crossed
Update docs with any document paths produced at the completed stage

Skill Routing

Each stage maps to a specific skill. After determining the current stage for a work item, recommend the appropriate command:

Stage	Skill	Recommended Command
A	define-prd	`/define-prd`
B	analyze-codebase	`/analyze-codebase <ID>`
C	define-tech-spec	`/define-tech-spec <name>`
D	record-decision	`/record-decision <ID> <slug>`
E	create-feature-spec	`/create-feature-spec <ID> <slug>`
F	run-tdd	`/run-tdd red`
G	run-tdd	`/run-tdd green`
H	run-tdd	`/run-tdd refactor`
I	prepare-release	`/prepare-release reconcile <ID>`
J	prepare-release	`/prepare-release opnote <slug>`
K	prepare-release	`/prepare-release check`
L	prepare-release	`/prepare-release check`

Checkpoint boundaries — recommend /validate-checkpoint <N> before advancing past:

Stage D → E (Checkpoint #1)
Stage E → F (Checkpoint #2)
Stage F → G (Checkpoint #3)
Stage H → I (Checkpoint #4)
Stage J → K (Checkpoint #5)
Stage L → done (Checkpoint #6)

Artifact Verification

Use detect_track.py to cross-check the manifest against actual artifacts:

# Verify a specific work item's artifacts match its manifest stage
python scripts/detect_track.py --workitem <ID> --verify

# Detect artifacts for a specific work item
python scripts/detect_track.py --workitem <ID>

# Detect artifacts for all registered work items
python scripts/detect_track.py --all-workitems

This catches drift between the manifest and actual project state.

Git Commit

After Manifest Updates (register/advance)

After register or advance updates the manifest, ask the user for permission before committing:

git add docs/workflow-state.yaml
git commit -m "chore(workflow): update manifest for <slug> (#ft-<ID>)"

After Close

The close flow handles its own commits inline (see "Close a Work Item" above). It commits all files via git add -A as part of Step 2, then pushes and creates a PR in Step 3.

Interactive PR Review and Merge

The close flow (Steps 3-5) manages the full PR lifecycle. Key commands and edge cases:

Commands used:

gh pr list --head feat/<slug> --state open --json url — check for existing PR
gh pr create --title "..." --body "..." — create PR if none exists
gh pr merge --merge --delete-branch — merge and delete remote branch
git checkout main && git pull — switch to main after merge
git branch -d feat/<slug> — clean up local branch

Edge cases:

No uncommitted changes: git status is clean → skip commit in Step 2
PR already exists: reuse the existing PR URL instead of creating a new one
Merge conflicts: report the conflict to the user, leave PR open, stay on branch
User declines merge: PR stays open, branch preserved, manifest already shows DONE

References

See references/workflow-summary.md for a condensed workflow overview.