ultra-builder-pro-cli 0.5.0

package/.ultra-template/delivery-report.json

@@ -0,0 +1,9 @@
+{
+  "timestamp": null,
+  "version": null,
+  "git_tag": null,
+  "git_commit": null,
+  "changelog_updated": false,
+  "build_success": false,
+  "pushed": false
+}

package/.ultra-template/docs/research/README.md

@@ -0,0 +1,53 @@
+# Research Reports
+
+This directory contains research reports generated by `/ultra-research` step-file architecture.
+
+## Structure
+
+Each round generates a report with quality metadata:
+
+| Steps | Round | Report File |
+|-------|-------|-------------|
+| 00-05 | R0: Product Discovery | `product-discovery-{date}.md` |
+| 10-11 | R1: User & Scenario | `user-scenario-{date}.md` |
+| 20-22 | R2: Feature Definition | `feature-definition-{date}.md` |
+| 30-32 | R3: Architecture Design | `architecture-design-{date}.md` |
+| 40-41 | R4: Quality & Deployment | `quality-deployment-{date}.md` |
+
+## Report Format
+
+Each report includes quality tracking in header:
+
+```markdown
+# Round {N}: {Round Name}
+
+> **Confidence**: 92%
+> **Steps completed**: {list}
+> **Completed**: {date}
+
+## Key Findings
+[3-5 bullet points]
+
+## Decisions Made
+[Choices and rationale]
+
+## Open Questions
+[What remains uncertain]
+```
+
+## Quality Gate
+
+- Each step uses [C] Continue user gate — user confirms before proceeding
+- Per-step SUCCESS METRICS and FAILURE MODES enforce output quality
+- Step 99 (Synthesis) validates field-level completeness of all spec files
+
+## Research Distillate
+
+After all steps complete, `step-99-synthesis` generates:
+- `.ultra/specs/research-distillate.md` — Token-efficient summary (<2000 tokens) for `/ultra-plan` consumption
+
+## Integration
+
+- Reports are referenced in `specs/` for technology decisions
+- Research distillate is the primary input for `/ultra-plan`
+- Quality summary displayed at end of `/ultra-research`

package/.ultra-template/specs/architecture.md

