@abdullahsahmad/work-kit 0.1.0

package/skills/full-kit/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: full-kit
+description: "Full pipeline for feature development. Runs all phases and sub-stages in order. Usage: /full-kit <description> to start, /full-kit to continue."
+user-invocable: true
+argument-hint: "[description]"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Work Orchestrator (Full Mode)**. You run the complete lifecycle of a feature through every phase and sub-stage. No shortcuts.
+
+Best for: large features, new systems, or when you want maximum rigor.
+
+## Prerequisites
+
+Before starting, verify the CLI is installed:
+```bash
+npx work-kit doctor
+```
+
+If `work-kit` is not found, ask the user to install it:
+> work-kit CLI is required but not installed. Install it with: `npm install -g work-kit-cli`
+
+Do not proceed until `doctor` reports all checks passed.
+
+## Phases
+
+1. **Plan** (8 steps) — Clarify → Investigate → Sketch → Scope → UX Flow → Architecture → Blueprint → Audit
+2. **Build** (8 steps) — Setup → Migration → Red → Core → UI → Refactor → Integration → Commit
+3. **Test** (3 steps) — Verify → E2E → Validate
+4. **Review** (5 steps) — Self-Review → Security → Performance → Compliance → Handoff
+5. **Deploy** (3 steps, optional) — Merge → Monitor → Remediate
+6. **Wrap-up** — Synthesize work-kit summary, clean up worktree
+
+## Starting New Work (`/full-kit <description>`)
+
+1. Create a git worktree and initialize state:
+   ```bash
+   git worktree add worktrees/<slug> -b feature/<slug>
+   cd worktrees/<slug>
+   npx work-kit init --mode full --description "<description>"
+   ```
+2. Parse the JSON response and follow the action
+3. Continue with the execution loop below
+
+## Continuing Work (`/full-kit` with no args)
+
+1. Find the active worktree — check `git worktree list` or look for `.work-kit/state.md`
+2. Run `npx work-kit status` to see current state
+3. Run `npx work-kit next` to get the next action
+4. Follow the execution loop below
+
+## Execution Loop
+
+The CLI manages all state transitions, prerequisites, and loopbacks. Follow this loop:
+
+1. Run `npx work-kit next` to get the next action
+2. Parse the JSON response
+3. Follow the action type:
+   - **`spawn_agent`**: Use the Agent tool with the provided `agentPrompt`. Pass `skillFile` path for reference. After the agent completes: `npx work-kit complete <phase>/<sub-stage> --outcome <outcome>`
+   - **`spawn_parallel_agents`**: Spawn all agents in the `agents` array in parallel using the Agent tool. Wait for all to complete. Then spawn `thenSequential` if provided. After all complete: `npx work-kit complete <onComplete target>`
+   - **`wait_for_user`**: Report the message to the user and stop. Wait for them to say "proceed" before running `npx work-kit next` again.
+   - **`loopback`**: Report the loopback to the user, then run `npx work-kit next` to continue from the target.
+   - **`complete`**: Done — run wrap-up if not already done.
+   - **`error`**: Report the error and suggestion to the user. Stop.
+4. After each agent completes: `npx work-kit complete <phase>/<sub-stage> --outcome <outcome>`
+5. Then `npx work-kit next` again to continue
+
+## Phase Prerequisites
+
+Prerequisites are enforced by the CLI (`npx work-kit validate <phase>`). You don't need to check manually — the `next` command handles it.
+
+| Phase    | Requires                          |
+|----------|-----------------------------------|
+| Plan     | — (first phase, always allowed)   |
+| Build    | Plan (complete)                   |
+| Test     | Build (complete)                  |
+| Review   | Test (complete)                   |
+| Deploy   | Review (complete), Handoff = approved |
+| Wrap-up  | Review (complete) or Deploy (complete) |
+
+## Agent Architecture
+
+Each phase runs as a **fresh agent** (sub-agent spawned by the orchestrator). This keeps context focused — the Build agent doesn't carry Plan's investigation notes, the Review agent doesn't carry Build's implementation context.
+
+```
+Orchestrator (main agent — you)
+│
+├── Agent: Plan (single agent, all 8 sub-stages)
+│   ├── reads: ## Description, ## Criteria, codebase
+│   ├── runs: Clarify → Investigate → ... → Audit
+│   └── writes: ### Plan: Final (Blueprint, Architecture, Scope, Constraints)
+│
+├── Agent: Build (single agent, all 8 sub-stages)
+│   ├── reads: ### Plan: Final, ## Criteria
+│   ├── runs: Setup → Migration → ... → Commit
+│   └── writes: ### Build: Final (PR, files changed, test status, deviations)
+│
+├── Agent: Test (orchestrates 2 parallel + 1 sequential)
+│   ├── reads: ### Build: Final, ### Plan: Final, ## Criteria
+│   ├── Sub-agent: Verify  ──┐ (parallel)
+│   ├── Sub-agent: E2E     ──┘
+│   ├── then: Validate (after both complete)
+│   └── writes: ### Test: Final (results, criteria status, confidence)
+│
+├── Agent: Review (orchestrates 4 parallel + 1 sequential)
+│   ├── reads: ### Plan: Final, ### Build: Final, ### Test: Final, ## Criteria
+│   ├── Sub-agent: Self-Review  ──┐
+│   ├── Sub-agent: Security     ──┤ (all 4 parallel)
+│   ├── Sub-agent: Performance  ──┤
+│   ├── Sub-agent: Compliance   ──┘
+│   ├── then: Handoff (reads all 4 results → ship decision)
+│   └── writes: ### Review: Final (decision, issues, concerns)
+│
+├── Agent: Deploy (single agent, all 3 sub-stages)
+│   ├── reads: ### Review: Final, ### Build: Final
+│   ├── runs: Merge → Monitor → Remediate
+│   └── writes: ### Deploy: Final (merge/deploy status)
+│
+└── Agent: Wrap-up (single agent)
+    ├── reads: full state.md
+    └── writes: summary + archive
+```
+
+### Agent Spawn Rules
+
+| Phase | Agent type | Mode | What it reads from state.md |
+|-------|-----------|------|----------------------------|
+| Plan | Single agent | `auto` | `## Description`, `## Criteria`, codebase |
+| Build | Single agent | `auto` | `### Plan: Final`, `## Criteria` |
+| Test: Verify | Sub-agent | `auto` | `### Build: Final`, `## Criteria` |
+| Test: E2E | Sub-agent | `auto` | `### Build: Final`, `### Plan: Final` |
+| Test: Validate | Single agent | `auto` | `### Test: Verify`, `### Test: E2E`, `## Criteria` |
+| Review: Self-Review | Sub-agent | `auto` | `### Build: Final`, git diff |
+| Review: Security | Sub-agent | `auto` | `### Build: Final`, git diff |
+| Review: Performance | Sub-agent | `auto` | `### Build: Final`, git diff |
+| Review: Compliance | Sub-agent | `auto` | `### Plan: Final`, `### Build: Final`, git diff |
+| Review: Handoff | Single agent | `auto` | All `### Review:` sections, `### Test: Final`, `## Criteria` |
+| Deploy | Single agent | `auto` | `### Review: Final`, `### Build: Final` |
+| Wrap-up | Single agent | `auto` | Full state.md |
+
+### Phase Handoff via Final Sections
+
+Each phase writes a `### <Phase>: Final` section — a self-contained summary of that phase's output. The next phase's agent reads **only** the Final sections it needs, not the sub-stage working notes.
+
+```
+state.md grows like this:
+  ### Plan: Clarify        ← working notes (Plan agent internal)
+  ### Plan: Investigate    ← working notes (Plan agent internal)
+  ...
+  ### Plan: Final          ← ★ Build agent reads this
+  ### Build: Setup         ← working notes (Build agent internal)
+  ### Build: Core          ← working notes (Build agent internal)
+  ...
+  ### Build: Final         ← ★ Test agent reads this
+  ### Test: Verify         ← working notes
+  ### Test: E2E            ← working notes
+  ### Test: Final          ← ★ Review agent reads this
+  ...
+```
+
+## Phase Execution
+
+For each phase:
+1. **Check prerequisites** — verify the required prior phase is marked complete in state.md
+2. **Spawn a fresh agent** for the phase — pass it the phase skill file and the relevant Final sections from state.md
+3. The agent reads each sub-stage file when directed (e.g., `.claude/skills/plan/stages/clarify.md`)
+4. The agent updates `.work-kit/state.md` after each sub-stage completes
+5. The agent writes the `### <Phase>: Final` section before exiting
+6. After the agent completes, summarize results to the user and wait for confirmation
+
+## Loop-Back Rules
+
+Some sub-stages can route backwards based on their outcome:
+
+- **Plan Audit** → "revise" → re-run Blueprint
+- **Build Refactor** → "broken" → re-run Core
+- **Review Handoff** → "changes_requested" → re-run Build (from Core)
+- **Deploy Merge** → "fix_needed" → re-run Build (from Core)
+- **Deploy Remediate** → "fix_and_redeploy" → re-run Build (from Core)
+
+On loop-back: add a `## Loop-back context` section to state.md with what needs to change and why, then resume at the target sub-stage.
+
+## Completion
+
+When all phases are done (or deploy is skipped):
+
+Run **Wrap-up** — read `.claude/skills/wrap-up.md` and follow its instructions. It handles writing the work-kit summary, committing it, and cleaning up the worktree.
+
+## Important
+
+- **Always work inside the worktree directory** — `cd worktrees/<slug>` before running any commands
+- **Commit state after each phase** — `git add .work-kit/ && git commit -m "work-kit: complete <phase>"`
+- **Don't skip phases** — even if a phase seems unnecessary, run it and let it determine "nothing to do"
+- **Human stays in control** — stop between phases, don't auto-proceed
+- **One feature per session** — each session handles a single feature. To work on multiple features in parallel, use separate terminal sessions

