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

Add architecture beliefs to manifesto and enhance software-architecture skill

Browse Source 
- 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>
This commit is contained in:
Hugo Nijhuis
2026-01-10 14:52:40 +01:00
parent 73caf4e4cf
commit f8d4640d4f
7 changed files with 308 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CLAUDE.md
View File

@@ -16,6 +16,7 @@ make install
| 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 |
@@ -27,9 +28,10 @@ make install
```
architecture/
├── manifesto.md # Organization vision and beliefs
├── learnings/ # Captured learnings and governance
├── commands/ # Slash commands (/work-issue, /dashboard)
├── 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)

3
agents/issue-worker/agent.md
View File

@@ -2,7 +2,7 @@
name: issue-worker
description: Autonomous agent that implements a single issue in an isolated git worktree
tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite
skills: gitea, issue-writing
skills: gitea, issue-writing, software-architecture
---
# Issue Worker Agent
@@ -119,6 +119,7 @@ This format is parsed by the orchestrator. Do NOT include verbose logs - only th
- **Always cleanup**: Remove the worktree when done, regardless of success/failure
- **Minimal changes**: Only change what's necessary to complete the issue
- **Follow patterns**: Match existing code style and conventions
- **Follow architecture**: Apply patterns from software-architecture skill, check vision.md for project-specific choices
## Error Handling

12
commands/work-issue.md
View File

@@ -6,12 +6,14 @@ argument-hint: <issue-number>
# Work on Issue #$1
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/software-architecture/SKILL.md
1. **View the issue** with `--comments` flag to understand requirements and context
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
3. **Plan**: Use TodoWrite to break down the work based on acceptance criteria
4. **Implement** the changes
5. **Commit** with message referencing the issue
6. **Push** the branch to origin
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
8. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number
4. **Check architecture**: Review the project's vision.md Architecture section for project-specific patterns and divergences
5. **Implement** the changes following architectural patterns (DDD, event sourcing where appropriate)
6. **Commit** with message referencing the issue
7. **Push** the branch to origin
8. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
9. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number

14
manifesto.md
View File

@@ -51,6 +51,20 @@ We believe AI fundamentally changes how software is built:
- **Iteration speed is a competitive advantage.** The faster you can go from idea to deployed code to learning, the faster you improve. AI collapses the feedback loop.
### Architecture Beliefs
We believe certain outcomes matter more than others when building systems:
- **Auditability by default.** Systems should remember what happened, not just current state. History is valuable - for debugging, compliance, understanding, and recovery.
- **Business language in code.** The words domain experts use should appear in the codebase. When code mirrors how the business thinks, everyone can reason about it.
- **Independent evolution.** Parts of the system should change without breaking other parts. Loose coupling isn't just nice - it's how small teams stay fast as systems grow.
- **Explicit over implicit.** Intent should be visible. Side effects should be traceable. When something important happens, the system should make that obvious.
See [software-architecture.md](./software-architecture.md) for the patterns we use to achieve these outcomes.
### Quality Without Ceremony
- Ship small, ship often

141
skills/software-architecture/SKILL.md
View File

@@ -1,12 +1,149 @@
---
name: software-architecture
description: Software architecture best practices, patterns, and review guidance. Foundation for architecture-related agents and commands including repo audits, issue refinement, and PR reviews.
description: >
Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
Use when implementing features, reviewing code, planning issues, refining architecture,
or making design decisions. Ensures alignment with organizational beliefs about
auditability, domain modeling, and independent evolution.
user-invocable: false
---
# Software Architecture
Best practices, patterns, and review guidance for software architecture. This skill serves as the knowledge base for architecture-related agents and commands.
Architectural patterns and best practices. This skill is auto-triggered when implementing, reviewing, or planning work that involves architectural decisions.
## Architecture Beliefs
These outcome-focused beliefs (from our organization manifesto) guide architectural decisions:
| Belief | Why It Matters |
|--------|----------------|
| **Auditability by default** | Systems should remember what happened, not just current state |
| **Business language in code** | Domain experts' words should appear in the codebase |
| **Independent evolution** | Parts should change without breaking other parts |
| **Explicit over implicit** | Intent and side effects should be visible and traceable |
## Beliefs → Patterns
| Belief | Primary Pattern | Supporting Patterns |
|--------|-----------------|---------------------|
| Auditability by default | Event Sourcing | Immutable events, temporal queries |
| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
| Independent evolution | Event-driven communication | Bounded contexts, published language |
| Explicit over implicit | Commands and Events | Domain events, clear intent |
## Event Sourcing
**Achieves:** Auditability by default
Instead of storing current state, store the sequence of events that led to it.
**Core concepts:**
- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
- **State** is derived by replaying events, not stored directly
- **Event store** is append-only - history is never modified
**Why this matters:**
- Complete audit trail for free
- Debug by replaying history
- Answer "what was the state at time X?"
- Recover from bugs by fixing logic and replaying
**Trade-offs:**
- More complex than CRUD for simple cases
- Requires thinking in events, not state
- Eventually consistent read models
## Domain-Driven Design
**Achieves:** Business language in code
The domain model reflects how the business thinks and talks.
**Core concepts:**
- **Ubiquitous language** - same terms in code, conversations, and documentation
- **Bounded contexts** - explicit boundaries where terms have consistent meaning
- **Aggregates** - clusters of objects that change together, with one root entity
- **Domain events** - capture what happened in business terms
**Why this matters:**
- Domain experts can read and validate the model
- New team members learn the domain through code
- Changes in business rules map clearly to code changes
**Trade-offs:**
- Upfront investment in understanding the domain
- Boundaries may need to shift as understanding grows
- Overkill for pure technical/infrastructure code
## Event-Driven Communication
**Achieves:** Independent evolution
Services communicate by publishing events, not calling each other directly.
**Core concepts:**
- **Publish events** when something important happens
- **Subscribe to events** you care about
- **No direct dependencies** between publisher and subscriber
- **Eventual consistency** - accept that not everything updates instantly
**Why this matters:**
- Add new services without changing existing ones
- Services can be deployed independently
- Natural resilience - if a subscriber is down, events queue
**Trade-offs:**
- Harder to trace request flow
- Eventual consistency requires different thinking
- Need infrastructure for reliable event delivery
## Commands and Events
**Achieves:** Explicit over implicit
Distinguish between requests (commands) and facts (events).
**Core concepts:**
- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
- Commands can be rejected (validation, business rules)
- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
- Events are immutable - what happened, happened
**Why this matters:**
- Clear separation of "trying to do X" vs "X happened"
- Commands validate, events just record
- Enables replay - reprocess events with new logic
## When to Diverge
These patterns are defaults, not mandates. Diverge intentionally when:
- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
- **Performance requires it** - sometimes synchronous calls are necessary
- **Team context** - patterns the team doesn't understand cause more harm than good
- **Prototyping** - validate ideas before investing in full architecture
When diverging, document the decision in the project's `vision.md` Architecture section.
## Project-Level Architecture
Each project documents architectural choices in `vision.md`:
```markdown
## Architecture
This project follows organization architecture patterns.
### Alignment
- Event sourcing for [which aggregates/domains]
- Bounded contexts: [list contexts and their responsibilities]
- Event-driven communication between [which services]
### Intentional Divergences
| Area | Standard Pattern | What We Do Instead | Why |
|------|------------------|-------------------|-----|
```
## Go-Specific Best Practices

11
skills/vision-management/SKILL.md
View File

@@ -123,6 +123,17 @@ These extend the organization's guiding principles:
These extend the organization's non-goals:
- **[Non-goal].** [Explanation]
## Architecture
This project follows organization architecture patterns (see software-architecture skill).
### Alignment
- [Which patterns we use and where]
### Intentional Divergences
| Area | Standard Pattern | What We Do Instead | Why |
|------|------------------|-------------------|-----|
```
### When to Update Vision

