vbounce-engine 2.5.1

package/skills/write-skill/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: write-skill
+description: Use when creating or updating Claude Code skills. Applies Anthropic best practices and persuasion principles for effective skill authoring.
+---
+
+# Skill Authoring
+
+Creates or updates Claude Code skills following Anthropic's best practices and tested persuasion principles.
+
+**Core principle:** No skill without a failing test first. RED-GREEN-REFACTOR for process documentation.
+
+## Trigger
+
+`/write-skill` OR `/write-skill [skill-name]` OR when creating/modifying any `.claude/skills/` content.
+
+## Announcement
+
+When using this skill, state: "I'm using the write-skill skill to author an effective skill definition."
+
+## Action
+
+### 1. Baseline (RED Phase)
+
+Before writing, establish that the skill is needed:
+- What specific failure or gap does this skill address?
+- Can you demonstrate the failure WITHOUT the skill?
+- If you can't show a gap, you don't need a new skill.
+
+### 2. Write Minimal Skill (GREEN Phase)
+
+Create the skill at `.claude/skills/[name]/SKILL.md` with this structure:
+
+```yaml
+---
+name: [kebab-case-name]
+description: [Use when... — must start with triggering conditions, not workflow summary]
+---
+```
+
+**Structure requirements:**
+- YAML frontmatter: `name` and `description` only
+- Description MUST start with "Use when..."
+- Include searchable keywords (errors, symptoms, tools)
+- Clear overview with core principle
+- Inline code for simple patterns; separate files for heavy reference
+
+**Size constraints:**
+- Keep SKILL.md under 500 lines
+- Split into reference files when approaching limit
+- Structure references one level deep from SKILL.md
+- Include table of contents for reference files over 100 lines
+
+### 3. Apply Persuasion Principles
+
+Use the right language patterns based on skill type:
+
+| Skill Type | Use | Avoid |
+|:---|:---|:---|
+| **Discipline-enforcing** (TDD, verification) | Authority + Commitment + Social Proof | Liking, Reciprocity |
+| **Guidance/technique** | Moderate Authority + Unity | Heavy authority |
+| **Collaborative** | Unity + Commitment | Authority, Liking |
+| **Reference** | Clarity only | All persuasion |
+
+**Effective patterns:**
+- Imperative: "YOU MUST", "Never", "Always", "No exceptions"
+- Commitment: "Announce: I'm using [Skill Name]"
+- Scarcity: "IMMEDIATELY after X", "Before proceeding"
+- Social proof: "Every time", "X without Y = failure"
+- Unity: "We're colleagues", "our codebase"
+
+**Example — discipline skill:**
+```markdown
+✅ Write code before test? Delete it. Start over. No exceptions.
+❌ Consider writing tests first when feasible.
+```
+
+### 4. Refine (REFACTOR Phase)
+
+- Test the skill across different scenarios
+- Plug loopholes where the agent might rationalize skipping steps
+- Add anti-rationalization language for critical rules
+- Verify the skill works with the target model
+
+### 5. Skill Type Checklist
+
+**Techniques** (step-by-step methods):
+- [ ] Clear trigger conditions
+- [ ] Ordered action steps
+- [ ] Explicit wait points
+- [ ] Output format example
+
+**Patterns** (mental models):
+- [ ] Recognition criteria
+- [ ] When to apply vs. when not to
+- [ ] Examples of correct application
+
+**References** (API docs/guides):
+- [ ] Table of contents
+- [ ] Searchable headings
+- [ ] Code examples with correct/incorrect pairs
+
+## Content Guidelines
+
+- **Assume Claude's intelligence** — don't over-explain what can be inferred
+- **Match specificity to fragility:**
+  - High freedom (text instructions) → flexible tasks
+  - Medium freedom (pseudocode) → preferred patterns
+  - Low freedom (exact scripts) → error-prone operations
+- **Avoid time-sensitive information** — use "old patterns" sections for deprecated approaches
+- **Use consistent terminology** — choose one term, not synonyms
+- **Use checklists** for multi-step operations (copyable via TodoWrite)
+- **Include validation loops** — run validator → fix → repeat
+
+## Anti-Patterns
+
+- Narrative examples (use code pairs instead)
+- Multi-language dilution (focus on the project's stack)
+- Code in flowcharts (use real code blocks)
+- Generic labels ("Step 1", "Step 2" without context)
+- Vague skill names ("helper", "utility")
+- Offering excessive options without clear defaults
+- Deeply nested file references (one level deep max)
+
+## Deployment Checklist
+
+Before marking complete:
+- [ ] RED: Demonstrated the gap without the skill
+- [ ] GREEN: Wrote minimal content addressing the gap
+- [ ] REFACTOR: Tested and plugged loopholes
+- [ ] Description starts with "Use when..."
+- [ ] SKILL.md under 500 lines
+- [ ] References one level deep
+- [ ] Tested against real task scenarios

package/templates/bug.md

@@ -0,0 +1,100 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This documents a defect found during or after sprint execution.
+
+1. **YAML Frontmatter**: Bug ID, Status, Severity, Found During, Affected Story, Reporter
+2. **§1 The Bug**: What's broken, reproduction steps, expected vs actual
+3. **§2 Impact**: What's affected, is it blocking?
+4. **§3 Fix Approach**: Proposed fix, affected files, estimated complexity
+5. **§4 Verification**: How to verify the fix
+
+When to use this template:
+- User reports something is broken mid-sprint
+- QA discovers a defect not covered by acceptance criteria
+- Post-sprint manual review finds an issue
+- A previously working feature regresses
+
+Triage rules (from mid-sprint-triage.md):
+- If the bug is L1 (1-2 files, trivial fix) → use .vbounce/templates/hotfix.md instead
+- If the bug is larger → use THIS template, add to current sprint as a fix task
+- Bug fixes do NOT increment QA/Architect bounce counts
+
+Output location: `product_plans/sprints/sprint-{XX}/BUG-{Date}-{Name}.md`
+If no sprint is active: `product_plans/backlog/BUG-{Date}-{Name}.md`
+
+Do NOT output these instructions.
+</instructions>
+
+---
+bug_id: "BUG-{YYYY-MM-DD}-{name}"
+status: "Open / In Progress / Fixed / Wont Fix"
+severity: "Critical / High / Medium / Low"
+found_during: "Sprint S-{XX} / Post-Sprint Review / User Report"
+affected_story: "STORY-{ID} / N/A (pre-existing)"
+reporter: "{human / QA / user}"
+---
+
+# BUG: {Short Description}
+
+## 1. The Bug
+
+**Current Behavior:**
+{What happens — be specific}
+
+**Expected Behavior:**
+{What should happen instead}
+
+**Reproduction Steps:**
+1. {Step 1}
+2. {Step 2}
+3. {Observe: ...}
+
+**Environment:**
+- {Browser/OS/Node version if relevant}
+- {Branch: sprint/S-XX or main}
+
+---
+
+## 2. Impact
+
+- **Blocking?** {Yes — blocks STORY-{ID} / No — cosmetic / degraded}
+- **Affected Areas:** {Which features, pages, or flows}
+- **Users Affected:** {All users / specific persona / edge case only}
+- **Data Impact:** {None / corrupted data / lost data}
+
+---
+
+## 3. Fix Approach
+
+- **Root Cause:** {Why it's broken — if known}
+- **Proposed Fix:** {What to change}
+- **Files to Modify:** `{filepath1}`, `{filepath2}`
+- **Complexity:** {L1 Trivial / L2 Standard / L3 Complex}
+
+> If complexity is L1 → consider using `.vbounce/templates/hotfix.md` instead for faster resolution.
+
+---
+
+## 4. Verification
+
+- [ ] {Reproduction steps no longer reproduce the bug}
+- [ ] {Existing tests still pass}
+- [ ] {New test covers the bug scenario — if applicable}
+- [ ] Run `./.vbounce/scripts/hotfix_manager.sh ledger "BUG: {Name}" "{Brief description}"`
+
+---
+
+---
+
+## Token Usage
+> Auto-populated by agents. Each agent runs `node .vbounce/scripts/count_tokens.mjs --self --append <this-file> --name <Agent>` before writing their report.
+
+| Agent | Input | Output | Total |
+|-------|-------|--------|-------|
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created |

package/templates/change_request.md

@@ -0,0 +1,105 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This documents a scope change or new requirement discovered mid-sprint.
+
+1. **YAML Frontmatter**: CR ID, Status, Category, Urgency, Affected Stories, Requestor
+2. **§1 The Change**: What's being requested and why
+3. **§2 Impact Assessment**: What it affects, what breaks, what gets delayed
+4. **§3 Decision**: Approved action with rationale
+5. **§4 Execution Plan**: How the change will be handled
+
+When to use this template:
+- User requests a new feature or scope expansion mid-sprint
+- User wants to change the technical approach of an active story
+- External dependency change forces a pivot
+- Requirements discovered during implementation that weren't in the original spec
+
+Categories (from mid-sprint-triage.md):
+- **Scope Change**: Adding/removing/modifying requirements → use THIS template
+- **Approach Change**: Different technical path → use THIS template
+- **Spec Clarification**: Just clarifying ambiguity → do NOT use this template (update story spec inline)
+- **Bug**: Something is broken → use .vbounce/templates/bug.md instead
+
+Triage rules:
+- Scope changes PAUSE the active bounce until the human approves
+- Approach changes reset the Dev pass
+- All CRs are logged in Sprint Plan §4 Execution Log with event type "CR"
+- CRs that can't fit in the current sprint go to backlog for next sprint planning
+
+Output location: `product_plans/sprints/sprint-{XX}/CR-{Date}-{Name}.md`
+If no sprint is active: `product_plans/backlog/CR-{Date}-{Name}.md`
+
+Do NOT output these instructions.
+</instructions>
+
+---
+cr_id: "CR-{YYYY-MM-DD}-{name}"
+status: "Open / Approved / Rejected / Deferred"
+category: "Scope Change / Approach Change"
+urgency: "Blocking / This Sprint / Next Sprint"
+affected_stories: ["STORY-{ID}"]
+requestor: "{human / AI / external}"
+---
+
+# CR: {Short Description}
+
+## 1. The Change
+
+**What is being requested:**
+{Describe the change clearly}
+
+**Why:**
+{Business reason, user feedback, technical discovery, external dependency change}
+
+**Original vs Proposed:**
+| Aspect | Original | Proposed |
+|--------|----------|----------|
+| {Scope/Approach/Tech} | {What was planned} | {What's now requested} |
+
+---
+
+## 2. Impact Assessment
+
+**Affected Stories:**
+| Story | Current State | Impact |
+|-------|--------------|--------|
+| STORY-{ID} | {Bouncing / QA Passed / ...} | {Must restart Dev / Spec update only / Blocked} |
+
+**Sprint Impact:**
+- {Does this delay the sprint? By how much?}
+- {Does this invalidate completed work?}
+- {Does this require new stories?}
+
+**Risk:**
+- {What could go wrong if we make this change?}
+- {What could go wrong if we DON'T make this change?}
+
+---
+
+## 3. Decision
+
+> Filled by human after reviewing the impact assessment.
+
+**Decision:** {Approved / Rejected / Deferred to S-{XX}}
+
+**Rationale:** {Why this decision}
+
+**Conditions:** {Any constraints on the approved change}
+
+---
+
+## 4. Execution Plan
+
+> Filled after decision is approved.
+
+- **Stories affected:** {Which stories need spec updates}
+- **New stories needed:** {If any — add to backlog or current sprint}
+- **Bounce impact:** {Which passes reset — Dev only / Dev + QA / full restart}
+- **Timeline:** {Can it fit in current sprint or deferred?}
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created |

package/templates/charter.md

@@ -0,0 +1,144 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-9.
+
+1. **YAML Frontmatter**: Set status, ambiguity, and readiness
+2. **§1 Project Identity**: What it is, what it's NOT, success metrics
+3. **§2 Design Principles**: 3-5 numbered rules (these guide all future decisions)
+4. **§3 Architecture**: System diagram + Tech Stack table (mark unknown as `[TBD]`)
+5. **§4 Core Entities**: Table of data objects (nouns)
+6. **§5 Key Workflows**: Numbered steps for main flows (verbs)
+7. **§6 Constraints**: Known limitations and mitigations
+8. **§7 Open Questions**: Unanswered items that may block progress
+9. **§8-9 Glossary & References**: Terms and links
+
+Ambiguity Score:
+- 🔴 High: Missing "why" or primary flow → Blocked
+- 🟡 Medium: Tech TBD but logic clear → Ready for Roadmap
+- 🟢 Low: All filled → Ready for Epics
+
+Output location: `product_plans/strategy/{project}_charter.md`
+
+Document Hierarchy Position: ROOT
+Charter is the source of truth for WHY. All downstream documents inherit from it:
+Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
+
+Downstream consumers:
+- Roadmap §1 pulls Vision, Goal, Users, and Success Metrics from Charter §1
+- Roadmap §3 ADRs are constrained by Charter §3 Tech Stack choices
+- Epic §1 Problem & Value traces back to Charter §1.1 and §5 Workflows
+- Design Principles (§2) are referenced by ALL agents when making ambiguous decisions
+
+Do NOT output these instructions.
+</instructions>
+
+---
+status: "🌱 Initial Draft / 🌿 Refining / 🌳 Approved"
+ambiguity: "🔴 High / 🟡 Medium / 🟢 Low"
+readiness: "Blocked / Ready for Roadmap / Ready for Epics"
+---
+
+# Project Charter: [Project Name]
+
+## 1. Project Identity
+
+### 1.1 What It Is
+> One paragraph: what the product does and for whom.
+
+### 1.2 What It Is NOT
+> Explicit boundaries. Prevents scope creep and AI hallucination.
+- Not a {similar product X}
+- Does not handle {out-of-scope capability}
+
+### 1.3 Success Definition
+> How do we know we won? Measurable outcomes.
+- {Metric 1}
+- {Metric 2}
+
+---
+
+## 2. Design Principles
+> Numbered rules that guide ALL decisions. AI agents reference these when uncertain.
+
+1. **{Principle Name}**: {One sentence explanation}
+2. **{Principle Name}**: {One sentence explanation}
+3. **{Principle Name}**: {One sentence explanation}
+
+---
+
+## 3. Architecture Overview
+
+### 3.1 System Context
+```mermaid
+flowchart LR
+    User --> Frontend
+    Frontend --> API
+    API --> Database
+    API --> ExternalService
+```
+
+### 3.2 Technical Foundation
+| Component | Choice | Status | Notes |
+|-----------|--------|--------|-------|
+| **Frontend** | {e.g. Next.js} | Selected / TBD | {Reasoning} |
+| **Backend** | {e.g. Python/FastAPI} | Selected / TBD | |
+| **Database** | {e.g. Supabase} | Selected / TBD | |
+| **AI/ML** | {e.g. Claude API} | Selected / TBD | |
+| **Integrations** | {List External APIs} | Selected / TBD | |
+
+---
+
+## 4. Core Entities
+> The nouns of your system. AI uses this to understand data flow.
+
+| Entity | Purpose | Key Fields |
+|--------|---------|------------|
+| User | Account holder | id, email, role |
+| {Entity} | {purpose} | {fields} |
+
+---
+
+## 5. Key Workflows
+> The verbs of your system. Reference these in Epics.
+
+### 5.1 {Workflow Name}
+1. {Step}
+2. {Step}
+3. {Step}
+
+### 5.2 {Workflow Name}
+1. {Step}
+2. {Step}
+
+---
+
+## 6. Constraints & Edge Cases
+| Constraint | Mitigation |
+|------------|------------|
+| {e.g., Rate limits on external API} | {how we handle it} |
+| {e.g., Offline support required} | {approach} |
+| {e.g., GDPR compliance} | {approach} |
+
+---
+
+## 7. Open Questions
+
+> [!QUESTION]
+> {Question that blocks progress}
+
+| Question | Options | Impact | Status |
+|----------|---------|--------|--------|
+| {decision needed} | A: {x}, B: {y} | Blocks {X} | Open / Decided |
+
+---
+
+## 8. Glossary
+| Term | Definition |
+|------|------------|
+| {term} | {what it means in THIS project} |
+
+---
+
+## 9. References
+- Design Docs: {link}
+- Competitor Analysis: {link}
+- User Research: {link}

package/templates/delivery_plan.md

@@ -0,0 +1,44 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+1. **Header**: Set Status, link to Roadmap + Risk Registry, Sprint Cadence
+2. **§1 Project Window**: Start/End dates, total sprints, team
+3. **§2 Epics Included**: Table of all Epics assigned to this delivery
+4. **§3 High-Level Backlog**: Unassigned stories (Epics being broken down)
+
+Delivery Lifecycle:
+- This document tracks the *milestone* across multiple sprints.
+- Active sprint work happens inside `sprints/sprint-{XX}/sprint-{XX}.md`, not here.
+- When the delivery is fully shipped, this entire document is archived.
+
+Output location: `product_plans/D-{NN}_{release_name}/D-{NN}_DELIVERY_PLAN.md`
+Do NOT output these instructions.
+</instructions>
+# Delivery Plan: {Project Name}
+---
+> **Last Updated**: {YYYY-MM-DD}
+> **Status**: Planning / In Delivery / Completed
+> **Roadmap**: `product_plans/{project}_roadmap.md`
+> **Risk Registry**: `product_plans/RISK_REGISTRY.md`
+> **Delivery**: `D-{NN}_{release_name}`
+> **Sprint Cadence**: 1-week sprints
+---
+## 1. Project Window
+| Key | Value |
+|-----|-------|
+| **Start Date** | {YYYY-MM-DD} |
+| **End Date** | {YYYY-MM-DD} |
+| **Total Sprints** | {N} |
+| **Team** | {CE name(s) / Agent config} |
+---
+## 2. Epics Included
+| Epic | Name | Status | Stories | V-Bounce Phase |
+|------|------|--------|---------|----------------|
+| EPIC-XXX | {Name} | Draft / Refinement / Bouncing / Done | {Y}/{X} | {Phase Name} |
+---
+## 3. High-Level Backlog
+> Stories prioritized for this delivery but not yet assigned to an active Sprint.
+| Priority | Story | Epic | Label | Blocker |
+|----------|-------|------|-------|---------|
+| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | — |
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}