🛡️ 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.
• Jira Story Scope: Discovery proposes related stories for you to accept, and specifications record the accepted set for later scope checks. Jira access is read-only during discovery and review. Story scope guide →
• Governance Suggestions: Discovery can propose rule or workflow changes with supporting evidence; applying them requires a separately approved edit. Discovery workflow →
• 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 →
• SonarLint Code Quality Bundle: Ships 37 architecture-relevant rules across Java, JavaScript, TypeScript, Python, and PHP (derived from SonarSource) to catch brain overload, cyclomatic/cognitive complexity, coupling, and boundary cast drift during implementation reviews. Sonar rules guide →
• Multi-Host Parallel Agent Teams: Coordinates specialist subagents (analyst_reviewer, code_reviewer, implementor_be, implementor_fe, implementor_test, implementor_e2e) across Claude Code, OpenAI Codex, Google Antigravity (agy), and OpenCode with tiered workspace isolation. Team roles guide →

🚀 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, a generic Markdown workflow, or any other SDD tool through a custom adapter.
   The code host (GitHub, GitLab, Bitbucket, Azure DevOps, or plain git) is auto-detected from the origin remote for pull-request work; override it with --forge. See FORGES.md.
3. Governed workflows — Pick the orchestration and governance workflows you need.

It installs the necessary command files directly into the agent command or skill directory. The installer uses @inquirer/prompts; lean prompts require a callable architecture-guard CLI for resource resolution and CLI-backed hygiene, while --vendor copies static engine resources locally and avoids bundled-resource lookup for those assets.

🧭 The Governed Workflows

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

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

Suggested Feature Delivery Flow

/ag-governed-discover (optional, to brainstorm an idea)
  → /ag-governed-spec (creates and clarifies the specification)
  → /ag-governed-delivery (generates or reconciles the plan and tasks)
  → /ag-governed-implement (writes the code)
  → /ag-verify base=main (checks for unapproved drift and runs the same change checks as the pull-request review)

Suggested Pull Request Flow

