flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Prepare for repo rename: ai -> architecture

Browse Source 
Updated all internal references for the rename:
- CLAUDE.md: New purpose statement, updated structure, added manifesto info
- README.md: Updated title, clone URL, folder structure
- commands/retro.md: Changed flowmade-one/ai to flowmade-one/architecture

The actual Gitea rename should be done after merging this PR.

Closes #44

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit was merged in pull request #52.
This commit is contained in:
Hugo Nijhuis
2026-01-07 20:55:06 +01:00
parent dc7b554ee6
commit f1c555706b
3 changed files with 73 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
CLAUDE.md
View File

@@ -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/<name>/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/<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
| 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
@@ -73,19 +74,32 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
# Create token at: https://git.flowmade.one/user/settings/applications
```
## Available Commands
## Architecture Components
| 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 |
### Skills
Knowledge modules that teach Claude how to do something.
## Vision & Goals
- **Purpose**: Encode best practices and tool knowledge
- **Location**: `skills/<name>/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/<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

12
README.md
View File

@@ -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

4
commands/retro.md
View File

@@ -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] <brief description>" \
--description "## Context
[Task that triggered this insight]