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>
3.7 KiB
3.7 KiB
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
# 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:
# 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