@abdullahsahmad/work-kit 0.1.0

package/skills/plan/stages/ux-flow.md

@@ -0,0 +1,49 @@
+---
+description: "Plan sub-stage: Define user-facing flows, screens, interactions, edge cases."
+---
+
+# UX Flow
+
+**Role:** UX Designer
+**Goal:** Define how the user will experience this feature.
+
+## Instructions
+
+1. If this feature has no UI changes, output `has_ui_changes: false` and move on
+2. Otherwise, define the user flow step by step
+3. List screens/pages affected (new or modified)
+4. Define interactions (clicks, forms, navigation)
+5. Cover edge cases: empty states, loading states, error states
+
+## Output (append to state.md)
+
+```markdown
+### Plan: UX Flow
+
+**Has UI Changes:** true/false
+
+**User Flow:**
+1. User navigates to <page>
+2. User clicks <element>
+3. System shows <response>
+4. ...
+
+**Screens Affected:**
+- <page/component> — <new or modified> — <what changes>
+
+**Interactions:**
+- <element>: <what happens on click/submit/hover>
+
+**Edge Cases:**
+- Empty state: <what shows when no data>
+- Loading state: <what shows during fetch>
+- Error state: <what shows on failure>
+- Permissions: <what if user can't access>
+```
+
+## Rules
+
+- Skip this entirely if there are zero UI changes (backend-only features)
+- Think from the user's perspective, not the developer's
+- Every screen should have empty, loading, and error states defined
+- Reference existing UI patterns from Investigate findings

package/skills/review/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: review
+description: "Run the Review phase — 5 sub-stages: Self-Review, Security, Performance, Compliance, Handoff."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
+---
+
+You are the **Senior Reviewer**. Perform multi-dimensional code review before the feature ships.
+
+## Sub-stages (in order)
+
+1. **Self-Review** — Check your own diff for obvious issues
+2. **Security** — OWASP top 10 security review
+3. **Performance** — Query efficiency, bundle size, rendering performance
+4. **Compliance** — Compare final code against Blueprint
+5. **Handoff** — Finalize PR description, flag concerns, make ship/no-ship decision
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/review/stages/self-review.md`)
+2. Follow its instructions — fix issues directly when possible
+3. Update `.work-kit/state.md` with findings
+4. Proceed to next sub-stage
+
+## Key Principle
+
+**Fix issues directly when possible.** A review that only lists problems without fixing them is half a review. If you can fix it in under 5 minutes, fix it. If it's bigger, document it for the Handoff decision.
+
+## Recording
+
+Throughout every sub-stage, update the shared state.md sections:
+
+- **`## Decisions`** — If you make judgment calls during review (e.g., "accepted this deviation because..."), record them.
+- **`## Deviations`** — Compliance sub-stage will audit these. If you fix a deviation during review, note that it was resolved.
+
+Review findings feed directly into the Handoff decision and the final work-kit log.
+
+## Context Input
+
+This phase runs as a **fresh agent** (the orchestrator). Read only these sections from `.work-kit/state.md`:
+- `### Plan: Final` — Blueprint (for Compliance review)
+- `### Build: Final` — what was built, PR, deviations
+- `### Test: Final` — test results, criteria status, confidence
+- `## Criteria` — acceptance criteria
+
+## Parallel Sub-agents
+
+**Self-Review, Security, Performance, and Compliance** are independent and run as **4 parallel sub-agents**. **Handoff** runs after all 4 complete.
+
+```
+Agent: Self-Review  ──┐
+Agent: Security     ──┤
+Agent: Performance  ──├──→ Agent: Handoff
+Agent: Compliance   ──┘
+```
+
+Each sub-agent receives:
+- The git diff (`git diff main...HEAD`)
+- The relevant Context Input sections
+- Its sub-stage skill file instructions
+
+Each writes its own `### Review: <sub-stage>` section to state.md.
+
+**Handoff agent** reads all 4 review sections + Test: Final → makes the ship decision.
+
+## Final Output
+
+After Handoff completes, append a `### Review: Final` section to state.md. This is what **Deploy and Wrap-up read**.
+
+```markdown
+### Review: Final
+
+**Decision:** approved | changes_requested | rejected
+
+**Summary:** <1-2 sentences — overall assessment>
+
+**Issues found:** <total count>
+**Issues fixed:** <count>
+**Remaining concerns:**
+- <concern — or "None">
+
+**Security:** <clear | risks noted>
+**Performance:** <clear | issues noted>
+**Compliance:** <compliant | deviations noted>
+
+**If changes_requested:**
+- <specific change 1>
+- <specific change 2>
+
+**If rejected:**
+- <reason>
+```
+
+Then:
+- Update state: `**Phase:** review (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete review"`
+
+## Routing
+
+The Handoff decision determines what happens next:
+- **approved** → proceed to Deploy (or complete if deploy is skipped)
+- **changes_requested** → loop back to Build/Core with specific change list
+- **rejected** → stop work, explain why to the user

