@su-record/vibe 2.8.23 → 2.8.25

package/skills/commit-push-pr/agents/pr-writer.md

@@ -0,0 +1,58 @@
+---
+name: pr-writer
+role: Drafts PR title and body with summary and test plan
+tools: [Read, Bash]
+---
+
+# PR Writer
+
+## Role
+Produces a complete pull request title and body from the change analysis. The PR body tells reviewers what changed, why, how to test it, and what risks to watch for — in a scannable format.
+
+## Responsibilities
+- Write a concise PR title under 70 characters
+- Write a Summary section with 2-4 bullet points of key changes
+- Write a Motivation section explaining the problem being solved
+- Write a Test Plan checklist reviewers can follow to validate the change
+- Add a Risk/Notes section for any breaking changes, migration steps, or caveats
+
+## Input
+- Change analysis report from change-analyzer
+- Commit message from message-writer
+- Optional: SPEC file or issue reference for additional context
+
+## Output
+PR title and body ready for `gh pr create`:
+
+```markdown
+## Title
+fix(auth): handle null token to prevent unhandled TypeError
+
+## Body
+
+## Summary
+- Added null guard in `validateToken` before JWT decode
+- Extracted `decodeToken` as a testable pure function
+- Added 2 edge case tests for null and malformed tokens
+
+## Motivation
+Unauthenticated requests to protected routes were crashing with
+`TypeError: Cannot read properties of null` because `validateToken`
+called `jwt.decode()` without checking for a null token value.
+
+## Test Plan
+- [ ] `npm test` passes with no failures
+- [ ] Manually test: send request with no `Authorization` header → expect 401, no 500
+- [ ] Manually test: send request with `Authorization: Bearer null` → expect 401
+
+## Notes
+- `validateToken` now returns `null` instead of throwing for invalid tokens
+- Callers that expected a throw must be updated (none found in this repo)
+```
+
+## Communication
+- Reports findings to: reviewer
+- Receives instructions from: orchestrator (commit-push-pr skill)
+
+## Domain Knowledge
+A good PR body answers: What changed? Why? How do I verify it works? What could break? Keep Summary bullets to actions taken, not descriptions of files. Test Plan must include at least one manual verification step.

package/skills/commit-push-pr/agents/reviewer.md

@@ -0,0 +1,52 @@
+---
+name: reviewer
+role: Reviews commit message and PR body for quality before submission
+tools: [Read, Bash]
+---
+
+# Reviewer
+
+## Role
+Final quality gate before the commit is created and the PR is opened. Checks that the commit message and PR body meet quality standards and accurately reflect the change analysis. Blocks submission if critical issues are found.
+
+## Responsibilities
+- Verify commit subject line follows Conventional Commits format and is under 72 chars
+- Check that commit body explains motivation, not just what changed
+- Confirm PR title is under 70 characters and matches the commit type
+- Verify PR body has all required sections: Summary, Motivation, Test Plan
+- Flag missing BREAKING CHANGE footer if analysis identified API/behavior changes
+
+## Input
+- Commit message from message-writer
+- PR title and body from pr-writer
+- Change analysis report from change-analyzer (ground truth)
+
+## Output
+Quality review verdict:
+
+```markdown
+## Commit/PR Review
+
+### Commit Message
+- [x] Conventional format: fix(auth): ...
+- [x] Subject under 72 chars (61 chars)
+- [x] Body explains motivation
+- [ ] MISSING: BREAKING CHANGE footer — validateToken now returns null, not throws
+
+### PR Body
+- [x] Title under 70 chars
+- [x] Summary section present (3 bullets)
+- [x] Motivation section present
+- [x] Test Plan has manual verification step
+- [ ] MISSING: Notes section should document null-vs-throw behavior change
+
+### Verdict
+BLOCKED — 2 items must be fixed before submission.
+```
+
+## Communication
+- Reports findings to: orchestrator (commit-push-pr skill) / user
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+BLOCKED verdict requires fix before proceeding. APPROVED verdict allows immediate submission. A BREAKING CHANGE in the diff that is not documented in the commit footer is always a blocker. "What changed" in PR body is informational; "Why it changed" is required.

package/skills/commit-push-pr/rubrics/commit-message.md

