work-kit-cli 0.2.0

package/skills/build/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: build
+description: "Run the Build phase — 8 sub-stages from Setup to Commit. Follows the Blueprint from Plan."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Lead Developer**. Execute the implementation plan from the Blueprint precisely.
+
+## Sub-stages (in order)
+
+1. **Setup** — Create branch, install deps, scaffold
+2. **Migration** — Database schema changes
+3. **Red** — Write failing tests first (TDD red phase)
+4. **Core** — Make tests pass — service layer, API, business logic (TDD green phase)
+5. **UI** — Components, pages, interactions
+6. **Refactor** — Improve code quality, keep tests green (TDD refactor phase)
+7. **Integration** — Wire everything together, verify full data flow
+8. **Commit** — Clean commits, push branch, create PR
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/build/stages/setup.md`)
+2. Reference the Blueprint in `.work-kit/state.md` — follow its steps for this layer
+3. Write actual code, run actual commands
+4. Update `.work-kit/state.md` with outputs
+5. Proceed to the next sub-stage
+
+## Key Principle
+
+**Follow the Blueprint.** The Plan phase already decided what to build and how. Your job is execution, not redesign. If you discover the Blueprint is wrong, note it and adapt minimally — don't redesign mid-build.
+
+## Recording
+
+Throughout every sub-stage, capture three things in the shared state.md sections:
+
+- **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
+- **`## Deviations`** — Whenever you diverge from the Blueprint, append: `**<Blueprint step>**: <what changed> — <why>`. Every deviation needs a reason.
+
+These feed into the final work-kit log summary. If you don't record them here, they're lost.
+
+## Loop-back
+
+If **Refactor** returns "broken" (tests failing after refactor):
+- Revert the refactoring that broke tests
+- Go back to **Core** to fix
+- Re-run **Refactor**
+- Max 2 loops, then proceed with tests passing (skip further refactoring)
+
+## Context Input
+
+This phase runs as a **fresh agent**. Read only these sections from `.work-kit/state.md`:
+- `### Plan: Final` — the Blueprint, Architecture, Scope, and Constraints
+- `## Criteria` — what "done" looks like
+- `## Description` — original request for context
+
+Do NOT read the Plan sub-stage working notes (Clarify, Investigate, Sketch, etc.) — they're consumed by Plan: Final.
+
+## Final Output
+
+After all sub-stages are done, append a `### Build: Final` section to state.md. This is the **only section the Test agent reads**.
+
+```markdown
+### Build: Final
+
+**PR:** #<number> — <title>
+**PR URL:** <url>
+**Branch:** feature/<slug>
+
+**What was built:**
+- <file>: <what was implemented>
+- ...
+
+**Test status:**
+- New tests: <count> (all passing)
+- Existing tests: all passing | <failures>
+
+**Deviations from Blueprint:**
+- <deviation and why — or "None">
+
+**Known issues:**
+- <anything the Test/Review agents should watch for — or "None">
+```
+
+Then:
+- Update state: `**Phase:** build (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete build"`

package/skills/build/stages/commit.md

@@ -0,0 +1,43 @@
+---
+description: "Build sub-stage: Create clean commits, push branch, create PR."
+---
+
+# Commit
+
+**Role:** Release Preparer
+**Goal:** Clean git history, push, and open a PR.
+
+## Instructions
+
+1. Review all changes with `git diff` and `git status`
+2. Stage changes in logical groups — don't dump everything in one commit
+3. Write clear commit messages:
+   - First line: imperative, under 72 chars (e.g., "Add avatar upload service and API endpoint")
+   - Body: explain what and why, not how
+4. Push the feature branch
+5. Create a pull request:
+   - Title: concise summary of the feature
+   - Body: description, what changed, how to test
+6. Record the PR URL
+
+## Output (append to state.md)
+
+```markdown
+### Build: Commit
+
+**Commits:**
+- `<hash>` — <message summary>
+- ...
+
+**Branch Pushed:** feature/<slug>
+**PR:** #<number> — <title>
+**PR URL:** <url>
+```
+
+## Rules
+
+- Don't include `.work-kit/` state files in the PR commits — commit those separately
+- Don't include unrelated changes
+- If there are secrets or env files staged, remove them
+- Prefer multiple focused commits over one giant commit
+- PR description should be useful to a reviewer — not a wall of text

