@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.
- package/README.md +107 -0
- package/bin/vbounce.mjs +165 -0
- package/brains/AGENTS.md +129 -0
- package/brains/CLAUDE.md +146 -0
- package/brains/GEMINI.md +134 -0
- package/brains/SETUP.md +180 -0
- package/brains/claude-agents/architect.md +140 -0
- package/brains/claude-agents/developer.md +69 -0
- package/brains/claude-agents/devops.md +219 -0
- package/brains/claude-agents/qa.md +112 -0
- package/brains/claude-agents/scribe.md +141 -0
- package/brains/cursor-rules/vbounce-docs.mdc +41 -0
- package/brains/cursor-rules/vbounce-process.mdc +45 -0
- package/brains/cursor-rules/vbounce-rules.mdc +26 -0
- package/package.json +40 -0
- package/skills/agent-team/SKILL.md +425 -0
- package/skills/doc-manager/SKILL.md +278 -0
- package/skills/lesson/SKILL.md +90 -0
- package/skills/react-best-practices/SKILL.md +3014 -0
- package/skills/react-best-practices/rules/_sections.md +46 -0
- package/skills/react-best-practices/rules/_template.md +28 -0
- package/skills/react-best-practices/rules/advanced-event-handler-refs.md +55 -0
- package/skills/react-best-practices/rules/advanced-init-once.md +42 -0
- package/skills/react-best-practices/rules/advanced-use-latest.md +39 -0
- package/skills/react-best-practices/rules/async-api-routes.md +38 -0
- package/skills/react-best-practices/rules/async-defer-await.md +80 -0
- package/skills/react-best-practices/rules/async-dependencies.md +51 -0
- package/skills/react-best-practices/rules/async-parallel.md +28 -0
- package/skills/react-best-practices/rules/async-suspense-boundaries.md +99 -0
- package/skills/react-best-practices/rules/bundle-barrel-imports.md +59 -0
- package/skills/react-best-practices/rules/bundle-conditional.md +31 -0
- package/skills/react-best-practices/rules/bundle-defer-third-party.md +49 -0
- package/skills/react-best-practices/rules/bundle-dynamic-imports.md +35 -0
- package/skills/react-best-practices/rules/bundle-preload.md +50 -0
- package/skills/react-best-practices/rules/client-event-listeners.md +74 -0
- package/skills/react-best-practices/rules/client-localstorage-schema.md +71 -0
- package/skills/react-best-practices/rules/client-passive-event-listeners.md +48 -0
- package/skills/react-best-practices/rules/client-swr-dedup.md +56 -0
- package/skills/react-best-practices/rules/js-batch-dom-css.md +107 -0
- package/skills/react-best-practices/rules/js-cache-function-results.md +80 -0
- package/skills/react-best-practices/rules/js-cache-property-access.md +28 -0
- package/skills/react-best-practices/rules/js-cache-storage.md +70 -0
- package/skills/react-best-practices/rules/js-combine-iterations.md +32 -0
- package/skills/react-best-practices/rules/js-early-exit.md +50 -0
- package/skills/react-best-practices/rules/js-hoist-regexp.md +45 -0
- package/skills/react-best-practices/rules/js-index-maps.md +37 -0
- package/skills/react-best-practices/rules/js-length-check-first.md +49 -0
- package/skills/react-best-practices/rules/js-min-max-loop.md +82 -0
- package/skills/react-best-practices/rules/js-set-map-lookups.md +24 -0
- package/skills/react-best-practices/rules/js-tosorted-immutable.md +57 -0
- package/skills/react-best-practices/rules/rendering-activity.md +26 -0
- package/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md +47 -0
- package/skills/react-best-practices/rules/rendering-conditional-render.md +40 -0
- package/skills/react-best-practices/rules/rendering-content-visibility.md +38 -0
- package/skills/react-best-practices/rules/rendering-hoist-jsx.md +46 -0
- package/skills/react-best-practices/rules/rendering-hydration-no-flicker.md +82 -0
- package/skills/react-best-practices/rules/rendering-hydration-suppress-warning.md +30 -0
- package/skills/react-best-practices/rules/rendering-svg-precision.md +28 -0
- package/skills/react-best-practices/rules/rendering-usetransition-loading.md +75 -0
- package/skills/react-best-practices/rules/rerender-defer-reads.md +39 -0
- package/skills/react-best-practices/rules/rerender-dependencies.md +45 -0
- package/skills/react-best-practices/rules/rerender-derived-state-no-effect.md +40 -0
- package/skills/react-best-practices/rules/rerender-derived-state.md +29 -0
- package/skills/react-best-practices/rules/rerender-functional-setstate.md +74 -0
- package/skills/react-best-practices/rules/rerender-lazy-state-init.md +58 -0
- package/skills/react-best-practices/rules/rerender-memo-with-default-value.md +38 -0
- package/skills/react-best-practices/rules/rerender-memo.md +44 -0
- package/skills/react-best-practices/rules/rerender-move-effect-to-event.md +45 -0
- package/skills/react-best-practices/rules/rerender-simple-expression-in-memo.md +35 -0
- package/skills/react-best-practices/rules/rerender-transitions.md +40 -0
- package/skills/react-best-practices/rules/rerender-use-ref-transient-values.md +73 -0
- package/skills/react-best-practices/rules/server-after-nonblocking.md +73 -0
- package/skills/react-best-practices/rules/server-auth-actions.md +96 -0
- package/skills/react-best-practices/rules/server-cache-lru.md +41 -0
- package/skills/react-best-practices/rules/server-cache-react.md +76 -0
- package/skills/react-best-practices/rules/server-dedup-props.md +65 -0
- package/skills/react-best-practices/rules/server-parallel-fetching.md +83 -0
- package/skills/react-best-practices/rules/server-serialization.md +38 -0
- package/skills/vibe-code-review/SKILL.md +70 -0
- package/skills/vibe-code-review/references/deep-audit.md +259 -0
- package/skills/vibe-code-review/references/pr-review.md +234 -0
- package/skills/vibe-code-review/references/quick-scan.md +178 -0
- package/skills/vibe-code-review/references/report-template.md +189 -0
- package/skills/vibe-code-review/references/trend-check.md +224 -0
- package/skills/vibe-code-review/scripts/generate-snapshot.sh +89 -0
- package/skills/vibe-code-review/scripts/pr-analyze.sh +180 -0
- package/skills/write-skill/SKILL.md +133 -0
- package/templates/charter.md +144 -0
- package/templates/delivery_plan.md +188 -0
- package/templates/epic.md +200 -0
- package/templates/hotfix.md +57 -0
- package/templates/risk_registry.md +89 -0
- package/templates/roadmap.md +176 -0
- package/templates/sprint_report.md +151 -0
- 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}
|