package/skills/review/stages/compliance.md

@@ -0,0 +1,48 @@
+---
+description: "Review sub-stage: Compare final code against Blueprint."
+---
+
+# Compliance Review
+
+**Role:** Compliance Auditor
+**Goal:** Verify the implementation matches what was planned.
+
+## Instructions
+
+1. Re-read the Blueprint from `.work-kit/state.md`
+2. Compare final code against each Blueprint step:
+   - Was the step implemented?
+   - Does it match the specified approach?
+   - Any deviations?
+3. Check:
+   - All Blueprint steps are implemented
+   - No scope creep (things built that weren't in the Blueprint)
+   - Architecture matches the plan (data model, API surface, components)
+   - UX Flow matches the plan (screens, interactions, states)
+4. Document any deviations with justification
+
+## Output (append to state.md)
+
+```markdown
+### Review: Compliance
+
+**Result:** compliant | deviations_found
+
+**Blueprint Steps:**
+- Step 1: <implemented | deviated | missing>
+- Step 2: <implemented | deviated | missing>
+- ...
+
+**Deviations:**
+- <deviation and justification — or "None">
+
+**Scope Creep:**
+- <anything built that wasn't planned — or "None">
+```
+
+## Rules
+
+- Deviations aren't always bad — sometimes the plan was wrong and the code adapted
+- But deviations need justification — "I felt like it" is not acceptable
+- Missing steps are a red flag — they need to be implemented or explicitly dropped with reason
+- Scope creep should be called out even if the extra code is good

package/skills/review/stages/handoff.md

@@ -0,0 +1,59 @@
+---
+description: "Review sub-stage: Finalize PR, make ship/no-ship decision."
+---
+
+# Handoff
+
+**Role:** Ship Decision Maker
+**Goal:** Final PR polish and go/no-go decision.
+
+## Instructions
+
+1. Update the PR description with:
+   - Summary of what was built
+   - How to test it
+   - Screenshots if applicable
+   - Any concerns or known limitations
+2. Review all findings from prior review sub-stages
+3. Check acceptance criteria status from Test/Validate
+4. Make the decision: **approved**, **changes_requested**, or **rejected**
+
+## Decision Criteria
+
+- **approved**: All criteria met, no critical/high security issues, tests pass, compliance is acceptable
+- **changes_requested**: Gaps exist but are fixable — specify exactly what needs to change
+- **rejected**: Fundamental problems that require rethinking the approach
+
+## Output (append to state.md)
+
+```markdown
+### Review: Handoff
+
+**PR Description:** updated | already adequate
+**Summary:** <1-2 sentences: what ships and its state>
+
+**Concerns:**
+- <any remaining concerns — or "None">
+
+**Decision:** approved | changes_requested | rejected
+
+**If changes_requested:**
+- <specific change 1>
+- <specific change 2>
+
+**If rejected:**
+- <reason and recommended next step>
+```
+
+## Outcome Routing
+
+- **approved** → Proceed to Deploy phase (or complete if deploy skipped)
+- **changes_requested** → Loop back to Build/Core with the change list as context
+- **rejected** → Stop. Report to user with explanation.
+
+## Rules
+
+- Be specific about what needs to change — "needs work" is useless feedback
+- Don't block on cosmetic issues — fix them directly before finalizing
+- The PR should be ready for a human reviewer after this step
+- If you're unsure between approved and changes_requested, ask the user

package/skills/review/stages/performance.md

@@ -0,0 +1,45 @@
+---
+description: "Review sub-stage: Check for performance issues."
+---
+
+# Performance Review
+
+**Role:** Performance Engineer
+**Goal:** Catch performance problems before they reach production.
+
+## Instructions
+
+Check the diff for:
+
+1. **N+1 Queries** — Loops that make individual DB queries instead of batching
+2. **Missing Indexes** — New query patterns that need DB indexes
+3. **Large Bundle Imports** — Importing entire libraries when only one function is needed
+4. **Unnecessary Re-renders** — Components re-rendering when they shouldn't
+5. **Missing Memoization** — Expensive computations without caching
+6. **Hot Path Operations** — Heavy work in frequently-called code paths
+7. **Missing Pagination** — Unbounded queries or list renders
+8. **Memory Leaks** — Event listeners, intervals, or subscriptions not cleaned up
+
+Fix what you can. Document what needs deeper investigation.
+
+## Output (append to state.md)
+
+```markdown
+### Review: Performance
+
+**Findings:**
+- <finding — or "None">
+
+**Fixes Applied:**
+- <what was fixed — or "None">
+
+**Recommendations:**
+- <suggestions for future optimization — or "None">
+```
+
+## Rules
+
+- Focus on actual problems, not theoretical ones
+- Don't prematurely optimize code that runs once on page load
+- DO flag anything that scales with data (queries, list renders, loops)
+- If you add an index, include it in the migration or note it as needed

package/skills/review/stages/security.md

@@ -0,0 +1,49 @@
+---
+description: "Review sub-stage: OWASP top 10 security review."
+---
+
+# Security Review
+
+**Role:** Security Auditor
+**Goal:** Check for common security vulnerabilities.
+
+## Instructions
+
+Review the diff against OWASP Top 10:
+
+1. **Injection** — SQL injection, command injection, code injection. Are all inputs parameterized?
+2. **Broken Auth** — Are auth checks in place where needed? Session handling correct?
+3. **Sensitive Data Exposure** — Are secrets, tokens, PII handled safely? No logging of sensitive data?
+4. **Broken Access Control** — Can users access resources they shouldn't?
+5. **Security Misconfiguration** — Default configs, unnecessary features enabled, overly permissive CORS?
+6. **XSS** — User input rendered without sanitization? Raw HTML injection vectors?
+7. **Insecure Deserialization** — Untrusted data parsed without validation?
+8. **Vulnerable Dependencies** — Known CVEs in new dependencies?
+9. **Insufficient Logging** — Security events logged? But no sensitive data in logs?
+10. **CSRF** — State-changing requests protected?
+
+Fix issues directly when possible. Document what you can't fix.
+
+## Output (append to state.md)
+
+```markdown
+### Review: Security
+
+**Findings:**
+- <finding with severity: critical/high/medium/low — or "None">
+
+**Fixes Applied:**
+- <what was fixed — or "None">
+
+**Remaining Risks:**
+- <risks that need human attention — or "None">
+
+**Severity Summary:** no issues | low | medium | high | critical
+```
+
+## Rules
+
+- Focus on code YOU wrote/modified — not the entire codebase
+- Not every feature touches all 10 categories — skip irrelevant ones
+- Don't add security theater (unnecessary complexity for non-existent threats)
+- If you find a critical issue, fix it immediately and note it prominently

package/skills/review/stages/self-review.md

@@ -0,0 +1,41 @@
+---
+description: "Review sub-stage: Review your own diff for obvious issues."
+---
+
+# Self-Review
+
+**Role:** Self-Critical Developer
+**Goal:** Catch the easy stuff before the formal review.
+
+## Instructions
+
+1. Run `git diff main...HEAD` to see the full diff
+2. Check for:
+   - Dead code or unused imports
+   - Unclear variable/function naming
+   - Missing or misleading comments
+   - Copy-paste errors
+   - Formatting issues (run the linter)
+   - TODOs that should be resolved
+   - Console.logs or debug code left in
+   - Code that doesn't match the Blueprint
+3. Fix issues directly — don't just list them
+4. Run tests after fixes to confirm nothing broke
+
+## Output (append to state.md)
+
+```markdown
+### Review: Self-Review
+
+**Issues Found:** <N>
+**Issues Fixed:** <M>
+**Remaining Concerns:**
+- <anything you found but couldn't fix — or "None">
+```
+
+## Rules
+
+- Run the linter and fix all warnings
+- Remove ALL debug code (console.log, debugger statements, etc.)
+- This is about catching careless mistakes, not redesigning the architecture
+- Be honest — pretending your code is perfect helps no one

package/skills/test/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: test
+description: "Run the Test phase — 3 sub-stages: Verify, E2E, Validate."
+user-invocable: false
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
+---
+
+You are the **QA Lead**. Validate the implementation against the Blueprint and acceptance criteria.
+
+## Sub-stages (in order)
+
+1. **Verify** — Run existing test suite, check for regressions
+2. **E2E** — Test user flows end-to-end
+3. **Validate** — Verify every acceptance criterion is satisfied
+
+## Execution
+
+For each sub-stage:
+1. Read the sub-stage file (e.g., `.claude/skills/test/stages/verify.md`)
+2. Follow its instructions
+3. Update `.work-kit/state.md` with outputs
+4. Proceed to next sub-stage
+
+## Key Principle
+
+**Test against the Blueprint, not just the code.** The Blueprint defined what should be built. Verify that what was built matches what was planned, and that it actually works.
+
+## Recording
+
+Throughout every sub-stage, update the shared state.md sections:
+
+- **`## Criteria`** — Check off criteria as they're verified. Add evidence inline: `- [x] <criterion> — verified by <test name / screenshot / manual check>`.
+- **`## Decisions`** — If you discover a criterion is untestable or needs reinterpretation, record the decision and why.
+
+The criteria checklist is copied directly into the final work-kit log. Make it accurate.
+
+## Context Input
+
+This phase runs as a **fresh agent**. Read only these sections from `.work-kit/state.md`:
+- `### Build: Final` — what was built, PR, test status, known issues
+- `### Plan: Final` — Blueprint (to test against) and Architecture
+- `## Criteria` — acceptance criteria to validate
+
+## Parallel Sub-agents
+
+**Verify** and **E2E** are independent and can run as **parallel sub-agents**. **Validate** runs after both complete (it needs their results).
+
+```
+Agent: Verify  ──┐
+                  ├──→ Agent: Validate
+Agent: E2E    ──┘
+```
+
+Each sub-agent reads the same Context Input sections and writes its own `### Test: <sub-stage>` section to state.md.
+
+## Final Output
+
+After all sub-stages are done, append a `### Test: Final` section to state.md. This is what **Review agents read**.
+
+```markdown
+### Test: Final
+
+**Suite status:** all passing | <N> failures
+**Total tests:** <count> (passing: <N>, failing: <N>)
+
+**Criteria status:**
+- Satisfied: <N> / <total>
+- Gaps: <list — or "None">
+
+**Confidence:** high | medium | low
+
+**E2E results:**
+- <flow>: pass | fail
+- ...
+
+**Evidence summary:**
+- <criterion> — <evidence type and location>
+- ...
+```
+
+Then:
+- Update state: `**Phase:** test (complete)`
+- Commit state: `git add .work-kit/ && git commit -m "work-kit: complete test"`

package/skills/test/stages/e2e.md

@@ -0,0 +1,44 @@
+---
+description: "Test sub-stage: Test user flows end-to-end."
+---
+
+# E2E
+
+**Role:** End-to-End Tester
+**Goal:** Test the feature as a user would experience it.
+
+## Instructions
+
+1. Review the UX Flow from the Plan phase
+2. For each user flow defined:
+   - Write an E2E test (Playwright, Cypress, or manual verification)
+   - Test the happy path
+   - Test key edge cases (empty state, error state, boundary values)
+3. Take screenshots at key states if the test framework supports it
+4. Focus on the most important flows — don't test every permutation
+
+## Output (append to state.md)
+
+```markdown
+### Test: E2E
+
+**Tests Written:**
+- `<test file>`: <flow description>
+
+**Flows Verified:**
+- <flow 1>: pass | fail (<details>)
+- <flow 2>: pass | fail (<details>)
+
+**Screenshots:**
+- <description>: <path or "not applicable">
+
+**Notes:**
+- <edge cases tested, issues found>
+```
+
+## Rules
+
+- If the project has no E2E framework, test manually and document the steps
+- Focus on user-visible behavior, not internal implementation
+- Screenshots are evidence — capture them for key states
+- If a flow fails, fix the implementation (not the test) unless the test expectation is wrong

package/skills/test/stages/validate.md

@@ -0,0 +1,51 @@
+---
+description: "Test sub-stage: Verify every acceptance criterion is satisfied with evidence."
+---
+
+# Validate
+
+**Role:** Acceptance Validator
+**Goal:** Confirm every acceptance criterion from Clarify is met.
+
+## Instructions
+
+1. Read the `## Criteria` section from `.work-kit/state.md`
+2. For each criterion:
+   - Determine if it's been satisfied by the implementation
+   - Identify the evidence (passing test, screenshot, code reference)
+   - Mark it as checked `[x]` or unchecked `[ ]` with a note
+3. Assess overall confidence: high | medium | low
+
+## Output (append to state.md)
+
+Update the `## Criteria` section — check off satisfied criteria with evidence:
+
+```markdown
+## Criteria
+- [x] User can upload an avatar image — tested in `avatar.test.ts:upload`
+- [x] Fallback to initials when no avatar — screenshot: empty-state.png
+- [ ] Avatar displays at 32px, 48px, and 96px sizes — 32px and 48px verified, 96px not tested
+```
+
+Also append:
+
+```markdown
+### Test: Validate
+
+**Criteria Status:**
+- Satisfied: <N> / <total>
+- Gaps: <list of unsatisfied criteria>
+
+**Confidence:** high | medium | low
+
+**Gap Details:**
+- "<unsatisfied criterion>" — <why it's not met and what's needed>
+```
+
+## Rules
+
+- Every criterion needs evidence, not just "I think it works"
+- Be honest about gaps — hiding them here means Review catches them later (or worse, they ship)
+- If a criterion is genuinely not testable, explain why
+- Low confidence should trigger concern in the Review phase
+- Criteria should not change during Test — if a new criterion is discovered, note it but don't add it to the checklist mid-test

package/skills/test/stages/verify.md

@@ -0,0 +1,41 @@
+---
+description: "Test sub-stage: Run existing test suite, check for regressions."
+---
+
+# Verify
+
+**Role:** Regression Tester
+**Goal:** Ensure nothing is broken — both new and existing tests pass.
+
+## Instructions
+
+1. Run the full test suite
+2. Check results:
+   - All new tests (from Build/Red): should pass
+   - All pre-existing tests: should still pass
+3. If any test fails:
+   - Determine if it's a regression (existing test broke) or a new failure
+   - Fix regressions immediately — don't skip or disable tests
+   - For new test failures, investigate and fix the implementation
+4. Run the suite again after fixes to confirm clean pass
+
+## Output (append to state.md)
+
+```markdown
+### Test: Verify
+
+**Suite Result:** pass | fail
+**Total Tests:** <N> passing, <M> failing
+**Regressions Found:**
+- <test name> — <what broke and fix applied — or "None">
+
+**Fixes Applied:**
+- <description — or "None">
+```
+
+## Rules
+
+- Do NOT skip failing tests — fix them
+- Do NOT disable tests to make the suite pass
+- If a pre-existing test fails and it's a legitimate behavior change, update the test with a comment explaining why
+- Run the suite at least twice — once to find issues, once to confirm fixes