package/skills/build/stages/core.md

@@ -0,0 +1,48 @@
+---
+description: "Build sub-stage: Make failing tests pass — service layer, API, business logic (TDD green phase)."
+---
+
+# Core — Make Tests Pass
+
+**Role:** Core Developer
+**Goal:** Implement the minimum code to make all failing tests pass.
+
+## Instructions
+
+1. Read the failing tests from the Red phase
+2. Implement the code needed to make them pass:
+   - Service layer functions
+   - API route handlers
+   - Validation schemas
+   - Business logic
+3. Follow the Blueprint's Architecture section for structure
+4. Match existing codebase patterns found during Investigate
+5. Run tests after each major piece — watch them go green one by one
+
+## Output (append to state.md)
+
+```markdown
+### Build: Core
+
+**Files Changed:**
+- `<path>` — <what was implemented>
+
+**Functions Implemented:**
+- `<name>` in `<file>` — <purpose>
+
+**Test Status:**
+- Previously failing: <N>
+- Now passing: <M>
+- Still failing: <K> (explain why if > 0)
+
+**Notes:**
+- <any deviations from Blueprint — also record in the `## Deviations` section of state.md>
+```
+
+## Rules
+
+- Write the **minimum** code to pass tests — no gold-plating
+- Don't refactor yet — that's the Refactor sub-stage
+- Don't build UI yet — that's the UI sub-stage
+- If a test expectation seems wrong, fix the test only if the Blueprint supports it
+- Match existing code patterns exactly — naming, file structure, error handling

package/skills/build/stages/integration.md

@@ -0,0 +1,44 @@
+---
+description: "Build sub-stage: Wire everything together, verify full data flow end-to-end."
+---
+
+# Integration
+
+**Role:** Integration Engineer
+**Goal:** Verify the full data flow works end-to-end: UI → API → Service → DB → Response → UI.
+
+## Instructions
+
+1. Trace every code path from user action to database and back
+2. Verify data flows correctly at each boundary:
+   - UI sends correct request to API
+   - API validates and calls correct service function
+   - Service performs correct DB operations
+   - Response flows back through each layer correctly
+3. Fix any wiring issues (wrong imports, missing props, incorrect types)
+4. Run the full test suite to confirm nothing broke
+5. Manually test key flows if possible (dev server)
+
+## Output (append to state.md)
+
+```markdown
+### Build: Integration
+
+**Integration Points Verified:**
+- <flow description>: working | fixed (<what was wrong>)
+
+**Issues Fixed:**
+- <issue and fix — or "None">
+
+**Full Test Suite:** passing | failing (<details>)
+
+**Notes:**
+- <anything discovered during integration>
+```
+
+## Rules
+
+- This is verification, not new development — if you're writing significant new code, something was missed earlier
+- Check TypeScript types across boundaries — mismatches here cause runtime bugs
+- If the dev server is available, actually navigate the flow
+- Document any issues found — they indicate gaps in the Blueprint for future reference

package/skills/build/stages/migration.md

@@ -0,0 +1,41 @@
+---
+description: "Build sub-stage: Generate and verify database schema changes."
+---
+
+# Migration
+
+**Role:** Database Engineer
+**Goal:** Apply schema changes from the Architecture plan.
+
+## Instructions
+
+1. Check the Blueprint/Architecture for data model changes
+2. If no DB changes needed, output `has_migration: false` and move on
+3. Otherwise:
+   - Update the schema definition files per your project's ORM
+   - Generate the migration
+   - Run the migration
+   - **Verify** the migration actually applied by checking the database directly
+4. Verify the application still connects to the DB and existing features work
+
+## Output (append to state.md)
+
+```markdown
+### Build: Migration
+
+**Has Migration:** true/false
+**Migration File:** <path>
+**Changes:**
+- <table.column: type — added/modified/removed>
+
+**Verification:**
+- Schema check: <pass/fail>
+- App connection: <pass/fail>
+```
+
+## Rules
+
+- Always verify migrations applied — don't trust "success" output alone
+- Use `IF NOT EXISTS` / `IF EXISTS` guards where appropriate
+- If the project uses Drizzle: run `pnpm db:generate` then `pnpm db:migrate`, then verify with psql
+- If migration fails, diagnose and fix before proceeding — don't skip

package/skills/build/stages/red.md

@@ -0,0 +1,44 @@
+---
+description: "Build sub-stage: Write failing tests BEFORE implementation (TDD red phase)."
+---
+
+# Red — Write Failing Tests
+
+**Role:** Test Author
+**Goal:** Define expected behavior through tests that don't pass yet.
+
+## Instructions
+
+1. Read the Blueprint's test expectations for each layer
+2. Write tests that describe the expected behavior:
+   - Service/business logic tests
+   - API endpoint tests (request → expected response)
+   - Component tests (render → expected output/behavior)
+3. Run the tests — **all new tests must fail** (that's the point)
+4. If any test accidentally passes, you're testing something that already exists — remove or adjust it
+
+## Output (append to state.md)
+
+```markdown
+### Build: Red (Failing Tests)
+
+**Tests Written:**
+- `<test file>`: <what it tests>
+  - <test case 1> — FAIL (expected)
+  - <test case 2> — FAIL (expected)
+
+**Test Output:**
+<summary of test run — X tests, Y failing, Z passing (pre-existing)>
+
+**Criteria Coverage:**
+- "<criterion>" → tested by <test name>
+```
+
+## Rules
+
+- Write tests FIRST — this is the "Red" in Red-Green-Refactor
+- Tests should be specific to acceptance criteria
+- Don't test implementation details — test behavior
+- Existing tests must still pass — only NEW tests should fail
+- Match the project's existing test patterns and frameworks
+- If the project has no test framework set up, set one up as part of this step

package/skills/build/stages/refactor.md

@@ -0,0 +1,48 @@
+---
+description: "Build sub-stage: Improve code quality while keeping all tests green (TDD refactor phase)."
+---
+
+# Refactor
+
+**Role:** Code Quality Engineer
+**Goal:** Clean up implementation code while maintaining all passing tests.
+
+## Instructions
+
+1. Run full test suite — confirm everything passes before starting
+2. Review code for:
+   - Duplication that should be extracted
+   - Unclear naming
+   - Functions that are too long
+   - Missing error handling at system boundaries
+   - Dead code or unused imports
+3. Refactor incrementally — run tests after each change
+4. If tests break: **stop immediately**, revert the breaking change
+
+## Output (append to state.md)
+
+```markdown
+### Build: Refactor
+
+**Refactoring Summary:**
+- <what was improved and why>
+
+**Test Status:** passing | broken
+
+**If broken:**
+- What broke: <description>
+- Reverted: yes/no
+```
+
+## Outcome Routing
+
+- **passing** → All tests green, proceed to Integration
+- **broken** → Tests broke and couldn't recover. Loop back to Core to fix.
+
+## Rules
+
+- Tests MUST be green before AND after refactoring
+- Don't add new features during refactor — only improve existing code
+- Don't refactor code you didn't write/modify in this feature
+- If code is already clean, say so and move on — don't refactor for its own sake
+- Small, incremental changes — not a big-bang rewrite

package/skills/build/stages/setup.md

@@ -0,0 +1,42 @@
+---
+description: "Build sub-stage: Branch creation, dependency installation, scaffolding."
+---
+
+# Setup
+
+**Role:** Project Scaffolder
+**Goal:** Prepare the workspace for implementation. No feature code yet.
+
+## Instructions
+
+1. Verify you're in the correct worktree on the feature branch
+2. Install any new dependencies specified in the Blueprint
+3. Create new files/directories that the Blueprint calls for (empty scaffolds)
+4. Update config files if the Blueprint requires it
+5. Verify the project still builds/compiles cleanly after setup
+
+## Output (append to state.md)
+
+```markdown
+### Build: Setup
+
+**Branch:** feature/<slug> (confirmed)
+**Dependencies Added:**
+- <package> — <why>
+
+**Files Created:**
+- `<path>` — <scaffold for what>
+
+**Config Changes:**
+- `<file>` — <what changed>
+
+**Build Status:** clean | issues (detail)
+```
+
+## Rules
+
+- Do NOT write implementation code — just scaffolding (empty files, directory structure)
+- Do NOT write tests yet — that's Red
+- If the worktree already has setup from a previous loop-back, verify state and skip what's done
+- If dependency installation fails, diagnose the issue — don't proceed with broken dependencies
+- Run the build/compile check to ensure nothing is broken before proceeding

package/skills/build/stages/ui.md

@@ -0,0 +1,51 @@
+---
+description: "Build sub-stage: Implement UI components, pages, and interactions."
+---
+
+# UI
+
+**Role:** Frontend Developer
+**Goal:** Build the user-facing interface per the UX Flow and Blueprint.
+
+## Instructions
+
+1. If no UI changes are needed (from UX Flow: `has_ui_changes: false`), skip this step
+2. Otherwise, implement:
+   - New components per Blueprint/Architecture
+   - Page modifications
+   - Forms, interactions, navigation
+   - Loading, error, and empty states (from UX Flow)
+3. Follow existing UI patterns from Investigate findings
+4. Wire components to the API/service layer built in Core
+5. Run any UI/component tests
+
+## Output (append to state.md)
+
+```markdown
+### Build: UI
+
+**Components Created:**
+- `<ComponentName>` in `<path>` — <purpose>
+
+**Components Modified:**
+- `<ComponentName>` in `<path>` — <what changed>
+
+**Pages Affected:**
+- `<route/path>` — <what changed>
+
+**States Handled:**
+- Loading: yes/no
+- Error: yes/no
+- Empty: yes/no
+
+**Notes:**
+- <deviations from UX Flow and why>
+```
+
+## Rules
+
+- Match the project's existing design system / component patterns
+- Every interactive element must have `cursor: pointer`
+- Handle all states from UX Flow — don't skip empty/error states
+- Don't introduce new UI libraries unless the Blueprint calls for it
+- Accessibility basics: labels, keyboard nav, ARIA where needed

package/skills/deploy/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: deploy
+description: "Run the Deploy phase (optional) — 3 sub-stages: Merge, Monitor, Remediate."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Release Engineer**. Get this PR merged and deployed safely.
+
+## Sub-stages (in order)
+
+1. **Merge** — Get the PR merged safely
+2. **Monitor** — Watch for deployment issues
+3. **Remediate** — Handle deployment outcome
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/deploy/stages/merge.md`)
+2. Follow its instructions
+3. Update `.work-kit/state.md` with outputs
+4. Proceed to next sub-stage
+
+## Key Principle
+
+**Verify before acting, monitor after acting.** Never merge with failing CI. Merge is automatic after review approval — no user confirmation needed. Never walk away after merge without checking deployment.
+
+## Recording
+
+Update the shared state.md sections:
+
+- **`## Decisions`** — Record merge method choice, any rollback decisions.
+
+## This phase is optional
+
+If the user says "skip deploy" or the project doesn't have CI/CD, skip this phase entirely. The feature is considered complete after Review/Handoff approval.
+
+## Context Input
+
+This phase runs as a **fresh agent**. Read only these sections from `.work-kit/state.md`:
+- `### Review: Final` — ship decision, concerns
+- `### Build: Final` — PR URL, branch
+- `## Criteria` — for final confirmation
+
+## Final Output
+
+After all sub-stages are done, append a `### Deploy: Final` section to state.md. This is what **Wrap-up reads**.
+
+```markdown
+### Deploy: Final
+
+**PR:** #<number>
+**Merge status:** merged | fix_needed | abort
+**Deploy status:** deployed | failed | not_applicable
+**Final status:** success | fix_and_redeploy | rolled_back
+
+**Summary:** <what happened>
+```
+
+Then:
+- Update state: `**Phase:** deploy (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete deploy"`

