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

Update vision system to properly extend manifesto

Browse Source 
- Rebuild vision.md to trace personas, jobs, and principles back to manifesto
- Improve /vision command with inheritance guidance and templates
- Update vision-management skill with explicit inheritance rules and formats

Product visions now explicitly extend (not duplicate) organization manifesto.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-07 22:14:25 +01:00
parent a3056bce12
commit c88304a271
3 changed files with 234 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
VISION.md
View File

@@ -1,5 +1,32 @@
# Vision
This product vision builds on the [organization manifesto](manifesto.md).
## Who This Product Serves
### Flowmade Developers
The team building Flowmade's platform. They need efficient, consistent AI workflows to deliver on the organization's promise: helping domain experts create software without coding.
*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
### AI-Augmented Developers
Developers in the broader community who want to treat AI assistance as a structured tool. They benefit from our "build in public" approach - adopting and adapting our workflows for their own teams.
*Extends: The manifesto's commitment to sharing practices with the developer community.*
## What They're Trying to Achieve
These trace back to organization-level jobs:
| Product Job | Enables Org Job |
|-------------|-----------------|
| "Help me work consistently with AI across sessions" | "Help me deliver maintainable solutions to clients faster" |
| "Help me encode best practices so AI applies them" | "Help me reduce dependency on developers for business process changes" |
| "Help me manage issues and PRs without context switching" | "Help me deliver maintainable solutions to clients faster" |
| "Help me capture and share learnings from my work" | (Build in public commitment) |
## The Problem
AI-assisted development is powerful but inconsistent. Claude Code can help with nearly any task, but without structure:
@@ -9,102 +36,60 @@ AI-assisted development is powerful but inconsistent. Claude Code can help with
- Context gets lost when switching between tasks
- There's no shared vocabulary for common patterns
The gap isn't in AI capability—it's in how we use it.
The gap isn't in AI capability - it's in how we use it.
## The Solution
This project provides a **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
A **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
Instead of asking Claude to "help with issues" differently each time, you run `/work-issue 42` and get a consistent workflow: fetch the issue, create a branch, plan the work, implement, commit with proper references, and create a PR.
The key insight: **encode your team's best practices into reusable components** that Claude can apply consistently.
### Architecture
## Composable Components
Three component types that stack together:
The system is built from three types of components that stack together:
| Component | Purpose | Example |
|-----------|---------|---------|
| **Skills** | Knowledge modules - teach Claude how to do something | `gitea`, `issue-writing` |
| **Agents** | Focused subtask handlers in isolated context | `code-reviewer` |
| **Commands** | User workflows - orchestrate skills and agents | `/work-issue`, `/dashboard` |
### Skills
Skills don't act on their own. Agents handle complex subtasks in isolation. Commands are the entry points that tie it together.
Skills are knowledge modules—focused documents that teach Claude how to do something well.
## Product Principles
Examples:
- `issue-writing`: How to structure clear, actionable issues
- `gitea`: How to use the Gitea CLI for issue/PR management
- `backlog-grooming`: What makes a healthy backlog
Skills don't do anything on their own. They're building blocks.
### Agents
Agents are small, focused units that handle specific subtasks in isolated context.
Unlike commands (which run in the main conversation), agents are spawned via the Task tool to do a specific job and report back. They should be:
- **Small and focused**: One clear responsibility
- **Isolated**: Work without needing conversation history
- **Result-oriented**: Return a specific output (analysis, categorization, generated content)
Examples:
- `code-reviewer`: Reviews a PR diff and reports issues
- A hypothetical `categorize-milestone`: Given an issue, determines which milestone it belongs to
Agents enable:
- **Parallel processing**: Multiple agents can work simultaneously
- **Context isolation**: Complex subtasks don't pollute the main conversation
- **Reusability**: Same agent can be spawned by different commands
### Commands
Commands are the user-facing entry points—what you actually invoke.
When you run `/plan-issues add dark mode`, the command:
1. Understands what you're asking for
2. References skills for knowledge (how to write issues, use Gitea, etc.)
3. Optionally spawns agents for complex subtasks
4. Guides you through the workflow with approvals
5. Takes action (creates issues, PRs, etc.)
Commands run in the main conversation context, using skills for knowledge and spawning agents only when isolated processing is beneficial.
## Target Users
This toolkit is for:
- **Developers using Claude Code** who want consistent, efficient workflows
- **Teams** who want to encode and share their best practices
- **Gitea/Git users** who want seamless issue and PR management integrated into their AI workflow
You should have:
- Claude Code CLI installed
- A Gitea instance (or adapt the tooling for GitHub/GitLab)
- Interest in treating AI assistance as a structured tool, not just a chat interface
## Guiding Principles
### Encode, Don't Repeat
If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. Capture it once, use it everywhere.
These extend the organization's guiding principles:
### Composability Over Complexity
Small, focused components that combine well beat large, monolithic solutions. A skill should do one thing. An agent should serve one role. A command should trigger one workflow.
Small, focused components that combine well beat large, monolithic solutions. A skill does one thing. An agent serves one role. A command triggers one workflow.
*Extends: "Small teams, big leverage"*
### Approval Before Action
Destructive or significant actions should require user approval. Commands should show what they're about to do and ask before doing it. This builds trust and catches mistakes.
Destructive or significant actions require user approval. Commands show what they're about to do and ask before doing it.
### Use the Tools to Build the Tools
*Extends: Non-goal "Replacing human judgment"*
This project uses its own commands to manage itself. Issues are created with `/create-issue`. Features are planned with `/plan-issues`. PRs are reviewed with `/review-pr`. Dogfooding ensures the tools actually work.
### Dogfooding
This project uses its own commands to manage itself. Issues are created with `/create-issue`. PRs are reviewed with `/review-pr`. If the tools don't work for us, they won't work for anyone.
*Extends: "Ship to learn"*
### Progressive Disclosure
Simple things should be simple. `/dashboard` just shows your issues and PRs. But the system supports complex workflows when you need them. Don't require users to understand the full architecture to get value.
Simple things should be simple. `/dashboard` just shows your issues and PRs. Complex workflows are available when needed, but not required to get value.
## What This Is Not
*Extends: "Opinionated defaults, escape hatches available"*
This is not:
- A replacement for Claude Code—it enhances it
- A rigid framework—adapt it to your needs
- Complete—it grows as we discover new patterns
## Non-Goals
It's a starting point for treating AI-assisted development as a first-class engineering concern.
These extend the organization's non-goals:
- **Replacing Claude Code.** This enhances Claude Code, not replaces it. The toolkit adds structure; Claude provides the capability.
- **One-size-fits-all workflows.** Teams should adapt these patterns to their needs. We provide building blocks, not a rigid framework.
- **Feature completeness.** The toolkit grows as we discover new patterns. It's a starting point, not an end state.

