ultra-builder-pro-cli 0.10.0 → 0.12.1

package/skills/ultra-research/steps/step-20-user-stories.md

@@ -1,156 +0,0 @@
-# Step 20: User Stories & Acceptance Criteria
-
-## MANDATORY EXECUTION RULES
-
-- DERIVE stories from scenarios (step-11) — not invented from thin air
-- EVERY story has acceptance criteria — no story ships without testable conditions
-- USE standard format: "As a [persona], I want [action], so that [benefit]"
-- PRIORITIZE using MoSCoW: Must / Should / Could / Won't
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Step 11 (User Scenarios) completed with [C]
-- `.ultra/specs/product.md` §1-3 exist
-
-## CONTEXT BOUNDARIES
-
-- Focus: What specific capabilities does the product need?
-- Stories must trace back to scenarios and personas
-- This is about WHAT the product does, not HOW it's built
-- Acceptance criteria must be testable and specific
-
-## EXECUTION SEQUENCE
-
-### 1. Extract Stories from Scenarios
-
-For each scenario from step-11, decompose into user stories:
-
-**Mapping**: Scenario → Stories
-- S1 (highest priority scenario) → 3-5 stories
-- S2 → 2-4 stories
-- S3 → 2-3 stories
-- Total: 8-15 stories for MVP
-
-### 2. Write Stories with Acceptance Criteria
-
-For each story:
-
-```
-As a [Persona Name],
-I want [specific action],
-so that [measurable benefit].
-
-Acceptance Criteria:
-- Given [context], when [action], then [expected result]
-- Given [context], when [edge case], then [expected result]
-- [Performance requirement if applicable]
-```
-
-### 3. Prioritize with MoSCoW
-
-Discuss with user via AskUserQuestion:
-"Here are the stories I've derived from our scenarios. For MVP, which are Must-Have vs Nice-to-Have?"
-
-| Priority | Definition | Guidance |
-|----------|-----------|---------|
-| **Must** | Product is useless without this | Blocks primary scenario |
-| **Should** | Important but workaround exists | Enhances primary scenario |
-| **Could** | Nice to have if time allows | Supports secondary scenarios |
-| **Won't** | Explicitly excluded for now | Out of scope (with rationale) |
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §4:
-
-```markdown
-## §4 User Stories & Features
-
-### Story Map Overview
-
-| ID | Story | Persona | Scenario | Priority | Complexity |
-|----|-------|---------|----------|----------|-----------|
-| US-01 | [Short title] | [P1] | S1 | Must | [S/M/L] |
-| US-02 | [Short title] | [P1] | S1 | Must | [S/M/L] |
-| US-03 | [Short title] | [P1] | S2 | Must | [S/M/L] |
-| US-04 | [Short title] | [P2] | S2 | Should | [S/M/L] |
-| ... | ... | ... | ... | ... | ... |
-
-### Must-Have Stories
-
-#### US-01: [Title]
-**As a** [Persona], **I want** [action], **so that** [benefit].
-
-**Acceptance Criteria**:
-- [ ] Given [context], when [action], then [result]
-- [ ] Given [context], when [edge case], then [result]
-- [ ] [Performance: response time < Xms]
-
-**Traces to**: Scenario [S#], Opportunity [O#]
-**Complexity**: [S/M/L] — [Brief rationale]
-
-#### US-02: [Title]
-[Same structure]
-
-#### US-03: [Title]
-[Same structure]
-
-### Should-Have Stories
-
-#### US-04: [Title]
-[Same structure]
-
-### Could-Have Stories
-
-#### US-07: [Title]
-[Same structure]
-
-### Story Statistics
-- **Total stories**: [N]
-- **Must-have**: [N] ([X]%)
-- **Should-have**: [N] ([X]%)
-- **Could-have**: [N] ([X]%)
-- **Traceability**: [X]% of stories trace to scenarios
-```
-
-### 5. Present to User and Gate
-
-Show the User Stories summary. Ask:
-- Are the Must-Have stories correct?
-- Any stories missing?
-- Are acceptance criteria testable?
-
-```
-[C] Continue — Stories validated, proceed to Features & Scope
-[R] Revise — Adjust stories, priorities, or acceptance criteria
-[A] Add — Include additional stories
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 6. Handle Response
-
-- **[C]**: Load next step: `./step-21-features-scope.md`
-- **[R]**: Revise stories, update product.md §4, re-present
-- **[A]**: Add stories, update, re-present
-
-## SUCCESS METRICS
-
-- 8-15 user stories derived from scenarios
-- Every story has testable acceptance criteria
-- MoSCoW prioritization applied with user input
-- Stories trace back to scenarios and personas
-- Output written to product.md §4
-
-## FAILURE MODES
-
-- Stories not connected to any scenario
-- Acceptance criteria are vague ("it should work well")
-- All stories are Must-Have (no real prioritization happened)
-- Too many stories (>20 for MVP — scope creep)
-- Not writing output before presenting to user
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-21-features-scope.md`

