Hugo Nijhuis
f8d4640d4f
- Add Architecture Beliefs section to manifesto with outcome-focused beliefs: auditability, business language in code, independent evolution, explicit over implicit - Create software-architecture.md as human-readable documentation - Enhance software-architecture skill with beliefs→patterns mapping (DDD, Event Sourcing, event-driven communication) and auto-trigger description - Update work-issue command to reference skill and check project architecture - Update issue-worker agent with software-architecture skill - Add Architecture section template to vision-management skill The skill is now auto-triggered when implementing, reviewing, or planning architectural work. Project-level architecture choices go in vision.md. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 |
|
|
| `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
|
|
|
|
```
|
|
architecture/
|
|
├── manifesto.md # Organization vision and beliefs
|
|
├── software-architecture.md # Patterns linked to beliefs (DDD, ES)
|
|
├── learnings/ # Captured learnings and governance
|
|
├── 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`.
|
|
|
|
## Two Levels of Vision
|
|
|
|
| Level | Document | Command | 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 Commands
|
|
|
|
| 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
|
|
|
|
Uses `tea` CLI for issue/PR management:
|
|
|
|
```bash
|
|
# 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
|
|
Knowledge modules that teach Claude how to do something.
|
|
|
|
- **Purpose**: Encode best practices and tool knowledge
|
|
- **Location**: `skills/<name>/SKILL.md`
|
|
- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
|
|
|
|
### 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
|