flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: add composable product strategy capability (vision-to-backlog)

Browse Source 
Replace monolithic ddd-analyst with composable agent architecture following
opinionated product strategy chain from manifesto to executable backlog.

New Components:
- product-strategy skill: 7-step framework with decision gates
- vision-to-backlog skill: Orchestrator with user decision gates (Haiku)
- problem-space-analyst agent: Vision → Event timeline (Haiku)
- context-mapper agent: Events → Bounded contexts (Haiku)
- domain-modeler agent: Contexts → Domain models (Haiku)
- capability-extractor agent: Domain → Capabilities (Haiku)
- backlog-builder agent: Capabilities → Features → Issues (Haiku)

The Chain:
Manifesto → Vision → Problem Space → Contexts → Domain → Capabilities → Features → Issues

Each step has decision gate preventing waste. Agents work autonomously, orchestrator
manages gates and user decisions.

Benefits:
- Composable: Each agent reusable independently
- DDD embedded throughout (not isolated)
- Prevents cargo-cult DDD (problem space before modeling)
- Works for greenfield + brownfield
- All Haiku models (cost-optimized)

Removed:
- ddd-breakdown skill (replaced by vision-to-backlog)
- ddd-analyst agent (replaced by 5 specialized agents)

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-12 16:38:20 +01:00
parent 03a665503c
commit dc8fade8f9
9 changed files with 2262 additions and 391 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
skills/ddd-breakdown/SKILL.md
View File

@@ -1,136 +0,0 @@
---
name: ddd-breakdown
description: >
Analyze product vision using DDD to identify bounded contexts and generate
implementation issues. Use when breaking down features into DDD-based vertical
slices, or when user says /ddd-breakdown.
model: haiku
argument-hint: [vision-file]
user-invocable: true
---
# DDD Breakdown
@~/.claude/skills/ddd/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Analyze product vision through a DDD lens to generate implementation issues.
## Process
1. **Locate manifesto and vision**:
**Manifesto** (organization-level):
```bash
# Always in architecture repo
cat ~/.claude/manifesto.md
# Or if in architecture repo:
cat ./manifesto.md
```
**Vision** (product-level):
```bash
# If argument provided: use that file
# Otherwise: look for vision.md in current repo
cat ./vision.md
```
Verify both files exist before proceeding.
2. **Spawn DDD analyst agent**:
Use Task tool to spawn `ddd-analyst` agent:
```
Analyze this product using DDD principles.
Manifesto: [path to manifesto.md]
Vision: [path to vision.md]
Codebase: [current working directory]
Identify bounded contexts, map features to DDD patterns, and generate
user stories with DDD implementation guidance.
```
The agent will:
- Analyze manifesto (personas, beliefs, domain language)
- Analyze vision (goals, features, milestones)
- Explore codebase (existing structure, boundaries, misalignments)
- Identify bounded contexts (intended vs actual)
- Map features to DDD patterns (aggregates, commands, events)
- Generate user stories with acceptance criteria and DDD guidance
3. **Review agent output**:
The agent returns structured analysis:
- Bounded contexts identified
- User stories per context
- Refactoring needs
- Suggested implementation order
Present this to the user for review.
4. **Confirm issue creation**:
Ask user:
- Create all issues?
- Select specific issues to create?
- Modify any stories before creating?
5. **Create issues in Gitea**:
For each approved user story:
```bash
tea issues create \
--title "[story title]" \
--description "[full story with DDD guidance]"
```
Apply labels:
- `feature` (or `refactor` for refactoring issues)
- `bounded-context/[context-name]`
- Any other relevant labels from the story
6. **Link dependencies**:
For stories with dependencies:
```bash
tea issues deps add <dependent-issue> <blocker-issue>
```
7. **Report results**:
Show created issues with links:
```
## Issues Created
### Context: [Context Name]
- #123: [Issue title]
- #124: [Issue title]
### Context: [Another Context]
- #125: [Issue title]
### Refactoring
- #126: [Issue title]
View all: [link to issues page]
```
## Guidelines
- **Manifesto is organization-wide**: Always read from architecture repo
- **Vision is product-specific**: Read from current repo or provided path
- **Let agent do the analysis**: Don't try to identify contexts yourself, spawn the agent
- **Review before creating**: Always show user the analysis before creating issues
- **Label by context**: Use `bounded-context/[name]` labels for filtering
- **Link dependencies**: Use `tea issues deps add` for blockers
- **Implementation order matters**: Create foundational issues (refactoring, core aggregates) first
## Tips
- Run this when starting a new product or major feature area
- Re-run periodically to identify drift between vision and code
- Use with `/vision` skill to manage product vision
- Combine with `/plan-issues` for additional breakdown
- Review with team before creating all issues

