Layered Architect

Deterministic architecture planning for humans and coding agents who occasionally think "TODO: figure it out later" is a design pattern.

What This Is

layered-architect is a skill/framework for producing architecture docs that are:

• structured,
• traceable,
• validated,
• hard to fake with hand-wavy prose.

It enforces a staged flow (L0-L5), strict gates, research evidence, and semantic cross-layer checks.

What Problem It Solves

Most architecture docs fail in one of these ways:

• no clear constraints,
• decisions not linked to requirements,
• great-looking diagrams that cannot survive implementation,
• "we validated it" with zero proof.

This repo fixes that with explicit gates and auditable artifacts.

Architecture Flow

flowchart TD
  A["doctor"] --> B["init (profile: agent-ai)"]
  B --> C["L0/L1"]
  C --> D["validate (strict)"]
  D --> E{"External deps or infra?"}
  E -->|Yes| F["Research Gate: research.md + research.evidence.json + approval receipt"]
  E -->|No| G["L2"]
  F --> G
  G --> H["Dependencies Gate"]
  H --> I["L3"]
  I --> J["L4"]
  J --> K["L5 (auto-trigger if needed)"]
  K --> L["Semantic Validation Shards A-E (+F/G)"]
  L --> M["semantic complete (receipt)"]
  M --> N["validate (strict, json)"]
  N --> O["gate sync"]
  O --> P["Ready for implementation / PRD"]

Core Principles

• Strict means strict: warnings block progression.
• No manual gate toggling: gate state is receipt-backed.
• Research must be evidenced: no "trust me bro, model memory said so".
• Cross-layer consistency matters: L1 constraints must survive into L4/L5 reality.

Repository Layout

• SKILL.md agent operating rules
• references/ARCHITECTURE_WORKFLOW.md canonical sequence and gates
• references/QUESTION_WORKFLOW.md canonical questioning and ambiguity handling
• references/INDEX.md reference map
• scripts/arch.py unified CLI (single entrypoint)
• schemas/ gate, dependency, and evidence schemas
• assets/ templates

Quick Start

python scripts/arch.py doctor --path .
python scripts/arch.py init --path . --profile agent-ai
python scripts/arch.py status --path .plan
python scripts/arch.py next --path .plan

When ready to validate:

python scripts/arch.py validate --path .plan --strict --format json > .plan/last-validation.json
python scripts/arch.py gate sync --path .plan --from .plan/last-validation.json

Unified CLI Cheatsheet

Project lifecycle

python scripts/arch.py doctor --path .
python scripts/arch.py init --path . --profile agent-ai
python scripts/arch.py status --path .plan
python scripts/arch.py next --path .plan
python scripts/arch.py run --path .plan

Validation

python scripts/arch.py validate --path .plan --strict
python scripts/arch.py validate --path .plan --soft
python scripts/arch.py validate --path .plan --strict --format json > .plan/last-validation.json
python scripts/arch.py deps --path .plan --strict
python scripts/arch.py lint --path . --strict
python scripts/arch.py consistency --path .plan

Research gate

python scripts/arch.py research validate --path .plan --strict
python scripts/arch.py research approve --path .plan --approved-by "<name>" --confirm-user-approval

Semantic gate

python scripts/arch.py semantic validate --path .plan --strict
python scripts/arch.py semantic complete --path .plan --completed-by "<name>"

Gate sync

python scripts/arch.py gate sync --path .plan --from .plan/last-validation.json

Required Artifacts

• .plan/gates.yml
• .plan/constraints.yml
• .plan/dependencies.yml
• .plan/research.md (when research required)
• .plan/research.evidence.json (when research required)
• .plan/semantic-validation.md|json

Research Evidence (Anti-Hallucination)

When research is required, approvals only count if evidence exists and validates:

• sources with retrieval timestamps,
• claims mapped to source IDs,
• decision impact mapping,
• executor metadata (task_id or manual_user_input path).

If strict mode is enabled and evidence is missing/weak, progression is blocked.

Semantic Validation (Shard-Based)

Required shards:

• A: L1 <-> L2
• B: L2 <-> L3
• C: L3 <-> L4
• D: constraints.yml <-> L2/L3/L4
• E: dependencies.yml <-> L3/L4
• F if L0 exists
• G if L5 exists

Each shard needs status, findings, executor metadata, and evidence refs.

Agent Docs (Canonical)

• SKILL.md
• references/ARCHITECTURE_WORKFLOW.md
• references/QUESTION_WORKFLOW.md
• references/INDEX.md

Deprecated docs are kept as lightweight redirects for compatibility.

Installing

Place this folder into your tool's skills/plugins location and restart:

• Codex skill directory, or
• your platform's equivalent skill folder.

Then invoke /layered-architect (or your platform's skill invocation syntax).

Testing

Run the built-in test suite:

python scripts/tests/test_all.py

Opinionated Notes

• This framework values determinism over vibes.
• If you want "just brainstorming", this is probably too strict.
• If you need architecture that survives real implementation and review, this is exactly the point.

FAQ

"Can I just set research_approved: true manually?"

No. That is equivalent to self-signing your own compliance audit.

"Can I skip semantic validation?"

You can, in the same way you can deploy on Friday at 5:59 PM. Technically possible, generally unwise.

"Why so many gates?"

Because postmortems are more expensive than validation.

License

MIT. See LICENSE.