diff --git a/CLAUDE.md b/CLAUDE.md index bdba767..ddcb9e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) diff --git a/agents/issue-worker/agent.md b/agents/issue-worker/agent.md index c0ffc79..701f289 100644 --- a/agents/issue-worker/agent.md +++ b/agents/issue-worker/agent.md @@ -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 diff --git a/commands/work-issue.md b/commands/work-issue.md index f0d58a0..d9c705e 100644 --- a/commands/work-issue.md +++ b/commands/work-issue.md @@ -6,12 +6,14 @@ argument-hint: # 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-` 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] " 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 diff --git a/manifesto.md b/manifesto.md index 1685398..c60da91 100644 --- a/manifesto.md +++ b/manifesto.md @@ -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 diff --git a/skills/software-architecture/SKILL.md b/skills/software-architecture/SKILL.md index 6e191aa..99db4ee 100644 --- a/skills/software-architecture/SKILL.md +++ b/skills/software-architecture/SKILL.md @@ -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 diff --git a/skills/vision-management/SKILL.md b/skills/vision-management/SKILL.md index 6e4aad4..ea5518d 100644 --- a/skills/vision-management/SKILL.md +++ b/skills/vision-management/SKILL.md @@ -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 diff --git a/software-architecture.md b/software-architecture.md new file mode 100644 index 0000000..b667748 --- /dev/null +++ b/software-architecture.md @@ -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.