package/skills/plan/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: plan
+description: "Run the Plan phase — 8 sub-stages from Clarify to Audit."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+You are the **Planning Lead**. Work through 8 focused sub-stages to produce a complete, executable Blueprint.
+
+## Sub-stages (in order)
+
+1. **Clarify** — Understand the request, define acceptance criteria, clarify requirements
+2. **Investigate** — Read codebase, trace paths, map blast radius
+3. **Sketch** — Rough directional plan
+4. **Scope** — Define in/out scope, complexity, criteria
+5. **UX Flow** — User-facing flows, screens, interactions
+6. **Architecture** — Technical design: data model, API, components
+7. **Blueprint** — Full ordered implementation plan
+8. **Audit** — Check blueprint for gaps and contradictions
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/plan/stages/clarify.md`)
+2. Follow its instructions completely
+3. Write outputs to `.work-kit/state.md` under a section for that sub-stage
+4. Update `**Phase:** plan` and `**Sub-stage:** <current>` in state.md
+5. Proceed to the next sub-stage
+
+## Continuity
+
+Maintain context across all sub-stages — each builds on the previous. Reference prior outputs explicitly. Don't re-discover what you already found.
+
+## Recording
+
+Throughout every sub-stage, capture two things in the shared state.md sections:
+
+- **`## Decisions`** — Whenever you choose between real alternatives, append: `**<context>**: chose <X> over <Y> — <why>`. Skip obvious choices.
+
+These feed into the final work-kit log summary. If you don't record decisions here, they're lost.
+
+## Loop-back
+
+If **Audit** returns "revise":
+- Read the audit findings
+- Go back to **Blueprint** and revise based on specific gaps identified
+- Re-run **Audit** after revision
+- Max 2 revision loops, then proceed with noted caveats
+
+## Final Output
+
+After all sub-stages are done, append a `### Plan: Final` section to state.md. This is the **only section the Build agent reads** — it must be self-contained.
+
+```markdown
+### Plan: Final
+
+**Blueprint:**
+<the full ordered implementation plan from Blueprint sub-stage — copy it here>
+
+**Architecture:**
+<data model, API surface, components, service layer — from Architecture sub-stage>
+
+**Criteria:**
+<reference to ## Criteria section>
+
+**Scope:**
+- In: <what's being built>
+- Out: <what's not>
+- Complexity: <small | medium | large | x-large>
+
+**Key Constraints:**
+- <anything the Build agent must know — patterns to follow, libs to use, gotchas>
+```
+
+Then:
+- Update state: `**Phase:** plan (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete plan"`

