architecture/CLAUDE.md

Claude Code AI Workflow

This repository contains configurations, prompts, and tools to improve the Claude Code AI workflow.

Setup

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

Project Structure

ai/
├── 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.

Architecture

Skills

Knowledge modules that teach Claude how to do something. Referenced by commands via @~/.claude/skills/xxx/SKILL.md.

• Purpose: Encode best practices and tool knowledge
• Location: skills/<name>/SKILL.md
• Usage: Included in commands for context, auto-triggered by Claude Code

Example: gitea skill teaches tea CLI usage, issue-writing teaches how to structure issues.

Commands

User-facing entry points invoked with /command-name. Run in main conversation context.

• Purpose: Orchestrate workflows with user interaction
• Location: commands/<name>.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/<name>/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

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

Available Commands

Command	Description
/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, create improvement issues
/vision	View/manage product vision and milestones
/plan-issues	Break down features into issues
/improve	Identify gaps between vision and backlog

Vision & Goals

Product vision lives in vision.md (philosophy) and Gitea milestones (goals with progress tracking). See /vision command.