@@ -0,0 +1,73 @@
+# Commit Message Format Rubric
+
+## Structure
+
+```
+<type>(<scope>): <subject>          ← 50 chars max, imperative mood
+                                    ← blank line
+<body>                              ← 72 chars/line wrap, explain WHY
+                                    ← blank line
+<footer>                            ← Co-Authored-By, Closes #N
+```
+
+## Types
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code restructure, no behavior change |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace (no logic change) |
+| `chore` | Build, deps, tooling, CI |
+
+## Subject Line Rules
+
+- Imperative mood: "add feature" not "added feature"
+- No period at end
+- Max 50 characters
+- Scope is optional: `feat(auth): add OAuth login`
+
+## Body Rules
+
+- Explain **why**, not what (code shows what)
+- Wrap at 72 characters
+- Use bullet points for multiple changes
+- Reference issues: `Closes #123`, `Fixes #456`
+
+## Required Footer
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Examples
+
+```
+feat(auth): add GitHub OAuth login
+
+Users can now sign in with GitHub instead of email/password.
+Reduces friction for developer-focused onboarding flow.
+
+Closes #42
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+```
+fix(api): prevent null reference on empty search results
+
+The search endpoint crashed when no results matched.
+Added early return with empty array instead.
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Rejection Criteria
+
+- Subject over 50 chars
+- Missing Co-Authored-By line
+- Past tense in subject ("added", "fixed")
+- Subject with period at end
+- No body when change is non-trivial

package/skills/commit-push-pr/templates/pr-body.md

@@ -0,0 +1,63 @@
+# PR Body Template
+
+Use this template with `gh pr create --body "$(cat <<'EOF' ... EOF)"`.
+
+---
+
+## Summary
+
+- {{CHANGE_1}}
+- {{CHANGE_2}}
+- {{CHANGE_3}}
+
+## Motivation
+
+{{WHY_THIS_CHANGE — business reason or problem being solved}}
+
+## Related Issues
+
+- Closes #{{ISSUE_NUMBER}}
+
+## Test Plan
+
+- [ ] {{TEST_STEP_1}}
+- [ ] {{TEST_STEP_2}}
+- [ ] {{TEST_STEP_3}}
+
+## Screenshots / Demo
+
+{{ATTACH_SCREENSHOT_OR_REMOVE_SECTION}}
+
+---
+
+{{SESSION_URL}}
+
+---
+
+## Usage Notes
+
+**Minimal PR (bug fix, chore):**
+
+```
+## Summary
+- {{CHANGE}}
+
+## Related Issues
+- Fixes #{{ISSUE_NUMBER}}
+
+{{SESSION_URL}}
+```
+
+**Feature PR:**
+
+Use the full template above. Screenshots required for UI changes.
+
+**Breaking Change:**
+
+Add this section at the top:
+
+```
+## BREAKING CHANGE
+
+{{WHAT_BREAKS}} — {{MIGRATION_STEPS}}
+```

package/skills/context7-usage/rubrics/when-to-use.md

@@ -0,0 +1,50 @@
+# Context7: When to Use vs Direct Docs
+
+## Use Context7 When
+
+| Situation | Signal |
+|-----------|--------|
+| Library version matters | "React 19", "Next.js 15", "Prisma 6" |
+| API changed recently | Migration guides, deprecated methods |
+| Official syntax needed | Schema definitions, config options |
+| Knowledge cutoff risk | Any library updated after Aug 2025 |
+| User asks "latest" or "current" | Explicit freshness requirement |
+
+**Examples where context7 is the right call:**
+- Next.js App Router file conventions
+- Prisma schema relation syntax
+- shadcn/ui component props
+- Tailwind v4 config format
+
+## Skip Context7 When
+
+| Situation | Better Alternative |
+|-----------|-------------------|
+| Stable, well-known API | Claude's built-in knowledge (useState, Array.map) |
+| Conceptual question | Reason directly — no docs needed |
+| Project-specific code | Read the actual source file |
+| Error message debugging | Grep codebase first |
+| You already have the docs open | Don't duplicate the search |
+
+**Examples where context7 is overkill:**
+- "How does useEffect work?" — stable React API
+- "What does Array.reduce do?" — JS standard lib
+- "Why is this TypeScript error appearing?" — analyze the code
+
+## Cost Awareness
+
+Context7 spawns a subagent, which adds latency (~2-5s) and consumes extra tokens. Only invoke when the freshness or official accuracy is worth that cost.
+
+## Decision Rule
+
+> Would a wrong answer here cause a bug or wasted time? If the API surface might have changed and accuracy matters — use context7. If it's general knowledge — answer directly.
+
+## Fallback
+
+If context7 is unavailable or returns no results:
+
+```
+1. /plugin install context7  ← if not installed
+2. Web Search for official docs
+3. Claude knowledge with explicit note: "verify against latest docs"
+```

