@sandrinio/vbounce 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +107 -0
  2. package/bin/vbounce.mjs +165 -0
  3. package/brains/AGENTS.md +129 -0
  4. package/brains/CLAUDE.md +146 -0
  5. package/brains/GEMINI.md +134 -0
  6. package/brains/SETUP.md +180 -0
  7. package/brains/claude-agents/architect.md +140 -0
  8. package/brains/claude-agents/developer.md +69 -0
  9. package/brains/claude-agents/devops.md +219 -0
  10. package/brains/claude-agents/qa.md +112 -0
  11. package/brains/claude-agents/scribe.md +141 -0
  12. package/brains/cursor-rules/vbounce-docs.mdc +41 -0
  13. package/brains/cursor-rules/vbounce-process.mdc +45 -0
  14. package/brains/cursor-rules/vbounce-rules.mdc +26 -0
  15. package/package.json +40 -0
  16. package/skills/agent-team/SKILL.md +425 -0
  17. package/skills/doc-manager/SKILL.md +278 -0
  18. package/skills/lesson/SKILL.md +90 -0
  19. package/skills/react-best-practices/SKILL.md +3014 -0
  20. package/skills/react-best-practices/rules/_sections.md +46 -0
  21. package/skills/react-best-practices/rules/_template.md +28 -0
  22. package/skills/react-best-practices/rules/advanced-event-handler-refs.md +55 -0
  23. package/skills/react-best-practices/rules/advanced-init-once.md +42 -0
  24. package/skills/react-best-practices/rules/advanced-use-latest.md +39 -0
  25. package/skills/react-best-practices/rules/async-api-routes.md +38 -0
  26. package/skills/react-best-practices/rules/async-defer-await.md +80 -0
  27. package/skills/react-best-practices/rules/async-dependencies.md +51 -0
  28. package/skills/react-best-practices/rules/async-parallel.md +28 -0
  29. package/skills/react-best-practices/rules/async-suspense-boundaries.md +99 -0
  30. package/skills/react-best-practices/rules/bundle-barrel-imports.md +59 -0
  31. package/skills/react-best-practices/rules/bundle-conditional.md +31 -0
  32. package/skills/react-best-practices/rules/bundle-defer-third-party.md +49 -0
  33. package/skills/react-best-practices/rules/bundle-dynamic-imports.md +35 -0
  34. package/skills/react-best-practices/rules/bundle-preload.md +50 -0
  35. package/skills/react-best-practices/rules/client-event-listeners.md +74 -0
  36. package/skills/react-best-practices/rules/client-localstorage-schema.md +71 -0
  37. package/skills/react-best-practices/rules/client-passive-event-listeners.md +48 -0
  38. package/skills/react-best-practices/rules/client-swr-dedup.md +56 -0
  39. package/skills/react-best-practices/rules/js-batch-dom-css.md +107 -0
  40. package/skills/react-best-practices/rules/js-cache-function-results.md +80 -0
  41. package/skills/react-best-practices/rules/js-cache-property-access.md +28 -0
  42. package/skills/react-best-practices/rules/js-cache-storage.md +70 -0
  43. package/skills/react-best-practices/rules/js-combine-iterations.md +32 -0
  44. package/skills/react-best-practices/rules/js-early-exit.md +50 -0
  45. package/skills/react-best-practices/rules/js-hoist-regexp.md +45 -0
  46. package/skills/react-best-practices/rules/js-index-maps.md +37 -0
  47. package/skills/react-best-practices/rules/js-length-check-first.md +49 -0
  48. package/skills/react-best-practices/rules/js-min-max-loop.md +82 -0
  49. package/skills/react-best-practices/rules/js-set-map-lookups.md +24 -0
  50. package/skills/react-best-practices/rules/js-tosorted-immutable.md +57 -0
  51. package/skills/react-best-practices/rules/rendering-activity.md +26 -0
  52. package/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md +47 -0
  53. package/skills/react-best-practices/rules/rendering-conditional-render.md +40 -0
  54. package/skills/react-best-practices/rules/rendering-content-visibility.md +38 -0
  55. package/skills/react-best-practices/rules/rendering-hoist-jsx.md +46 -0
  56. package/skills/react-best-practices/rules/rendering-hydration-no-flicker.md +82 -0
  57. package/skills/react-best-practices/rules/rendering-hydration-suppress-warning.md +30 -0
  58. package/skills/react-best-practices/rules/rendering-svg-precision.md +28 -0
  59. package/skills/react-best-practices/rules/rendering-usetransition-loading.md +75 -0
  60. package/skills/react-best-practices/rules/rerender-defer-reads.md +39 -0
  61. package/skills/react-best-practices/rules/rerender-dependencies.md +45 -0
  62. package/skills/react-best-practices/rules/rerender-derived-state-no-effect.md +40 -0
  63. package/skills/react-best-practices/rules/rerender-derived-state.md +29 -0
  64. package/skills/react-best-practices/rules/rerender-functional-setstate.md +74 -0
  65. package/skills/react-best-practices/rules/rerender-lazy-state-init.md +58 -0
  66. package/skills/react-best-practices/rules/rerender-memo-with-default-value.md +38 -0
  67. package/skills/react-best-practices/rules/rerender-memo.md +44 -0
  68. package/skills/react-best-practices/rules/rerender-move-effect-to-event.md +45 -0
  69. package/skills/react-best-practices/rules/rerender-simple-expression-in-memo.md +35 -0
  70. package/skills/react-best-practices/rules/rerender-transitions.md +40 -0
  71. package/skills/react-best-practices/rules/rerender-use-ref-transient-values.md +73 -0
  72. package/skills/react-best-practices/rules/server-after-nonblocking.md +73 -0
  73. package/skills/react-best-practices/rules/server-auth-actions.md +96 -0
  74. package/skills/react-best-practices/rules/server-cache-lru.md +41 -0
  75. package/skills/react-best-practices/rules/server-cache-react.md +76 -0
  76. package/skills/react-best-practices/rules/server-dedup-props.md +65 -0
  77. package/skills/react-best-practices/rules/server-parallel-fetching.md +83 -0
  78. package/skills/react-best-practices/rules/server-serialization.md +38 -0
  79. package/skills/vibe-code-review/SKILL.md +70 -0
  80. package/skills/vibe-code-review/references/deep-audit.md +259 -0
  81. package/skills/vibe-code-review/references/pr-review.md +234 -0
  82. package/skills/vibe-code-review/references/quick-scan.md +178 -0
  83. package/skills/vibe-code-review/references/report-template.md +189 -0
  84. package/skills/vibe-code-review/references/trend-check.md +224 -0
  85. package/skills/vibe-code-review/scripts/generate-snapshot.sh +89 -0
  86. package/skills/vibe-code-review/scripts/pr-analyze.sh +180 -0
  87. package/skills/write-skill/SKILL.md +133 -0
  88. package/templates/charter.md +144 -0
  89. package/templates/delivery_plan.md +188 -0
  90. package/templates/epic.md +200 -0
  91. package/templates/hotfix.md +57 -0
  92. package/templates/risk_registry.md +89 -0
  93. package/templates/roadmap.md +176 -0
  94. package/templates/sprint_report.md +151 -0
  95. package/templates/story.md +150 -0