210
skills/product-strategy/SKILL.md Normal file
View File

@@ -0,0 +1,210 @@
---
name: product-strategy
description: >
Opinionated framework for translating manifesto into executable backlog through
problem space analysis, domain modeling, and capability mapping. Use when planning
product strategy or decomposing vision into work.
user-invocable: false
---
# Product Strategy Framework
A disciplined chain from organizational values to executable work, preventing cargo-cult DDD and feature churn.
## The Chain
```
Manifesto
↓ (constraints + outcomes)
Product Vision
↓ (events + decisions)
Problem Space
↓ (boundaries)
Bounded Contexts
↓ (invariants)
Domain Models
↓ (system abilities)
Capabilities
↓ (user value)
Features
↓ (executable)
Issues
```
Each step has a clear artifact and decision gate.
## Step 1: Manifesto → Product Vision
**Purpose:** Decide what is worth building (and what not).
**Artifact:** 1-page Product Vision (per product)
**Method:**
Translate values into constraints + outcomes, not features.
| Manifesto Element | Vision Element |
|-------------------|----------------|
| Value | Non-negotiable design rule |
| Belief | Product promise |
| Principle | Trade-off rule |
**Vision must answer (hard requirement):**
- Who is this product for?
- What pain is eliminated?
- What job is now trivial?
- What won't we do?
**Decision gate:** If this can't be answered crisply → stop.
## Step 2: Product Vision → Problem Space
**Purpose:** Understand reality before modeling software.
**Artifact:** Problem Map (language-first)
**Do NOT start with DDD yet.**
**First, explore:**
- Core user journeys
- Decisions users struggle with
- Irreversible vs reversible actions
- Where mistakes are expensive
**Techniques:**
- Event Storming (Big Picture)
- Jobs-To-Be-Done
- Narrative walkthroughs ("a day in the life")
**Output:**
A timeline of business events, not entities.
**Anti-pattern:** If you don't see events, you're still thinking in CRUD.
## Step 3: Problem Space → Domain Boundaries
**Purpose:** Decide where models must be pure and where they may rot.
**Artifact:** Bounded Context Map
**How to cut boundaries (rules):**
- Different language → different context
- Different lifecycle → different context
- Different owners → different context
- Different scaling needs → different context
**Anti-pattern:** "One big domain model" is not DDD; it's denial.
## Step 4: Bounded Context → Domain Model
**Purpose:** Capture business invariants, not data structures.
**Artifact (per context):**
- Aggregates
- Commands
- Events
- Policies
- Read models
**Process:**
1. Identify invariants (what must never break)
2. Define aggregates only where invariants exist
3. Everything else becomes a read model or policy
**Anti-pattern:** If an aggregate has no invariant, it shouldn't exist.
## Step 5: Domain Model → Product Capabilities
**Purpose:** Bridge domain thinking to roadmap thinking.
**Artifact:** Capability Map
**A capability is:**
"The system's ability to cause a meaningful domain change"
**Examples:**
- "Validate eligibility"
- "Authorize execution"
- "Resolve conflicts"
- "Publish outcome"
**Key insight:** Capabilities ≠ features
Capabilities survive UI rewrites and tech changes.
## Step 6: Capabilities → Features
**Purpose:** Define user-visible value slices.
**Artifact:** Feature definitions
**Each feature:**
- Enables or improves one capability
- Has a clear success condition
- Is demoable
**Rule:** If a feature doesn't move a capability, it's noise.
## Step 7: Features → Work Items
**Purpose:** Make work executable without losing intent.
**Artifact:** Issues / Stories / Tasks
**Decomposition order:**
1. Command handling
2. Domain rules
3. Events
4. Read models
5. UI last
**Golden rule:**
Issues should reference domain concepts, not screens.
**Bad:** "Create edit form"
**Good:** "Allow policy to approve eligibility override"
## Common Failure Modes
| Failure | Result |
|---------|--------|
| Starting DDD before product vision | Elegant nonsense |
| Treating aggregates as data models | Anemic domains |
| Roadmaps built from features instead of capabilities | Churn |
| Tickets written in UI language | Lost intent |
## Decision Gates
**After Vision:** Can you answer the 4 questions crisply? No → stop and clarify.
**After Problem Space:** Do you see events, not entities? No → go deeper.
**After Contexts:** Are boundaries clear? No → re-examine language/lifecycle/ownership.
**After Domain Models:** Does each aggregate enforce an invariant? No → simplify.
**After Capabilities:** Can each capability be demoed? No → clarify.
**After Features:** Does each feature move a capability? No → cut it.
## Brownfield (Existing Code)
At each step, compare intended state vs actual state:
**Context Mapping:**
- Intended contexts vs actual modules
- Identify leaky boundaries
**Domain Modeling:**
- Intended aggregates vs actual models
- Identify anemic domains
**Result:** Refactoring issues + new feature issues
## Tips
- Don't skip steps (especially problem space)
- Each artifact is 1 page max
- Decision gates prevent waste
- DDD starts at step 3, not step 1
- Capabilities are the pivot between domain and product
- Issues reference domain language, not UI elements

