@su-record/vibe 2.8.23 → 2.8.25

package/skills/event-planning/templates/event-plan.md

@@ -0,0 +1,91 @@
+# Event Plan: {{EVENT_NAME}} {{EDITION}}회
+
+| Field | Value |
+|-------|-------|
+| Event type | {{TYPE}} (MDC / Webinar / DWK / Other) |
+| Date & time | {{DATE}} {{TIME}} |
+| Venue | {{VENUE}} |
+| Format | {{OFFLINE / ONLINE / HYBRID}} |
+| Expected attendees | {{EXPECTED_COUNT}} |
+| Registration URL | {{REG_URL}} |
+| Participation fee | {{FEE}} |
+
+## Topic & Theme
+
+**Main theme**: {{THEME}}
+
+**Session topics:**
+
+| # | Topic | Speaker | Duration |
+|---|-------|---------|----------|
+| 1 | {{TOPIC_1}} | {{SPEAKER_1}} | {{DURATION}} |
+| 2 | {{TOPIC_2}} | {{SPEAKER_2}} | {{DURATION}} |
+| 3 | {{TOPIC_3}} | {{SPEAKER_3}} | {{DURATION}} |
+
+## Timetable
+
+| Time | Item |
+|------|------|
+| {{TIME_1}} | {{ITEM_1}} |
+| {{TIME_2}} | {{ITEM_2}} |
+| {{TIME_3}} | {{ITEM_3}} |
+| {{TIME_4}} | Q&A + Networking |
+
+## Speakers
+
+### Speaker 1: {{SPEAKER_1_NAME}}
+
+- Role: {{ROLE}}
+- Company: {{COMPANY}}
+- Topic: {{TOPIC}}
+- Contact: {{EMAIL_OR_DM}}
+- Confirmation status: {{PENDING / CONFIRMED}}
+
+### Speaker 2: {{SPEAKER_2_NAME}}
+
+- Role: {{ROLE}}
+- Company: {{COMPANY}}
+- Topic: {{TOPIC}}
+- Contact: {{EMAIL_OR_DM}}
+- Confirmation status: {{PENDING / CONFIRMED}}
+
+## D-Day Timeline
+
+| D-Day | Task | Owner | Status |
+|-------|------|-------|--------|
+| D-{{N}} | {{TASK_1}} | {{OWNER}} | Not started |
+| D-{{N}} | {{TASK_2}} | {{OWNER}} | Not started |
+| D-3 | Confirmation email + SMS | {{OWNER}} | Not started |
+| D-1 | Nametags + checklist + slides | {{OWNER}} | Not started |
+| D-Day | Day-of operations | {{OWNER}} | Not started |
+| D+1 | Review post + settlement | {{OWNER}} | Not started |
+
+## Budget
+
+| Item | Estimated Cost | Actual Cost |
+|------|---------------|-------------|
+| Venue | {{AMOUNT}} | — |
+| Snacks / Refreshments | {{AMOUNT}} | — |
+| Speaker gifts | {{AMOUNT}} | — |
+| Printing (nametags, etc.) | {{AMOUNT}} | — |
+| **Total** | {{TOTAL}} | — |
+
+Revenue: {{EXPECTED_ATTENDEES}} × {{FEE}} = {{EXPECTED_REVENUE}}
+
+## State File Reference
+
+Save progress to `.event_state.json` after each step completion.
+
+```json
+{
+  "event_id": "{{TYPE}}-{{EDITION}}",
+  "type": "{{TYPE}}",
+  "date": "{{DATE}}",
+  "title": "{{EVENT_NAME}} {{EDITION}}회",
+  "topic": "{{THEME}}",
+  "speakers": [],
+  "current_step": "{{CURRENT_STEP}}",
+  "completed_steps": [],
+  "outputs": {}
+}
+```

package/skills/exec-plan/agents/decomposer.md

