# Manage Work > Register work items, create feature branches, track and advance stages, close work items in the VibeFlow docs-first development workflow - Skill: `hardness1020/manage-work` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add hardness1020/manage-work` - Raw SKILL.md: https://api.skillmd.com/api/skills/hardness1020/manage-work/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: hardness1020 (https://skillmd.com/u/hardness1020) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hardness1020/manage-work --- # 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/` 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/ └── 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/ ├── 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 "" ``` Registers a work item in `docs/workflow-state.yaml`, determines the starting stage, and creates a git branch `feat/`. Steps: 1. Generate kebab-case slug from description 2. Add entry to manifest with `branch: feat/` 3. Create and checkout git branch: `git checkout -b feat/` 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 ``` 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 `) ### Advance a Work Item ``` /manage-work advance ``` 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 ``` 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 `) - 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/` - If there are changes: `git add -A && git commit -m "chore(workflow): close (#ft-)"` - If working tree is clean: skip commit **Step 3 — Push & create PR** - Check for an existing PR: `gh pr list --head feat/ --state open --json url` - If no PR exists: push and create one: ```bash git push -u origin feat/ gh pr create --title "[ft-] " --body "## Summary Closes work item #ft-: Track: Stages completed: " ``` - 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: ```bash gh pr merge --merge --delete-branch git checkout main git pull ``` Delete the local branch if it still exists: `git branch -d feat/` - **User declines →** leave the PR open, stay on `feat/`, 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 ``` 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: ```yaml 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/`), `started` (today), `checkpoint: 0`, and empty `docs` hierarchy 4. Create and checkout git branch: `git checkout -b feat/` 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 --json --project-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: | Stage | Skill | Recommended Command | |-------|-------|--------------------| | A | define-prd | `/define-prd` | | B | analyze-codebase | `/analyze-codebase ` | | C | define-tech-spec | `/define-tech-spec ` | | D | record-decision | `/record-decision ` | | E | create-feature-spec | `/create-feature-spec ` | | F | run-tdd | `/run-tdd red` | | G | run-tdd | `/run-tdd green` | | H | run-tdd | `/run-tdd refactor` | | I | prepare-release | `/prepare-release reconcile ` | | J | prepare-release | `/prepare-release opnote ` | | K | prepare-release | `/prepare-release check` | | L | prepare-release | `/prepare-release check` | **Checkpoint boundaries** — recommend `/validate-checkpoint ` 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: ```bash # Verify a specific work item's artifacts match its manifest stage python scripts/detect_track.py --workitem --verify # Detect artifacts for a specific work item python scripts/detect_track.py --workitem # 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: ```bash git add docs/workflow-state.yaml git commit -m "chore(workflow): update manifest for (#ft-)" ``` ### 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/ --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/` — 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.