From c88304a27120bb11b4d7b9ca3eda803f8c1a727d Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Wed, 7 Jan 2026 22:14:25 +0100 Subject: [PATCH] Update vision system to properly extend manifesto MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- VISION.md | 133 +++++++++++++---------------- commands/vision.md | 136 ++++++++++++++++++++++++------ skills/vision-management/SKILL.md | 103 ++++++++++++++-------- 3 files changed, 234 insertions(+), 138 deletions(-) diff --git a/VISION.md b/VISION.md index e578903..db7a099 100644 --- a/VISION.md +++ b/VISION.md @@ -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. diff --git a/commands/vision.md b/commands/vision.md index 27c6a1d..e8784a3 100644 --- a/commands/vision.md +++ b/commands/vision.md @@ -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: " tea milestones close ``` +## 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 diff --git a/skills/vision-management/SKILL.md b/skills/vision-management/SKILL.md index f5e7ff9..7f8a8ea 100644 --- a/skills/vision-management/SKILL.md +++ b/skills/vision-management/SKILL.md @@ -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) |