package/skills/plan/stages/architecture.md

@@ -0,0 +1,53 @@
+---
+description: "Plan sub-stage: Define technical design — data model, API surface, component structure."
+---
+
+# Architecture
+
+**Role:** Technical Architect
+**Goal:** Precise technical design that the Blueprint will turn into step-by-step instructions.
+
+## Instructions
+
+1. Define data model changes (new tables, columns, relations, indexes)
+2. Define API surface (new endpoints or changes to existing ones, request/response shapes)
+3. Define component structure (new components, modifications to existing ones)
+4. Define service layer (new functions, business logic location)
+5. Define integration points (how pieces connect, data flow)
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Architecture
+
+**Data Model:**
+- <table/column changes with types>
+- <new relations>
+- <indexes needed>
+
+**API Surface:**
+- `POST /api/v1/<resource>` — <purpose, request body, response>
+- ...
+
+**Components:**
+- `<ComponentName>` — <purpose, props, where it's used>
+- ...
+
+**Service Layer:**
+- `<functionName>(args)` in `<file>` — <what it does>
+- ...
+
+**Integration Points:**
+- <how UI calls API>
+- <how API calls service>
+- <how service calls DB>
+- <external services if any>
+```
+
+## Rules
+
+- Use exact file paths based on Investigate findings
+- Match existing patterns — don't invent new conventions
+- Include TypeScript types/interfaces that will be needed
+- If you need a migration, specify the exact columns and types
+- This is the technical contract — Blueprint will reference it directly

package/skills/plan/stages/audit.md

@@ -0,0 +1,58 @@
+---
+description: "Plan sub-stage: Audit the Blueprint for gaps, contradictions, and coverage."
+---
+
+# Audit
+
+**Role:** Plan Auditor
+**Goal:** Catch problems in the Blueprint before Build starts.
+
+## Instructions
+
+1. Re-read ALL prior sub-stage outputs (Clarify through Blueprint)
+2. Check for:
+   - **Gaps:** Steps missing that are needed to satisfy criteria
+   - **Contradictions:** Blueprint says X but Architecture says Y
+   - **Coverage:** Every criterion has mapped steps
+   - **Ordering:** Dependencies are respected (can't use a table before migrating)
+   - **Patterns:** Blueprint follows conventions found in Investigate
+   - **Edge cases:** UX Flow edge cases have corresponding steps
+3. Decide: **proceed** or **revise**
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Audit
+
+**Result:** proceed | revise
+
+**Gaps Found:**
+- <gap description — or "None">
+
+**Contradictions:**
+- <contradiction — or "None">
+
+**Coverage:**
+- All criteria mapped: yes/no
+- Unmapped criteria: <list or "None">
+
+**Notes:**
+- <anything else worth flagging>
+```
+
+## Outcome Routing
+
+- **proceed** → Plan phase is complete, move to Build
+- **revise** → Go back to Blueprint with specific revision instructions. Add:
+  ```markdown
+  **Revision Instructions:**
+  - Fix: <specific thing to fix in Blueprint>
+  - Add: <specific thing missing>
+  ```
+
+## Rules
+
+- Be genuinely critical — a bad plan caught here saves hours of rework
+- "Proceed" means you'd bet money this plan works
+- "Revise" is not failure — it's the audit doing its job
+- Max 2 revision loops — after that, proceed with noted caveats

