@kennethsolomon/shipkit 1.0.0

package/skills/sk:setup-claude/templates/CLAUDE.md.template

@@ -0,0 +1,299 @@
+<!-- Generated by /setup-claude -->
+
+# [PROJECT_NAME]
+
+[ONE_SENTENCE_DESCRIPTION]
+
+## Tech Stack
+
+| Tech | Details |
+|------|---------|
+| **Language** | [LANGUAGE] |
+| **Framework** | [FRAMEWORK] |
+| **Database** | [DATABASE] |
+| **UI** | [UI] |
+| **Testing** | [TESTING] |
+| **AI/LLM** | [AI] |
+| **Browser Automation** | [BROWSER_AUTOMATION] |
+
+## Key Directories
+
+| Path | Purpose |
+|------|---------|
+| `tasks/` | Planning + findings + progress + security logs |
+
+## Build & Run
+
+```bash
+[DEV_COMMAND]
+[BUILD_COMMAND]
+[LINT_COMMAND]
+[TEST_COMMAND]
+```
+
+## Workflow — Follow This Order
+<!-- LOCK -->
+
+**Flow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → Finish
+
+Progress is tracked in `tasks/workflow-status.md`. This file persists across conversations.
+
+| # | Step | Command | Type | Loop? |
+|---|------|---------|------|-------|
+| 1 | Read Todo | read `tasks/todo.md` | required | no |
+| 2 | Read Lessons | read `tasks/lessons.md` | required | no |
+| 3 | Explore | `/brainstorm` | required | no |
+| 4 | Design | `/frontend-design` or `/api-design` | optional (confirm to skip) | no |
+| 5 | Accessibility | `/accessibility` | optional (confirm to skip) | no |
+| 6 | Plan | `/write-plan` | required | no |
+| 7 | Branch | `/branch` | required | no |
+| 8 | Migrate | `/schema-migrate` | optional (confirm to skip) | no |
+| 9 | Write Tests | `/write-tests` | required | no |
+| 10 | Implement | `/execute-plan` | required | no |
+| 11 | Commit | `/smart-commit` | required | no |
+| 12 | Lint | `/lint` | required | yes — must be clean |
+| 13 | Commit | `/smart-commit` | conditional (skip if lint was clean) | no |
+| 14 | Verify Tests | `/test` | required | yes — 100% coverage required |
+| 15 | Commit | `/smart-commit` | conditional (skip if tests passed clean) | no |
+| 16 | Security | `/security-check` | required | yes — must reach 0 issues |
+| 17 | Commit | `/smart-commit` | conditional (skip if security was clean) | no |
+| 18 | Performance | `/perf` | optional (confirm to skip) | yes — loop until critical/high = 0 |
+| 19 | Commit | `/smart-commit` | conditional (skip if perf was clean) | no |
+| 20 | Review | `/review` | required | yes — must reach 0 issues |
+| 21 | Commit | `/smart-commit` | conditional (skip if review was clean) | no |
+| 22 | Update | `/update-task` | required | no |
+| 23 | Finalize | `/finish-feature` | required | no |
+| 24 | Release | `/release` | optional (confirm to skip) | no |
+
+### Step Details
+
+1.  **Read** `tasks/todo.md` — pick the next incomplete task
+2.  **Read** `tasks/lessons.md` — review past corrections before writing code
+3.  **Explore** — run `/brainstorm` to clarify requirements, constraints, and approach. No code in this step.
+4.  **Design** — run `/frontend-design` for UI mockup or `/api-design` for API contracts. No code — design only. Skip if pure backend with no UI and no new API. After `/frontend-design`, the skill prompts to create a Pencil visual mockup (saved to `docs/design/`). Requires Pencil app open and Pencil MCP connected.
+5.  **Accessibility** — run `/accessibility` to audit the design spec for WCAG 2.1 AA compliance. Produces `tasks/accessibility-findings.md`. Skip if backend-only with no frontend.
+6.  **Plan** — run `/write-plan` to write a decision-complete plan into `tasks/todo.md` using brainstorm + design outputs. No code in this step.
+7.  **Branch** — run `/branch` to create a feature branch auto-named from the current task.
+8.  **Migrate** — run `/schema-migrate` for database changes. Skip if no schema changes needed.
+9.  **Write Tests** — run `/write-tests` (TDD red phase). Write failing tests for all planned code. If modifying existing behavior, update existing tests first. Tests SHOULD fail — no implementation yet.
+10. **Implement** — run `/execute-plan` to execute `tasks/todo.md` checkboxes in small batches, making the failing tests pass (TDD green phase). Log progress to `tasks/progress.md`.
+11. **Commit** — run `/smart-commit` to commit tests + implementation
+12. **Lint** — run `/lint` — auto-detects and runs all project linters. Fix all issues immediately, then re-run until clean. Do not ask to re-run — fix and re-run automatically.
+13. **Commit** — run `/smart-commit` if lint required fixes. Auto-skip if lint was clean.
+14. **Verify Tests** — run `/test` — auto-detects and runs all project test suites. **100% test coverage required.** Fix failures immediately, then re-run. Do not ask to re-run — fix and re-run automatically.
+15. **Commit** — run `/smart-commit` if test fixes were needed. Auto-skip if tests passed first try.
+16. **Security** — run `/security-check`. Must reach 0 issues across all severities. Fix issues immediately, commit, then re-run. Loop until clean.
+17. **Commit** — run `/smart-commit` if security required fixes. Auto-skip if clean.
+18. **Performance** — run `/perf` to audit for performance issues. Produces `tasks/perf-findings.md`. Fix critical/high findings, commit, then re-run. Loop until critical/high = 0. Skip if confirmed with user.
+19. **Commit** — run `/smart-commit` if perf required fixes. Auto-skip if clean.
+20. **Review** — run `/review`. Must reach 0 issues including nitpicks. Fix issues immediately, commit, then re-run. Loop until clean.
+21. **Commit** — run `/smart-commit` if review required fixes. Auto-skip if clean.
+22. **Update** — run `/update-task` to mark the task done in `tasks/todo.md` and log completion to `tasks/progress.md`.
+23. **Finalize** — run `/finish-feature` for changelog + PR
+24. **Release** — run `/release` if deploying. Skip if not ready.
+
+### Workflow Tracker Rules
+
+**These rules are mandatory for every step:**
+
+1. **Read tracker first.** At the start of every step, read `tasks/workflow-status.md` to verify the current step. If the step being run does not match the `>> next <<` step, STOP and ask the user to confirm skipping the intervening steps.
+
+2. **Update tracker after.** At the end of every step, update `tasks/workflow-status.md`:
+   - Set the current step's Status to `done`, `skipped`, or `partial`
+   - Add relevant Notes (e.g., "clean on attempt 2", "backend-only, no UI")
+   - Move `>> next <<` to the next pending step
+
+3. **Optional steps** (4, 5, 7, 18, 24): Ask the user "Skip [step]?" and require explicit confirmation. Record the reason in Notes.
+
+4. **Conditional commits** (13, 15, 17, 19, 21): Auto-skip if no changes were made. Record reason (e.g., "lint was clean", "tests passed first try").
+
+5. **Loop steps are HARD GATES** (12, 14, 16, 20): These steps BLOCK all forward progress until they pass clean. Fix issues immediately and re-run. Do NOT ask the user to re-run — fix and re-run automatically. Track attempt number in Notes (e.g., "clean on attempt 3").
+   - **Step 12 (Lint)**: All detected linting tools must pass — every single one.
+   - **Step 14 (Verify Tests)**: All detected test suites (BE + FE) must pass with 100% coverage on new code.
+   - **Step 16 (Security)**: 0 issues across all severities.
+   - **Step 20 (Review)**: 0 issues including nitpicks.
+   - **Step 18 (Performance)**: Optional gate — if run, loop until critical/high findings = 0. Can be skipped with explicit confirmation.
+   - **DO NOT mark these steps as `done` until every check passes.** If even one tool fails, the step is NOT done. Never proceed to the next step with errors remaining.
+
+6. **Never skip steps without confirmation.** Steps cannot run out of order. Hard gate steps (12, 14, 16, 20) can NEVER be skipped. Optional gate step (18) requires explicit confirmation to skip.
+
+7. **Never auto-advance.** When one step completes, stop and tell the user which step is next. Do not proceed automatically.
+
+8. **Never write code during design or plan phases.** Steps 1-6 are reading/exploring/planning/design only — no code, no file edits (except `tasks/` files).
+
+9. **Step completion summary is NON-NEGOTIABLE.** After finishing ANY step, you MUST output a summary block in this exact format before stopping:
+
+```
+--- Step [#] [Name]: [done/skipped/partial] ---
+Summary: [1-2 sentence summary of what was done]
+Next step: [#] [Name] — run `[command]`
+```
+
+This tells the user exactly what happened and what to do next. Never finish a step silently.
+
+### Tracker Reset
+
+- When starting a new task, check if `tasks/workflow-status.md` has any `done` or `skipped` steps. If yes, ask: "Existing workflow detected. Start fresh and reset tracker?"
+- Reset sets all steps to `not yet` and marks step 1 as `>> next <<`.
+
+### Bug Fix Flow
+
+When fixing a bug (not building a feature), use `/debug` as the entry point. This sets up a shorter workflow:
+
+| # | Step | Command |
+|---|------|---------|
+| 1 | Debug | `/debug` |
+| 2 | Branch | `/branch` |
+| 3 | Write Tests | `/write-tests` (regression test) |
+| 4 | Fix | implement the fix |
+| 5 | Commit | `/smart-commit` |
+| 6 | Lint | `/lint` |
+| 7 | Commit | `/smart-commit` (skip if clean) |
+| 8 | Verify Tests | `/test` |
+| 9 | Commit | `/smart-commit` (skip if clean) |
+| 10 | Security | `/security-check` |
+| 11 | Commit | `/smart-commit` (skip if clean) |
+| 12 | Review | `/review` |
+| 13 | Commit | `/smart-commit` (skip if clean) |
+| 14 | Update | `/update-task` |
+| 15 | Finalize | `/finish-feature` |
+
+Start with `/debug` to investigate, then follow the abbreviated flow.
+
+### Hotfix Flow
+
+For production emergencies that need to ship immediately, use `/hotfix`. Skips brainstorm, design, and write-tests. Quality gates still apply.
+
+| # | Step | Command |
+|---|------|---------|
+| 1 | Investigate | `/debug` |
+| 2 | Branch | `/branch` |
+| 3 | Fix | implement directly |
+| 4 | Smoke Test | run existing tests |
+| 5 | Commit | `/smart-commit` |
+| 6 | Lint | `/lint` |
+| 7 | Commit | `/smart-commit` (skip if clean) |
+| 8 | Verify Tests | `/test` |
+| 9 | Commit | `/smart-commit` (skip if clean) |
+| 10 | Security | `/security-check` |
+| 11 | Commit | `/smart-commit` (skip if clean) |
+| 12 | Review | `/review` |
+| 13 | Commit | `/smart-commit` (skip if clean) |
+| 14 | Update | `/update-task` |
+| 15 | Finalize | `/finish-feature` |
+
+After merging: add a regression test and a lessons.md entry.
+
+## Sub-Agent Patterns
+<!-- BEGIN:sub-agent-patterns -->
+
+Use Claude Code sub-agents to parallelize independent work and speed up development.
+
+### Codebase Exploration (before implementation)
+
+Before implementing a feature, launch parallel Explore agents to understand the affected areas:
+
+```
+Use Agent tool with subagent_type="Explore" — launch all in a single message:
+  - Agent 1: Explore related models, migrations, and relationships
+  - Agent 2: Explore existing routes, controllers, and middleware
+  - Agent 3: Explore test patterns and existing test coverage for the area
+```
+
+This replaces sequential file reading and gives a complete picture before writing code.
+
+### Parallel Quality Checks (/lint)
+
+After formatters run, launch analyzers in parallel (both are read-only):
+
+```
+1. Formatters (sequential — modify files)
+2. Then in parallel:
+   - Agent 1: Static analysis
+   - Agent 2: Code quality checks
+```
+
+### Code Review Parallelization
+
+For `/review` and `/security-check`, split into parallel agents for faster feedback:
+
+```
+Launch in a single message:
+  - Agent 1: Security review — OWASP, injection, auth bypass
+  - Agent 2: Performance review — N+1 queries, missing indexes, cache misses
+  - Agent 3: Test coverage gaps — untested paths, missing edge cases
+```
+
+### Worktree Isolation for Risky Changes
+
+For refactors or experimental approaches, use `isolation: "worktree"` to try the change on an isolated copy:
+
+```
+Agent tool with isolation: "worktree":
+  - Try the refactor in isolation
+  - If it works, apply the same changes to the main worktree
+  - If it fails, the worktree is discarded — no cleanup needed
+```
+
+### Background Agents for Long-Running Tasks
+
+Use `run_in_background: true` for tasks that don't block your next step:
+
+```
+- Background agent: Run full test suite while you continue implementing
+- Background agent: Static analysis while you fix other suggestions
+- You'll be notified when they complete
+```
+<!-- END:sub-agent-patterns -->
+
+## Project Memory
+
+Read these files at the start of every task:
+- `tasks/findings.md` — key decisions and project constraints
+- `tasks/lessons.md` — past mistakes and how to avoid them
+- `tasks/todo.md` — current plan
+
+Write to these files continuously:
+- `tasks/progress.md` — every attempt, error, and resolution
+- `tasks/findings.md` — anything important discovered mid-task
+
+**Never overwrite** `tasks/lessons.md` or `tasks/security-findings.md`.
+
+## Lessons Capture
+
+When the user corrects you:
+- Explicit: `lesson:`, `remember:`, `don't do this again:` → append to `tasks/lessons.md` immediately
+- Implicit: detect "no", "don't", "instead", "wrong" → ask "Should I add this to lessons.md?" → append on confirmation
+
+Entry format:
+```
+### [YYYY-MM-DD] [Brief title]
+**Mistake:** What went wrong
+**Root cause:** Why it happened
+**Prevention:** What to do differently
+```
+
+## Testing — TDD, 100% Coverage Required
+
+Tests are written **before** implementation (step 9) and verified **after** (step 14).
+
+### TDD Flow
+
+1. `/write-tests` — write failing tests based on the plan (RED)
+2. `/execute-plan` — implement code to make tests pass (GREEN)
+3. `/test` — verify all tests pass with 100% coverage (VERIFY)
+
+Every new function, endpoint, component, and module needs tests. No code proceeds past step 13 without 100% coverage on new code.
+
+## 3-Strike Protocol
+
+When blocked:
+1. Log attempt + error to `tasks/progress.md`
+2. Try a different approach
+3. On 3rd failure — stop and ask the user what was tried
+
+Never retry the same failing approach.
+
+## Architectural Change Log
+
+Create entries in: `[ARCH_CHANGELOG_DIR]`