package/skills/deploy/stages/merge.md

@@ -0,0 +1,59 @@
+---
+description: "Deploy sub-stage: Get the PR merged safely."
+---
+
+# Merge
+
+**Role:** Merge Manager
+**Goal:** Get the PR merged with confidence.
+
+## Instructions
+
+1. Determine the default branch (`main` or `master`):
+   ```bash
+   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
+   ```
+2. Sync the feature branch with the default branch:
+   ```bash
+   git fetch origin
+   git rebase origin/<default-branch>
+   ```
+   If rebase conflicts occur, resolve them. If they're non-trivial, report to the user and abort.
+3. If a PR exists, check CI status — all checks must pass. If CI fails, diagnose and fix (loop back to Build if needed).
+4. Merge automatically using the project's preferred method (check CONTRIBUTING.md or README; default to squash):
+   - If a PR exists: merge via `gh pr merge --squash --delete-branch`
+   - If no PR: merge locally:
+     ```bash
+     git checkout <default-branch>
+     git merge --squash feature/<slug>
+     git commit -m "feat: <slug>"
+     git branch -d feature/<slug>
+     ```
+
+## Output (append to state.md)
+
+```markdown
+### Deploy: Merge
+
+**PR:** #<number>
+**CI Status:** passing | failing
+**Conflicts:** none | resolved
+**Merge Method:** squash | merge | rebase
+**Result:** merged | fix_needed | abort
+```
+
+## Outcome Routing
+
+- **merged** → Proceed to Monitor
+- **fix_needed** → Loop back to Build/Core with the specific issue
+- **abort** → Stop work. Report to user.
+
+## Rules
+
+- NEVER force push to main/master
+- NEVER merge with failing CI
+- If CI fails, diagnose the issue — don't just retry
+- If rebase conflicts are non-trivial, explain them to the user before resolving
+- Merge is fully autonomous — do NOT ask the user for permission at any step (review phase already approved it)
+- Push, create PR, and merge without stopping for confirmation
+- The entire sync → push → PR → merge flow should complete in one agent pass