package/skills/plan/stages/blueprint.md

@@ -0,0 +1,60 @@
+---
+description: "Plan sub-stage: Produce a full ordered step-by-step implementation plan."
+---
+
+# Blueprint
+
+**Role:** Implementation Planner
+**Goal:** A precise, ordered, step-by-step plan that can be executed without ambiguity.
+
+## Instructions
+
+1. Synthesize ALL prior sub-stage outputs (Clarify → Architecture) into one executable plan
+2. Order steps by dependency — what must be done first
+3. Each step must specify:
+   - What to do (create file, modify function, run command)
+   - Where (exact file path)
+   - Why (which requirement/criterion it satisfies)
+4. Group steps logically (DB → Service → API → UI)
+5. Include test expectations at each layer
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Blueprint
+
+#### Phase: Database
+1. Create migration for <table> — columns: <list with types>
+2. Run migration and verify with psql
+
+#### Phase: Service Layer
+3. Create `<function>` in `<file>` — <what it does>
+4. Add validation schema in `<file>`
+
+#### Phase: API
+5. Create route handler `<method> <path>` in `<file>`
+6. Wire validation → service → response
+
+#### Phase: UI
+7. Create `<Component>` in `<file>` — <props, behavior>
+8. Add to page `<path>` — <where in the layout>
+9. Handle loading/error/empty states
+
+#### Phase: Tests
+10. Unit test for service function — <what to assert>
+11. API test for endpoint — <what to assert>
+12. Component test — <what to assert>
+
+#### Acceptance Criteria Mapping
+- Criterion "<text>" → satisfied by steps <N, M>
+- ...
+```
+
+## Rules
+
+- Every acceptance criterion must map to at least one step. If a criterion can't be mapped, it's a gap — flag it for Audit
+- Every step must have an exact file path
+- Steps should be small enough to implement in one focused session
+- If a step is "update 5 files", break it into 5 steps
+- The Blueprint is the contract — Build phase follows it literally
+- Include commands to run (migrations, test commands) as steps

package/skills/plan/stages/clarify.md

@@ -0,0 +1,61 @@
+---
+description: "Plan sub-stage: Understand the request, define acceptance criteria, and clarify requirements."
+---
+
+# Clarify
+
+**Role:** Requirements Analyst
+**Goal:** Fully understand what's being asked, define what "done" looks like, before touching any code.
+
+## Instructions
+
+1. **Read the request** in `.work-kit/state.md` under `## Description`
+2. **Generate a clear title** — descriptive, not generic. Update the `# Title` in state.md
+3. **Ask clarifying questions** if the request is ambiguous. Wait for answers before proceeding.
+4. **Identify affected areas** — which parts of the codebase are likely impacted. List in state.md.
+5. **Define acceptance criteria** — concrete, testable conditions for "done". Add as checklist:
+   ```markdown
+   ## Criteria
+   - [ ] User can upload an avatar image
+   - [ ] Fallback to initials when no avatar
+   - [ ] Avatar displays at 32px, 48px, and 96px sizes
+   ```
+6. **Add initial notes** — anything notable about the request (risks, dependencies, related past work)
+7. **Write a summary** of your understanding
+
+## Output (append to state.md)
+
+Update the `## Criteria` section with acceptance criteria, then append:
+
+```markdown
+### Plan: Clarify
+
+**Understanding:**
+<2-3 sentence summary of what needs to be built and why>
+
+**Affected Areas:**
+- <area 1>
+- <area 2>
+
+**Confirmed Requirements:**
+- <requirement 1>
+- <requirement 2>
+
+**Assumptions:**
+- <assumption — things you're proceeding with unless corrected>
+
+**Open Questions:**
+- <anything still unclear — empty if all resolved>
+
+**Notes:**
+- <risks, dependencies, related past work — or "None">
+```
+
+## Rules
+
+- **Keep it lightweight** — 5 minutes of thinking, not 30
+- Do NOT read code yet — that's Investigate
+- Do NOT propose solutions — that's Sketch
+- **Do ask questions** — ambiguity caught here saves hours later
+- If the request is crystal clear, don't invent questions just to ask them
+- Ask questions only when the answer materially changes what gets built

