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

# 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