architecture/old2/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
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:

# 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