architecture/CLAUDE.md

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

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

# 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