@su-record/vibe 2.9.18 → 2.9.20

package/skills/handoff/agents/verifier.md

@@ -1,48 +1,48 @@
----
-name: verifier
-role: Checks handoff completeness against the HANDOFF.md rubric
-tools: [Read, Bash]
----
-
-# Verifier
-
-## Role
-Reviews the generated HANDOFF.md against a completeness rubric before the session ends. Flags any missing or vague sections and either requests fixes from document-writer or escalates to the user.
-
-## Responsibilities
-- Check all required sections are present and non-empty
-- Verify "In Progress" items each have a % complete and "Next step"
-- Confirm the git branch, last commit hash, and test status are recorded
-- Ensure "Related Files" lists every file from the state snapshot
-- Validate that open questions are explicitly marked, not buried in prose
-
-## Input
-- HANDOFF.md written by document-writer
-- State snapshot from state-collector (ground truth for cross-checking)
-
-## Output
-Verification report:
-
-```markdown
-## Handoff Verification
-
-### Rubric Check
-- [x] Completed tasks listed
-- [x] In-progress tasks have % and next step
-- [x] Next tasks prioritized
-- [ ] MISSING: Open questions section not found
-- [x] Related files match modified files
-- [x] Branch and commit recorded
-- [x] Test status recorded
-
-### Verdict
-INCOMPLETE — 1 item must be fixed before session ends.
-Fix: add ## Open Questions section with 2 unresolved items from context-summarizer.
-```
-
-## Communication
-- Reports findings to: orchestrator (handoff skill) / user
-- Receives instructions from: orchestrator
-
-## Domain Knowledge
-Rubric thresholds: 0 blockers = COMPLETE. Any missing required section = INCOMPLETE. Optional sections (Assumptions, Decisions) are best-effort. A HANDOFF.md that scores INCOMPLETE must be revised before the session closes.
+---
+name: verifier
+role: Checks handoff completeness against the HANDOFF.md rubric
+tools: [Read, Bash]
+---
+
+# Verifier
+
+## Role
+Reviews the generated HANDOFF.md against a completeness rubric before the session ends. Flags any missing or vague sections and either requests fixes from document-writer or escalates to the user.
+
+## Responsibilities
+- Check all required sections are present and non-empty
+- Verify "In Progress" items each have a % complete and "Next step"
+- Confirm the git branch, last commit hash, and test status are recorded
+- Ensure "Related Files" lists every file from the state snapshot
+- Validate that open questions are explicitly marked, not buried in prose
+
+## Input
+- HANDOFF.md written by document-writer
+- State snapshot from state-collector (ground truth for cross-checking)
+
+## Output
+Verification report:
+
+```markdown
+## Handoff Verification
+
+### Rubric Check
+- [x] Completed tasks listed
+- [x] In-progress tasks have % and next step
+- [x] Next tasks prioritized
+- [ ] MISSING: Open questions section not found
+- [x] Related files match modified files
+- [x] Branch and commit recorded
+- [x] Test status recorded
+
+### Verdict
+INCOMPLETE — 1 item must be fixed before session ends.
+Fix: add ## Open Questions section with 2 unresolved items from context-summarizer.
+```
+
+## Communication
+- Reports findings to: orchestrator (handoff skill) / user
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+Rubric thresholds: 0 blockers = COMPLETE. Any missing required section = INCOMPLETE. Optional sections (Assumptions, Decisions) are best-effort. A HANDOFF.md that scores INCOMPLETE must be revised before the session closes.

package/skills/handoff/rubrics/completeness.md

