# Architecture

This repository is the organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.

## Setup

```bash
# Clone and install symlinks
git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
cd architecture
make install
```

## What This Repo Contains

| Component | Purpose |
|-----------|---------|
| `manifesto.md` | Organization vision, personas, beliefs, principles |
| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
| `learnings/` | Historical record and governance |
| `skills/` | AI workflows and knowledge modules |
| `agents/` | Focused subtask handlers |
| `settings.json` | Claude Code configuration |
| `Makefile` | Install symlinks to ~/.claude/ |

## Project Structure

```
architecture/
├── manifesto.md              # Organization vision and beliefs
├── software-architecture.md  # Patterns linked to beliefs (DDD, ES)
├── learnings/                # Captured learnings and governance
├── skills/                   # User-invocable (/work-issue) and background skills
├── agents/                   # Focused subtask handlers (isolated context)
├── scripts/                  # Hook scripts (pre-commit, token loading)
├── settings.json             # Claude Code settings
└── Makefile                  # Install/uninstall symlinks
```

All files symlink to `~/.claude/` via `make install`.

## Two Levels of Vision

| Level | Document | Skill | Purpose |
|-------|----------|-------|---------|
| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
| Product | `vision.md` | `/vision` | Product-specific direction and goals |

See the manifesto for our identity, personas, and beliefs about AI-augmented development.

## Available Skills

| Skill | Description |
|-------|-------------|
| `/vision-to-backlog [vision-file]` | Transform product vision into executable backlog via DDD |
| `/create-milestones` | Organize issues into value-based milestones |
| `/spawn-issues <n> [<n>...]` | Implement multiple issues in parallel with automated review |
| `/spawn-pr-reviews <n> [<n>...]` | Review one or more PRs using code-reviewer agents |
| `/spawn-pr-fixers <n> [<n>...]` | Fix one or more PRs based on review feedback |
| `/create-capability` | Create new skill, agent, or capability for the architecture |
| `/capability-writing` | Guide for designing capabilities following best practices |

## Gitea Integration

Uses `tea` CLI for issue/PR management:

```bash
# Setup (one-time)
brew install tea
tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>

# Create token at: https://git.flowmade.one/user/settings/applications
```

## Architecture Components

### Skills

Skills come in two types:

**User-invocable** (`user-invocable: true`): Workflows users trigger with `/skill-name`
- **Purpose**: Orchestrate workflows with user interaction
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.

**Background** (`user-invocable: false`): Knowledge auto-loaded when needed
- **Purpose**: Encode best practices and tool knowledge
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: Referenced by other skills via `@~/.claude/skills/xxx/SKILL.md`

### Agents
Focused units that handle specific subtasks in isolated context.

- **Purpose**: Complex subtasks that benefit from isolation
- **Location**: `agents/<name>/AGENT.md`
- **Usage**: Spawned via Task tool, return results to caller

### Learnings
Captured insights from work, encoded into skills/agents.

- **Purpose**: Historical record + governance + continuous improvement
- **Location**: `learnings/YYYY-MM-DD-title.md`
- **Flow**: Retro → Issue → Encode into learning + system update