@@ -0,0 +1,250 @@
+# Architecture Design
+
+> **Purpose**: This document defines HOW the system is built. Based on arc42 template.
+> Generated by `/ultra-research` Steps 30-41
+> **Reference**: [arc42.org](https://arc42.org)
+
+---
+
+## §1 Quality Goals
+
+| Priority | Quality Attribute | Scenario | Metric |
+|----------|------------------|----------|--------|
+| 1 | [NEEDS CLARIFICATION] | Concrete scenario | Measurable target |
+| 2 | | | |
+| 3 | | | |
+
+---
+
+## §2 Constraints
+
+### Technical Constraints
+
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+
+### Organizational Constraints
+
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+
+### Regulatory Constraints
+
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [NEEDS CLARIFICATION] | Why this exists | What it limits |
+
+---
+
+## §3 System Context
+
+### Users
+- [NEEDS CLARIFICATION]: How they interact
+
+### External Systems
+
+| System | Direction | Data | Protocol | Notes |
+|--------|-----------|------|----------|-------|
+| [NEEDS CLARIFICATION] | Inbound/Outbound | What data | REST/gRPC | |
+
+### Data Flows
+- [User] → [System] → [External]: [NEEDS CLARIFICATION]
+
+---
+
+## §4 Solution Strategy
+
+### Technology Decisions
+
+#### Language & Runtime
+- **Chosen**: [NEEDS CLARIFICATION]
+- **Alternatives considered**: Option B, Option C
+- **Rationale**: Why — reference §1 quality goals
+- **Trade-off**: What we give up
+- **Source**: URL
+
+#### Web Framework
+- **Chosen**: [NEEDS CLARIFICATION]
+- **Alternatives considered**:
+- **Rationale**:
+- **Source**:
+
+#### Database
+- **Chosen**: [NEEDS CLARIFICATION]
+- **Alternatives considered**:
+- **Rationale**:
+- **Source**:
+
+#### Authentication
+- **Chosen**: [NEEDS CLARIFICATION]
+- **Alternatives considered**:
+- **Rationale**:
+- **Source**:
+
+#### Hosting & Infrastructure
+- **Chosen**: [NEEDS CLARIFICATION]
+- **Alternatives considered**:
+- **Rationale**:
+- **Estimated cost**: $/month at launch scale
+- **Source**:
+
+### Tech Stack Summary
+
+| Layer | Technology | Version | Purpose |
+|-------|-----------|---------|---------|
+| Frontend | [NEEDS CLARIFICATION] | | |
+| Backend | | | |
+| Database | | | |
+| Cache | | | |
+| Auth | | | |
+| Hosting | | | |
+| CI/CD | | | |
+| Monitoring | | | |
+
+---
+
+## §5 Building Block View
+
+### Module Decomposition
+
+| Module | Layer | Responsibility | Dependencies |
+|--------|-------|---------------|-------------|
+| [NEEDS CLARIFICATION] | Domain | Pure logic | None |
+| | Application | Orchestration | Domain |
+| | Infrastructure | IO handling | Application |
+
+### Code Organization
+
+```
+src/
+├── domain/           # Functional Core (pure logic)
+│   ├── entities/     # Domain objects
+│   ├── values/       # Value objects
+│   └── services/     # Domain services (pure functions)
+├── application/      # Use cases (orchestration)
+│   └── usecases/     # One file per use case
+├── infrastructure/   # Imperative Shell (IO)
+│   ├── http/         # HTTP handlers/routes
+│   ├── persistence/  # Database repositories
+│   └── external/     # External API clients
+└── config/           # Configuration
+```
+
+### Feature → Module Mapping
+
+| Feature | Domain | Application | Infrastructure |
+|---------|--------|------------|---------------|
+| [NEEDS CLARIFICATION] | Entities | UseCases | Handlers, Repos |
+
+---
+
+## §6 Runtime Scenarios
+
+### Scenario 1: [NEEDS CLARIFICATION] (from product.md S1)
+
+**Trigger**: User action
+**Flow**:
+1. User sends request to endpoint
+2. Handler validates input, maps to DTO
+3. UseCase orchestrates: loads Entity via Repository
+4. DomainService applies business logic (pure)
+5. Repository persists result
+6. Handler returns response
+
+**Error paths**: [NEEDS CLARIFICATION]
+
+### Scenario 2: [NEEDS CLARIFICATION]
+
+[Same structure]
+
+---
+
+## §7 Deployment View
+
+### Environments
+
+| Environment | Purpose | Infrastructure | URL Pattern |
+|------------|---------|---------------|-------------|
+| Development | Local dev | [NEEDS CLARIFICATION] | localhost |
+| Staging | Pre-prod | | staging.X |
+| Production | Live | | X.com |
+
+### Production Topology
+- **Compute**: [NEEDS CLARIFICATION]
+- **Database**: [NEEDS CLARIFICATION]
+- **Cache**: [NEEDS CLARIFICATION]
+- **CDN**: [NEEDS CLARIFICATION]
+
+---
+
+## §8 Crosscutting Concerns
+
+### Logging
+- **Format**: Structured JSON
+- **Fields**: timestamp, level, service, traceId, message, context
+- **Tool**: [NEEDS CLARIFICATION]
+
+### Authentication
+- **Method**: [NEEDS CLARIFICATION]
+- **Provider**: [NEEDS CLARIFICATION]
+- **Session**: [NEEDS CLARIFICATION]
+
+### Error Handling
+- **Pattern**: Result/Either in domain, global handler in infrastructure
+- **Alerting**: [NEEDS CLARIFICATION]
+
+---
+
+## §9 Cost Estimate
+
+| Service | Monthly Cost | Annual Cost | Source |
+|---------|-------------|------------|--------|
+| Compute | [NEEDS CLARIFICATION] | | |
+| Database | | | |
+| Other | | | |
+| **Total** | | | |
+
+_Assumptions: user count, traffic, storage_
+
+---
+
+## §10 Quality Scenarios
+
+| # | Quality Attribute | Scenario | Stimulus | Expected Response | Metric |
+|---|------------------|---------|----------|------------------|--------|
+| Q1 | Performance | [NEEDS CLARIFICATION] | | | |
+| Q2 | Scalability | | | | |
+| Q3 | Security | | | | |
+| Q4 | Availability | | | | |
+
+---
+
+## §11 Risks & Technical Debt
+
+### Risk Register
+
+| # | Risk | Category | Probability | Impact | Score | Mitigation | Contingency |
+|---|------|----------|------------|--------|-------|-----------|-------------|
+| R1 | [NEEDS CLARIFICATION] | Technical | | | | | |
+| R2 | | Business | | | | | |
+
+### Known Technical Debt
+
+| # | Debt Item | Reason for Deferral | Impact if Not Addressed | Address By |
+|---|----------|--------------------|-----------------------|-----------|
+| TD1 | [NEEDS CLARIFICATION] | | | |
+
+---
+
+## §12 Architecture Decision Records
+
+| # | Decision | Context | Options | Chosen | Rationale |
+|---|---------|---------|---------|--------|-----------|
+| ADR-1 | [NEEDS CLARIFICATION] | Why needed | A, B, C | Choice | Why |
+
+---
+
+**Document Status**: Draft
+**Last Updated**: [Date]

package/.ultra-template/specs/discovery.md

@@ -0,0 +1,248 @@
+# Product Discovery & Strategy
+
+> Generated by `/ultra-research` Steps 00-05
+> Status: [NEEDS CLARIFICATION]
+
+---
+
+## §0 Problem Validation Summary
+
+### Product Stage
+- **Stage**: [NEEDS CLARIFICATION] — Pre-product / Has users / Has paying customers / Engineering-Infra
+- **Evidence**: [NEEDS CLARIFICATION]
+
+### Demand Signal
+- **Strength**: [NEEDS CLARIFICATION] — Strong / Moderate / Weak / Unvalidated
+- **Evidence**: [NEEDS CLARIFICATION] — Specific behaviors observed
+- **Risk**: [NEEDS CLARIFICATION] — What could invalidate this demand
+
+### Status Quo Analysis
+- **Current solutions**: [NEEDS CLARIFICATION] — What users do today
+- **Cost of workaround**: [NEEDS CLARIFICATION] — Time, money, friction
+- **Switching motivation**: [NEEDS CLARIFICATION] — Why they'd change
+
+### Target User Profile
+- **Primary**: [NEEDS CLARIFICATION] — Specific role/person description
+- **Stakes**: [NEEDS CLARIFICATION] — What gets them promoted / fired
+- **Pain frequency**: [NEEDS CLARIFICATION] — Daily / Weekly / Occasional
+
+### Narrowest Wedge
+- **MVP scope**: [NEEDS CLARIFICATION] — Single feature/workflow
+- **Willingness to pay**: [NEEDS CLARIFICATION]
+- **Ship timeline**: [NEEDS CLARIFICATION] — Days / Weeks / Months
+
+### Validation Confidence
+- **Overall**: [NEEDS CLARIFICATION]%
+- **Strongest signal**: [NEEDS CLARIFICATION]
+- **Biggest risk**: [NEEDS CLARIFICATION]
+- **Recommended next step**: [NEEDS CLARIFICATION] — Proceed / Investigate further / Pivot
+
+---
+
+## §1 Opportunity Space
+
+### Desired Outcome
+- **Outcome**: [NEEDS CLARIFICATION] — Single measurable outcome
+- **Metric**: [NEEDS CLARIFICATION] — How we measure it
+- **Timeline**: [NEEDS CLARIFICATION] — When we expect movement
+
+### Opportunity Map
+
+| # | Opportunity (Customer Framing) | Importance | Satisfaction | Score | Source |
+|---|-------------------------------|-----------|-------------|-------|--------|
+| O1 | [NEEDS CLARIFICATION] | | | | |
+| O2 | | | | | |
+| O3 | | | | | |
+
+> Opportunity Score = Importance × (1 - Satisfaction)
+
+### Prioritized Opportunities (Top 3)
+
+#### Opportunity 1: [NEEDS CLARIFICATION]
+- **Importance**: /10
+- **Current satisfaction**: — How users cope today
+- **Score**:
+- **Evidence**: Source URL
+
+**Solution Approaches:**
+1. **PM approach**: [NEEDS CLARIFICATION]
+2. **Design approach**: [NEEDS CLARIFICATION]
+3. **Engineering approach**: [NEEDS CLARIFICATION]
+
+### Key Insight
+[NEEDS CLARIFICATION] — Non-obvious insight from opportunity analysis
+
+---
+
+## §2 Market Assessment
+
+### Market Sizing Summary
+
+| Metric | Current Estimate | 2-3 Year Projection | Source |
+|--------|-----------------|---------------------|--------|
+| TAM | [NEEDS CLARIFICATION] | | |
+| SAM | [NEEDS CLARIFICATION] | | |
+| SOM | [NEEDS CLARIFICATION] | | |
+
+### Top-Down Analysis
+
+#### TAM: [NEEDS CLARIFICATION]
+- **Definition**: Market category
+- **Source**: Report name + URL
+- **Growth**: CAGR
+
+#### SAM: [NEEDS CLARIFICATION]
+- **TAM filter 1**: Geographic
+- **TAM filter 2**: Segment
+- **TAM filter 3**: Technology fit
+
+#### SOM: [NEEDS CLARIFICATION]
+- **Realistic capture**: % of SAM
+- **Basis**: Why achievable
+- **Comparable**: Similar company reference
+
+### Bottom-Up Analysis
+
+| Variable | Value | Source |
+|----------|-------|--------|
+| Target customers | [NEEDS CLARIFICATION] | |
+| Conversion rate | [NEEDS CLARIFICATION] | |
+| ARPU (annual) | [NEEDS CLARIFICATION] | |
+| Retention rate | [NEEDS CLARIFICATION] | |
+| **Year 1 Revenue** | **Calculated** | |
+| **Year 3 Revenue** | **Calculated** | |
+
+### Cross-Validation
+- **Top-down SOM**: [NEEDS CLARIFICATION]
+- **Bottom-up Year 3**: [NEEDS CLARIFICATION]
+- **Ratio**: x
+- **Assessment**: [NEEDS CLARIFICATION]
+
+### Growth Drivers
+
+| # | Driver | Direction | Impact | Timeline | Source |
+|---|--------|-----------|--------|----------|--------|
+| 1 | [NEEDS CLARIFICATION] | | | | |
+
+---
+
+## §3 Competitive Landscape
+
+### Competitive Overview
+
+| Dimension | Us | Competitor A | Competitor B | Do Nothing |
+|-----------|-----|-------------|-------------|------------|
+| Core value prop | [NEEDS CLARIFICATION] | | | Status quo |
+| Target segment | | | | Everyone |
+| Pricing | | | | Free |
+| Key strength | | | | Familiar |
+| Key weakness | | | | Inefficient |
+| Traction | | | | N/A |
+
+### Direct Competitors
+
+#### [NEEDS CLARIFICATION]
+- **What they do**:
+- **Strengths**:
+- **Weaknesses**: — Source: URL
+- **Pricing**: — Source: URL
+- **Traction**: — Source: URL
+- **Threat level**: High / Medium / Low
+
+### Indirect Competitors & Alternatives
+- [NEEDS CLARIFICATION]
+- **Do Nothing**: Cost of inaction
+
+### Porter's Five Forces Summary
+
+| Force | Rating | Assessment |
+|-------|--------|-----------|
+| Supplier power | [1-5] | [NEEDS CLARIFICATION] |
+| Buyer power | [1-5] | |
+| New entrant threat | [1-5] | |
+| Substitute threat | [1-5] | |
+| Rivalry intensity | [1-5] | |
+
+### Our Competitive Edge
+- **Where we can win**: [NEEDS CLARIFICATION]
+- **Where we cannot win**: [NEEDS CLARIFICATION]
+- **Unfilled gap**: [NEEDS CLARIFICATION]
+
+---
+
+## §4 Product Strategy
+
+### Vision
+[NEEDS CLARIFICATION] — 2-3 sentences, inspiring, specific, ambitious
+
+### Target Segments
+
+#### Primary: [NEEDS CLARIFICATION]
+- **Description**: Defined by problem/JTBD
+- **Why them**: Why most urgent
+- **Value Proposition**: When [situation], they want [motivation], so they can [outcome]
+
+#### Explicitly NOT Serving
+- [NEEDS CLARIFICATION]: Why not
+
+### Strategic Trade-offs
+
+| # | We Choose | Over | Because |
+|---|-----------|------|---------|
+| 1 | [NEEDS CLARIFICATION] | | |
+| 2 | | | |
+| 3 | | | |
+
+### Defensibility
+
+| Moat Type | Applicable | Strength (1-5) | Timeline |
+|-----------|-----------|----------------|----------|
+| Network effects | [NEEDS CLARIFICATION] | | |
+| Data advantage | | | |
+| Switching costs | | | |
+| Brand / trust | | | |
+| Technical IP | | | |
+
+---
+
+## §5 Key Assumptions & Validation Plan
+
+### Assumption Inventory
+
+| # | Assumption | Category | Impact | Uncertainty | Priority |
+|---|-----------|----------|--------|-------------|----------|
+| A1 | [NEEDS CLARIFICATION] | Value | | | |
+| A2 | | Viability | | | |
+| A3 | | GTM | | | |
+| A4 | | Feasibility | | | |
+| A5 | | Usability | | | |
+
+### Leap-of-Faith Assumptions (Top 3)
+
+#### A1: [NEEDS CLARIFICATION]
+- **Category**: Value / Viability / GTM
+- **Why it matters**: What happens if wrong
+- **Current evidence**: From steps 00-04
+
+**Validation Experiment:**
+- **Method**: [NEEDS CLARIFICATION]
+- **Success criteria**: Measurable outcome
+- **Failure criteria**: Measurable outcome
+- **Effort**: Hours/days
+- **Timeline**: When results expected
+
+**Decision Framework:**
+- If validated → Proceed to Round 1
+- If invalidated → Pivot / Investigate / Kill
+- If ambiguous → Additional experiment
+
+### Validation Roadmap
+
+| Week | Experiment | Assumption | Expected Result |
+|------|-----------|-----------|----------------|
+| 1 | [NEEDS CLARIFICATION] | A1 | |
+
+---
+
+**Document Status**: Draft
+**Last Updated**: [Date]