130
software-architecture.md Normal file
View File

@@ -0,0 +1,130 @@
# Software Architecture
> **For Claude:** This content is mirrored in `skills/software-architecture/SKILL.md` which is auto-triggered when relevant. You don't need to load this file directly.
This document describes the architectural patterns we use to achieve our [architecture beliefs](./manifesto.md#architecture-beliefs). It serves as human-readable organizational documentation.
## Beliefs to Patterns
| Belief | Primary Pattern | Supporting Patterns |
|--------|-----------------|---------------------|
| Auditability by default | Event Sourcing | Immutable events, temporal queries |
| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
| Independent evolution | Event-driven communication | Bounded contexts, published language |
| Explicit over implicit | Commands and Events | Domain events, clear intent |
## Event Sourcing
**Achieves:** Auditability by default
Instead of storing current state, we store the sequence of events that led to it.
**Core concepts:**
- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
- **State** is derived by replaying events, not stored directly
- **Event store** is append-only - history is never modified
**Why this matters:**
- Complete audit trail for free
- Debug by replaying history
- Answer "what was the state at time X?"
- Recover from bugs by fixing logic and replaying
**Trade-offs:**
- More complex than CRUD for simple cases
- Requires thinking in events, not state
- Eventually consistent read models
## Domain-Driven Design
**Achieves:** Business language in code
The domain model reflects how the business thinks and talks.
**Core concepts:**
- **Ubiquitous language** - same terms in code, conversations, and documentation
- **Bounded contexts** - explicit boundaries where terms have consistent meaning
- **Aggregates** - clusters of objects that change together, with one root entity
- **Domain events** - capture what happened in business terms
**Why this matters:**
- Domain experts can read and validate the model
- New team members learn the domain through code
- Changes in business rules map clearly to code changes
**Trade-offs:**
- Upfront investment in understanding the domain
- Boundaries may need to shift as understanding grows
- Overkill for pure technical/infrastructure code
## Event-Driven Communication
**Achieves:** Independent evolution
Services communicate by publishing events, not calling each other directly.
**Core concepts:**
- **Publish events** when something important happens
- **Subscribe to events** you care about
- **No direct dependencies** between publisher and subscriber
- **Eventual consistency** - accept that not everything updates instantly
**Why this matters:**
- Add new services without changing existing ones
- Services can be deployed independently
- Natural resilience - if a subscriber is down, events queue
**Trade-offs:**
- Harder to trace request flow
- Eventual consistency requires different thinking
- Need infrastructure for reliable event delivery
## Commands and Events
**Achieves:** Explicit over implicit
Distinguish between requests (commands) and facts (events).
**Core concepts:**
- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
- Commands can be rejected (validation, business rules)
- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
- Events are immutable - what happened, happened
**Why this matters:**
- Clear separation of "trying to do X" vs "X happened"
- Commands validate, events just record
- Enables replay - reprocess events with new logic
## When to Diverge
These patterns are defaults, not mandates. Diverge intentionally when:
- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
- **Performance requires it** - sometimes synchronous calls are necessary
- **Team context** - patterns the team doesn't understand cause more harm than good
- **Prototyping** - validate ideas before investing in full architecture
When diverging, document the decision in the project's vision.md (see below).
## Project-Level Architecture
Each project should document its architectural choices in `vision.md` under an **Architecture** section:
```markdown
## Architecture
This project follows organization architecture patterns.
### Alignment
- Event sourcing for [which aggregates/domains]
- Bounded contexts: [list contexts and their responsibilities]
- Event-driven communication between [which services]
### Intentional Divergences
| Area | Standard Pattern | What We Do Instead | Why |
|------|------------------|-------------------|-----|
| [area] | [expected pattern] | [actual approach] | [reasoning] |
```
This creates traceability: org beliefs → patterns → project decisions.