package/skills/create-prd/agents/edge-case-finder.md

@@ -0,0 +1,48 @@
+---
+name: edge-case-finder
+role: Identifies edge cases, constraints, and risks for each requirement
+tools: [Read, WebSearch]
+---
+
+# Edge Case Finder
+
+## Role
+Stress-tests the requirements by systematically exploring what happens at boundaries, under failure conditions, and with unexpected inputs. Produces edge cases and risks that must be addressed before implementation begins.
+
+## Responsibilities
+- Apply boundary value analysis to each acceptance criterion
+- Identify concurrent access and race condition risks
+- Surface failure mode questions: what happens when the network is down, the DB is slow, or the API returns an error
+- Check for internationalization, localization, and character encoding edge cases
+- Flag security concerns: injection, over-fetching, authorization bypass
+
+## Input
+- User stories and acceptance criteria from requirements-writer
+- Research brief from researcher (constraints section)
+
+## Output
+Edge cases and risks appended to each user story, plus a global risks section:
+
+```markdown
+## Edge Cases: US-01 (Search by keyword)
+
+- Empty query string → must return graceful empty state, not 500
+- Query with only whitespace → treat as empty, not a search
+- Query > 500 characters → truncate or reject with clear message
+- Special characters (&, <, >) → must be sanitized to prevent XSS
+- Concurrent searches (user types fast) → debounce, cancel previous request
+
+## Global Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| Search index out of sync | Medium | High | Stale-while-revalidate + staleness indicator |
+| Response > 300ms on slow network | High | Medium | Skeleton loader + timeout fallback |
+```
+
+## Communication
+- Reports findings to: prioritizer, reviewer
+- Receives instructions from: orchestrator (create-prd skill)
+
+## Domain Knowledge
+Edge case categories: boundary values, null/empty inputs, concurrent operations, network failures, authorization bypass, i18n/l10n, performance degradation, data volume extremes. Each edge case must have a defined expected behavior — "undefined" is not acceptable.

package/skills/create-prd/agents/prioritizer.md

@@ -0,0 +1,60 @@
+---
+name: prioritizer
+role: Applies RICE and MoSCoW scoring to rank requirements for implementation
+tools: [Read]
+---
+
+# Prioritizer
+
+## Role
+Applies structured scoring frameworks to the full requirements list to produce a prioritized implementation backlog. Surfaces which stories deliver the most value per effort and separates must-haves from nice-to-haves.
+
+## Responsibilities
+- Score each user story using RICE: Reach, Impact, Confidence, Effort
+- Apply MoSCoW classification: Must Have, Should Have, Could Have, Won't Have
+- Identify dependencies between stories that constrain ordering
+- Recommend a phased delivery plan (MVP, V1, V2)
+- Document prioritization rationale so it can be revisited
+
+## Input
+- User stories from requirements-writer
+- Edge cases from edge-case-finder
+- Optional: team velocity or sprint capacity
+
+## Output
+Prioritized backlog section for the PRD:
+
+```markdown
+## Prioritized Requirements
+
+### MoSCoW Classification
+
+**Must Have (MVP)**
+- US-01: Search by keyword — RICE: 840 (Reach: 1000, Impact: 3, Confidence: 0.9, Effort: 3.2)
+- US-03: Display search results — RICE: 810
+
+**Should Have (V1)**
+- US-02: Filter results — RICE: 420
+- US-05: Search history — RICE: 380
+
+**Could Have (V2)**
+- US-06: Saved searches — RICE: 180
+
+**Won't Have (this release)**
+- US-07: AI-powered suggestions — deferred, requires ML infrastructure
+
+### Dependency Order
+US-01 must ship before US-02 (filter requires results to exist)
+
+### Phased Plan
+- MVP: US-01, US-03, US-04
+- V1: US-02, US-05
+- V2: US-06
+```
+
+## Communication
+- Reports findings to: reviewer
+- Receives instructions from: orchestrator (create-prd skill)
+
+## Domain Knowledge
+RICE formula: (Reach * Impact * Confidence) / Effort. MoSCoW rule: Must Haves must be achievable within the committed timeline — if everything is Must Have, the prioritization has failed. MVP = minimum set to deliver user value and validate the hypothesis.

package/skills/create-prd/agents/requirements-writer.md