@@ -1,62 +1,62 @@
-# Handoff Completeness Rubric
-
-A HANDOFF.md is complete only when all required items are present and accurate.
-
-## Required Sections (all must be filled)
-
-### Status Block
-- [ ] Build status is current (run `npm run build` immediately before writing)
-- [ ] Test status is current (run `npx vitest run` immediately before writing)
-- [ ] Branch name matches `git branch --show-current`
-- [ ] Last commit hash is correct (`git log --oneline -1`)
-
-### Completed Work
-- [ ] At least one item listed (even if just "initial exploration")
-- [ ] Each item is specific enough to be verifiable
-- [ ] No vague entries like "worked on auth"
-
-### In Progress
-- [ ] The single task currently active is identified
-- [ ] The exact next step is described (not "continue working on X")
-- [ ] Any blocking question is explicitly stated or marked "none"
-- [ ] At least one "where to look first" file is listed
-
-### Remaining Tasks
-- [ ] All known remaining tasks are listed
-- [ ] Each task has a P1/P2/P3 priority label
-- [ ] Tasks are ordered by priority
-
-### Decisions Made
-- [ ] Any architectural or design decisions from this session are recorded
-- [ ] Rationale is included (not just "we decided X")
-- [ ] Rejected alternatives noted where non-obvious
-
-### Modified Files
-- [ ] `git status` output or equivalent is included
-- [ ] Every modified file is present (no omissions)
-
-### Resume Instructions
-- [ ] The exact command to restore context is present
-- [ ] The exact point to resume from is described
-
-## Optional but Strongly Recommended
-
-- Known issues / workarounds (if any discovered this session)
-- "Do not touch" warnings (if any fragile areas identified)
-- Memory keys saved via `core_save_memory`
-
-## Quality Bar
-
-| Criterion | Pass |
-|-----------|------|
-| A new session can start without asking any clarifying questions | Required |
-| The next developer can find the relevant files within 60 seconds | Required |
-| Build/test status reflects reality at time of handoff | Required |
-| Handoff written within 5 minutes of session end | Recommended |
-
-## Failure Modes to Avoid
-
-- Writing completed tasks from memory instead of `git log` — use actual git output
-- Listing "in progress" without a concrete next step — be specific
-- Omitting the current branch — always include
-- Skipping the status block — it expires; run commands fresh
+# Handoff Completeness Rubric
+
+A HANDOFF.md is complete only when all required items are present and accurate.
+
+## Required Sections (all must be filled)
+
+### Status Block
+- [ ] Build status is current (run `npm run build` immediately before writing)
+- [ ] Test status is current (run `npx vitest run` immediately before writing)
+- [ ] Branch name matches `git branch --show-current`
+- [ ] Last commit hash is correct (`git log --oneline -1`)
+
+### Completed Work
+- [ ] At least one item listed (even if just "initial exploration")
+- [ ] Each item is specific enough to be verifiable
+- [ ] No vague entries like "worked on auth"
+
+### In Progress
+- [ ] The single task currently active is identified
+- [ ] The exact next step is described (not "continue working on X")
+- [ ] Any blocking question is explicitly stated or marked "none"
+- [ ] At least one "where to look first" file is listed
+
+### Remaining Tasks
+- [ ] All known remaining tasks are listed
+- [ ] Each task has a P1/P2/P3 priority label
+- [ ] Tasks are ordered by priority
+
+### Decisions Made
+- [ ] Any architectural or design decisions from this session are recorded
+- [ ] Rationale is included (not just "we decided X")
+- [ ] Rejected alternatives noted where non-obvious
+
+### Modified Files
+- [ ] `git status` output or equivalent is included
+- [ ] Every modified file is present (no omissions)
+
+### Resume Instructions
+- [ ] The exact command to restore context is present
+- [ ] The exact point to resume from is described
+
+## Optional but Strongly Recommended
+
+- Known issues / workarounds (if any discovered this session)
+- "Do not touch" warnings (if any fragile areas identified)
+- Memory keys saved via `core_save_memory`
+
+## Quality Bar
+
+| Criterion | Pass |
+|-----------|------|
+| A new session can start without asking any clarifying questions | Required |
+| The next developer can find the relevant files within 60 seconds | Required |
+| Build/test status reflects reality at time of handoff | Required |
+| Handoff written within 5 minutes of session end | Recommended |
+
+## Failure Modes to Avoid
+
+- Writing completed tasks from memory instead of `git log` — use actual git output
+- Listing "in progress" without a concrete next step — be specific
+- Omitting the current branch — always include
+- Skipping the status block — it expires; run commands fresh

package/skills/handoff/templates/handoff.md