package/skills/sk:setup-claude/templates/arch-changelog-guide.md.template

@@ -0,0 +1,3 @@
+<!-- Deprecated template path. -->
+<!-- Source of truth: templates/.claude/docs/arch-changelog-guide.md.template -->
+

package/skills/sk:setup-claude/templates/changelog-guide.md.template

@@ -0,0 +1,3 @@
+<!-- Deprecated template path. -->
+<!-- Source of truth: templates/.claude/docs/changelog-guide.md.template -->
+

package/skills/sk:setup-claude/templates/commands/brainstorm.md.template

@@ -0,0 +1,74 @@
+---
+description: "Start with design questions before writing code."
+---
+
+<!-- Generated by /setup-claude -->
+
+# /brainstorm
+
+**Workflow:** Read → **Explore** → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → Finalize → Release
+
+Explore design and clarify requirements **before** any code is written.
+
+## Hard Rules
+
+- **DO NOT write, edit, or generate any code.** No files, no snippets, no pseudo-implementations.
+- **DO NOT create a plan.** That is `/write-plan`'s job.
+- **DO NOT run build/test/lint commands.** You are in design mode only.
+- You may **read** existing code to understand the current state, but nothing more.
+
+## Steps
+
+0. **Check workflow tracker:**
+   - Read `tasks/workflow-status.md`. If it doesn't exist, create it using the standard
+     14-step template (all steps `not yet`, step 1 `>> next <<`).
+   - If any steps show `done`, `skipped`, or `partial`: ask the user —
+     "Existing workflow detected. Start fresh and reset tracker?" Wait for confirmation.
+   - If yes: reset all steps to `not yet`, mark step 1 as `>> next <<`, and clear all Notes
+     (except the default labels: optional, conditional, loop).
+   - If no: continue from current state (the user is resuming a prior workflow).
+
+1. **Read context files first:**
+   - If `tasks/findings.md` exists and has content, read it — summarize prior decisions
+     and ask: extend, revise, or start fresh?
+   - If `tasks/lessons.md` exists, read it in full. Apply every active lesson as a design
+     constraint throughout this brainstorm — treat each prevention rule as a hard constraint
+     when proposing approaches.
+   - If `tasks/security-findings.md` exists and has audit results, skim for recurring
+     patterns — factor security constraints into proposed approaches (e.g., if prior audits
+     flagged missing input validation, ensure new designs account for it).
+
+2. **Understand the request** — Ask clarifying questions about what the user wants. Do not assume. Cover:
+   - What problem are we solving?
+   - Who is it for?
+   - What are the expected inputs/outputs or behaviors?
+   - Are there constraints (performance, compatibility, existing patterns)?
+
+3. **Explore the current codebase** (read-only) — Identify:
+   - Relevant files, modules, and patterns already in place
+   - How similar features are implemented today
+   - Potential impact areas and dependencies
+
+4. **Propose approaches** — Present 2–3 design options with trade-offs:
+   - Approach name + 1-sentence summary
+   - Pros and cons
+   - Complexity estimate (small / medium / large)
+   - Which existing patterns it follows or breaks
+
+5. **Get alignment** — Ask the user which approach they prefer (or if they want a hybrid). Do not proceed without explicit approval on the direction.
+
+6. **Record findings** — Write discoveries and the agreed-upon direction to `tasks/findings.md`:
+   - Problem statement
+   - Key decisions made
+   - Chosen approach + rationale
+   - Open questions (if any remain)
+
+## When Done
+
+1. Update `tasks/workflow-status.md`: set step 1 (`/brainstorm`) to `done`, move `>> next <<` to the next pending step.
+2. Print the full workflow status dashboard table.
+3. Tell the user:
+   > "Brainstorming complete. Findings saved to `tasks/findings.md`."
+4. If step 2 (`/frontend-design`) is next, ask: "Step 2 is `/frontend-design` (optional). Run it or skip?"
+
+**Do not proceed to planning or implementation yourself.** The user must explicitly invoke the next step.

