diff --git a/CLAUDE.md b/CLAUDE.md index 4840dae..bdba767 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,34 @@ -# Claude Code AI Workflow +# Architecture -This repository contains configurations, prompts, and tools to improve the Claude Code AI workflow. +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/ai.git -cd ai +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 ``` -ai/ +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) @@ -25,41 +39,28 @@ ai/ All files symlink to `~/.claude/` via `make install`. -## Architecture +## Two Levels of Vision -### Skills -Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`. +| Level | Document | Command | Purpose | +|-------|----------|---------|---------| +| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs | +| Product | `vision.md` | `/vision` | Product-specific direction and goals | -- **Purpose**: Encode best practices and tool knowledge -- **Location**: `skills//SKILL.md` -- **Usage**: Included in commands for context, auto-triggered by Claude Code +See the manifesto for our identity, personas, and beliefs about AI-augmented development. -Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues. +## Available Commands -### Commands -User-facing entry points invoked with `/command-name`. Run in main conversation context. - -- **Purpose**: Orchestrate workflows with user interaction -- **Location**: `commands/.md` -- **Usage**: User types `/dashboard`, `/work-issue 42`, etc. - -Commands reference skills for knowledge and optionally spawn agents for subtasks. - -### Agents -Small, focused units that handle specific subtasks in isolated context. - -- **Purpose**: Complex subtasks that benefit from isolation -- **Location**: `agents//agent.md` -- **Usage**: Spawned via Task tool, return results to caller - -Good agent candidates: -- Code review (analyze diff, report issues) -- Content generation (write issue body, PR description) -- Analysis tasks (categorize, prioritize, summarize) - -**When to use agents vs direct execution:** -- Use agents when: task is self-contained, benefits from isolation, can run in parallel -- Use direct execution when: task needs conversation history, requires user interaction mid-task +| Command | Description | +|---------|-------------| +| `/manifesto` | View/manage organization manifesto | +| `/vision` | View/manage product vision and milestones | +| `/work-issue ` | Fetch issue, create branch, implement, create PR | +| `/dashboard` | Show open issues and PRs | +| `/review-pr ` | 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 @@ -73,19 +74,32 @@ tea logins add --name flowmade --url https://git.flowmade.one --token ` | Fetch issue, create branch, implement, create PR | -| `/dashboard` | Show open issues and PRs | -| `/review-pr ` | Review PR with diff and comments | -| `/create-issue` | Create single or batch issues | -| `/retro` | Capture learnings, create improvement issues | -| `/vision` | View/manage product vision and milestones | -| `/plan-issues` | Break down features into issues | -| `/improve` | Identify gaps between vision and backlog | +### Skills +Knowledge modules that teach Claude how to do something. -## Vision & Goals +- **Purpose**: Encode best practices and tool knowledge +- **Location**: `skills//SKILL.md` +- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md` -Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command. +### Commands +User-facing entry points invoked with `/command-name`. + +- **Purpose**: Orchestrate workflows with user interaction +- **Location**: `commands/.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//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 diff --git a/README.md b/README.md index 8d604db..c5ae520 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# Claude Code AI Workflow +# Architecture + +The organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI. A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices. @@ -53,8 +55,8 @@ The project is built around three composable component types: ```bash # Clone the repository -git clone ssh://git@code.flowmade.one/flowmade-one/ai.git -cd ai +git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git +cd architecture # Install symlinks to ~/.claude/ make install @@ -87,7 +89,9 @@ echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username ## Project Structure ``` -ai/ +architecture/ +├── manifesto.md # Organization vision, personas, beliefs +├── learnings/ # Captured learnings and governance ├── commands/ # Slash commands invoked by users │ ├── work-issue.md │ ├── dashboard.md diff --git a/commands/retro.md b/commands/retro.md index 71dcc53..5adfff4 100644 --- a/commands/retro.md +++ b/commands/retro.md @@ -32,10 +32,10 @@ The retro creates the issue. Encoding happens when the issue is worked on. - **Where to encode it**: Which skill, command, or agent should change? - **Governance impact**: What does this mean for how we work? -4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`: +4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`: ```bash - tea issues create -r flowmade-one/ai \ + tea issues create -r flowmade-one/architecture \ --title "[Learning] " \ --description "## Context [Task that triggered this insight]