package/skills/ultra-research/steps/step-21-features-scope.md

@@ -1,157 +0,0 @@
-# Step 21: Features & Scope Definition
-
-## MANDATORY EXECUTION RULES
-
-- EXPLICITLY DEFINE what is OUT of scope — this prevents scope creep
-- GROUP stories into features — features are implementable units
-- EVERY exclusion needs a RATIONALE — "not now" is not enough
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Step 20 (User Stories) completed with [C]
-- `.ultra/specs/product.md` §1-4 exist
-
-## CONTEXT BOUNDARIES
-
-- Focus: Group stories into features, define scope boundaries
-- Features are clusters of related stories that deliver a capability
-- "Features Out" is as important as "Features In"
-- Reference step-04 (Strategic Trade-offs) for scope decisions
-
-## EXECUTION SEQUENCE
-
-### 1. Group Stories into Features
-
-Cluster related user stories into features:
-
-```
-Feature A: [Name]
-├── US-01: [Story]
-├── US-02: [Story]
-└── US-03: [Story]
-
-Feature B: [Name]
-├── US-04: [Story]
-└── US-05: [Story]
-```
-
-Each feature should be:
-- Independently valuable (delivers user value on its own)
-- Estimable (can assess complexity)
-- Testable (can verify it works end-to-end)
-
-### 2. Define Scope Boundaries
-
-For each potential feature, classify:
-
-| Classification | Meaning |
-|---------------|---------|
-| **In scope (MVP)** | Must-have stories, ships in v1 |
-| **In scope (v2)** | Should-have stories, planned for later |
-| **Out of scope** | Won't build — with explicit rationale |
-
-### 3. Document "Features Out"
-
-For each excluded feature, document:
-- What it is
-- Why it's excluded (reference strategic trade-offs from step-04)
-- When it might be reconsidered
-- What users should do instead
-
-This prevents:
-- Future scope creep ("but we said we'd do X")
-- Re-debating settled decisions
-- Building things that conflict with strategy
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §5:
-
-```markdown
-## §5 Feature Scope
-
-### Features In (MVP)
-
-#### Feature 1: [Name]
-- **Description**: [What this feature does]
-- **Stories**: US-01, US-02, US-03
-- **User value**: [What user can do with this]
-- **Priority**: Must-Have
-- **Complexity**: [S/M/L]
-
-#### Feature 2: [Name]
-- **Description**: [What this feature does]
-- **Stories**: US-04, US-05
-- **User value**: [What user can do with this]
-- **Priority**: Must-Have
-- **Complexity**: [S/M/L]
-
-#### Feature 3: [Name]
-[Same structure]
-
-### Features In (v2 — Planned)
-
-#### Feature 4: [Name]
-- **Description**: [What this feature does]
-- **Stories**: US-07, US-08
-- **Rationale for deferral**: [Why not MVP]
-- **Trigger to build**: [When to reconsider]
-
-### Features Out (Explicitly Excluded)
-
-| Feature | Rationale | Reconsider When | Alternative |
-|---------|-----------|----------------|-------------|
-| [Feature X] | [Why excluded — reference strategy §4] | [Condition] | [What users do instead] |
-| [Feature Y] | [Why excluded] | [Condition] | [Alternative] |
-| [Feature Z] | [Why excluded] | [Condition] | [Alternative] |
-
-### Scope Summary
-- **MVP features**: [N] features, [N] stories
-- **v2 features**: [N] features, [N] stories
-- **Excluded features**: [N] features
-- **Scope confidence**: [X]%
-```
-
-### 5. Present to User and Gate
-
-Show the Feature Scope summary. Ask:
-- Is the MVP scope right? Too big? Too small?
-- Are the exclusions correct?
-- Any missing features?
-
-```
-[C] Continue — Scope locked, proceed to Success Metrics
-[R] Revise — Adjust feature grouping or scope boundaries
-[E] Expand — Move something from v2 to MVP
-[T] Trim — Move something from MVP to v2
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 6. Handle Response
-
-- **[C]**: Load next step: `./step-22-success-metrics.md`
-- **[R]**: Revise features, update product.md §5, re-present
-- **[E]/[T]**: Adjust scope, update, re-present
-
-## SUCCESS METRICS
-
-- Stories grouped into coherent features
-- Clear MVP vs v2 scope boundary
-- Every exclusion has a rationale and reconsideration trigger
-- Features trace to user stories and scenarios
-- Output written to product.md §5
-
-## FAILURE MODES
-
-- No "Features Out" section (everything is in scope)
-- Features that don't map to any user stories
-- Exclusion rationale is just "not now" (needs specific reason)
-- MVP scope is too large (>5-7 features for a first version)
-- Not writing output before presenting to user
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-22-success-metrics.md`