package/skills/sk:setup-claude/templates/commands/execute-plan.md.template

@@ -0,0 +1,57 @@
+---
+description: "Execute tasks/todo.md checkboxes in small batches; log to tasks/progress.md."
+---
+
+<!-- Generated by /setup-claude -->
+
+# /execute-plan
+
+**Workflow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → **Implement** → Lint → Verify Tests → Security → Performance → Review → Finalize → Release
+
+Execute the plan in `tasks/todo.md` in small batches with clear checkpoints.
+
+## Before You Start
+
+1. If `tasks/lessons.md` exists, read it in full. Treat every active lesson as a
+   standing constraint for this entire session. Apply each prevention rule before
+   executing the first batch.
+
+2. If `tasks/progress.md` exists and has Error Log entries, read the last 20 lines.
+   Do NOT repeat any action already recorded as a failed attempt — change approach.
+
+## Steps
+
+1. Read `tasks/todo.md` and identify the next unchecked items.
+2. Execute the next **batch of 3 items** (default). For each item:
+   - Mark it in progress (in your narrative)
+   - Make the smallest change that satisfies the step
+   - Run the verification specified (or add it if missing)
+   - Log what you did in `tasks/progress.md` (files touched + commands run + results)
+   - If you learned something important, append it to `tasks/findings.md`
+3. After the batch, report:
+   - what changed
+   - verification results
+   - what's next
+   - After all items in this batch pass verification, the code is ready to stage.
+     Run `/commit` after any passed batch, or accumulate and commit at plan completion.
+     Never combine more than one logical unit of work in a single commit.
+4. Stop and wait for user feedback before continuing.
+
+## Failure handling
+- Log every failure (error + attempt # + fix) in `tasks/progress.md`.
+- Do not repeat the same failing action; change approach.
+- After 3 failed attempts, stop and ask the user with details.
+
+## On User Correction
+
+If the user corrects your approach during execution, immediately append to
+`tasks/lessons.md`:
+
+```
+### [YYYY-MM-DD] [Brief title]
+**Bug:** What you did wrong
+**Root cause:** Why the approach was wrong
+**Prevention:** What to do instead next time
+```
+
+Then continue with the corrected approach.

package/skills/sk:setup-claude/templates/commands/features.md.template

@@ -0,0 +1,238 @@
+---
+name: features
+description: "Sync docs/features/ specs with the current codebase. Auto-detects changed areas and updates only affected specs. Creates the spec system from scratch if it doesn't exist."
+---
+
+<!-- Generated by /setup-claude -->
+
+# /features
+
+Keep feature specifications in `docs/features/` in sync with the actual codebase.
+Works with **any project** — framework-agnostic, auto-discovers source structure.
+
+## What This Does
+
+Maintains `docs/features/` as a platform-agnostic feature specification system —
+the single source of truth shared between web, mobile, and any other platform
+that uses the same backend. Each spec covers: DB schema, business logic, API
+contract, permissions, edge cases, error states, web/mobile UI behavior, and
+platform divergences.
+
+---
+
+## Steps
+
+### Step 1: Detect Project State
+
+Check what exists:
+
+```bash
+ls docs/features/ 2>/dev/null && echo "EXISTS" || echo "MISSING"
+ls docs/FEATURES.md 2>/dev/null && echo "INDEX_EXISTS" || echo "INDEX_MISSING"
+```
+
+**If `docs/features/` does not exist:**
+Ask the user: "No feature specification system found. Create one from scratch?"
+- Yes → jump to **[Create From Scratch](#create-from-scratch)** below
+- No → stop
+
+**If `docs/features/` exists:**
+Continue to Step 2.
+
+---
+
+### Step 2: Determine Update Scope
+
+Present three options:
+
+> **What would you like to update?**
+> **A. Auto-detect** *(recommended)* — scan recent git changes, update only affected specs
+> **B. Select features** — pick which specs to update from the list
+> **C. Refresh all** — update every spec from current source code
+
+Wait for the user's choice.
+
+---
+
+### Step 3A: Auto-detect Changed Features
+
+```bash
+git log --since="7 days ago" --name-only --pretty=format: | grep -v '^$' | sort -u
+```
+
+Map changed file paths to feature specs using these rules:
+
+1. **Read `docs/FEATURES.md`** to get the list of all spec files and their names.
+2. For each changed file, determine which spec it belongs to:
+   - Match by **feature name similarity**: if the spec is `expenses.md`, look for changed files containing `expense` in their path.
+   - Match by **directory**: if the spec is `budgets.md`, match files under any `budgets/` or `budget/` directory.
+   - Match by **schema files**: if any migration file, `schema.sql`, `schema.prisma`, `database.ts`, or similar schema file changed → mark ALL specs as potentially affected (schema changes ripple everywhere).
+3. Deduplicate the affected spec list.
+4. Report which specs will be updated and ask for confirmation.
+
+---
+
+### Step 3B: User Selects Features
+
+List all `.md` files in `docs/features/` (excluding `_template.md`).
+Let the user pick which ones to update.
+
+---
+
+### Step 3C: Refresh All
+
+Set update list = all `.md` files in `docs/features/` (excluding `_template.md`).
+
+---
+
+### Step 4: Update Each Affected Spec
+
+For each spec file to update, follow this sequence:
+
+#### 4a. Read the existing spec
+Understand its current content and section structure.
+
+#### 4b. Discover relevant source files
+
+Use a three-step lookup — no hardcoded paths:
+
+1. **Name-based search**: the feature name from the spec filename (e.g., `expenses.md` → feature name `expenses`). Search the repo:
+   ```bash
+   # Find files whose name contains the feature keyword
+   find . -type f \( -name "*expense*" -o -name "*expenses*" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/docs/*" \
+     2>/dev/null | head -30
+   ```
+   Adjust the keyword to match the feature name.
+
+2. **Related Docs in spec**: read the `## Related Docs` section of the existing spec — it lists previously referenced files. Read those files too.
+
+3. **DB schema hint**: read the `## Database Schema` section — it names tables. Search migrations and schema files for those table names.
+
+#### 4c. Read the source files
+Read all discovered source files to understand the current implementation.
+
+#### 4d. Identify what changed
+Compare the current source code against what the spec describes:
+- New or removed DB columns / tables / constraints
+- Changed business logic rules or state transitions
+- New/changed API payloads or query patterns
+- Updated permission keys or tier requirements
+- New edge cases, error codes, or recovery paths
+
+#### 4e. Update only changed sections
+Rewrite only the sections that are out of date. **Preserve all unchanged sections verbatim.**
+Update the `> Status` block if the implementation status on either platform changed.
+
+---
+
+### Step 5: Handle New Features
+
+If source code has a clear new feature (new hook, new route group, new major component) with no corresponding spec:
+
+1. Create `docs/features/<feature-name>.md` using `docs/features/_template.md` as base.
+   If `_template.md` doesn't exist, use this 11-section structure:
+   ```
+   Status → Overview → Database Schema → Business Logic → API Contract
+   → Permissions & Access Control → Edge Cases → Error States
+   → UI/UX Behavior (### Web + ### Mobile) → Platform Notes → Related Docs
+   ```
+2. Fill all 11 sections from current source code.
+3. Add the new spec to `docs/FEATURES.md` under the appropriate section.
+
+---
+
+### Step 6: Update Master Index
+
+Review `docs/FEATURES.md`:
+- Add links for any new specs
+- Update status columns (Web / Mobile) if implementation status changed
+- Update any tier/feature tables if permissions changed
+
+---
+
+### Step 7: Report and Commit
+
+Show a summary:
+- ✅ **Updated**: `spec-name.md` — what changed (1 sentence each)
+- ➕ **Added**: any new spec files
+- ⏭️ **Skipped**: specs with no detected changes
+
+Ask: **"Commit the updated specs?"**
+- Yes → stage only files under `docs/` and commit:
+  `docs(features): update feature specs to reflect current implementation`
+- No → leave changes unstaged for the user to review
+
+---
+
+## Create From Scratch
+
+When `docs/features/` doesn't exist, discover and document all features:
+
+### Discovery Phase
+
+1. **Detect source structure** — find where feature logic lives:
+   ```bash
+   # Look for hooks, services, controllers, models, routes
+   ls src/ lib/ app/ 2>/dev/null
+   find . -maxdepth 4 -type f \
+     \( -name "use-*.ts" -o -name "use-*.js" \
+        -o -name "*.service.ts" -o -name "*.controller.ts" \
+        -o -name "*.model.ts" -o -name "*.router.ts" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null | head -50
+   ```
+
+2. **Detect schema files** — migrations, ORM schemas:
+   ```bash
+   find . -maxdepth 5 \
+     \( -name "schema.sql" -o -name "*.schema.prisma" \
+        -o -name "database.ts" -o -name "*.migration.*" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null
+   ls supabase/migrations/ 2>/dev/null | tail -10
+   ls prisma/ 2>/dev/null
+   ```
+
+3. **Identify feature domains** from the discovered files — group related files into named features.
+
+4. **Report discovered features** and ask the user to confirm/adjust the list before creating anything.
+
+### Creation Phase
+
+For each confirmed feature:
+1. Read all relevant source files.
+2. Create `docs/features/<feature-name>.md` with all 11 sections — based entirely on source code.
+
+Also create:
+- `docs/FEATURES.md` — master index with:
+  - How-to-use section (web path + mobile path via `../project-name/docs/`)
+  - Feature table grouped by domain
+  - Tier/subscription overview (if the project has tiers)
+- `docs/features/_template.md` — 11-section template for future specs
+
+Commit: `docs: add feature specification system`
+
+---
+
+## Quality Rules (Always Apply)
+
+- **Source-verified only** — every claim must be findable in source code; never invent behavior
+- **No placeholders** — no `// TODO`, no `false // will be computed`, no assumed values
+- **Surgical updates** — only rewrite what changed; preserve unchanged sections verbatim
+- **Numeric JSX coercion** — when documenting frontend behavior, note `!!value` (not `value &&`) for numerics to avoid rendering `0` as text in React/React Native
+- **Local date, not UTC** — for any time-bounded query (current month, today, etc.), document that implementations must use local `new Date()`, not `toISOString()` which returns UTC and causes off-by-one for users in non-UTC timezones
+- **All 11 sections required** — mark "N/A" only if genuinely not applicable
+
+## Source Discovery Heuristics (Reference)
+
+When locating source files for a feature named `<name>`:
+
+| What to look for | Search pattern |
+|---|---|
+| Hooks / composables | `use-<name>.*`, `use<Name>.*` |
+| Components | directories or files matching `<name>/`, `*<name>*` |
+| API routes / controllers | `<name>.route.*`, `<name>.controller.*`, `api/<name>/` |
+| Services / repositories | `<name>.service.*`, `<name>.repo.*` |
+| DB schema | `migrations/` containing table name, `schema.prisma`, `database.ts` |
+| Tests | `<name>.test.*`, `<name>.spec.*` |
+
+These are starting points — read broadly and verify before updating any section.