package/skills/plan/stages/investigate.md

@@ -0,0 +1,47 @@
+---
+description: "Plan sub-stage: Read codebase systematically, trace paths, map blast radius."
+---
+
+# Investigate
+
+**Role:** Code Archaeologist
+**Goal:** Understand the existing code that this feature will touch or depend on.
+
+## Instructions
+
+1. Based on the Clarify output, identify which areas of the codebase to examine
+2. Read relevant files systematically — don't skim, understand the patterns
+3. Trace code paths end-to-end (UI → API → service → DB if applicable)
+4. Map the blast radius — what existing functionality could be affected
+5. Note patterns and conventions the codebase already uses (you must match them)
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Investigate
+
+**Affected Files:**
+- `path/to/file.ts` — <why it's relevant>
+- ...
+
+**Code Paths Traced:**
+- <path description: e.g., "User creation: form → action → service → DB">
+
+**Patterns Found:**
+- <e.g., "All API routes use zod validation + service delegation">
+- <e.g., "Components use compound pattern with Context">
+
+**Blast Radius:**
+- <what existing features could break>
+- <what tests cover these areas>
+
+**Key Findings:**
+- <anything surprising, important constraints, technical debt to navigate>
+```
+
+## Rules
+
+- Be thorough — missed dependencies here cause bugs in Build
+- Do NOT propose solutions yet — that's Sketch
+- Note file paths precisely — these will be referenced in Blueprint
+- If the codebase has no tests for affected areas, note that as a risk

package/skills/plan/stages/scope.md

@@ -0,0 +1,46 @@
+---
+description: "Plan sub-stage: Define in/out scope, estimate complexity, refine criteria."
+---
+
+# Scope
+
+**Role:** Scope Manager
+**Goal:** Draw clear boundaries around what gets built now vs. later.
+
+## Instructions
+
+1. Based on the Sketch, define what's in scope and what's explicitly out
+2. Estimate complexity (small / medium / large / x-large)
+3. Review and refine acceptance criteria from Clarify — add any new ones discovered during investigation
+4. Identify prerequisites (things that must exist before this work starts)
+5. Flag anything that should be a separate work item
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Scope
+
+**In Scope:**
+- <what will be built in this work item>
+
+**Out of Scope:**
+- <what will NOT be built — and why>
+
+**Complexity:** <small | medium | large | x-large>
+
+**Updated Criteria:**
+(update the main ## Criteria section if new criteria were discovered)
+
+**Prerequisites:**
+- <things that must be true before build starts>
+
+**Separate Work Items:**
+- <anything that should be split out — empty if none>
+```
+
+## Rules
+
+- Be ruthless about scope — feature creep kills velocity
+- If Clarify criteria are too vague, sharpen them now
+- "Out of scope" is a decision, not a deferral — explain why
+- Complexity estimate should factor in blast radius from Investigate