136
commands/vision.md
View File

@@ -18,30 +18,56 @@ This command manages **product-level** vision. For organization-level vision, us
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
Product vision inherits from and extends the organization manifesto.
Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
## Process
1. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context)
1. **Load organization context**: Read `manifesto.md` from the architecture repo (`~/.claude/manifesto.md` or repo root)
- Extract personas (Who We Serve)
- Extract jobs to be done (What They're Trying to Achieve)
- Extract guiding principles
- Extract non-goals
2. **Check for product vision**: Look for `vision.md` in the current repo root
3. **If no vision exists**:
- Reference the organization manifesto if it exists
- Show the organization manifesto summary
- Ask if the user wants to create a product vision
- Guide them through defining:
1. **Product personas**: Who does this product serve? (may extend org personas)
2. **Product jobs**: What specific jobs does this product address?
3. **The problem**: What pain points does this product solve?
4. **The solution**: How does this product address those jobs?
5. **Product principles**: Any product-specific principles (beyond org principles)?
6. **Product non-goals**: What is this product explicitly NOT doing?
- Create `vision.md`
- Guide them through defining (with inheritance):
**Who This Product Serves**
- Show manifesto personas first
- Ask: "Which personas does this product serve? How does it extend or specialize them?"
- Product personas should reference org personas with product-specific context
**What They're Trying to Achieve**
- Show manifesto jobs first
- Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
- Use a table format showing the connection
**The Problem**
- What pain points does this product solve?
**The Solution**
- How does this product address those jobs?
**Product Principles**
- Show manifesto principles first
- Ask: "Any product-specific principles? These should extend, not duplicate."
- Each principle should note what org principle it extends
**Product Non-Goals**
- Show manifesto non-goals first
- Ask: "Any product-specific non-goals?"
- Org non-goals apply automatically
- Create `vision.md` with proper inheritance markers
- Ask about initial goals, create as Gitea milestones
4. **If vision exists**:
- Display organization context (if manifesto exists)
- Display organization context summary
- Display the product vision from `vision.md`
- Validate inheritance (warn if vision duplicates rather than extends)
- Show current milestones and their progress: `tea milestones`
- Check if `$1` specifies an action:
- `goals`: Manage milestones (add, close, view progress)
@@ -64,47 +90,101 @@ Success: <criteria>"
tea milestones close <milestone-name>
```
## Vision Structure Template
```markdown
# Vision
This product vision builds on the [organization manifesto](link-to-manifesto).
## Who This Product Serves
### [Persona Name]
[Product-specific description]
*Extends: [Org persona] (from manifesto)*
## What They're Trying to Achieve
These trace back to organization-level jobs:
| Product Job | Enables Org Job |
|-------------|-----------------|
| "[Product-specific job]" | "[Org job from manifesto]" |
## The Problem
[Pain points this product addresses]
## The Solution
[How this product solves those problems]
## Product Principles
These extend the organization's guiding principles:
### [Principle Name]
[Description]
*Extends: "[Org principle]"*
## Non-Goals
These extend the organization's non-goals:
- **[Non-goal].** [Explanation]
```
## Output Format
```
## Organization Context
See manifesto for shared personas, beliefs, and principles.
[Link or note about manifesto.md location]
From manifesto.md:
- **Personas**: [list from manifesto]
- **Core beliefs**: [key beliefs]
- **Principles**: [list]
## Product: [Name]
### Who This Product Serves
- **[Persona 1]**: [Product-specific description]
- **[Persona 2]**: [Product-specific description]
↳ Extends: [Org persona]
### What They're Trying to Achieve
- "[Product-specific job 1]"
- "[Product-specific job 2]"
| Product Job | → Org Job |
|-------------|-----------|
| [job] | [org job it enables] |
### Product Vision
### Vision Summary
[Summary of problem/solution from vision.md]
[Problem/solution from vision.md]
### Goals (Milestones)
| Goal | For | Progress | Due |
|------|-----|----------|-----|
| [title] | [Persona] | 3/5 issues | [date] |
### Current Focus
[Open milestones with nearest due dates or most activity]
```
## Inheritance Rules
- **Personas**: Product personas extend org personas with product-specific context
- **Jobs**: Product jobs trace back to org-level jobs (show the connection)
- **Beliefs**: Inherited from manifesto, never duplicated in vision
- **Principles**: Product adds specific principles that extend org principles
- **Non-Goals**: Product adds its own; org non-goals apply automatically
## Guidelines
- Product vision builds on organization manifesto - don't duplicate, extend
- Product personas can be more specific versions of org personas
- Product jobs should trace back to org-level jobs to be done
- Milestones are product-specific goals toward the vision
- Product vision builds on organization manifesto - extend, don't duplicate
- Every product persona should reference which org persona it extends
- Every product job should show which org job it enables
- Product principles should note which org principle they extend
- Use `/manifesto` for organization-level identity and beliefs
- Use `/vision` for product-specific direction and goals
- If this is the architecture repo itself, use `/manifesto` instead

103
skills/vision-management/SKILL.md
View File

@@ -15,7 +15,7 @@ How to create, maintain, and evolve organizational direction at two levels: mani
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
Product vision inherits from and extends the organization manifesto.
Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
---
@@ -74,32 +74,54 @@ What the organization explicitly does NOT do.
## Vision (Product Level)
The vision defines what a specific product does. It lives in each product repo and extends the manifesto.
The vision defines what a specific product does. It lives in each product repo and **extends the manifesto**.
### Vision Structure
```markdown
# Vision
This product vision builds on the [organization manifesto](link-to-manifesto).
## Who This Product Serves
Product-specific personas (may extend org personas).
- **Persona Name**: Product-specific context
### [Persona Name]
[Product-specific description]
*Extends: [Org persona] (from manifesto)*
## What They're Trying to Achieve
Product-specific jobs to be done.
- "Help me [outcome] without [pain]"
These trace back to organization-level jobs:
| Product Job | Enables Org Job |
|-------------|-----------------|
| "[Product-specific job]" | "[Org job from manifesto]" |
## The Problem
Pain points this product addresses.
[Pain points this product addresses]
## The Solution
How this product solves those problems.
[How this product solves those problems]
## Product Principles
Product-specific principles (beyond org principles).
These extend the organization's guiding principles:
### [Principle Name]
[Description]
*Extends: "[Org principle]"*
## Non-Goals
What this product explicitly does NOT do.
These extend the organization's non-goals:
- **[Non-goal].** [Explanation]
```
### When to Update Vision
@@ -111,51 +133,58 @@ What this product explicitly does NOT do.
### Creating a Product Vision
1. Reference the organization manifesto
2. Define product-specific personas (can extend org personas)
3. Identify product-specific jobs to be done
1. **Start with the manifesto** - read it first
2. Define product personas that extend org personas
3. Identify product jobs that trace back to org jobs
4. Articulate the problem this product solves
5. Define the solution approach
6. Set product-specific principles (if any)
6. Set product-specific principles (noting what they extend)
7. Document product non-goals
8. Create initial milestones
---
## Relationship: Manifesto → Vision
## Inheritance Model
```
Manifesto (org) Vision (product)
├── Shared Personas → Product Personas (more specific)
├── Org Jobs → Product Jobs (subset/extension)
├── Beliefs → (inherited, not duplicated)
├── Principles → Product Principles (additional)
└── Non-Goals → Product Non-Goals (additional)
Manifesto (org) Vision (product)
├── Personas → Product Personas (extend with specifics)
├── Jobs → Product Jobs (trace back to org jobs)
├── Beliefs → (inherited, never duplicated)
├── Principles → Product Principles (extend, note source)
└── Non-Goals → Product Non-Goals (additive)
```
### Inheritance Model
### Inheritance Rules
- **Personas**: Product personas can be more specific versions of org personas
- **Jobs**: Product jobs should trace back to org-level jobs
- **Beliefs**: Inherited from manifesto, not duplicated in vision
- **Principles**: Product can add specific principles; org principles apply automatically
- **Non-Goals**: Product adds its own; org non-goals apply automatically
| Component | Rule | Format |
|-----------|------|--------|
| **Personas** | Extend with product-specific context | `*Extends: [Org persona] (from manifesto)*` |
| **Jobs** | Trace back to org-level jobs | Table with Product Job → Org Job columns |
| **Beliefs** | Inherited automatically | Never include in vision |
| **Principles** | Add product-specific, note what they extend | `*Extends: "[Org principle]"*` |
| **Non-Goals** | Additive | Org non-goals apply automatically |
### Example
**Manifesto** (organization):
```markdown
## Who We Serve
- **Solo Developer**: Individual shipping side projects, time-constrained
- **Agencies & Consultancies**: Teams building solutions for clients
```
**Vision** (product - e.g., CLI tool):
**Vision** (product - architecture tooling):
```markdown
## Who This Product Serves
- **Solo Developer (CLI user)**: Uses terminal daily, prefers keyboard over GUI
### Flowmade Developers
The team building Flowmade's platform. They need efficient, consistent AI workflows.
*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
```
The product persona extends the org persona with product-specific context.
The product persona extends the org persona with product-specific context and explicitly notes the connection.
---
@@ -180,8 +209,8 @@ Success: /commit and /pr commands handle 80% of workflows"
### Milestone-to-Vision Alignment
Every milestone should trace to:
- A persona (from vision or manifesto)
- A job to be done (from vision)
- A persona (from vision, which extends manifesto)
- A job to be done (from vision, which traces to manifesto)
- A measurable outcome
---
@@ -218,7 +247,7 @@ Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
```
1. **Manifesto** defines organizational identity (very stable)
2. **Vision** defines product direction (stable)
2. **Vision** defines product direction, extends manifesto (stable)
3. **Milestones** define measurable goals (evolve)
4. **Issues** are work items toward goals
5. **Work** implements the issues
@@ -232,9 +261,11 @@ Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
| Question | Answer |
|----------|--------|
| Where do shared personas live? | `manifesto.md` in architecture repo |
| Where do product personas live? | `vision.md` in product repo |
| Where do beliefs live? | `manifesto.md` only (inherited) |
| Where do product personas live? | `vision.md` in product repo (extend org personas) |
| Where do beliefs live? | `manifesto.md` only (inherited, never duplicated) |
| Where do goals live? | Gitea milestones (per repo) |
| What command for org vision? | `/manifesto` |
| What command for product vision? | `/vision` |
| What repo for learnings? | Architecture repo |
| How do product jobs relate to org jobs? | They trace back (show in table) |
| How do product principles relate? | They extend (note the source) |