@su-record/vibe 2.9.18 → 2.9.20

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

@@ -1,55 +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
+# 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/SKILL.md

@@ -1,110 +1,110 @@
----
-name: handoff
-tier: standard
-description: "Generate HANDOFF.md work handover document before session end. Auto-activates on handoff, handover, session cleanup keywords."
-triggers: [handoff, handover, session cleanup, session end, context save]
-priority: 70
----
-
-# Handoff — Session Handover Document
-
-Record work status before session end so the next session can pick up immediately.
-
-## What is HANDOFF.md?
-
-A file that records the current work status before context reset. Reading this file in a new session allows immediate continuation.
-
-### Difference from `/vibe.utils --continue`
-
-| Item | `/vibe.utils --continue` | Handoff |
-|------|--------------------------|---------|
-| Method | Automatic session context restore | Manual handover document |
-| Includes | Memory + session state | Work progress + notes + file list |
-| When to use | At new session start | Before session end |
-| Purpose | Quick auto-restore | Detailed handover (team/future self) |
-
-## When to Use
-
-- When context reaches 80-100k tokens
-- After using `/compact` 3 times
-- Before pausing work for an extended period
-- When progress recording is needed during complex work
-
-## VIBE Tool Integration
-
-Use VIBE built-in tools to save current state before generating Handoff:
-
-```bash
-# Save current session context
-core_auto_save_context
-
-# Save important decisions to memory
-core_save_memory --key "handoff-decision" --value "Decided on JWT for auth" --category "project"
-
-# Verify saved memories
-core_list_memories --category "project"
-```
-
-## HANDOFF.md Template
-
-```markdown
-# Work Handover Document
-
-## Completed Tasks
-- [x] Completed task 1
-- [x] Completed task 2
-
-## In Progress
-- [ ] Currently working on
-  - Progress: 70%
-  - Next step: implement ~~
-
-## Next Tasks
-1. High priority task
-2. Next task
-
-## Notes & Cautions
-- Do not touch: ~~
-- Known bugs: ~~
-- Temporary workarounds: ~~
-
-## Related Files
-- src/components/Login.tsx — Login form
-- src/api/auth.ts — Auth API
-
-## Last State
-- Branch: feature/auth
-- Last commit: abc1234
-- Test status: passing
-```
-
-## Generation Steps
-
-1. Check current changed files with `git status`
-2. Check recent commits with `git log --oneline -5`
-3. Organize in-progress and remaining tasks
-4. Save session context with `core_auto_save_context`
-5. Save key decisions with `core_save_memory`
-6. Generate HANDOFF.md file
-
-## Restoring in New Session
-
-```
-Read HANDOFF.md and continue working
-```
-
-Or use alongside VIBE auto-restore:
-
-```
-/vibe.utils --continue
-```
-
-In this case, saved decisions are also restored via `core_recall_memory`.
-
-## Done Criteria (K4)
-
-- [ ] HANDOFF.md created with all sections filled
-- [ ] Completed/in-progress/next tasks accurately listed
-- [ ] Related files section includes all modified files
-- [ ] Session context saved via `core_auto_save_context`
-- [ ] Key decisions saved via `core_save_memory`
+---
+name: handoff
+tier: standard
+description: "Generate HANDOFF.md work handover document before session end. Auto-activates on handoff, handover, session cleanup keywords."
+triggers: [handoff, handover, session cleanup, session end, context save]
+priority: 70
+---
+
+# Handoff — Session Handover Document
+
+Record work status before session end so the next session can pick up immediately.
+
+## What is HANDOFF.md?
+
+A file that records the current work status before context reset. Reading this file in a new session allows immediate continuation.
+
+### Difference from `/vibe.utils --continue`
+
+| Item | `/vibe.utils --continue` | Handoff |
+|------|--------------------------|---------|
+| Method | Automatic session context restore | Manual handover document |
+| Includes | Memory + session state | Work progress + notes + file list |
+| When to use | At new session start | Before session end |
+| Purpose | Quick auto-restore | Detailed handover (team/future self) |
+
+## When to Use
+
+- When context reaches 80-100k tokens
+- After using `/compact` 3 times
+- Before pausing work for an extended period
+- When progress recording is needed during complex work
+
+## VIBE Tool Integration
+
+Use VIBE built-in tools to save current state before generating Handoff:
+
+```bash
+# Save current session context
+core_auto_save_context
+
+# Save important decisions to memory
+core_save_memory --key "handoff-decision" --value "Decided on JWT for auth" --category "project"
+
+# Verify saved memories
+core_list_memories --category "project"
+```
+
+## HANDOFF.md Template
+
+```markdown
+# Work Handover Document
+
+## Completed Tasks
+- [x] Completed task 1
+- [x] Completed task 2
+
+## In Progress
+- [ ] Currently working on
+  - Progress: 70%
+  - Next step: implement ~~
+
+## Next Tasks
+1. High priority task
+2. Next task
+
+## Notes & Cautions
+- Do not touch: ~~
+- Known bugs: ~~
+- Temporary workarounds: ~~
+
+## Related Files
+- src/components/Login.tsx — Login form
+- src/api/auth.ts — Auth API
+
+## Last State
+- Branch: feature/auth
+- Last commit: abc1234
+- Test status: passing
+```
+
+## Generation Steps
+
+1. Check current changed files with `git status`
+2. Check recent commits with `git log --oneline -5`
+3. Organize in-progress and remaining tasks
+4. Save session context with `core_auto_save_context`
+5. Save key decisions with `core_save_memory`
+6. Generate HANDOFF.md file
+
+## Restoring in New Session
+
+```
+Read HANDOFF.md and continue working
+```
+
+Or use alongside VIBE auto-restore:
+
+```
+/vibe.utils --continue
+```
+
+In this case, saved decisions are also restored via `core_recall_memory`.
+
+## Done Criteria (K4)
+
+- [ ] HANDOFF.md created with all sections filled
+- [ ] Completed/in-progress/next tasks accurately listed
+- [ ] Related files section includes all modified files
+- [ ] Session context saved via `core_auto_save_context`
+- [ ] Key decisions saved via `core_save_memory`

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

