architect-first

Document system design before implementation with YAML-config-first constraints.

Updated May 6, 2025
One-click install
npx skills add https://github.com/rodrigo-altissimo/qiartificial --skill architect-first-rodrigo-altissimo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architect-first
Source: https://github.com/rodrigo-altissimo/qiartificial/tree/main/.claude/skills/architect-first
Command: npx skills add https://github.com/rodrigo-altissimo/qiartificial --skill architect-first-rodrigo-altissimo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires os, sys, argparse, re, pathlib, typing, yaml, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Architect-First prevents costly redesigns by forcing complete architecture and documentation before implementation, while ensuring zero coupling and capability preservation through validation and tests.

Core Features & Use Cases

  • Architecture and documentation gate: Stop and design fully before writing code, including diagrams, data flows, integration points, and configuration schema.
  • Multi-agent validation: Validate structural decisions with PO/Architect/User perspectives and document rationale before proceeding.
  • Quality escape hatch with tests: Allow pragmatic or imperfect code only when backed by a defined test plan and observation/logging points.
  • Capability preservation & zero coupling: Maintain all prior capabilities (gold standard baseline) and enforce independent expansion-pack/module boundaries, using coupling checks.

Use this skill when you are starting new features, refactoring systems, or making architectural decisions that affect module boundaries, integrations, or long-term maintainability.

Quick Start

Use the architect-first skill when you begin a structural change by writing a complete design and validation package first, then only proceed to implementation after multi-agent sign-off and zero-coupling validation.

Frequently Asked Questions about architect-first

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

FAQPage Schema
How do I enforce zero coupling between modules during a system refactor?

Zero coupling is enforced by applying independent expansion-pack and module boundary checks before implementation. Your refactor must pass coupling validation to ensure modules remain structurally independent and preserve all prior functional capabilities.

What is an architecture-first workflow and when do I need it for new features?

An architecture-first workflow forces complete system design, including diagrams and integration points, before any code is written. It is needed when starting new features or structural changes that affect long-term maintainability and module boundaries.

Can I write pragmatic code without full documentation during test-driven development?

Pragmatic code is allowed as a quality escape hatch only when backed by a defined test plan. You must include observation and logging points to maintain execution safety gates while preserving system capabilities.

How do I externalize configuration schema before implementing architectural changes?

Configuration schema is externalized using YAML-config-first constraints as part of the architecture gate. You must define the complete configuration schema in YAML before proceeding to implementation and multi-agent sign-off.

Why do I need multi-agent validation for architectural decisions?

Multi-agent validation checks structural decisions against PO, Architect, and User perspectives to ensure system design integrity. It requires documenting rationale before proceeding to implementation, preventing costly redesigns.

What are the limitations of allowing pragmatic code without full documentation?

Pragmatic or imperfect code is only permitted as a quality escape hatch when backed by a defined test plan. You must include observation and logging points to maintain test-backed execution safety gates and preserve all prior capabilities.