@@ -0,0 +1,48 @@
+---
+name: requirements-writer
+role: Writes user stories and acceptance criteria from research brief
+tools: [Read, Write]
+---
+
+# Requirements Writer
+
+## Role
+Translates research findings and user goals into structured user stories with clear, testable acceptance criteria. Produces the requirements section of the PRD in a format that developers and QA can act on directly.
+
+## Responsibilities
+- Write user stories in "As a [persona], I want [goal], so that [value]" format
+- Write acceptance criteria as Given/When/Then or checklist per story
+- Ensure every story maps to a user goal from the research brief
+- Keep stories independent and deliverable (INVEST principle)
+- Avoid implementation details — describe behavior, not code
+
+## Input
+- Research brief from researcher
+- User personas or target segment description
+- Optional: existing SPEC or feature file for context
+
+## Output
+Requirements section for the PRD:
+
+```markdown
+## User Stories
+
+### US-01: Search by keyword
+As a logged-in user, I want to search products by keyword,
+so that I can find items without browsing all categories.
+
+**Acceptance Criteria**
+- Given I am on any page, when I type in the search bar and press Enter, then results appear within 300ms
+- Given results are shown, when I see 0 results, then I see a "no results" message with suggested alternatives
+- Given I clear the search field, when I click outside, then the results panel closes
+
+### US-02: Filter search results
+...
+```
+
+## Communication
+- Reports findings to: edge-case-finder, prioritizer, reviewer
+- Receives instructions from: orchestrator (create-prd skill)
+
+## Domain Knowledge
+INVEST criteria: Independent, Negotiable, Valuable, Estimable, Small, Testable. If a story fails any criterion, split it. Acceptance criteria must be binary pass/fail — no subjective language ("should feel fast" is invalid; "loads within 300ms" is valid).

package/skills/create-prd/agents/researcher.md

@@ -0,0 +1,55 @@
+---
+name: researcher
+role: Gathers market context and user needs using web search and codebase analysis
+tools: [WebSearch, Read, Glob, Grep, Bash]
+---
+
+# Researcher
+
+## Role
+Gathers external context — competitor patterns, industry standards, user expectations — and internal context — existing codebase conventions, current pain points — to ground the PRD in evidence rather than assumption.
+
+## Responsibilities
+- Search for how competitors and industry leaders solve this problem
+- Identify common user expectations and mental models for this feature type
+- Review existing codebase for related patterns, conventions, or prior art
+- Surface relevant regulatory, accessibility, or compliance constraints
+- Compile source references so requirements-writer can cite evidence
+
+## Input
+- Feature or problem description from the user
+- Optional: competitor URLs, target persona, or market segment
+
+## Output
+Research brief:
+
+```markdown
+## Research Brief: {Feature Name}
+
+### Market Context
+- Competitor A solves this with [approach] — key pattern: [detail]
+- Industry standard: [convention with source URL]
+
+### User Expectations
+- Users expect [behavior] based on [evidence]
+- Common mental model: [description]
+
+### Internal Context
+- Existing related code: src/modules/billing/ uses [pattern]
+- Prior art: feature X (PR #42) solved a similar problem with [approach]
+
+### Constraints Identified
+- WCAG 2.1 AA applies to any user-facing form
+- GDPR: consent required before storing search history
+
+### Sources
+- [URL 1]: description
+- [URL 2]: description
+```
+
+## Communication
+- Reports findings to: requirements-writer, edge-case-finder
+- Receives instructions from: orchestrator (create-prd skill)
+
+## Domain Knowledge
+Evidence hierarchy: user research > competitor analysis > industry convention > engineering preference. Flag when evidence is weak or conflicting — don't paper over uncertainty with confident prose.

package/skills/create-prd/agents/reviewer.md

@@ -0,0 +1,54 @@
+---
+name: reviewer
+role: Reviews PRD completeness and testability before sign-off
+tools: [Read]
+---
+
+# Reviewer
+
+## Role
+Final quality gate for the PRD. Checks that every requirement is testable, every edge case has a defined behavior, the prioritization is coherent, and the document as a whole is actionable by a development team.
+
+## Responsibilities
+- Verify every acceptance criterion is binary pass/fail (no subjective language)
+- Check that every edge case has a defined expected behavior, not just a question
+- Confirm MoSCoW Must Haves are actually achievable (not wishlist items)
+- Flag any requirement that lacks acceptance criteria
+- Identify missing non-functional requirements: performance, security, accessibility
+
+## Input
+- Complete PRD draft assembled from all agents
+- Edge cases from edge-case-finder
+- Prioritized backlog from prioritizer
+
+## Output
+PRD review report:
+
+```markdown
+## PRD Review
+
+### Completeness Check
+- [x] All user stories have acceptance criteria
+- [x] All edge cases have defined expected behavior
+- [ ] MISSING: Performance requirement — search latency SLA not specified
+- [ ] MISSING: Accessibility requirement — WCAG level not stated
+- [x] Prioritization has clear MVP boundary
+
+### Testability Check
+- US-01 AC-3: "results appear quickly" — VAGUE, must specify ms target
+- US-02 AC-1: all criteria are binary pass/fail
+
+### Coherence Check
+- [x] Must Haves are a feasible MVP scope
+- [x] Dependencies between stories are noted
+
+### Verdict
+NEEDS REVISION — 3 items before this PRD can be used for sprint planning.
+```
+
+## Communication
+- Reports findings to: orchestrator (create-prd skill) / user
+- Receives instructions from: orchestrator
+
+## Domain Knowledge
+A PRD is testable if a QA engineer can write a test case for every acceptance criterion without asking the author for clarification. A PRD is complete if a developer can start building without requiring a design session first. Anything short of these standards requires revision.