@@ -0,0 +1,133 @@
1
+ ---
2
+ name: write-skill
3
+ description: Use when creating or updating Claude Code skills. Applies Anthropic best practices and persuasion principles for effective skill authoring.
4
+ ---
5
+
6
+ # Skill Authoring
7
+
8
+ Creates or updates Claude Code skills following Anthropic's best practices and tested persuasion principles.
9
+
10
+ **Core principle:** No skill without a failing test first. RED-GREEN-REFACTOR for process documentation.
11
+
12
+ ## Trigger
13
+
14
+ `/write-skill` OR `/write-skill [skill-name]` OR when creating/modifying any `.claude/skills/` content.
15
+
16
+ ## Announcement
17
+
18
+ When using this skill, state: "I'm using the write-skill skill to author an effective skill definition."
19
+
20
+ ## Action
21
+
22
+ ### 1. Baseline (RED Phase)
23
+
24
+ Before writing, establish that the skill is needed:
25
+ - What specific failure or gap does this skill address?
26
+ - Can you demonstrate the failure WITHOUT the skill?
27
+ - If you can't show a gap, you don't need a new skill.
28
+
29
+ ### 2. Write Minimal Skill (GREEN Phase)
30
+
31
+ Create the skill at `.claude/skills/[name]/SKILL.md` with this structure:
32
+
33
+ ```yaml
34
+ ---
35
+ name: [kebab-case-name]
36
+ description: [Use when... — must start with triggering conditions, not workflow summary]
37
+ ---
38
+ ```
39
+
40
+ **Structure requirements:**
41
+ - YAML frontmatter: `name` and `description` only
42
+ - Description MUST start with "Use when..."
43
+ - Include searchable keywords (errors, symptoms, tools)
44
+ - Clear overview with core principle
45
+ - Inline code for simple patterns; separate files for heavy reference
46
+
47
+ **Size constraints:**
48
+ - Keep SKILL.md under 500 lines
49
+ - Split into reference files when approaching limit
50
+ - Structure references one level deep from SKILL.md
51
+ - Include table of contents for reference files over 100 lines
52
+
53
+ ### 3. Apply Persuasion Principles
54
+
55
+ Use the right language patterns based on skill type:
56
+
57
+ | Skill Type | Use | Avoid |
58
+ |:---|:---|:---|
59
+ | **Discipline-enforcing** (TDD, verification) | Authority + Commitment + Social Proof | Liking, Reciprocity |
60
+ | **Guidance/technique** | Moderate Authority + Unity | Heavy authority |
61
+ | **Collaborative** | Unity + Commitment | Authority, Liking |
62
+ | **Reference** | Clarity only | All persuasion |
63
+
64
+ **Effective patterns:**
65
+ - Imperative: "YOU MUST", "Never", "Always", "No exceptions"
66
+ - Commitment: "Announce: I'm using [Skill Name]"
67
+ - Scarcity: "IMMEDIATELY after X", "Before proceeding"
68
+ - Social proof: "Every time", "X without Y = failure"
69
+ - Unity: "We're colleagues", "our codebase"
70
+
71
+ **Example — discipline skill:**
72
+ ```markdown
73
+ ✅ Write code before test? Delete it. Start over. No exceptions.
74
+ ❌ Consider writing tests first when feasible.
75
+ ```
76
+
77
+ ### 4. Refine (REFACTOR Phase)
78
+
79
+ - Test the skill across different scenarios
80
+ - Plug loopholes where the agent might rationalize skipping steps
81
+ - Add anti-rationalization language for critical rules
82
+ - Verify the skill works with the target model
83
+
84
+ ### 5. Skill Type Checklist
85
+
86
+ **Techniques** (step-by-step methods):
87
+ - [ ] Clear trigger conditions
88
+ - [ ] Ordered action steps
89
+ - [ ] Explicit wait points
90
+ - [ ] Output format example
91
+
92
+ **Patterns** (mental models):
93
+ - [ ] Recognition criteria
94
+ - [ ] When to apply vs. when not to
95
+ - [ ] Examples of correct application
96
+
97
+ **References** (API docs/guides):
98
+ - [ ] Table of contents
99
+ - [ ] Searchable headings
100
+ - [ ] Code examples with correct/incorrect pairs
101
+
102
+ ## Content Guidelines
103
+
104
+ - **Assume Claude's intelligence** — don't over-explain what can be inferred
105
+ - **Match specificity to fragility:**
106
+ - High freedom (text instructions) → flexible tasks
107
+ - Medium freedom (pseudocode) → preferred patterns
108
+ - Low freedom (exact scripts) → error-prone operations
109
+ - **Avoid time-sensitive information** — use "old patterns" sections for deprecated approaches
110
+ - **Use consistent terminology** — choose one term, not synonyms
111
+ - **Use checklists** for multi-step operations (copyable via TodoWrite)
112
+ - **Include validation loops** — run validator → fix → repeat
113
+
114
+ ## Anti-Patterns
115
+
116
+ - Narrative examples (use code pairs instead)
117
+ - Multi-language dilution (focus on the project's stack)
118
+ - Code in flowcharts (use real code blocks)
119
+ - Generic labels ("Step 1", "Step 2" without context)
120
+ - Vague skill names ("helper", "utility")
121
+ - Offering excessive options without clear defaults
122
+ - Deeply nested file references (one level deep max)
123
+
124
+ ## Deployment Checklist
125
+
126
+ Before marking complete:
127
+ - [ ] RED: Demonstrated the gap without the skill
128
+ - [ ] GREEN: Wrote minimal content addressing the gap
129
+ - [ ] REFACTOR: Tested and plugged loopholes
130
+ - [ ] Description starts with "Use when..."
131
+ - [ ] SKILL.md under 500 lines
132
+ - [ ] References one level deep
133
+ - [ ] Tested against real task scenarios
@@ -0,0 +1,144 @@
1
+ <instructions>
2
+ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-9.
3
+
4
+ 1. **Header**: Set Status, Ambiguity Score, Readiness based on completeness
5
+ 2. **§1 Project Identity**: What it is, what it's NOT, success metrics
6
+ 3. **§2 Design Principles**: 3-5 numbered rules (these guide all future decisions)
7
+ 4. **§3 Architecture**: System diagram + Tech Stack table (mark unknown as `[TBD]`)
8
+ 5. **§4 Core Entities**: Table of data objects (nouns)
9
+ 6. **§5 Key Workflows**: Numbered steps for main flows (verbs)
10
+ 7. **§6 Constraints**: Known limitations and mitigations
11
+ 8. **§7 Open Questions**: Unanswered items that may block progress
12
+ 9. **§8-9 Glossary & References**: Terms and links
13
+
14
+ Ambiguity Score:
15
+ - 🔴 High: Missing "why" or primary flow → Blocked
16
+ - 🟡 Medium: Tech TBD but logic clear → Ready for Roadmap
17
+ - 🟢 Low: All filled → Ready for Epics
18
+
19
+ Output location: `product_plans/{project}_charter.md`
20
+
21
+ Document Hierarchy Position: ROOT
22
+ Charter is the source of truth for WHY. All downstream documents inherit from it:
23
+ Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
24
+
25
+ Downstream consumers:
26
+ - Roadmap §1 pulls Vision, Goal, Users, and Success Metrics from Charter §1
27
+ - Roadmap §3 ADRs are constrained by Charter §3 Tech Stack choices
28
+ - Epic §1 Problem & Value traces back to Charter §1.1 and §5 Workflows
29
+ - Design Principles (§2) are referenced by ALL agents when making ambiguous decisions
30
+
31
+ Do NOT output these instructions.
32
+ </instructions>
33
+
34
+ # Project Charter: [Project Name]
35
+
36
+ > **Status**: 🌱 Initial Draft / 🌿 Refining / 🌳 Approved
37
+ > **Ambiguity Score**: 🔴 High / 🟡 Medium / 🟢 Low
38
+ > **Readiness**: Blocked / Ready for Roadmap / Ready for Epics
39
+
40
+ ---
41
+
42
+ ## 1. Project Identity
43
+
44
+ ### 1.1 What It Is
45
+ > One paragraph: what the product does and for whom.
46
+
47
+ ### 1.2 What It Is NOT
48
+ > Explicit boundaries. Prevents scope creep and AI hallucination.
49
+ - Not a {similar product X}
50
+ - Does not handle {out-of-scope capability}
51
+
52
+ ### 1.3 Success Definition
53
+ > How do we know we won? Measurable outcomes.
54
+ - {Metric 1}
55
+ - {Metric 2}
56
+
57
+ ---
58
+
59
+ ## 2. Design Principles
60
+ > Numbered rules that guide ALL decisions. AI agents reference these when uncertain.
61
+
62
+ 1. **{Principle Name}**: {One sentence explanation}
63
+ 2. **{Principle Name}**: {One sentence explanation}
64
+ 3. **{Principle Name}**: {One sentence explanation}
65
+
66
+ ---
67
+
68
+ ## 3. Architecture Overview
69
+
70
+ ### 3.1 System Context
71
+ ```mermaid
72
+ flowchart LR
73
+ User --> Frontend
74
+ Frontend --> API
75
+ API --> Database
76
+ API --> ExternalService
77
+ ```
78
+
79
+ ### 3.2 Technical Foundation
80
+ | Component | Choice | Status | Notes |
81
+ |-----------|--------|--------|-------|
82
+ | **Frontend** | {e.g. Next.js} | Selected / TBD | {Reasoning} |
83
+ | **Backend** | {e.g. Python/FastAPI} | Selected / TBD | |
84
+ | **Database** | {e.g. Supabase} | Selected / TBD | |
85
+ | **AI/ML** | {e.g. Claude API} | Selected / TBD | |
86
+ | **Integrations** | {List External APIs} | Selected / TBD | |
87
+
88
+ ---
89
+
90
+ ## 4. Core Entities
91
+ > The nouns of your system. AI uses this to understand data flow.
92
+
93
+ | Entity | Purpose | Key Fields |
94
+ |--------|---------|------------|
95
+ | User | Account holder | id, email, role |
96
+ | {Entity} | {purpose} | {fields} |
97
+
98
+ ---
99
+
100
+ ## 5. Key Workflows
101
+ > The verbs of your system. Reference these in Epics.
102
+
103
+ ### 5.1 {Workflow Name}
104
+ 1. {Step}
105
+ 2. {Step}
106
+ 3. {Step}
107
+
108
+ ### 5.2 {Workflow Name}
109
+ 1. {Step}
110
+ 2. {Step}
111
+
112
+ ---
113
+
114
+ ## 6. Constraints & Edge Cases
115
+ | Constraint | Mitigation |
116
+ |------------|------------|
117
+ | {e.g., Rate limits on external API} | {how we handle it} |
118
+ | {e.g., Offline support required} | {approach} |
119
+ | {e.g., GDPR compliance} | {approach} |
120
+
121
+ ---
122
+
123
+ ## 7. Open Questions
124
+
125
+ > [!QUESTION]
126
+ > {Question that blocks progress}
127
+
128
+ | Question | Options | Impact | Status |
129
+ |----------|---------|--------|--------|
130
+ | {decision needed} | A: {x}, B: {y} | Blocks {X} | Open / Decided |
131
+
132
+ ---
133
+
134
+ ## 8. Glossary
135
+ | Term | Definition |
136
+ |------|------------|
137
+ | {term} | {what it means in THIS project} |
138
+
139
+ ---
140
+
141
+ ## 9. References
142
+ - Design Docs: {link}
143
+ - Competitor Analysis: {link}
144
+ - User Research: {link}
@@ -0,0 +1,188 @@
1
+ <instructions>
2
+ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
3
+
4
+ 1. **Header**: Set Status, link to Roadmap + Risk Registry, Sprint Cadence
5
+ 2. **§1 Project Window**: Start/End dates, total sprints, team
6
+ 3. **§2 Sprint Registry**: Table of ALL sprints with goals and status (auto-populated between markers)
7
+ 4. **§3 Active Sprint**: CURRENT sprint only — goal + assigned stories with L1-L4 labels + V-Bounce state
8
+ 5. **§4 Backlog**: Prioritized stories not yet assigned to a sprint (includes Escalated + Parking Lot)
9
+ 6. **§5 Context Pack Status**: Per-story readiness checklist (ONLY for Active Sprint stories)
10
+ 6b. **§5b Open Questions**: Operational questions that may block active sprint stories
11
+ 7. **§6 Completed Sprints**: ONE-LINE summaries of finished sprints (full detail in version history)
12
+ 8. **§7 Change Log**: Auto-appended on updates
13
+
14
+ Sprint Lifecycle:
15
+ - When a sprint completes: update Sprint Registry row to "Completed",
16
+ REPLACE §3 Active Sprint with the next sprint's stories,
17
+ move old sprint summary to §6 Completed Sprints (one row, not full detail).
18
+ - Full historical detail is preserved in vp_document_versions (auto-snapshots on every update).
19
+
20
+ Sprint States: Planning → Active → Completed → Cancelled
21
+
22
+ Story Labels (complexity_label):
23
+ - L1: Trivial (single file, <1hr vibe time)
24
+ - L2: Standard (2-3 files, known pattern) — DEFAULT
25
+ - L3: Complex (cross-cutting, spike may be needed)
26
+ - L4: Uncertain (requires Probing/Spiking before Bounce)
27
+
28
+ V-Bounce States (11 total):
29
+ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
30
+ ↳ Refinement → Probing/Spiking → Refinement (spike loop)
31
+ ↳ Any → Parking Lot (deferred)
32
+ ↳ Bouncing → Escalated (3+ failures)
33
+
34
+ IMPORTANT: The §2 Sprint Registry is auto-populated by SyncEngine.
35
+ Rows between <!-- SPRINT_REGISTRY_START --> and <!-- SPRINT_REGISTRY_END -->
36
+ markers MUST be on their own lines (not inside table pipes).
37
+
38
+ Output location: `product_plans/{delivery}/DELIVERY_PLAN.md`
39
+ (Lives at the root of its delivery folder. One Delivery Plan per delivery/release.)
40
+
41
+ Document Hierarchy Position: LEVEL 5 — EXECUTION
42
+ Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → **Delivery Plan** (execution) → Risk Registry (risks)
43
+
44
+ This is the OPERATIONAL layer. It does NOT define what to build (that's Roadmap + Epic).
45
+ It defines WHEN and in WHAT ORDER stories execute within sprints.
46
+
47
+ Upstream sources:
48
+ - Stories come from Epics (via Epic §9 Artifact Links)
49
+ - Sprint goals align with Roadmap §2 Release Plan milestones
50
+ - Story complexity labels (L1-L4) are defined in the Story template
51
+
52
+ Downstream consumers:
53
+ - Team Lead Agent reads this to initialize the Bounce (via agent-team skill)
54
+ - §5 Context Pack Status gates whether a story is Ready to Bounce
55
+ - Sprint Reports are generated from Active Sprint data + agent reports
56
+ - Risk Registry §2 Risk Analysis Log references sprint transitions
57
+
58
+ Do NOT output these instructions.
59
+ </instructions>
60
+
61
+ # Delivery Plan: {Project Name}
62
+
63
+ ---
64
+
65
+ > **Last Updated**: {YYYY-MM-DD}
66
+ > **Status**: Planning / In Sprint / Delivered
67
+ > **Roadmap**: `product_plans/{project}_roadmap.md`
68
+ > **Risk Registry**: `product_plans/RISK_REGISTRY.md`
69
+ > **Delivery**: `D-{NN}_{release_name}`
70
+ > **Sprint Cadence**: 1-week sprints within 2-week project window
71
+
72
+ ---
73
+
74
+ ## 1. Project Window
75
+
76
+ | Key | Value |
77
+ |-----|-------|
78
+ | **Start Date** | {YYYY-MM-DD} |
79
+ | **End Date** | {YYYY-MM-DD} |
80
+ | **Total Sprints** | {N} |
81
+ | **Sprint Length** | 1 week |
82
+ | **Project Window** | 2 weeks |
83
+ | **Team** | {CE name(s) / Agent config} |
84
+
85
+ ---
86
+
87
+ ## 2. Sprint Registry
88
+
89
+ <!--
90
+ AUTO-POPULATED SECTION
91
+ Updated when sprints are created or completed.
92
+ DO NOT manually edit the table rows - they are managed by the system.
93
+ -->
94
+
95
+ | Sprint | Dates | Sprint Goal | Status | Stories | Completed |
96
+ |--------|-------|-------------|--------|---------|-----------|
97
+ <!-- SPRINT_REGISTRY_START -->
98
+ | S-01 | {MM/DD - MM/DD} | {One-sentence North Star} | Planning / Active / Completed | {X} | {Y}/{X} |
99
+ <!-- SPRINT_REGISTRY_END -->
100
+
101
+ ---
102
+
103
+ ## 3. Active Sprint
104
+
105
+ ### Sprint Goal
106
+ > {One-sentence functional "North Star" — what is shippable at the end of this sprint?}
107
+
108
+ ### Assigned Stories
109
+
110
+ | # | Story | Epic | Label | V-Bounce State | Context Pack |
111
+ |---|-------|------|-------|----------------|--------------|
112
+ | 1 | STORY-XXX-YY: {name} | EPIC-XXX | L1/L2/L3/L4 | Draft / Refinement / Ready to Bounce / Bouncing | Locked / Open |
113
+
114
+ ### Sprint Notes
115
+ - {Blockers, dependencies, decisions made during the sprint}
116
+
117
+ ---
118
+
119
+ ## 4. Backlog
120
+
121
+ > Prioritized stories not yet assigned to a sprint.
122
+
123
+ | Priority | Story | Epic | Label | V-Bounce State | Blocker |
124
+ |----------|-------|------|-------|----------------|---------|
125
+ | 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | Draft | — |
126
+
127
+ ### Escalated
128
+ > Stories with 3+ bounce failures requiring PM/BA intervention.
129
+
130
+ | Story | Epic | Bounce Count | Escalation Reason |
131
+ |-------|------|--------------|-------------------|
132
+ | — | — | — | No escalated stories |
133
+
134
+ ### Parking Lot
135
+ > Stories moved out of current project window scope (V-Bounce state: Parking Lot).
136
+
137
+ - STORY-XXX-YY: {name} — Reason: {why deferred}
138
+
139
+ ---
140
+
141
+ ## 5. Context Pack Status
142
+
143
+ > Tracks readiness of ACTIVE SPRINT stories only.
144
+ > A story is **Ready to Bounce** only when all items are checked.
145
+ > Context Packs for future sprints are tracked when they enter the Active Sprint.
146
+ > L4 stories MUST pass through Probing/Spiking before reaching Ready to Bounce.
147
+
148
+ ### {STORY-XXX-YY}: {name} (Label: {L1/L2/L3/L4})
149
+ - [ ] Story spec complete (§1 The Spec)
150
+ - [ ] Acceptance criteria written (§2 The Truth)
151
+ - [ ] Implementation guide filled (§3 Implementation Guide)
152
+ - [ ] Ambiguity: Low
153
+ - [ ] BA sign-off
154
+ - [ ] Architect sign-off
155
+ - [ ] Spike completed (L4 only — skip for L1-L3)
156
+ - **V-Bounce State**: {current state} → Ready to Bounce
157
+
158
+ ---
159
+
160
+ ## 5b. Open Questions
161
+
162
+ > Operational questions that may block stories in the active sprint.
163
+ > Strategic questions belong in the Roadmap §6.
164
+ > The Team Lead MUST check this section before starting a sprint — do NOT bounce stories with unresolved blocking questions.
165
+
166
+ | Question | Affects Story | Impact | Owner | Status |
167
+ |----------|--------------|--------|-------|--------|
168
+ | {e.g., "Which date format for the API?"} | STORY-001-02 | Blocks implementation | {name} | Open / Resolved |
169
+
170
+ ---
171
+
172
+ ## 6. Completed Sprints
173
+
174
+ > One-line summaries only. Full detail preserved in document version history.
175
+
176
+ | Sprint | Goal | Delivered | Notes |
177
+ |--------|------|-----------|-------|
178
+ | — | — | — | No sprints completed yet |
179
+
180
+ ---
181
+
182
+ ## 7. Change Log
183
+
184
+ <!-- Auto-appended when Delivery Plan is updated -->
185
+
186
+ | Date | Change | By |
187
+ |------|--------|-----|
188
+ | {YYYY-MM-DD} | Initial creation from Roadmap | Architect |
@@ -0,0 +1,200 @@
1
+ <instructions>
2
+ FOLLOW THIS EXACT STRUCTURE. Output sections in order.
3
+
4
+ 1. **Metadata Table**: Status, Ambiguity, Priority, Owner, Tags, Target Date
5
+ 2. **§1 Problem & Value**: Why (problem), What (solution), Success Metrics
6
+ 3. **§2 Scope Boundaries**: IN-SCOPE checkboxes, OUT-OF-SCOPE list
7
+ 4. **§3 Context**: Personas, User Journey diagram, Constraints table
8
+ 5. **§4 Technical Context**: Affected files, Dependencies, Integrations, Data changes
9
+ 6. **§5 Decomposition Guidance**: Story categories checklist + suggested sequence
10
+ 7. **§6 Risks & Edge Cases**: Risk table with mitigations
11
+ 8. **§7 Acceptance Criteria**: Gherkin scenarios (happy path + error case)
12
+ 9. **§8 Open Questions**: Blocking decisions table
13
+ 10. **§9 Artifact Links**: Stories list + references
14
+
15
+ Ambiguity Score:
16
+ - 🔴 High: Scope unclear → Needs refinement
17
+ - 🟡 Medium: Scope clear, tech TBD → Ready for decomposition
18
+ - 🟢 Low: All filled → Ready for Stories
19
+
20
+ Output location: `product_plans/{delivery}/EPIC-{NNN}_{epic_name}/EPIC-{NNN}.md`
21
+
22
+ Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
23
+
24
+ Upstream sources:
25
+ - §1 Problem & Value traces to Charter §1.1 (What It Is) and §5 (Key Workflows)
26
+ - §3.3 Constraints inherits from Charter §6 and Roadmap §5 Strategic Constraints
27
+ - §4 Technical Context references Roadmap §3 ADRs for architecture decisions
28
+ - Metadata.Priority aligns with Roadmap §2 Release Plan epic priorities
29
+
30
+ Downstream consumers:
31
+ - Stories are decomposed from §5 Decomposition Guidance
32
+ - Story §1 The Spec inherits from Epic §2 Scope Boundaries
33
+ - Story §3 Implementation Guide references Epic §4 Technical Context
34
+ - Delivery Plan §3 Active Sprint pulls stories linked in §9 Artifact Links
35
+ - Risk Registry §1 Active Risks may reference Epic §6 Risks
36
+
37
+ Do NOT output these instructions.
38
+ </instructions>
39
+
40
+ # EPIC-{ID}: {Epic Name}
41
+
42
+ ## Metadata
43
+ | Field | Value |
44
+ |-------|-------|
45
+ | **Status** | Draft / Ready / In Progress / Done |
46
+ | **Ambiguity** | 🔴 High / 🟡 Medium / 🟢 Low |
47
+ | **Context Source** | Charter §{section} / Roadmap §{section} / User Input |
48
+ | **Release** | {Release name from Roadmap §2} |
49
+ | **Owner** | {PM/PO name} |
50
+ | **Priority** | P0 - Critical / P1 - High / P2 - Medium |
51
+ | **Tags** | #frontend, #api, #auth |
52
+ | **Target Date** | {YYYY-MM-DD} |
53
+
54
+ ---
55
+
56
+ ## 1. Problem & Value
57
+ > Target Audience: Stakeholders, Business Sponsors
58
+
59
+ ### 1.1 The Problem
60
+ > 1-2 sentences. Why are we doing this?
61
+
62
+ ### 1.2 The Solution
63
+ > High-level what we're building.
64
+
65
+ ### 1.3 Success Metrics (North Star)
66
+ - {Measurable outcome 1}
67
+ - {Measurable outcome 2}
68
+
69
+ ---
70
+
71
+ ## 2. Scope Boundaries
72
+ > Target Audience: AI Agents (Critical for preventing hallucinations)
73
+
74
+ ### ✅ IN-SCOPE (Build This)
75
+ - [ ] {Capability 1}
76
+ - [ ] {Capability 2}
77
+ - [ ] {Capability 3}
78
+
79
+ ### ❌ OUT-OF-SCOPE (Do NOT Build This)
80
+ - {Explicitly excluded capability}
81
+ - {Deferred to EPIC-XXX}
82
+
83
+ ---
84
+
85
+ ## 3. Context
86
+
87
+ ### 3.1 User Personas
88
+ - **{Persona A}**: {Role} - {Primary Goal}
89
+ - **{Persona B}**: {Role} - {Primary Goal}
90
+
91
+ ### 3.2 User Journey (Happy Path)
92
+ ```mermaid
93
+ flowchart LR
94
+ A[User Action] --> B[System Response] --> C[Success State]
95
+ ```
96
+
97
+ ### 3.3 Constraints
98
+ | Type | Constraint |
99
+ |------|------------|
100
+ | **Performance** | {e.g., Must complete in < 200ms} |
101
+ | **Security** | {e.g., GDPR compliant, no PII logging} |
102
+ | **Tech Stack** | {e.g., Must use existing UserAPI v2} |
103
+
104
+ ---
105
+
106
+ ## 4. Technical Context
107
+ > Target Audience: AI Agents - READ THIS before decomposing.
108
+
109
+ ### 4.1 Affected Areas
110
+ | Area | Files/Modules | Change Type |
111
+ |------|---------------|-------------|
112
+ | API | `src/api/{file}.ts` | New / Modify |
113
+ | Database | `prisma/schema.prisma` | Add table / Modify |
114
+ | UI | `src/components/` | New component |
115
+ | Config | `.env`, `config/` | Add vars |
116
+
117
+ ### 4.2 Dependencies
118
+ | Type | Dependency | Status |
119
+ |------|------------|--------|
120
+ | **Requires** | EPIC-{ID}: {name} | Done / In Progress / Blocked |
121
+ | **Unlocks** | EPIC-{ID}: {name} | Waiting |
122
+
123
+ ### 4.3 Integration Points
124
+ | System | Purpose | Docs |
125
+ |--------|---------|------|
126
+ | {External API} | {what we use it for} | {link} |
127
+
128
+ ### 4.4 Data Changes
129
+ | Entity | Change | Fields |
130
+ |--------|--------|--------|
131
+ | {Entity} | NEW | id, name, ... |
132
+ | {Entity} | MODIFY | + new_field |
133
+
134
+ ---
135
+
136
+ ## 5. Decomposition Guidance
137
+ > Hints for AI story breakdown. Check all that apply.
138
+
139
+ - [ ] **Schema/Migration** - Database changes, new tables/fields
140
+ - [ ] **API Work** - New/modified endpoints
141
+ - [ ] **UI Work** - New screens or components
142
+ - [ ] **Integration** - External service connection
143
+ - [ ] **Infrastructure** - Config, env vars, deployment
144
+ - [ ] **Testing** - E2E, integration tests
145
+ - [ ] **Documentation** - User-facing or API docs
146
+
147
+ ### Suggested Story Sequence
148
+ 1. {First: usually schema/data layer}
149
+ 2. {Then: API/backend layer}
150
+ 3. {Then: UI/frontend layer}
151
+ 4. {Finally: integration + E2E tests}
152
+
153
+ ---
154
+
155
+ ## 6. Risks & Edge Cases
156
+ | Risk | Likelihood | Mitigation |
157
+ |------|------------|------------|
158
+ | {e.g., Email delivery delay} | Medium | {e.g., "Resend" button after 30s} |
159
+ | {e.g., Rate limiting hit} | Low | {e.g., Exponential backoff} |
160
+
161
+ ---
162
+
163
+ ## 7. Acceptance Criteria (Epic-Level)
164
+ > How do we know the EPIC is complete? Full user flow.
165
+
166
+ ```gherkin
167
+ Feature: {Epic Name}
168
+
169
+ Scenario: Complete Happy Path
170
+ Given {precondition - user state}
171
+ When {user completes full flow}
172
+ Then {end-to-end outcome achieved}
173
+ And {data persisted correctly}
174
+
175
+ Scenario: Key Error Case
176
+ Given {precondition}
177
+ When {error condition}
178
+ Then {graceful handling}
179
+ ```
180
+
181
+ ---
182
+
183
+ ## 8. Open Questions
184
+ | Question | Options | Impact | Owner | Status |
185
+ |----------|---------|--------|-------|--------|
186
+ | {decision needed} | A: {x}, B: {y} | Blocks {stories X,Y} | {name} | Open / Decided |
187
+
188
+ ---
189
+
190
+ ## 9. Artifact Links
191
+ > Auto-populated as Epic is decomposed.
192
+
193
+ **Stories:**
194
+ - [ ] STORY-{ID}-01: {name}
195
+ - [ ] STORY-{ID}-02: {name}
196
+
197
+ **References:**
198
+ - Charter: [PROJECT CHARTER](link)
199
+ - Design: {link}
200
+ - API Spec: {link}