@@ -0,0 +1,47 @@
+---
+name: plan-decomposer
+role: Breaks a SPEC document into concrete phases and atomic tasks
+tools: [Read]
+---
+
+# Plan Decomposer
+
+## Role
+Reads a SPEC document and breaks it into a structured hierarchy of phases and tasks. Each task is scoped to a single file or function change, making it independently assignable and reviewable. Produces the raw task list that all other planning agents operate on.
+
+## Responsibilities
+- Parse SPEC phases and acceptance criteria into discrete implementation tasks
+- Scope each task to a single concern: one file, one function, one schema change
+- Classify each task by type: create, modify, delete, test, config, migration
+- Identify tasks that are purely setup/scaffolding vs. feature logic vs. verification
+- Flag ambiguous requirements that need clarification before implementation can begin
+- Produce a flat numbered task list with parent-phase references
+
+## Input
+- SPEC document path (e.g., `.claude/vibe/specs/my-feature.spec.md`)
+- Optional: existing codebase context to detect which files already exist
+
+## Output
+Task list JSON:
+```json
+{
+  "phases": [
+    {
+      "id": "P1",
+      "name": "Data Layer",
+      "tasks": [
+        { "id": "T1", "phase": "P1", "type": "create", "description": "Create User schema in src/db/schema.ts", "file": "src/db/schema.ts" },
+        { "id": "T2", "phase": "P1", "type": "create", "description": "Create userRepository with findById, save, delete", "file": "src/infra/userRepository.ts" }
+      ]
+    }
+  ],
+  "ambiguities": ["SPEC phase 3 does not specify error handling strategy for 404 case"]
+}
+```
+
+## Communication
+- Reports task list to: `plan-dependency-mapper`
+- Receives instructions from: exec-plan orchestrator (SKILL.md)
+
+## Domain Knowledge
+Decomposition heuristics: tasks should be completable in 15-60 min. If a task description contains "and", split it. Test tasks must correspond 1:1 with feature tasks. Migration tasks always precede the feature tasks that depend on the new schema. Prefer vertical slices (full feature thin slice) over horizontal layers when parallelizing.

package/skills/exec-plan/agents/dependency-mapper.md