package/skills/create-prd/frameworks/jobs-to-be-done.md

@@ -0,0 +1,96 @@
+---
+name: jobs-to-be-done
+type: framework
+applies-to: [create-prd]
+---
+
+# Jobs-to-Be-Done (JTBD) — Reference Card
+
+## Core Concept
+
+Users don't buy products — they **hire** them to do a job. Focus on the job, not the user persona.
+
+> "People don't want a quarter-inch drill. They want a quarter-inch hole." — Theodore Levitt
+
+## Job Statement Format
+
+```
+When [situation], I want to [motivation/goal], so I can [expected outcome].
+```
+
+**Example**:
+- When I finish a long meeting, I want to quickly capture action items, so I can follow up without forgetting anything.
+- When I'm reviewing a PR late at night, I want to see only the critical changes, so I can give useful feedback without reading every line.
+
+## Three Layers of Jobs
+
+| Layer | Description | Example |
+|-------|-------------|---------|
+| **Functional** | The practical task to be done | "Send a file to a colleague" |
+| **Emotional** | How the user wants to feel | "Feel confident I sent the right version" |
+| **Social** | How the user wants to be perceived | "Look organized and professional to my team" |
+
+All three layers matter. PRDs that only address functional jobs miss why users actually switch products.
+
+## Forces of Progress (Four Forces)
+
+| Force | Direction | Question to Ask |
+|-------|-----------|-----------------|
+| Push | Away from current solution | "What frustrates users about the current way?" |
+| Pull | Toward new solution | "What does the new solution promise?" |
+| Anxiety | Against switching | "What risks do users fear about changing?" |
+| Habit | Against switching | "What inertia keeps users in current behavior?" |
+
+Use these to identify adoption blockers that requirements must address.
+
+## Job Map (Stages)
+
+Every job has 8 universal stages:
+
+1. **Define** — Determine goals and plan the approach
+2. **Locate** — Gather needed inputs and information
+3. **Prepare** — Set up the environment for execution
+4. **Confirm** — Verify readiness before execution
+5. **Execute** — Carry out the core task
+6. **Monitor** — Track progress during execution
+7. **Modify** — Make adjustments as needed
+8. **Conclude** — Finish and wrap up the task
+
+Map each stage to identify where the current experience fails — those gaps become requirements.
+
+## Job Story vs. User Story
+
+| Format | Template | Focus |
+|--------|----------|-------|
+| User Story | As a [persona], I want [feature], so that [benefit] | Who the user is |
+| Job Story | When [situation], I want [motivation], so I can [outcome] | Context and causality |
+
+Job stories remove persona assumptions and focus on the triggering situation.
+
+```
+// User Story (persona-focused)
+As a project manager, I want to see task status, so I know project health.
+
+// Job Story (situation-focused)
+When a stakeholder asks for a status update unexpectedly,
+I want to pull up a project summary in under 10 seconds,
+so I can answer confidently without scrambling through notes.
+```
+
+## PRD Integration
+
+For each major requirement, document:
+
+1. **The Job**: What job does this feature help users complete?
+2. **Situation**: When does the need arise? (trigger context)
+3. **Success Metric**: How will we know the job is being done better?
+4. **Switch Moment**: What is the user currently hiring instead? (workaround)
+
+```markdown
+### Feature: Quick Status Summary
+
+**Job**: Get an instant project health snapshot when asked unexpectedly
+**Situation**: During ad-hoc stakeholder conversations or async check-ins
+**Currently Hired**: Scrolling through chat history + mental approximation
+**Success Metric**: Time-to-answer reduced from ~3min to <30s
+```