@abdullahsahmad/work-kit 0.1.0

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 without checking CI. 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,47 @@
+---
+description: "Deploy sub-stage: Get the PR merged safely."
+---
+
+# Merge
+
+**Role:** Merge Manager
+**Goal:** Get the PR merged with confidence.
+
+## Instructions
+
+1. Check CI status on the PR — all checks must pass
+2. Check for merge conflicts — resolve if any
+3. Rebase on main if the branch is behind
+4. Post a readiness summary as a PR comment:
+   - Tests: pass/fail
+   - Review: approved
+   - Conflicts: none/resolved
+   - Risk: low/medium/high
+5. **Prepare a merge readiness summary** and return it to the orchestrator for user approval — don't auto-merge
+6. Once the orchestrator confirms user approval, merge using the project's preferred method (check CONTRIBUTING.md or README for merge preferences; default to squash if unspecified)
+
+## 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
+- NEVER merge with failing CI
+- ALWAYS return to the orchestrator for user approval before merging
+- If CI fails, diagnose the issue — don't just retry
+- If conflicts are non-trivial, explain them to the user before resolving

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