package/skills/deploy/stages/monitor.md

@@ -0,0 +1,39 @@
+---
+description: "Deploy sub-stage: Monitor deployment after merge."
+---
+
+# Monitor
+
+**Role:** Deployment Monitor
+**Goal:** Verify the deployment succeeds and the feature works in production.
+
+## Instructions
+
+1. Check CI/CD pipeline status after merge
+2. Wait for deployment to complete (if applicable)
+3. Verify health checks pass
+4. Check for errors in logs (if accessible)
+5. Verify the feature works as expected in the deployed environment
+
+## Output (append to state.md)
+
+```markdown
+### Deploy: Monitor
+
+**Deploy Status:** deployed | pending | failed | not_applicable
+**Pipeline:** <url or "no CI/CD">
+**Health Checks:** passing | failing | not_applicable
+**Notes:**
+- <observations>
+```
+
+## Outcome Routing
+
+- **deployed** → Proceed to Remediate (success path)
+- **failed** → Proceed to Remediate (failure path)
+
+## Rules
+
+- If the project has no CI/CD, mark as `not_applicable` and move on
+- Don't wait indefinitely — if deployment takes more than a few minutes, note it and move on
+- If you can't access production logs/monitoring, say so

package/skills/deploy/stages/remediate.md

@@ -0,0 +1,54 @@
+---
+description: "Deploy sub-stage: Handle deployment outcome — confirm success or manage failure."
+---
+
+# Remediate
+
+**Role:** Incident Responder
+**Goal:** Confirm successful deployment or manage failure.
+
+## Instructions
+
+### If deployment succeeded:
+1. Confirm the feature is healthy
+2. Output `final_status: success`
+3. Done — the feature is shipped
+
+### If deployment failed:
+1. Analyze the failure:
+   - Build failure? Test failure? Runtime error? Config issue?
+2. Recommend action:
+   - **fix_and_redeploy**: Issue is small and fixable → loop back to Build/Core
+   - **rolled_back**: Issue is serious → revert the merge, explain to user
+
+## Output (append to state.md)
+
+```markdown
+### Deploy: Remediate
+
+**Final Status:** success | fix_and_redeploy | rolled_back
+**Failure Category:** build | test | deploy | runtime | config | none
+**Summary:**
+- <what happened>
+
+**If fix_and_redeploy:**
+- Issue: <what needs to be fixed>
+- Plan: <how to fix>
+
+**If rolled_back:**
+- Reason: <why rollback was necessary>
+- Revert: <commit hash or PR>
+```
+
+## Outcome Routing
+
+- **success** → Work is complete. Orchestrator writes work-kit log.
+- **fix_and_redeploy** → Loop back to Build/Core with the fix context
+- **rolled_back** → Work is stopped. Report to user.
+
+## Rules
+
+- Don't panic on failure — diagnose first
+- Prefer fix-forward over rollback for small issues
+- Rollback is the right call for data corruption, security issues, or widespread breakage
+- Always explain to the user what happened and why