package/skills/ultra-research/steps/step-22-success-metrics.md

@@ -1,195 +0,0 @@
-# Step 22: Success Metrics
-
-## MANDATORY EXECUTION RULES
-
-- EVERY METRIC must have a specific numerical TARGET — not "improve X"
-- INCLUDE both business AND user metrics
-- DEFINE how each metric is MEASURED — not just what to measure
-- BASELINE required — you can't improve what you haven't measured
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Step 21 (Features & Scope) completed with [C]
-- `.ultra/specs/product.md` §1-5 exist
-
-## CONTEXT BOUNDARIES
-
-- Focus: How will we know if this product is succeeding?
-- Metrics must be measurable, specific, and time-bound
-- Connect metrics to strategic goals from step-04
-- This is the LAST step of Round 2
-
-## SEARCH STRATEGY (MANDATORY)
-
-Execute these web searches:
-
-```
-Search: "{{product_domain}} key metrics KPIs benchmarks"
-Search: "{{product_domain}} SaaS metrics success benchmarks"
-Search: "{{product_domain}} user engagement retention benchmarks"
-Search: "{{product_domain}} north star metric examples"
-```
-
-## EXECUTION SEQUENCE
-
-### 1. Define North Star Metric
-
-Ask user via AskUserQuestion:
-"What single metric best captures whether this product is delivering value? (e.g., 'Weekly active workflows completed', 'Time saved per user per week')"
-
-The North Star Metric should:
-- Reflect core value delivery
-- Be leading (not lagging)
-- Be actionable (team can influence it)
-
-### 2. Define Business Metrics
-
-| Metric | What to define |
-|--------|---------------|
-| Revenue/adoption targets | Month 1, 3, 6, 12 |
-| Growth rate | MoM or WoW targets |
-| Retention | Day 1, Day 7, Day 30 |
-| Conversion | Free → Paid (if applicable) |
-| Unit economics | CAC, LTV, LTV/CAC ratio |
-
-Use web search benchmarks for realistic targets.
-
-### 3. Define User Metrics
-
-| Metric | What to define |
-|--------|---------------|
-| Task completion | Success rate for key scenarios |
-| Time on task | vs baseline (current workflow) |
-| User satisfaction | NPS or CSAT target |
-| Feature adoption | % of users using key features |
-| Error rate | Failure frequency |
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §6:
-
-```markdown
-## §6 Success Metrics
-
-### North Star Metric
-- **Metric**: [Name]
-- **Definition**: [Exactly what is measured]
-- **Current baseline**: [Current state or industry benchmark]
-- **Target**: [Specific number]
-- **Timeline**: [When to achieve]
-- **Measurement method**: [How to collect this data]
-
-### Business Metrics
-
-| Metric | Baseline | Target (M3) | Target (M6) | Target (M12) | How Measured |
-|--------|----------|-------------|-------------|--------------|-------------|
-| [Revenue/Users] | [N/A or current] | [Target] | [Target] | [Target] | [Method] |
-| [Growth rate] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
-| [Retention D30] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
-| [Conversion] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
-
-_Benchmark sources: [URLs]_
-
-### User Metrics
-
-| Metric | Baseline | Target | How Measured |
-|--------|----------|--------|-------------|
-| Task completion rate | [Current %] | [Target %] | [Method] |
-| Time on task | [Current min] | [Target min] | [Method] |
-| User satisfaction (NPS) | [Industry avg] | [Target] | [Survey] |
-| Feature adoption | [N/A] | [Target %] | [Analytics] |
-| Error rate | [Current %] | [Target %] | [Logging] |
-
-### Metric Prioritization
-
-| Priority | Metric | Why |
-|----------|--------|-----|
-| P0 (check daily) | [North Star] | [Core value signal] |
-| P0 (check daily) | [Critical metric] | [Business health] |
-| P1 (check weekly) | [Important metric] | [Growth signal] |
-| P2 (check monthly) | [Supporting metric] | [Quality signal] |
-
-### Anti-Metrics (What NOT to Optimize)
-
-| Anti-Metric | Why Not | What It Could Sacrifice |
-|------------|---------|------------------------|
-| [e.g., Page views] | [Vanity metric] | [Could sacrifice quality for clicks] |
-| [e.g., Time in app] | [Could mean confusion] | [Could sacrifice efficiency] |
-
-### Round 2 Summary
-
-**Feature Definition Confidence**:
-- **Story completeness**: [X]% — [One-line assessment]
-- **Scope clarity**: [X]% — [One-line assessment]
-- **Metric measurability**: [X]% — [One-line assessment]
-- **Overall R2 confidence**: [X]%
-```
-
-### 5. Write Round 2 Research Report
-
-**WRITE** to `.ultra/docs/research/feature-definition-{date}.md`:
-
-```markdown
-# Round 2: Feature Definition
-
-> **Confidence**: [X]%
-> **Steps completed**: 20-22
-> **Completed**: [date]
-
-## Key Findings
-[3-5 bullet points]
-
-## Stories Created
-[Count by priority: Must/Should/Could]
-
-## Scope Decisions
-[Key inclusions and exclusions]
-
-## Metrics Defined
-[North Star + top 3 metrics]
-```
-
-### 6. Present to User and Gate
-
-Show the Success Metrics summary. Ask:
-- Are the targets realistic?
-- Is the North Star metric right?
-- Any metrics missing?
-
-```
-[C] Continue — Metrics defined, proceed to Round 3 (Architecture Design)
-[R] Revise — Adjust targets or metrics
-[D] Discuss — Explore specific metric benchmarks
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 7. Handle Response
-
-- **[C]**: Load next step: `./step-30-architecture-context.md`
-- **[R]**: Revise metrics, update product.md §6, re-present
-- **[D]**: Deep-dive specific benchmarks, then re-present gate
-
-## SUCCESS METRICS
-
-- North Star metric defined with baseline and target
-- Business metrics have specific targets at M3/M6/M12
-- User metrics have baselines and targets
-- Benchmark sources cited from web search
-- Anti-metrics defined (what NOT to optimize)
-- Round 2 research report written
-- Output written to product.md §6
-
-## FAILURE MODES
-
-- Metrics without specific targets ("improve retention")
-- No baseline or benchmark for comparison
-- Only business metrics, no user metrics (or vice versa)
-- Unrealistic targets (100% retention, 0% error rate)
-- Not writing output before presenting to user
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-30-architecture-context.md`