@@ -1,51 +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.
+---
+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.

package/skills/handoff/agents/document-writer.md

@@ -1,63 +1,63 @@
----
-name: document-writer
-role: Writes HANDOFF.md from collected state data and session summary
-tools: [Write, Read, Bash]
----
-
-# Document Writer
-
-## Role
-Assembles the final HANDOFF.md by combining the state snapshot and decision log into a structured document that enables the next session to continue without any ramp-up time.
-
-## Responsibilities
-- Merge state-collector data and context-summarizer output into one document
-- Write completed tasks, in-progress tasks (with % and next step), and next tasks
-- Include notes on known bugs, workarounds, and files to avoid
-- List all relevant modified files with a one-line description of each
-- Save the document to the project root as `HANDOFF.md`
-
-## Input
-- State snapshot from state-collector
-- Decision log from context-summarizer
-- Any explicit notes provided by the user
-
-## Output
-`HANDOFF.md` written to project root:
-
-```markdown
-# Work Handover Document
-
-## Completed Tasks
-- [x] JWT auth middleware implemented and tested
-
-## In Progress
-- [ ] Refresh token flow — 40% complete
-  - Next step: implement POST /auth/refresh endpoint
-
-## Next Tasks
-1. Add rate limiting to /auth/login
-2. Write integration tests for token expiry edge cases
-
-## Decisions & Rationale
-{from context-summarizer}
-
-## Notes & Cautions
-- Do not touch src/legacy-auth.ts — will be removed next sprint
-- Known bug: FIXME in src/middleware.ts:18
-
-## Related Files
-- src/auth.ts — JWT validation logic
-- src/types.ts — AuthToken and User types
-
-## Last State
-- Branch: feature/auth-refactor
-- Last commit: abc1234
-- Test status: PASSING (24/24)
-```
-
-## Communication
-- Reports findings to: verifier
-- Receives instructions from: orchestrator (handoff skill)
-
-## Domain Knowledge
-Write for a developer with zero session context. The next person reading this has no memory of what happened. Every section must be self-contained.
+---
+name: document-writer
+role: Writes HANDOFF.md from collected state data and session summary
+tools: [Write, Read, Bash]
+---
+
+# Document Writer
+
+## Role
+Assembles the final HANDOFF.md by combining the state snapshot and decision log into a structured document that enables the next session to continue without any ramp-up time.
+
+## Responsibilities
+- Merge state-collector data and context-summarizer output into one document
+- Write completed tasks, in-progress tasks (with % and next step), and next tasks
+- Include notes on known bugs, workarounds, and files to avoid
+- List all relevant modified files with a one-line description of each
+- Save the document to the project root as `HANDOFF.md`
+
+## Input
+- State snapshot from state-collector
+- Decision log from context-summarizer
+- Any explicit notes provided by the user
+
+## Output
+`HANDOFF.md` written to project root:
+
+```markdown
+# Work Handover Document
+
+## Completed Tasks
+- [x] JWT auth middleware implemented and tested
+
+## In Progress
+- [ ] Refresh token flow — 40% complete
+  - Next step: implement POST /auth/refresh endpoint
+
+## Next Tasks
+1. Add rate limiting to /auth/login
+2. Write integration tests for token expiry edge cases
+
+## Decisions & Rationale
+{from context-summarizer}
+
+## Notes & Cautions
+- Do not touch src/legacy-auth.ts — will be removed next sprint
+- Known bug: FIXME in src/middleware.ts:18
+
+## Related Files
+- src/auth.ts — JWT validation logic
+- src/types.ts — AuthToken and User types
+
+## Last State
+- Branch: feature/auth-refactor
+- Last commit: abc1234
+- Test status: PASSING (24/24)
+```
+
+## Communication
+- Reports findings to: verifier
+- Receives instructions from: orchestrator (handoff skill)
+
+## Domain Knowledge
+Write for a developer with zero session context. The next person reading this has no memory of what happened. Every section must be self-contained.

