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.