package/skills/ultra-research/steps/step-30-architecture-context.md

@@ -1,154 +0,0 @@
-# Step 30: Architecture Context
-
-## MANDATORY EXECUTION RULES
-
-- WEB SEARCH REQUIRED — verify technology claims against official docs
-- USE Context7 MCP for framework/library documentation lookups
-- ARCHITECTURE FOLLOWS PRODUCT — decisions must trace to product requirements
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Round 2 completed (steps 20-22) with [C], OR user chose "Architecture Change" starting at step-30
-- `.ultra/specs/architecture.md` exists
-
-## CONTEXT BOUNDARIES
-
-- Focus: Quality goals, constraints, and system context (arc42 §1-3)
-- Decisions must be grounded in product requirements from product.md
-- This is about WHAT the system must achieve, not HOW to build it (that's step-31)
-
-## SEARCH STRATEGY (MANDATORY)
-
-```
-Search: "{{product_domain}} architecture quality attributes"
-Search: "{{product_domain}} system integration patterns"
-Search: "{{product_domain}} technical constraints regulations"
-```
-
-Use Context7 MCP for specific framework/library documentation.
-
-## EXECUTION SEQUENCE
-
-### 1. Define Quality Goals
-
-Derive from product.md §6 (Success Metrics) and user scenarios:
-
-| Quality Attribute | Concrete Scenario | Priority |
-|------------------|-------------------|----------|
-| Performance | [e.g., "API response < 200ms for 95th percentile"] | [1-3] |
-| Scalability | [e.g., "Handle 10K concurrent users"] | [1-3] |
-| Security | [e.g., "SOC 2 compliance, encrypted at rest"] | [1-3] |
-| Availability | [e.g., "99.9% uptime, < 5min recovery"] | [1-3] |
-| Maintainability | [e.g., "New developer productive in < 1 week"] | [1-3] |
-
-Ask user via AskUserQuestion: "Which quality attributes matter most? Performance? Security? Scalability?"
-
-### 2. Identify Constraints
-
-**Technical constraints**:
-- Required platforms/browsers
-- Mandatory integrations
-- Technology restrictions (e.g., "must use Python for ML team compatibility")
-
-**Organizational constraints**:
-- Team size and skill profile
-- Budget limitations
-- Timeline constraints
-
-**Regulatory constraints**:
-- Data privacy (GDPR, CCPA)
-- Industry regulations
-- Compliance requirements
-
-### 3. Map System Context
-
-Identify all external systems and interfaces:
-
-**Users**: Who interacts with the system?
-**External systems**: What APIs, services, databases does it connect to?
-**Data flows**: What data enters and leaves the system?
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/architecture.md` §1-3:
-
-```markdown
-## §1 Quality Goals
-
-| Priority | Quality Attribute | Scenario | Metric |
-|----------|------------------|----------|--------|
-| 1 | [Attribute] | [Concrete scenario] | [Measurable target] |
-| 2 | [Attribute] | [Concrete scenario] | [Measurable target] |
-| 3 | [Attribute] | [Concrete scenario] | [Measurable target] |
-
-## §2 Constraints
-
-### Technical Constraints
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [Constraint] | [Why this exists] | [What it limits] |
-
-### Organizational Constraints
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [Constraint] | [Why this exists] | [What it limits] |
-
-### Regulatory Constraints
-| Constraint | Rationale | Impact |
-|-----------|-----------|--------|
-| [Constraint] | [Why this exists] | [What it limits] |
-
-## §3 System Context
-
-### Context Diagram
-
-**Users**:
-- [User type 1]: [How they interact]
-- [User type 2]: [How they interact]
-
-**External Systems**:
-| System | Direction | Data | Protocol | Notes |
-|--------|-----------|------|----------|-------|
-| [System A] | Inbound | [What data] | [REST/gRPC/etc] | [Notes] |
-| [System B] | Outbound | [What data] | [Protocol] | [Notes] |
-| [System C] | Bidirectional | [What data] | [Protocol] | [Notes] |
-
-**Data Flows**:
-- [User] → [System] → [External]: [Description of flow]
-- [External] → [System] → [User]: [Description of flow]
-```
-
-### 5. Present to User and Gate
-
-```
-[C] Continue — Context defined, proceed to Solution Strategy
-[R] Revise — Adjust quality goals, constraints, or context
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 6. Handle Response
-
-- **[C]**: Load next step: `./step-31-solution-strategy.md`
-- **[R]**: Revise, update architecture.md §1-3, re-present
-
-## SUCCESS METRICS
-
-- Quality goals are specific and measurable (not "good performance")
-- Constraints identified across technical/organizational/regulatory
-- System context shows all external interfaces
-- All quality goals trace to product requirements
-- Output written to architecture.md §1-3
-
-## FAILURE MODES
-
-- Vague quality goals ("system should be fast")
-- Missing regulatory constraints
-- System context missing key external integrations
-- Quality goals not derived from product requirements
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-31-solution-strategy.md`