architect-first

Enforces architecture-first development with validation checklists, coupling checks, and test-backed quality gates.

Updated May 13, 2026
One-click install
npx skills add https://github.com/MarcoBolsa/motor-cotacoes --skill architect-first-marcobolsa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architect-first
Source: https://github.com/MarcoBolsa/motor-cotacoes/tree/main/.claude/skills/architect-first
Command: npx skills add https://github.com/MarcoBolsa/motor-cotacoes --skill architect-first-marcobolsa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Teams often start coding before architecture is designed and validated, leading to coupled modules, lost capabilities, hardcoded configuration, and undocumented decisions that are expensive to fix later. ## Core Features & Use Cases - Architecture-First Workflow: Enforces complete design documentation, multi-agent validation (PO/Architect/User), and zero-coupling checks before any code is written. - Quality Escape Hatch: Permits pragmatic, imperfect implementation only when backed by a defined test plan and strategic logging points. - Validation Tooling: Ships Python scripts to validate architecture documentation completeness, detect cross-module coupling, and verify risk mitigation coverage. - Use Case: When starting a new feature, the skill guides you to map the current system, present A/B/C design options with trade-offs, document the architecture from a template, externalize configuration to YAML, and only then implement with tests. ## Quick Start Ask the AI to apply the architect-first workflow to design and document a new feature before writing any implementation code.

Frequently Asked Questions about architect-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce architecture documentation before coding?▼

Use the architecture flow: map the current system, present A/B/C design options with trade-offs, get validation from Product Owner, Architect, and User, then complete the architecture template. The architecture_validator.py script checks that required sections, diagrams, and configuration schemas exist before implementation begins.

How to check for coupling between modules in Python?▼

Run the check_coupling.py script against your project path. It scans Python, JavaScript, TypeScript, and YAML files for hardcoded cross-module imports, hardcoded file paths to other modules, and shared global state, then reports violations with remediation steps.

When is quick and dirty code acceptable in development?▼

Imperfect code is acceptable only when backed by comprehensive tests, strategic logging points, and a working core use case. Code without tests, hardcoded mutable values, or deployments missing the core workflow are explicitly rejected by the stop rules.

What triggers the stop rules in this workflow?▼

Six conditions halt work immediately: capability loss versus baseline, structural decisions without multi-agent validation, coupling between modules, missing architectural documentation, quick code without a test plan, and hardcoded mutable configuration values. Each rule has a remediation guide.

Does this approach slow down feature development?▼

It includes a fast mode activated only after architectural validation completes, enabling binary decisions and rapid delegation. Risk mitigations like time-boxed planning, proof-of-concept requirements, and the rule of three prevent excessive planning and perfectionism cascades.