314
skills/vision-to-backlog/SKILL.md Normal file
View File

@@ -0,0 +1,314 @@
---
name: vision-to-backlog
description: >
Orchestrate the full product strategy chain from manifesto to executable backlog.
Use when breaking down product vision into work, or when user says /vision-to-backlog.
model: haiku
argument-hint: [vision-file]
user-invocable: true
---
# Vision to Backlog
@~/.claude/skills/product-strategy/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Orchestrate the disciplined chain: Manifesto → Vision → Problem Space → Contexts → Domain → Capabilities → Features → Issues.
## Arguments
Optional: path to vision.md file (defaults to `./vision.md`)
## Process
### 1. Locate Manifesto and Vision
**Manifesto** (organization-level):
```bash
cat ~/.claude/manifesto.md
# Or if in architecture repo:
cat ./manifesto.md
```
**Vision** (product-level):
```bash
# If argument provided: use that file
# Otherwise: look for vision.md in current repo
cat ./vision.md
```
Verify both files exist. If vision doesn't exist, help user create it following product-strategy framework.
### 2. Vision Decision Gate
Show vision to user and ask:
**Can you answer these crisply:**
- Who is this product for?
- What pain is eliminated?
- What job is now trivial?
- What won't we do?
If NO → help refine vision first, don't proceed.
If YES → continue to problem space.
### 3. Spawn Problem Space Analyst
Use Task tool to spawn `problem-space-analyst` agent:
```
Analyze the product vision to identify the problem space.
Manifesto: [path]
Vision: [path]
Codebase: [current directory]
Output:
- Event timeline (business events, not entities)
- User journeys
- Decision points
- Irreversible vs reversible actions
- Where mistakes are expensive
Follow problem-space-analyst agent instructions.
```
Agent returns Problem Map artifact.
### 4. Problem Space Decision Gate
Show Problem Map to user and ask:
**Do you see events, not entities?**
- If NO → problem space needs more work
- If YES → continue to context mapping
### 5. Spawn Context Mapper
Use Task tool to spawn `context-mapper` agent:
```
Identify bounded contexts from the problem space.
Problem Map: [from previous step]
Codebase: [current directory]
Analyze:
- Intended contexts (from problem space)
- Actual contexts (from codebase structure)
- Misalignments
Output:
- Bounded Context Map
- Boundary rules
- Refactoring needs (if brownfield)
Follow context-mapper agent instructions.
```
Agent returns Bounded Context Map.
### 6. Context Decision Gate
Show Bounded Context Map to user and ask:
**Are boundaries clear?**
- Different language per context?
- Different lifecycles per context?
If NO → revise contexts
If YES → continue to domain modeling
### 7. Spawn Domain Modeler (Per Context)
For each bounded context, spawn `domain-modeler` agent:
```
Model the domain for bounded context: [CONTEXT_NAME]
Context: [context details from map]
Codebase: [current directory]
Identify:
- Aggregates (only where invariants exist)
- Commands
- Events
- Policies
- Read models
Compare with existing code if present.
Follow domain-modeler agent instructions.
```
Agent returns Domain Model for this context.
### 8. Domain Model Decision Gate
For each context, verify:
**Does each aggregate enforce an invariant?**
- If NO → simplify (might be read model or policy)
- If YES → continue
### 9. Spawn Capability Extractor
Use Task tool to spawn `capability-extractor` agent:
```
Extract product capabilities from domain models.
Domain Models: [all contexts]
Output:
- Capability Map
- System abilities that cause meaningful domain changes
Follow capability-extractor agent instructions.
```
Agent returns Capability Map.
### 10. Capability Decision Gate
Show Capability Map to user and ask:
**Which capabilities do you want to build?**
- Show all capabilities with descriptions
- Let user select subset
- Prioritize if needed
### 11. Spawn Backlog Builder
Use Task tool to spawn `backlog-builder` agent:
```
Generate features and issues from selected capabilities.
Selected Capabilities: [user selection]
Domain Models: [all contexts]
Codebase: [current directory]
For each capability:
1. Define features (user-visible value)
2. Decompose into issues (domain-order: commands, rules, events, reads, UI)
3. Identify refactoring issues (if misaligned with domain)
Follow issue-writing skill format.
Follow backlog-builder agent instructions.
```
Agent returns Features + Issues.
### 12. Feature Decision Gate
Show generated features and ask:
**Does each feature move a capability?**
**Is each feature demoable?**
If NO → refine features
If YES → continue to issue creation
### 13. Issue Review and Creation
Present all generated issues to user:
```
## Generated Backlog
### Context: [Context Name]
**Refactoring:**
- #issue: [title]
- #issue: [title]
**Features:**
- Feature: [name]
- #issue: [title] (command)
- #issue: [title] (domain rule)
- #issue: [title] (event)
- #issue: [title] (read model)
- #issue: [title] (UI)
```
Ask user:
- Create all issues?
- Select specific issues?
- Modify any before creating?
### 14. Create Issues in Gitea
For each approved issue:
```bash
tea issues create \
--title "[issue title]" \
--description "[full issue with acceptance criteria]"
```
Apply labels:
- `feature` or `refactor`
- `bounded-context/[context-name]`
- `capability/[capability-name]`
### 15. Link Dependencies
For issues with dependencies:
```bash
tea issues deps add <dependent-issue> <blocker-issue>
```
### 16. Final Report
Show created issues with links:
```
## Backlog Created
### Context: Authentication
- #42: Implement User aggregate
- #43: Add RegisterUser command
- #44: Publish UserRegistered event
### Context: Orders
- #45: Refactor Order model to enforce invariants
- #46: Add PlaceOrder command
- #47: Publish OrderPlaced event
Total: 6 issues created across 2 contexts
View backlog: [gitea issues link]
```
## Guidelines
**Follow the chain:**
- Don't skip steps
- Each step has decision gate
- User approves before proceeding
**Let agents work:**
- Agents do analysis autonomously
- Orchestrator just dispatches and gates
**Decision gates prevent waste:**
- Stop early if vision unclear
- Verify events before contexts
- Verify invariants before building
**Brownfield handling:**
- Agents analyze existing code at each step
- Generate refactoring issues for misalignments
- Generate feature issues for new capabilities
**Issue quality:**
- Reference domain concepts, not UI
- Follow domain decomposition order
- Link dependencies properly
## Tips
- Run when starting new product or major feature area
- Each artifact is presented for review
- User can iterate at any decision gate
- Issues are DDD-informed and executable
- Works for greenfield and brownfield