package/skills/handoff/agents/state-collector.md

@@ -1,53 +1,53 @@
----
-name: state-collector
-role: Gathers current branch, commits, test status, and open TODOs for handoff
-tools: [Bash, Glob, Grep, Read]
----
-
-# State Collector
-
-## Role
-Takes a snapshot of the current repository state so the handoff document reflects reality. Collects factual, objective data — not interpretation. Feeds raw data to context-summarizer and document-writer.
-
-## Responsibilities
-- Run `git status`, `git branch`, and `git log --oneline -10` to capture branch and commit state
-- Run the test suite (or last known test run) to record pass/fail counts
-- Scan for open TODO/FIXME/HACK comments in recently changed files
-- List all files modified since the last commit
-- Check for any stashed changes or untracked files
-
-## Input
-- Project root path
-- Optional: test command override (defaults to `npm test` or `npx vitest run`)
-
-## Output
-Raw state data bundle:
-
-```markdown
-## State Snapshot
-
-### Git State
-- Branch: feature/auth-refactor
-- Last commit: abc1234 "Add JWT validation"
-- Uncommitted changes: 3 files (src/auth.ts, src/types.ts, tests/auth.test.ts)
-- Stashed: none
-
-### Test Status
-- Last run: PASSING (24 passed, 0 failed)
-- Coverage: 87%
-
-### Open TODOs
-- src/auth.ts:42 — TODO: handle refresh token expiry
-- src/middleware.ts:18 — FIXME: rate limiter not applied to /health
-
-### Modified Files (since last commit)
-- src/auth.ts
-- src/types.ts
-```
-
-## Communication
-- Reports findings to: document-writer, context-summarizer
-- Receives instructions from: orchestrator (handoff skill)
-
-## Domain Knowledge
-Collect facts, not interpretation. If a test run hasn't happened, state that explicitly. If git state is dirty, list every uncommitted file.
+---
+name: state-collector
+role: Gathers current branch, commits, test status, and open TODOs for handoff
+tools: [Bash, Glob, Grep, Read]
+---
+
+# State Collector
+
+## Role
+Takes a snapshot of the current repository state so the handoff document reflects reality. Collects factual, objective data — not interpretation. Feeds raw data to context-summarizer and document-writer.
+
+## Responsibilities
+- Run `git status`, `git branch`, and `git log --oneline -10` to capture branch and commit state
+- Run the test suite (or last known test run) to record pass/fail counts
+- Scan for open TODO/FIXME/HACK comments in recently changed files
+- List all files modified since the last commit
+- Check for any stashed changes or untracked files
+
+## Input
+- Project root path
+- Optional: test command override (defaults to `npm test` or `npx vitest run`)
+
+## Output
+Raw state data bundle:
+
+```markdown
+## State Snapshot
+
+### Git State
+- Branch: feature/auth-refactor
+- Last commit: abc1234 "Add JWT validation"
+- Uncommitted changes: 3 files (src/auth.ts, src/types.ts, tests/auth.test.ts)
+- Stashed: none
+
+### Test Status
+- Last run: PASSING (24 passed, 0 failed)
+- Coverage: 87%
+
+### Open TODOs
+- src/auth.ts:42 — TODO: handle refresh token expiry
+- src/middleware.ts:18 — FIXME: rate limiter not applied to /health
+
+### Modified Files (since last commit)
+- src/auth.ts
+- src/types.ts
+```
+
+## Communication
+- Reports findings to: document-writer, context-summarizer
+- Receives instructions from: orchestrator (handoff skill)
+
+## Domain Knowledge
+Collect facts, not interpretation. If a test run hasn't happened, state that explicitly. If git state is dirty, list every uncommitted file.