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 with structured workflows, issue management, and AI-assisted development practices.

Why This Project?

Claude Code is powerful, but its effectiveness depends on how you use it. This project provides:

• Structured workflows for common development tasks (issue tracking, PR reviews, planning)
• Composable components that build on each other (skills, agents, commands)
• Forgejo integration for seamless issue and PR management
• Consistent patterns that make AI assistance more predictable and effective

Core Concepts

The project is built around three composable component types:

┌─────────────────────────────────────────────────────────┐
│                      COMMANDS                           │
│         User-facing entry points (/work-issue)          │
│                         │                               │
│                         ▼                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │                    AGENTS                        │   │
│  │    Subprocesses with isolated context            │   │
│  │    (parallel processing, complex workflows)      │   │
│  │                      │                           │   │
│  │                      ▼                           │   │
│  │  ┌───────────────────────────────────────────┐  │   │
│  │  │                 SKILLS                     │  │   │
│  │  │   Reusable knowledge modules               │  │   │
│  │  │   (gitea, issue-writing, planning)       │  │   │
│  │  └───────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Component	Purpose	Example
Commands	Entry points users invoke directly	/work-issue 42 starts implementation workflow
Skills	Domain knowledge modules	issue-writing knows how to structure good issues
Agents	Autonomous subprocesses	product-manager combines skills for complex planning

Quick Start

Prerequisites

• Claude Code CLI installed
• Forgejo CLI (tea) for issue/PR management

Installation

# Clone the repository
git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
cd architecture

# Install symlinks to ~/.claude/
make install

Forgejo Setup

# Install gitea-cli
brew install gitea-cli

# Authenticate (one-time)
echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username

# Required token scopes: read:user, read:repository, write:issue, write:repository

Available Commands

Command	Description
/dashboard	Show open issues and PRs for the current repo
/work-issue <n>	Fetch issue, create branch, implement, and create PR
/review-pr <n>	Review a PR with diff analysis and feedback
/create-issue	Create single or batch issues interactively
/plan-issues <desc>	Break down a feature into discrete issues
/groom [n]	Improve issue quality (single or batch)
/roadmap	Visualize issues by status and dependencies

Project Structure

architecture/
├── manifesto.md        # Organization vision, personas, beliefs
├── learnings/          # Captured learnings and governance
├── commands/           # Slash commands invoked by users
│   ├── work-issue.md
│   ├── dashboard.md
│   ├── review-pr.md
│   ├── create-issue.md
│   ├── plan-issues.md
│   ├── groom.md
│   └── roadmap.md
├── skills/             # Reusable knowledge modules
│   ├── gitea/        # Forgejo CLI integration
│   ├── issue-writing/  # Issue structure best practices
│   ├── backlog-grooming/  # Backlog maintenance
│   ├── roadmap-planning/  # Feature breakdown
│   └── code-review/    # Code review best practices
├── agents/             # Specialized subagents
│   ├── product-manager/  # Combines skills for PM tasks
│   └── code-reviewer/  # Automated PR code review
├── scripts/            # Git hooks and utilities
│   └── pre-commit-checks.sh
├── settings.json       # Claude Code configuration
├── Makefile            # Symlink management
└── CLAUDE.md           # Instructions for Claude Code

Example Workflows

Working on an Issue

> /work-issue 42

Fetching issue #42: "Add user authentication"
Creating branch: feature/42-add-user-authentication
Planning implementation...
[Claude implements the feature]
Creating PR with reference to issue...

Planning a Feature

> /plan-issues Add dark mode support

Proposed Issues:
1. Create theme context and provider
2. Add theme toggle component
3. Update components to use theme variables
4. Add system preference detection

Create these issues? [y/n]

Daily Standup

> /dashboard

Open Issues (3):
| #  | Title                    | Labels      |
|----|--------------------------|-------------|
| 42 | Add user authentication  | feature     |
| 38 | Fix login redirect       | bug         |
| 35 | Update dependencies      | maintenance |

Open PRs (1):
| #  | Title                    | Status      |
|----|--------------------------|-------------|
| 41 | Add password reset flow  | review      |

Configuration

The settings.json configures Claude Code behavior:

• Model selection: Uses Opus for complex tasks
• Status line: Shows git branch and status
• Hooks: Pre-commit validation for secrets and YAML

Uninstall

make uninstall

This removes symlinks from ~/.claude/ and restores any backed-up files.

License

MIT