# 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 |
| `commands/` | AI workflow entry points (/work-issue, /manifesto, etc.) |
| `skills/` | Tool and practice knowledge |
| `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
├── commands/                 # Slash commands (/work-issue, /dashboard)
├── skills/         # Knowledge modules (auto-triggered)
├── 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 | Command | 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 Commands

| Command | Description |
|---------|-------------|
| `/manifesto` | View/manage organization manifesto |
| `/vision` | View/manage product vision and milestones |
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
| `/dashboard` | Show open issues and PRs |
| `/review-pr <n>` | Review PR with diff and comments |
| `/create-issue` | Create single or batch issues |
| `/retro` | Capture learnings as issues for encoding |
| `/plan-issues` | Break down features into issues |
| `/groom` | Improve issue quality |

## 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
Knowledge modules that teach Claude how to do something.

- **Purpose**: Encode best practices and tool knowledge
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`

### Commands
User-facing entry points invoked with `/command-name`.

- **Purpose**: Orchestrate workflows with user interaction
- **Location**: `commands/<name>.md`
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.

### 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/commands/agents.

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