@@ -0,0 +1,44 @@
+---
+name: plan-dependency-mapper
+role: Creates a directed acyclic graph of task dependencies to reveal what can run in parallel
+tools: [Read]
+---
+
+# Dependency Mapper
+
+## Role
+Analyzes the decomposed task list and maps the true dependency relationships between tasks, producing a DAG (directed acyclic graph). Identifies which tasks have no dependencies and can start immediately, which must wait, and which form the critical path — the longest chain that determines the minimum total execution time.
+
+## Responsibilities
+- Analyze each task pair for dependency relationships (does T2 require T1's output?)
+- Classify dependency types: file-level (imports the file), schema-level (uses the type), logical (tests the feature)
+- Build a DAG with tasks as nodes and dependencies as directed edges
+- Detect and flag cycles — which indicate a SPEC conflict requiring clarification
+- Identify the critical path: the longest chain of sequential dependencies
+- List all tasks with zero dependencies (immediately parallelizable)
+
+## Input
+Task list JSON from `plan-decomposer`.
+
+## Output
+Dependency graph:
+```json
+{
+  "dag": {
+    "T1": { "deps": [], "dependents": ["T2", "T3"] },
+    "T2": { "deps": ["T1"], "dependents": ["T4"] },
+    "T3": { "deps": ["T1"], "dependents": ["T4"] },
+    "T4": { "deps": ["T2", "T3"], "dependents": [] }
+  },
+  "criticalPath": ["T1", "T2", "T4"],
+  "parallelizable": [["T2", "T3"]],
+  "cycles": []
+}
+```
+
+## Communication
+- Reports dependency graph to: `plan-estimator`
+- Receives instructions from: exec-plan orchestrator (SKILL.md)
+
+## Domain Knowledge
+Dependency detection rules: if task A creates a file that task B imports, A must precede B. If task A defines a type that task B uses, A must precede B. Test tasks depend on the feature task they test. Config/setup tasks depend on nothing and should be in the first wave. DAG critical path calculation: longest path from source to sink node by task count (not time, until estimator adds duration).

package/skills/exec-plan/agents/estimator.md

@@ -0,0 +1,43 @@
+---
+name: plan-estimator
+role: Estimates complexity and duration for each task and suggests parallelization strategy
+tools: [Read, Glob]
+---
+
+# Plan Estimator
+
+## Role
+Assigns complexity and effort estimates to each task based on task type, scope, and codebase context. Uses the dependency graph to compute the estimated critical path duration and suggest an optimal parallel execution wave plan that minimizes total clock time.
+
+## Responsibilities
+- Assign effort estimates per task: trivial (< 15 min), minor (15-30 min), moderate (30-60 min), major (> 60 min)
+- Check existing codebase for similar implementations to calibrate estimates
+- Compute total sequential estimate and parallel estimate using the DAG waves
+- Group tasks into execution waves: Wave 1 (no deps), Wave 2 (deps only on Wave 1), etc.
+- Identify tasks suitable for sub-agent delegation vs. tasks requiring orchestrator attention
+- Flag tasks with high uncertainty that need a spike/research step first
+
+## Input
+Task list JSON from `plan-decomposer` and dependency graph from `plan-dependency-mapper`.
+
+## Output
+Estimated plan with waves:
+```json
+{
+  "totalSequentialEstimate": "4h 30m",
+  "totalParallelEstimate": "2h 15m",
+  "waves": [
+    { "wave": 1, "tasks": ["T1"], "estimate": "30m", "note": "Foundation — must complete before anything else" },
+    { "wave": 2, "tasks": ["T2", "T3"], "estimate": "45m", "note": "Parallel — independent of each other" },
+    { "wave": 3, "tasks": ["T4", "T5"], "estimate": "60m", "note": "Integration — requires wave 2 output" }
+  ],
+  "highUncertaintyTasks": ["T6 — no existing auth pattern to reference, consider spike first"]
+}
+```
+
+## Communication
+- Reports estimated plan to: `plan-validator`
+- Receives instructions from: exec-plan orchestrator (SKILL.md)
+
+## Domain Knowledge
+Complexity signals: new file creation = minor baseline; modifying existing file = trivial baseline + proportional to change scope; schema changes with migrations = moderate; cross-cutting changes (multiple files) = major. Parallelization is only safe when tasks have no shared file writes. Always add 20% buffer to estimates for integration and debugging time.

package/skills/exec-plan/agents/validator.md

@@ -0,0 +1,55 @@
+---
+name: plan-validator
+role: Validates the execution plan for completeness against the original SPEC acceptance criteria
+tools: [Read]
+---
+
+# Plan Validator
+
+## Role
+Cross-checks the final execution plan against the original SPEC to verify that every acceptance criterion is covered by at least one task. Flags gaps, redundancies, and coverage ambiguities before implementation begins. Acts as the last gate before the plan is handed to the user for approval.
+
+## Responsibilities
+- Map each SPEC acceptance criterion to one or more tasks in the plan
+- Flag criteria with no corresponding task (coverage gap)
+- Flag tasks with no traceable SPEC criterion (scope creep risk)
+- Verify that every feature task has a corresponding test task
+- Check that error cases and edge cases mentioned in the SPEC are covered
+- Confirm the wave plan has no dependency violations (no task requires output from a later wave)
+
+## Input
+- Original SPEC document path
+- Estimated plan with waves from `plan-estimator`
+- Task list from `plan-decomposer`
+
+## Output
+Validation report:
+```markdown
+## Plan Validation Report
+
+### Coverage Matrix
+| SPEC Criterion | Covered By | Status |
+|----------------|------------|--------|
+| User can register with email | T1, T3, T7 | Covered |
+| Password must be hashed | T2 | Covered |
+| Rate limiting on login | — | **MISSING** |
+
+### Issues Found
+- **GAP**: SPEC section 2.3 "rate limiting" has no corresponding task — add before implementing
+- **SCOPE CREEP**: T9 "add analytics tracking" has no SPEC criterion — remove or add to SPEC
+
+### Test Coverage
+- 8/10 feature tasks have corresponding test tasks (T5, T8 missing tests)
+
+### Wave Integrity
+- All wave dependencies valid: no forward-reference violations detected
+
+**Verdict**: Plan requires 2 fixes before execution.
+```
+
+## Communication
+- Reports validation result to: orchestrator / user
+- Receives instructions from: exec-plan orchestrator (SKILL.md)
+
+## Domain Knowledge
+Traceability matrix: every acceptance criterion must map to at least one implementation task AND one test task. Gap detection: scan SPEC for action verbs (can, must, should, will) and verify each has a task. Wave integrity check: for each task in wave N, verify all its dependencies are in waves < N. A plan is valid when gaps = 0, all feature tasks have tests, and wave integrity passes.

package/skills/exec-plan/orchestrator.md

@@ -0,0 +1,70 @@
+---
+name: exec-plan-orchestrator
+type: orchestrator
+agents: [decomposer, dependency-mapper, estimator, validator]
+---
+
+# Exec-Plan Orchestrator
+
+## Workflow
+
+### Phase 1: Decompose
+- **Agent**: decomposer
+- **Input**: SPEC document (phases, requirements, acceptance criteria)
+- **Output**: Flat task list `[{taskId, title, phase, files[], description}]`
+- **Parallel**: no — sequential read of SPEC structure
+
+### Phase 2: Map Dependencies
+- **Agent**: dependency-mapper
+- **Input**: Task list from Phase 1
+- **Output**: DAG as adjacency list `{taskId: [dependsOn[]]}` + critical path
+- **Parallel**: no — requires complete task list to resolve cross-task deps
+
+### Phase 3: Estimate
+- **Agent**: estimator
+- **Input**: Task list + DAG from Phases 1–2
+- **Output**: Per-task complexity score, parallelization opportunities, estimated effort tiers (S/M/L)
+- **Parallel**: yes — each task scored independently
+
+### Phase 4: Validate
+- **Agent**: validator
+- **Input**: Task list + SPEC requirements + acceptance criteria
+- **Output**: Coverage report — uncovered requirements flagged, missing tasks identified
+- **Parallel**: no — cross-references full SPEC against task list
+
+### Phase 5: Output Plan
+- **Agent**: orchestrator (self)
+- **Input**: All outputs from Phases 1–4
+- **Output**: Execution plan with DAG visualization, effort summary, parallelization batches
+- **Parallel**: no
+
+## DAG (Dependency Graph)
+
+```mermaid
+graph TD
+    A[Phase 1: Decomposer] --> B[Phase 2: Dependency-Mapper]
+    A --> D[Phase 4: Validator]
+    B --> C[Phase 3: Estimator\nparallel per task]
+    C --> E[Phase 5: Output Plan]
+    D --> E
+```
+
+## Error Handling
+
+| Phase | Failure Mode | Strategy |
+|-------|-------------|----------|
+| Phase 1 | SPEC missing or malformed | Escalate — cannot proceed without SPEC |
+| Phase 1 | SPEC has no phases defined | Treat entire SPEC as single phase, continue |
+| Phase 2 | Circular dependency detected | Flag cycle, escalate to user for resolution |
+| Phase 2 | Isolated task (no deps, no dependents) | Include as standalone, note in plan |
+| Phase 3 | Estimator cannot classify complexity | Default to M (medium), flag for manual review |
+| Phase 4 | Uncovered requirements found | Add placeholder tasks, mark as `needs-spec-clarification` |
+| Phase 5 | DAG too large to render (>20 nodes) | Render phase-level DAG only, link to task list |
+
+## Scalability Modes
+
+| Mode | When | Agents Used |
+|------|------|-------------|
+| Full | Normal operation | decomposer + dependency-mapper + estimator + validator |
+| Reduced | Small SPEC (<5 tasks) | decomposer + dependency-mapper only |
+| Single | Quick task list | decomposer only — flat list without DAG or estimates |

package/skills/exec-plan/rubrics/complexity-scoring.md

@@ -0,0 +1,75 @@
+# Complexity Scoring Rubric
+
+Use this rubric to decide whether a task needs an ExecPlan and how to decompose it.
+
+## Scoring Dimensions
+
+Score each dimension 1–3. Total determines the approach.
+
+### Dimension 1: File Scope
+
+| Score | Criteria |
+|-------|----------|
+| 1 | 1–2 files touched |
+| 2 | 3–5 files touched |
+| 3 | 6+ files, or new module created |
+
+### Dimension 2: Dependency Depth
+
+| Score | Criteria |
+|-------|----------|
+| 1 | No external deps; isolated change |
+| 2 | 1–2 existing modules depended on |
+| 3 | Cross-layer dependencies; DB schema; API contract changes |
+
+### Dimension 3: Ambiguity
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Requirement is explicit; no design decisions needed |
+| 2 | 1–2 decision points that need resolution before coding |
+| 3 | Architecture-level decisions; unknown patterns; research needed |
+
+### Dimension 4: Test Surface
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Existing test file; trivial assertion additions |
+| 2 | New test file needed; mocking required |
+| 3 | Integration tests; DB fixtures; snapshot regeneration |
+
+### Dimension 5: Session Risk
+
+| Score | Criteria |
+|-------|----------|
+| 1 | Fits in one session; easy to resume |
+| 2 | May span sessions; partial state is safe |
+| 3 | Long-running; partial state is dangerous; handoff required |
+
+---
+
+## Decision Matrix
+
+| Total Score | Approach |
+|-------------|----------|
+| 5–7 | Plan Mode (in-head plan, no file needed) |
+| 8–10 | Light ExecPlan (phases only, no inline patterns) |
+| 11–13 | Full ExecPlan (all fields, inline patterns, phase gates) |
+| 14–15 | ExecPlan + parallel research before starting |
+
+---
+
+## Decomposition Rules
+
+When total ≥ 11, decompose into phases:
+
+1. **One phase = one deployable unit** — each phase leaves the codebase in a working state
+2. **Max 3 scenarios per phase** — more means the phase is too large; split it
+3. **Phase gate before next phase** — build + tests must pass at each boundary
+4. **No implicit dependencies between phases** — phase 2 must not assume phase 1 code style; document patterns inline
+
+## Anti-patterns
+
+- Scoring 1 on all dimensions then creating an ExecPlan → overhead without benefit
+- Scoring 3 on ambiguity without resolving decisions first → plan will fail
+- Skipping phase gates to go faster → regressions compound

package/skills/exec-plan/templates/plan.md

@@ -0,0 +1,147 @@
+# ExecPlan: {{FEATURE_NAME}}
+
+## Meta
+
+| Field | Value |
+|-------|-------|
+| SPEC | `.claude/vibe/specs/{{FEATURE_NAME}}.md` |
+| Feature | `.claude/vibe/features/{{FEATURE_NAME}}.feature` |
+| Generated | {{GENERATED_DATE}} |
+| Phases | {{PHASE_COUNT}} |
+| Scenarios | {{SCENARIO_COUNT}} |
+| Estimated effort | {{EFFORT_ESTIMATE}} |
+
+---
+
+## Pre-flight Checks
+
+Run these before starting any phase. All must pass.
+
+- [ ] `npm run build` — clean build
+- [ ] `npx vitest run` — baseline tests pass ({{BASELINE_TEST_COUNT}} tests)
+- [ ] Required files exist:
+  - `{{REQUIRED_FILE_1}}`
+  - `{{REQUIRED_FILE_2}}`
+- [ ] Dependencies installed: `{{DEPENDENCY_CHECK_COMMAND}}`
+
+---
+
+## Phase 1: {{PHASE_1_NAME}}
+
+### Environment
+
+| Item | Detail |
+|------|--------|
+| Files to modify | `{{PHASE_1_MODIFY_FILES}}` |
+| Files to create | `{{PHASE_1_CREATE_FILES}}` |
+| Dependencies | `{{PHASE_1_DEPENDENCIES}}` |
+| Pattern to follow | See inline snippet below |
+
+**Pattern (copy from codebase, do not paraphrase):**
+
+```typescript
+{{PHASE_1_PATTERN_SNIPPET}}
+```
+
+### Scenario 1.1: {{SCENARIO_1_1_NAME}}
+
+**REQ**: {{REQ_ID}}
+
+**Given**: {{GIVEN_CONDITION}}
+→ Setup:
+```typescript
+{{SETUP_CODE}}
+```
+
+**When**: {{ACTION}}
+→ Implement in `{{TARGET_FILE}}`, after line containing `{{ANCHOR_TEXT}}`:
+```typescript
+{{IMPLEMENTATION_SNIPPET}}
+```
+Imports needed: `{{IMPORTS_LIST}}`
+
+**Then**: {{EXPECTED_RESULT}}
+→ Verify:
+```bash
+{{VERIFY_COMMAND}}
+```
+Expected output: `{{EXPECTED_OUTPUT}}`
+Fallback if fails: {{FALLBACK_INSTRUCTION}}
+
+---
+
+### Scenario 1.2: {{SCENARIO_1_2_NAME}}
+
+**Given**: {{GIVEN_CONDITION}}
+→ Setup: {{SETUP_INSTRUCTION}}
+
+**When**: {{ACTION}}
+→ Implement: {{IMPLEMENTATION_INSTRUCTION}}
+
+**Then**: {{EXPECTED_RESULT}}
+→ Verify: `{{VERIFY_COMMAND}}`
+
+---
+
+### Phase 1 Gate
+
+- [ ] `npm run build` — no type errors
+- [ ] `npx vitest run {{PHASE_1_TEST_FILES}}` — all pass
+- [ ] `npx tsc --noEmit` — clean
+
+---
+
+## Phase 2: {{PHASE_2_NAME}}
+
+### Environment
+
+| Item | Detail |
+|------|--------|
+| Files to modify | `{{PHASE_2_MODIFY_FILES}}` |
+| Files to create | `{{PHASE_2_CREATE_FILES}}` |
+| Dependencies | `{{PHASE_2_DEPENDENCIES}}` |
+
+### Scenario 2.1: {{SCENARIO_2_1_NAME}}
+
+**Given**: {{GIVEN_CONDITION}}
+→ Setup: {{SETUP_INSTRUCTION}}
+
+**When**: {{ACTION}}
+→ Implement: {{IMPLEMENTATION_INSTRUCTION}}
+
+**Then**: {{EXPECTED_RESULT}}
+→ Verify: `{{VERIFY_COMMAND}}`
+
+---
+
+### Phase 2 Gate
+
+- [ ] `npm run build`
+- [ ] `npx vitest run {{PHASE_2_TEST_FILES}}`
+- [ ] `npx tsc --noEmit`
+
+---
+
+## Completion Criteria
+
+- [ ] All scenarios passing
+- [ ] Coverage: ≥ {{COVERAGE_THRESHOLD}}%
+- [ ] No regressions in existing tests
+- [ ] `npm run build` exits 0
+- [ ] RTM generated: `generateTraceabilityMatrix("{{FEATURE_NAME}}")`
+
+---
+
+## Handoff (if incomplete)
+
+Save state before ending session:
+
+```
+save_memory("execplan-{{FEATURE_NAME}}", {
+  "last_completed": "Phase X, Scenario Y.Z",
+  "next_step": "{{NEXT_STEP_DESCRIPTION}}",
+  "blockers": "{{BLOCKERS_IF_ANY}}"
+})
+```
+
+Resume: `/vibe.utils --continue` → load this file.

package/skills/git-worktree/rubrics/when-to-use.md

@@ -0,0 +1,55 @@
+# Git Worktree: When to Use Decision Guide
+
+## Decision Tree
+
+```
+Need to work on a different branch?
+    │
+    ├─ How long? < 5 minutes
+    │       └─ Use git stash + switch
+    │
+    ├─ Will you need to run tests/build?
+    │       └─ No → git stash is fine
+    │           Yes → Consider worktree
+    │
+    └─ Can you commit current work?
+            └─ Yes → commit + switch (simplest)
+                No → worktree or stash
+```
+
+## Use Worktree When
+
+| Scenario | Reason |
+|----------|--------|
+| Reviewing a PR that needs running | Avoids dirty working tree; test in isolation |
+| Critical hotfix while mid-feature | Keep feature branch untouched |
+| A/B testing two implementations | Both runnable simultaneously |
+| Long-running parallel experiment | Work on both without context switching |
+
+## Skip Worktree When
+
+| Scenario | Better Alternative |
+|----------|--------------------|
+| Quick config change on another branch | `git stash && git switch` |
+| Just reading code on another branch | `git show branch:file` |
+| Already committed current work | `git switch` directly |
+| Change touches same files | Merging will conflict regardless |
+| Repo uses large node_modules | Each worktree needs separate install — expensive |
+
+## Cost/Benefit
+
+| Factor | Worktree Cost |
+|--------|--------------|
+| Disk space | Full working copy per worktree |
+| `npm install` / `pnpm install` | Required in each worktree |
+| Mental overhead | Tracking multiple worktree paths |
+| Cleanup discipline | Must `git worktree remove` when done |
+
+**Rule of thumb**: If the task is under 15 minutes, `git stash` is almost always faster than setting up a worktree.
+
+## Gotchas
+
+- A branch can only be checked out in **one** worktree at a time
+- Worktrees share `.git` — commits in any worktree are immediately visible in all
+- Forgetting to remove worktrees leaves stale locks — run `git worktree prune` periodically
+- CI/CD hooks may not run correctly outside the main worktree path

package/skills/handoff/agents/context-summarizer.md

@@ -0,0 +1,51 @@
+---
+name: context-summarizer
+role: Summarizes decisions made during the session and their rationale
+tools: [Read, Bash]
+---
+
+# Context Summarizer
+
+## Role
+Distills the session's reasoning into a compact decision log. Captures the "why" behind architectural and implementation choices so the next session (or developer) doesn't re-litigate resolved questions.
+
+## Responsibilities
+- Review recent conversation context for key decisions and trade-offs
+- Summarize rejected alternatives and the reason they were rejected
+- Identify blockers that were encountered and how they were resolved
+- Note any assumptions made that should be validated later
+- Flag unresolved debates or open questions for the next session
+
+## Input
+- State snapshot from state-collector
+- Session conversation context (decisions, debates, trade-offs discussed)
+
+## Output
+Decision log section for HANDOFF.md:
+
+```markdown
+## Decisions & Rationale
+
+### Decided: JWT over sessions
+Chose stateless JWT for auth because the API must support mobile clients.
+Rejected: server-side sessions — would require sticky sessions in Kubernetes.
+
+### Decided: Skip refresh token for now
+Deferred refresh token implementation — out of scope for this sprint.
+Risk: tokens expire after 1h, users must re-login.
+
+### Open Questions
+- Should we store token revocation list in Redis or Postgres?
+- Confirm with team: is 1h token TTL acceptable for mobile?
+
+### Assumptions Made
+- Mobile client handles 401 → re-login flow gracefully
+- Redis will be available in production (not confirmed)
+```
+
+## Communication
+- Reports findings to: document-writer
+- Receives instructions from: orchestrator (handoff skill)
+
+## Domain Knowledge
+Decisions without rationale are useless. Every decision entry must include: what was decided, why, and what was rejected with reason. Keep each entry under 3 lines.