architecture-patterns

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):

# 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