@@ -1,107 +1,107 @@
-# Work Handover: {{FEATURE_OR_TASK_NAME}}
-
-**Date**: {{DATE}}
-**Branch**: {{GIT_BRANCH}}
-**Author**: {{AUTHOR}}
-**Session context**: {{CONTEXT_PERCENT}}% used
-
----
-
-## Status at Handoff
-
-| Area | Status | Notes |
-|------|--------|-------|
-| Build | {{BUILD_STATUS}} | `npm run build` |
-| Tests | {{TEST_STATUS}} | `npx vitest run` |
-| Type check | {{TYPECHECK_STATUS}} | `npx tsc --noEmit` |
-| Lint | {{LINT_STATUS}} | |
-
----
-
-## Completed Work
-
-- [x] {{COMPLETED_TASK_1}}
-- [x] {{COMPLETED_TASK_2}}
-- [x] {{COMPLETED_TASK_3}}
-
-Last commit: `{{LAST_COMMIT_HASH}}` — {{LAST_COMMIT_MESSAGE}}
-
----
-
-## In Progress (resume here)
-
-### {{IN_PROGRESS_TASK_NAME}}
-
-- Progress: {{PROGRESS_PERCENT}}%
-- Current state: {{CURRENT_STATE_DESCRIPTION}}
-- Next immediate step: {{NEXT_STEP}}
-- Blocking question (if any): {{BLOCKER_OR_NONE}}
-
-**Where to look first:**
-- `{{KEY_FILE_1}}` — {{KEY_FILE_1_CONTEXT}}
-- `{{KEY_FILE_2}}` — {{KEY_FILE_2_CONTEXT}}
-
----
-
-## Remaining Tasks (in priority order)
-
-1. **[P1]** {{P1_TASK}} — must complete before merge
-2. **[P2]** {{P2_TASK}} — complete before PR review
-3. **[P3]** {{P3_TASK}} — nice-to-have
-
----
-
-## Decisions Made This Session
-
-| Decision | Rationale | Alternatives Rejected |
-|----------|-----------|----------------------|
-| {{DECISION_1}} | {{RATIONALE_1}} | {{ALTERNATIVES_1}} |
-| {{DECISION_2}} | {{RATIONALE_2}} | {{ALTERNATIVES_2}} |
-
----
-
-## Do Not Touch
-
-- `{{FRAGILE_FILE_1}}` — {{REASON_1}}
-- `{{FRAGILE_FILE_2}}` — {{REASON_2}}
-
----
-
-## Known Issues / Workarounds
-
-- {{KNOWN_ISSUE_1}}
-- {{KNOWN_ISSUE_2}}
-
----
-
-## All Modified Files
-
-```
-{{GIT_STATUS_OUTPUT}}
-```
-
----
-
-## How to Resume
-
-```bash
-# 1. Load context
-/vibe.utils --continue
-
-# 2. Read this file if context is missing
-# cat HANDOFF.md
-
-# 3. Verify baseline
-npm run build && npx vitest run
-
-# 4. Pick up from: {{RESUME_INSTRUCTION}}
-```
-
----
-
-## Session Memory Keys
-
-The following keys were saved with `core_save_memory`:
-
-- `{{MEMORY_KEY_1}}` — {{MEMORY_KEY_1_DESCRIPTION}}
-- `{{MEMORY_KEY_2}}` — {{MEMORY_KEY_2_DESCRIPTION}}
+# Work Handover: {{FEATURE_OR_TASK_NAME}}
+
+**Date**: {{DATE}}
+**Branch**: {{GIT_BRANCH}}
+**Author**: {{AUTHOR}}
+**Session context**: {{CONTEXT_PERCENT}}% used
+
+---
+
+## Status at Handoff
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Build | {{BUILD_STATUS}} | `npm run build` |
+| Tests | {{TEST_STATUS}} | `npx vitest run` |
+| Type check | {{TYPECHECK_STATUS}} | `npx tsc --noEmit` |
+| Lint | {{LINT_STATUS}} | |
+
+---
+
+## Completed Work
+
+- [x] {{COMPLETED_TASK_1}}
+- [x] {{COMPLETED_TASK_2}}
+- [x] {{COMPLETED_TASK_3}}
+
+Last commit: `{{LAST_COMMIT_HASH}}` — {{LAST_COMMIT_MESSAGE}}
+
+---
+
+## In Progress (resume here)
+
+### {{IN_PROGRESS_TASK_NAME}}
+
+- Progress: {{PROGRESS_PERCENT}}%
+- Current state: {{CURRENT_STATE_DESCRIPTION}}
+- Next immediate step: {{NEXT_STEP}}
+- Blocking question (if any): {{BLOCKER_OR_NONE}}
+
+**Where to look first:**
+- `{{KEY_FILE_1}}` — {{KEY_FILE_1_CONTEXT}}
+- `{{KEY_FILE_2}}` — {{KEY_FILE_2_CONTEXT}}
+
+---
+
+## Remaining Tasks (in priority order)
+
+1. **[P1]** {{P1_TASK}} — must complete before merge
+2. **[P2]** {{P2_TASK}} — complete before PR review
+3. **[P3]** {{P3_TASK}} — nice-to-have
+
+---
+
+## Decisions Made This Session
+
+| Decision | Rationale | Alternatives Rejected |
+|----------|-----------|----------------------|
+| {{DECISION_1}} | {{RATIONALE_1}} | {{ALTERNATIVES_1}} |
+| {{DECISION_2}} | {{RATIONALE_2}} | {{ALTERNATIVES_2}} |
+
+---
+
+## Do Not Touch
+
+- `{{FRAGILE_FILE_1}}` — {{REASON_1}}
+- `{{FRAGILE_FILE_2}}` — {{REASON_2}}
+
+---
+
+## Known Issues / Workarounds
+
+- {{KNOWN_ISSUE_1}}
+- {{KNOWN_ISSUE_2}}
+
+---
+
+## All Modified Files
+
+```
+{{GIT_STATUS_OUTPUT}}
+```
+
+---
+
+## How to Resume
+
+```bash
+# 1. Load context
+/vibe.utils --continue
+
+# 2. Read this file if context is missing
+# cat HANDOFF.md
+
+# 3. Verify baseline
+npm run build && npx vitest run
+
+# 4. Pick up from: {{RESUME_INSTRUCTION}}
+```
+
+---
+
+## Session Memory Keys
+
+The following keys were saved with `core_save_memory`:
+
+- `{{MEMORY_KEY_1}}` — {{MEMORY_KEY_1_DESCRIPTION}}
+- `{{MEMORY_KEY_2}}` — {{MEMORY_KEY_2_DESCRIPTION}}