/ag-review-pr <number or URL>   (reviewing a teammate's pull request)
/ag-pr-feedback                 (working through feedback on your own pull request)
/ag-pr-queue                    (all of it in one command: feedback on your open pull requests, reviews for your team's)

Both skills reach your code host through a forge adapter: a registered MCP server for the host, then its CLI (gh, glab, az), then plain git. Nothing is posted, pushed, or resolved without your approval.

📚 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, implementation, and pull-request flows
    ├── reference-manual.md      ← Setup, commands, install, and validation details
    ├── presets.md               ← Supported framework presets (Angular, React, Vue, Next.js, Laravel, NestJS, 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
• Workflow Guide
• Adapter Reference
• Forge Reference (code hosts and pull-request skills)
• Spec Kit Integration Guide
• OpenSpec Integration Guide
• Beginner Guide
• Architecture Overview
• Governance Model
• Workflows
• Reference Manual
• Framework Presets
• DRY Cleanup Guide
• Repository Hygiene
• SonarLint Rules Bundle
• Release Notes

⚙️ 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, and all new features ship there. The legacy Spec Kit extension (extension.yml installation) remains available for existing Spec Kit users with limited support: it receives safety and breakage fixes only, not new features. New Spec Kit projects should use the standalone installer with --framework spec-kit.

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.

Multi-host Agent Teams (Claude, Codex, Antigravity, OpenCode)

Install skills and optional native team roles with architecture-guard init . --yes --agent <host> --<host>-agents (supports claude with --claude-agent-teams, codex with --codex-agents, antigravity with --agy-agents, and opencode with --opencode-agents). Interactive CLI setup asks a unified multi-select across all selected team-role hosts, interviews for custom rosters/models, and configures auto-activation (agent_teams.activation: auto | ask | manual) and workspace isolation (agent_teams.isolation: auto | worktree | shared) in .architecture-guard/config.yml. Refresh roles anytime with architecture-guard sync-team-roles --agent <host>. Profiles and role files remain separate per host (.codex/agents/*.toml, .agents/agents/*.md, .opencode/agents/*.md, .claude/agents/*.md).

Sequential execution is the default when unconfigured. Coordinated implementation activates automatically when configured with agent_teams.activation: auto or when explicitly selected for the run, dispatching parallel read-only review passes (Analyst Reviewer || Plan/Task Security Review, and Code Reviewer || Implementation Security Review || E2E) and concurrent writer implementors ([BE], [FE], [TEST], [E2E]). Concurrent writers run with tiered workspace isolation: host-native workspace sharing (agy share) or per-role Git worktrees (.git/ag-worktrees/agteam-<role>) in the owning repository for shared-tree hosts (codex, opencode). Lead sessions reconcile worktrees, halt on conflicts, and prune temporary worktrees before hygiene checks. Parent permissions apply; Codex and OpenCode role files cannot override sandbox, approval, or MCP settings. Unsupported required restrictions prevent role activation.

Shared contracts govern delegation, complete handoffs, current-context reuse, and exact-scope approval reuse. Distinct human gates and external effects retain approval. See setup and permission details and execution policy. Fixture tests do not prove runtime host enforcement; unavailable host/security checks are reported explicitly.

Resource overrides and generic/OpenSpec archive paths must not contain symbolic links below the workspace root; the CLI rejects them to prevent paths escaping the workspace. These checks assume the workspace is not concurrently modified by an untrusted process while the CLI runs.

🙏 Credits, Inspirations & Ecosystem References

Architecture Guard is built alongside and inspired by open-source tools, methodologies, and specifications across the AI-assisted engineering ecosystem:

Spec-Driven Development (SDD) Frameworks

• Spec Kit (spec-kit.dev) — Constitutional Spec-Driven Development toolkit that inspired Architecture Guard's layered constitution model and legacy extension format.
• OpenSpec — Spec-driven change lifecycle (propose → specs → design → tasks → apply → archive) supported as a first-class built-in SDD adapter.

Engineering Methodology & Pragmatism

• Ponytail Pragmatism Skill by Dietrich Gebert — Direct inspiration for the Ponytail Core contract (templates/ponytail_core.md), enforcing an ordered YAGNI decision ladder, root-cause caller tracing, a non-negotiable safety floor, and runnable verification.

Companion Governance, Memory & Testing Ecosystem

• Flash-Mem — SQLite-backed Model Context Protocol (MCP) server for durable project memory, typed knowledge objects, and token-budgeted context retrieval.
• Security Review — Companion whitebox security governance skill suite (sr-init, sr-plan, sr-tasks, sr-branch, sr-audit, sr-verify) for OWASP/CWE verification across plans, tasks, branches, and pull requests.
• Spec-Kit E2E Stream & Playwright (microsoft/playwright) — End-to-end UI and API verification patterns powering ag-e2e-testing.

Code Quality & Static Analysis Rule Catalogs

• SonarSource Rules Catalog — Upstream rule metadata, severities, and complexity/coupling semantics from sonar-java, SonarJS, sonar-python, and sonar-php powering the 37 architecture-focused rules in sonar-rules/sonarlint-rules.json.

Backlog, Issue Tracking & Code Host Protocols

• Beads (bd) by Steve Yegge — Distributed, git-backed issue tracker for AI coding agents integrated as a native queue source in ag-governed-backlog.
• Model Context Protocol (MCP) & GitHub MCP Server — Standardized tool protocol used for Jira story-scope checks, User Story tracker sync, and code-host forge operations.

Multi-Host Agent & Subagent Runtimes

• Claude Code & Agent Teams — Native agteam-* subagent definitions and experimental team orchestration.
• OpenAI Codex CLI (Subagent Configuration) — Scoped .codex/agents/agteam-*.toml role profiles and feature reductions.
• Google Antigravity (agy) — Native .agents/agents/agteam-*.md subagent invocation and share workspace isolation.
• OpenCode (opencode.ai) — Native .opencode/agents/agteam-*.md subagents with declarative read-only tool envelopes.