🛡️ Architecture Guard

Keep AI-generated code aligned with your architecture, specs, and delivery workflow.

Architecture Guard is a technology-agnostic SDD Tools Orchestration layer for AI-assisted engineering.

AI agents (like Claude Code, Gemini, and OpenCode) are incredibly fast but often create architectural drift, duplicate business logic, and ignore established patterns. Architecture Guard solves this by wrapping their actions in structured, governed workflows. It automatically forces agents to check historical memory, validate plans against architecture rules, and apply pragmatic engineering constraints before writing any code.

It orchestrates the full delivery path—from discovery and specification through planning, implementation, and verification—while adapting to the project's existing SDD tool. It works with OpenSpec, Spec Kit, or a generic Markdown workflow without replacing them.

🌟 Core Features: Built for AI Engineering

Architecture Guard doesn't just manage files; it actively constraints AI behavior using proven engineering practices:

• OpenSpec & Spec Kit Governance: Detects the active SDD tool and applies the matching artifact paths, commands, and gap fills.
• Ponytail Core: Applies one shared decision ladder across discovery, planning, tasks, implementation, and review. Includes root-cause caller tracing, a safety floor, and runnable checks for non-trivial logic. (Inspired by the Ponytail Pragmatism Skill)
• DRY Cleanup Guidance: Prevents agents from blindly copying code. It helps find duplicated business logic, validation, DTO mapping, and orchestration, turning them into small refactor tasks instead of silent drift.
• Flash-Mem Context Injection: Automatically queries Flash-Mem first to inject historical architectural decisions before the AI generates any new plans or specs.
• Repository Hygiene Guard: Automatically detects stray *-copy.ts drafts, orphaned code, and debug artifacts generated by AI before they hit your main branch. Learn more →

🚀 Installation & Setup

Architecture Guard is published on npm as a standalone SDD orchestration tool and installer for agent-native workflows. The simplest way to use it is directly via npx:

npx architecture-guard

Or, if you prefer to install it globally on your machine:

npm install -g architecture-guard
architecture-guard

To update a globally installed CLI explicitly, run architecture-guard update (or architecture-guard self-update).

The installer launches a setup wizard that asks you to select:

1. AI agent(s) — OpenCode, Claude Code, Gemini CLI, etc.
2. SDD tool — Spec Kit, OpenSpec, or a generic Markdown workflow.
3. Governed workflows — Pick the orchestration and governance workflows you need.

It installs the necessary command files directly into your agent's command or skill directory. The installer uses @inquirer/prompts; the installed governance commands themselves are Markdown and require no runtime dependency.

🧭 The Governed Workflows

Instead of letting AI agents run wild, Architecture Guard provides structured entry points that guide them from idea to implementation safely:

| Workflow Command | When To Use | What It Does | | :--- | :--- | :--- | | ag-governed-discover(or /speckit.ag-governed-discover) | Idea-stage | Shapes a rough request into a spec-ready direction before formal specification. | | ag-governed-delivery(or /speckit.ag-governed-delivery) | Delivery stage | Resumes governed delivery from an active specification through plan and task generation, with optional memory context, security and architecture gates, task reconciliation, and analysis. | | ag-governed-delivery-team(or /speckit.ag-governed-delivery-team) | Team delivery | Creates a stakeholder-approved User Story before the governed plan-to-tasks workflow. | | ag-governed-archive(or /speckit.ag-governed-archive) | Finalization | Archives a completed feature after verification, with explicit approval for changelog, memory, Git, and cleanup actions. | | ag-governed-implement(or /speckit.ag-governed-implement) | Implementation | Executes the generated tasks while strictly following the plan and architecture rules. |

(Note: Granular commands like ag-governed-spec, ag-governed-plan, and ag-governed-tasks are still available if you want manual control. See the Manual Workflow Guide.)

Suggested Feature Delivery Flow

/ag-governed-discover (optional, to brainstorm an idea)
  → /ag-governed-delivery (generates or reconciles the plan and tasks)
  → /ag-governed-implement (writes the code)
  → /ag-verify (checks for unapproved drift)

📚 Technical Documentation Map

We split the Architecture Guard manual into focused technical resources:

architecture-guard/
├── README.md                  ← Readable, high-level project summary
└── docs/
    ├── beginner-guide.md       ← Plain-language explanation and first workflow
    ├── architecture-overview.md ← Problem statement, value, and behavior
    ├── governance-model.md      ← Constitution layers and delegation model
    ├── workflows.md             ← Governed discovery, specification, planning, task, and implementation flows
    ├── reference-manual.md      ← Setup, commands, install, and validation details
    ├── presets.md               ← Supported framework presets (Django, Laravel, Next.js, etc.)
    ├── dry-cleanup.md           ← Brownfield DRY cleanup flow and duplication signals
    ├── repository-hygiene.md    ← Repository Hygiene rules and configuration
    └── release-notes.md         ← Change history and workflow updates

Direct Links

• Standalone Usage Guide
• Manual Workflow Guide
• Adapter Reference
• Spec Kit Integration Guide
• OpenSpec Integration Guide
• Beginner Guide
• Architecture Overview
• Governance Model
• Workflows
• Reference Manual
• Framework Presets
• DRY Cleanup Guide
• Repository Hygiene

⚙️ Design Philosophy

• Non-blocking by default: violations become refactor tasks unless a rule is explicitly marked blocking.
• Reviewable in Git: the rules live in markdown files, not hidden state.
• Architecture first: orchestration keeps boundaries, ownership, and drift visible across the delivery lifecycle.
• Ponytail Core: one shared ladder prevents both over-building and unsafe under-building across every delivery phase.

🔄 Spec Kit Compatibility

The standalone orchestrator is the primary experience. Existing SpecKit users (v1.15.1 and earlier) remain fully supported through extension.yml installation.

If your project is already centered on Spec Kit, you can continue installing Architecture Guard as a native Spec Kit extension. See the Spec Kit Integration Guide.