package/skills/parallel-research/SKILL.md

@@ -1,89 +1,104 @@
----
-name: parallel-research
-tier: standard
-description: "Parallel research with 4 specialized agents (best-practices, framework-docs, codebase-patterns, security-advisory) running simultaneously. Use when facing unfamiliar technology, choosing between libraries/frameworks, designing architecture for a new feature, or investigating security implications. Must use this skill when user asks 'how should we build X', 'which library for Y', or when starting work on a complex feature with unknown requirements. Not for simple lookups — use web search directly for those."
-triggers: [parallel research, complex feature, technology selection, architecture design, security critical]
-priority: 60
-chain-next: [exec-plan]
----
-# Parallel Research
-
-Parallel research patterns for solving complex problems.
-
-## When Parallel Research is Needed
-
-| Situation | Reason |
-|-----------|--------|
-| New technology adoption | Need best practices |
-| Security-related features | Multi-angle review needed |
-| Architecture design | Multiple perspectives needed |
-| Technology selection | Comparison analysis needed |
-| Complex bugs | Explore multiple causes |
-
-## Research Agents (4 Parallel)
-
-| Agent | Role | Tools |
-|-------|------|-------|
-| best-practices | Search best practices | Web Search, context7 |
-| framework-docs | Search official docs | context7 |
-| codebase-patterns | Analyze existing code patterns | Grep, Glob |
-| security-advisory | Search security advisories | Web Search |
-
-## Usage Methods
-
-### Method 1: Direct Orchestrator Call
-
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/infra/orchestrator/index.js').then(o =>
-  o.research('passkey authentication', ['React', 'Supabase'])
-  .then(r => console.log(r.content[0].text))
-)"
-```
-
-### Method 2: Use /vibe.spec
-
-```
-/vibe.spec "feature-name"
-→ Parallel research runs automatically after requirements confirmed
-```
-
-### Method 3: Parallel Task Tool Execution
-
-```
-Task 1: "Search React auth best practices"
-Task 2: "Search Supabase Auth official docs" (concurrent)
-Task 3: "Analyze existing auth code patterns" (concurrent)
-Task 4: "Search auth security vulnerabilities" (concurrent)
-```
-
-## Using Research Results
-
-```
-Parallel research complete
-    ↓
-Synthesize results
-    ↓
-Reflect in SPEC Context section
-OR
-Reference during implementation
-```
-
-## When Research is NOT Needed
-
-- Simple CRUD operations
-- Already familiar patterns
-- Similar code exists in project
-- Time-critical (supplement with review later)
-
-## Notes
-
-- Research runs **after requirements confirmed**
-- Split overly broad topics
-- Research results are references, not absolute truth
-
-## Done Criteria (K4)
-
-- [ ] All 4 research agents returned results (or documented why not)
-- [ ] Results synthesized into actionable recommendations
-- [ ] Key findings reflected in SPEC Context section or implementation notes
-- [ ] Conflicting recommendations resolved with reasoning
+---
+name: parallel-research
+tier: standard
+description: "Parallel research with 4 specialized agents (best-practices, framework-docs, codebase-patterns, security-advisory) running simultaneously. Use when facing unfamiliar technology, choosing between libraries/frameworks, designing architecture for a new feature, or investigating security implications. Must use this skill when user asks 'how should we build X', 'which library for Y', or when starting work on a complex feature with unknown requirements. Not for simple lookups — use web search directly for those."
+triggers: [parallel research, complex feature, technology selection, architecture design, security critical]
+priority: 60
+chain-next: [exec-plan]
+---
+# Parallel Research
+
+Parallel research patterns for solving complex problems.
+
+## When Parallel Research is Needed
+
+| Situation | Reason |
+|-----------|--------|
+| New technology adoption | Need best practices |
+| Security-related features | Multi-angle review needed |
+| Architecture design | Multiple perspectives needed |
+| Technology selection | Comparison analysis needed |
+| Complex bugs | Explore multiple causes |
+
+## Research Agents (4 Parallel)
+
+| Agent | Role | Tools |
+|-------|------|-------|
+| best-practices | Search best practices | Web Search, context7 |
+| framework-docs | Search official docs | context7 |
+| codebase-patterns | Analyze existing code patterns | Grep, Glob |
+| security-advisory | Search security advisories | Web Search |
+
+## Usage Methods
+
+### Method 1: Direct Orchestrator Call
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/infra/orchestrator/index.js').then(o =>
+  o.research('passkey authentication', ['React', 'Supabase'])
+  .then(r => console.log(r.content[0].text))
+)"
+```
+
+### Method 2: Use /vibe.spec
+
+```
+/vibe.spec "feature-name"
+→ Parallel research runs automatically after requirements confirmed
+```
+
+### Method 3: Parallel Task Tool Execution
+
+```
+Task 1: "Search React auth best practices"
+Task 2: "Search Supabase Auth official docs" (concurrent)
+Task 3: "Analyze existing auth code patterns" (concurrent)
+Task 4: "Search auth security vulnerabilities" (concurrent)
+```
+
+## Using Research Results
+
+```
+Parallel research complete
+    ↓
+Synthesize results
+    ↓
+Persist to .claude/vibe/research/<topic-slug>/
+    ├── synthesis.md      (conversational report)
+    ├── awesome-list.md   (curated links/repos)
+    └── paper.md          (structured survey for /vibe.spec Context)
+    ↓
+Reflect in SPEC Context section
+OR
+Reference during implementation
+```
+
+### Output Location (SSOT)
+
+All research artifacts live under `.claude/vibe/research/<topic-slug>/`. Reference `paper.md` explicitly when writing a SPEC (e.g. paste its path into the Context section). Re-running research on the same topic overwrites unless the slug collides across dates (then `-YYYYMMDD` suffix).
+
+> Wire-up note: `/vibe.spec` does **not** yet auto-scan this directory — that integration is a follow-up. For now, cite the path manually.
+
+Pass `--ephemeral` to skip persistence when exploring throwaway questions.
+
+## When Research is NOT Needed
+
+- Simple CRUD operations
+- Already familiar patterns
+- Similar code exists in project
+- Time-critical (supplement with review later)
+
+## Notes
+
+- Research runs **after requirements confirmed**
+- Split overly broad topics
+- Research results are references, not absolute truth
+
+## Done Criteria (K4)
+
+- [ ] All 4 research agents returned results (or documented why not)
+- [ ] Results synthesized into actionable recommendations
+- [ ] Three artifacts written to `.claude/vibe/research/<slug>/` (synthesis / awesome-list / paper) — unless `--ephemeral`
+- [ ] Every awesome-list entry has a one-line "why"
+- [ ] Key findings reflected in SPEC Context section or implementation notes
+- [ ] Conflicting recommendations resolved with reasoning