/architect-first

name: architect-first
description: Guide for implementing the Architect-First development philosophy - perfect architecture, pragmatic execution, quality guaranteed by tests. Use this skill when starting new features, refactoring systems, or when architectural decisions are needed. Enforces non-negotiables like complete design/documentation before code, zero coupling, and validation by multiple perspectives before structural decisions.

Architect First

Overview

This skill embodies the "Architect-First" development philosophy: **Perfect architecture, pragmatic execution, quality guaranteed by tests**. Apply this skill when making architectural decisions, starting new features, refactoring existing systems, or when quality gates need to be enforced.

The core principle: **Architecture and documentation are non-negotiable and must precede implementation. Code quality is negotiable IF backed by tests as a safety net (escape hatch).**

Core Philosophy

Mantra

"Arquitetura perfeita, execução pragmática, qualidade garantida por testes"

Quality Gates

**Non-Negotiable (STOP if violated):**

• **Architecture**: Complete design and documentation BEFORE any code
• **Documentation**: Must precede and accompany implementation
• **Capability Preservation**: Never lose capability/granularity vs previous versions
• **Zero Coupling**: Expansion packs must be independent
• **Multi-Agent Validation**: Structural decisions validated by PO/Architect/User

**Negotiable (with escape hatch):**

• **Code Style**: Acceptable if backed by tests as safety net
• **Feature Completeness**: 80% acceptable IF core use case works
• **Quick & Dirty Code**: Allowed ONLY with test plan and minimal logging

Decision Modes

**Architect-First Mode (default):**

• Design and document completely before coding
• Map structure and pointers before proposing implementation
• Validate architecture with multiple agents/perspectives
• Externalize all mutable configurations to YAML

**Fast Mode (post-validation only):**

• Binary decisions and rapid delegation
• Activated ONLY after architectural validation is complete
• Speed through automation, not shortcuts

Workflow Decision Tree

New Task/Feature Request
    ↓
┌──────────────────────────────────────┐
│ Is this a structural/architectural   │
│ decision?                            │
└──────────────────────────────────────┘
    ↓ YES                    ↓ NO
    ↓                        ↓
[Architecture Flow]    [Execution Flow]

Architecture Flow (Structural Decisions)

**STOP and follow this sequence:**

1. **Map Before Modify**

• Document current state completely
• Identify all dependencies and touch points
• Create architectural diagrams/flows
• Load `references/architecture-checklist.md` for validation

2. **Multi-Agent Validation**

• Present A/B/C options with explicit trade-offs
• Get validation from:
• Product Owner (business alignment)
• Architect (technical soundness)
• User (final decision)
• Document decision rationale

3. **Design Documentation**

• Complete design document BEFORE code
• Include:
• System architecture diagrams
• Component interactions
• Data flows
• Configuration schema (YAML)
• Integration points
• Use templates from `assets/architecture-template.md`

4. **Gold Standard Baseline**

• Ensure new design meets/exceeds capability baseline
• Validate: Does this maintain ALL previous capabilities?
• STOP if capability loss detected → restore or redesign

5. **Zero Coupling Validation**

• Run validation script: `scripts/check_coupling.py`
• Ensure expansion pack independence
• No hardcoded cross-module dependencies

6. **Proceed to Implementation**

• Now and only now: write code
• Follow execution flow for implementation

Execution Flow (Implementation)

1. **Pre-Implementation Checklist**

• [ ] Architecture documented and validated?
• [ ] Core use case clearly defined?
• [ ] Configuration externalized to YAML?
• [ ] Test strategy defined?
• Use `references/pre-implementation-checklist.md`

2. **Test-Driven Safety Net**

• Define test plan FIRST
• Identify logging/observation points
• Tests permit temporary imperfection (escape hatch)
• Quality validation via: tests + logs + manual inspection

3. **Implementation Style**

   ACCEPTABLE:
   ✓ "Ugly" code WITH comprehensive tests
   ✓ 80% feature completeness IF core case works
   ✓ Quick implementation WITH test plan + logging

   REJECTED:
   ✗ "Ugly" code WITHOUT tests
   ✗ Capability loss without explicit justification
   ✗ Hardcoded mutable values (must be YAML)
   ✗ Deployment without core case working

4. **Debugging Philosophy**

• Observational via logs (console/logging) > static analysis
• Add strategic log points before debugging
• Inspect actual runtime behavior
• Validate through execution, not just reading code

5. **Documentation**

• Update docs as code evolves
• Keep short and actionable: "How to customize"
• Include code examples
• Document configuration options

Heuristics (Decision Rules)

Apply these heuristics when making decisions:

1. **Gold Standard Baseline**: 22 artifacts minimum (adjust to your context) 2. **Never Lose Capability**: Accumulate, never reduce 3. **Architect Before Build**: Design/docs before code, always 4. **Zero Coupling, Max Modularity**: Independent expansion packs 5. **Config > Hardcoding**: Externalize to YAML for all mutable values 6. **Map Before Modify**: Document structure before changing it 7. **Binary Decision Post-Validation**: Fast execution after architectural validation 8. **Speed via Automation**: Not via shortcuts or cutting corners 9. **Quality Escape Hatch**: Tests permit temporary imperfection

Stop Rules (Hard Boundaries)

**STOP immediately if detecting:**

• ⛔ **Capability loss** vs baseline
• ⛔ **Structural decision** without multi-agent validatio