architecture-patterns v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/8c5b4b4a8e9a1bc2.

---
name: architecture-patterns
version: 1.0.0
type: knowledge
description: "File-by-file architecture planning with ADR format, dependency ordering, and testability gates. Use when designing system architecture or creating ADRs. TRIGGER when: architecture plan, system design, ADR, file breakdown, component design. DO NOT TRIGGER when: simple config edits, single-file bug fixes, documentation-only changes."
keywords: [architecture, planning, design, adr, file-breakdown, dependencies]
auto_activate: true
allowed-tools: [Read, Grep, Glob]
---

# Architecture Patterns Enforcement Skill

Ensures every architecture plan is thorough, actionable, and testable. Used by the planner agent.

## Decision Framework

Every architectural decision MUST follow this structure:

### 1. Problem Statement
- What problem are we solving?
- What are the constraints (performance, compatibility, timeline)?
- What does PROJECT.md say about scope?

### 2. Options Analysis
- Minimum 2 alternatives considered
- Each option has explicit pros and cons
- Effort estimate for each (low/medium/high)

### 3. Recommendation
- Which option and why
- What tradeoffs are we accepting
- What risks remain

---

## Plan Structure Requirements

Every architecture plan MUST include:

### File-by-File Breakdown
```
## Files to Create/Modify

### 1. lib/new_module.py (CREATE)
- Purpose: [what this file does]
- Key classes/functions: [list]
- Dependencies: [what it imports]
- Tests: tests/unit/test_new_module.py

### 2. lib/existing_module.py (MODIFY)
- Changes: [what changes and why]
- Lines affected: ~[range]
- Risk: [low/medium/high]
```

### Ordered Steps with Dependencies
```
## Implementation Order

1. Create lib/new_module.py (no dependencies)
2. Create tests/unit/test_new_module.py (depends on step 1)
3. Modify lib/existing_module.py (depends on step 1)
4. Update integration tests (depends on steps 1-3)
```

Steps MUST be ordered so each step can be tested independently before proceeding.

### Testing Strategy
- Unit tests for each new module
- Integration tests for cross-module interactions
- What to mock and why
- Expected test count estimate

### Integration Points
- What existing code is affected
- API contracts between modules
- Backward compatibility considerations

---

## ADR Format for Major Decisions

For decisions that affect architecture (new patterns, technology choices, major refactors):

```markdown
# ADR-NNN: [Title]

**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded

## Context
[Problem and constraints]

## Decision
[What we chose and why]

## Consequences
[Positive and negative outcomes]

## Alternatives Considered
[Other options and why rejected]
```

---

## This Project's Patterns

When planning for this codebase, follow these established patterns:

### Two-Tier Design
- **Core lib** (`plugins/autonomous-dev/lib/`): Pure Python, no side effects, testable
- **CLI layer** (`plugins/autonomous-dev/commands/`): Markdown prompts that invoke lib

### Progressive Enhancement
- Base functionality works without optional dependencies
- GenAI reasoning enhances but never replaces deterministic checks
- Skills loaded on-demand, not all at once

### HARD GATE Enforcement
- Critical rules use FORBIDDEN/REQUIRED language
- Hooks validate at commit/push time (100% reliable)
- Agents enforce at review time (conditional intelligence)

### Hook-Based Validation
- Pre-commit hooks for formatting, secrets, alignment
- Pre-push hooks for tests, coverage
- Pre-tool hooks for security and workflow enforcement

---

## HARD GATE: Plan Quality

**FORBIDDEN**:
- Plans without specific file paths (e.g., "create a new module" without saying where)
- "TBD" or "to be determined" placeholders — decide now or state why you cannot
- Plans with no testing strategy
- Plans that skip scope validation against PROJECT.md
- Monolithic steps that cannot be tested incrementally
- Plans that ignore existing codebase patterns
- Hand-wavy "refactor later" promises

**REQUIRED**:
- File-by-file breakdown with CREATE/MODIFY labels
- Dependency ordering (what must come before what)
- Error handling strategy (what happens when things fail)
- At least 2 alternatives considered for major decisions
- Testing strategy with expected test locations
- Rollback plan (how to undo if the plan fails)
- Scope check against PROJECT.md goals

---

## Anti-Patterns

### BAD: Hand-wavy plan
```
"We should refactor the auth module to be more modular.
We can add better error handling later."
```
No file paths, no steps, no testing, no "later" promises.

### GOOD: Actionable plan
```
## Files to Modify
1. lib/auth.py (MODIFY) — Extract token validation into TokenValidator class
2. lib/token_validator.py (CREATE) — Pure validation logic, no side effects
3. tests/unit/test_token_validator.py (CREATE) — 8 tests covering valid/invalid/expired

## Order
1. Create token_validator.py + tests (independent)
2. Modify auth.py to use TokenValidator (depends on step 1)
3. Run full test suite to verify no regressions
```

### BAD: Monolithic steps
```
Step 1: Rewrite the entire authentication system
Step 2: Test everything
```
Cannot test incrementally, cannot roll back partially.

### GOOD: Incremental steps
Each step produces a testable, committable unit of work.

### BAD: Missing rollback plan
If the migration fails halfway through, what happens? Every plan needs a recovery path.

---

## Cross-References

- **research-patterns**: Research feeds into architecture planning
- **code-review**: Plans are reviewed against these quality standards
- **documentation-guide**: ADR format and documentation requirements