package/skills/plan/stages/sketch.md

@@ -0,0 +1,44 @@
+---
+description: "Plan sub-stage: Produce a rough directional plan based on investigation findings."
+---
+
+# Sketch
+
+**Role:** Solution Architect (first draft)
+**Goal:** Rough directional plan — not precise, just directionally correct.
+
+## Instructions
+
+1. Based on Clarify (requirements) and Investigate (code understanding), sketch a high-level approach
+2. Consider 2-3 possible approaches if there's a non-obvious choice
+3. Pick the best approach and explain why
+4. Outline the rough shape: what gets created, modified, deleted
+
+## Output (append to state.md)
+
+```markdown
+### Plan: Sketch
+
+**Approach:**
+<1-2 paragraphs describing the chosen direction>
+
+**Alternatives Considered:**
+- <option A — why not>
+- <option B — why not>
+(skip if the approach is obvious)
+
+**Rough Shape:**
+- Create: <new files/components/tables>
+- Modify: <existing files that change>
+- Delete: <anything being removed>
+
+**Open Risks:**
+- <things that might not work as expected>
+```
+
+## Rules
+
+- This is a sketch, not a blueprint — stay high-level
+- Don't specify exact function signatures or SQL yet
+- Focus on the "what" and "why", not the "how" in detail
+- The sketch guides Scope and Architecture — it doesn't need to be complete