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:

1. Generate kebab-case slug from description
2. Add entry to manifest with branch: feat/<slug>
3. 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

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:

1. Create docs/workflow-state.yaml if it doesn't exist (use assets/workflow-state-template.yaml)
2. Generate a kebab-case slug from the description (e.g., "Add anti-hallucination guardrails" → add-anti-hallucination-guardrails)
3. 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
4. Create and checkout git branch: git checkout -b feat/<slug>

When advancing a work item:

1. Read docs/workflow-state.yaml
2. 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)
3. 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
4. Update stage field to the next stage in the track
5. Update checkpoint if a checkpoint boundary was crossed
6. 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:

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.