# 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:

- Workflows vary between sessions and team members
- Knowledge about good practices stays in heads, not systems
- 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 Solution

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.

### Architecture

Three component types 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 don't act on their own. Agents handle complex subtasks in isolation. Commands are the entry points that tie it together.

## Product Principles

These extend the organization's guiding principles:

### Composability Over Complexity

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 require user approval. Commands show what they're about to do and ask before doing it.

*Extends: Non-goal "Replacing human judgment"*

### 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. Complex workflows are available when needed, but not required to get value.

*Extends: "Opinionated defaults, escape hatches available"*

## Non-Goals

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.