Aegis — AI Development Quality Guardian

AI Development Quality Guardian — contract-driven, design-first quality guardrails for AI-assisted full-stack development. Five-layer defense: Design → Contr...

Security Scan

The skill's files and runtime instructions are coherent with a contract-first, repo-level guardrails tool — it modifies the project (creates contracts/, .aegis/, CI workflows, and git hooks) and runs local generators/validators, which is expected for this purpose.

Purpose & Capability

The name/description (contract-driven QA guardrails) match the included templates and scripts: init-project.sh, setup-guardrails.sh, validate/generate scripts, and many contract-first references. The requested capabilities (reading/writing contracts, generating types, installing pre-commit hooks and CI files) are consistent with a repo-level guardrails tool.

Instruction Scope

SKILL.md instructs scanning the workspace and running the provided scripts (validate-contract.sh, setup-guardrails.sh, init-project.sh). Those scripts read many project files and will create/copy files into the project (contracts/, .aegis/, CLAUDE.md, docker-compose.integration.yml, .github workflows, .git/hooks/pre-commit). This behavior is expected for guardrails but is broader than a read-only linter: it changes the repo and installs hooks/CI config. Users should expect repository modifications and review the files first.

Install Mechanism

There is no formal install spec (instruction-only), but bundled scripts invoke network tools when executed (e.g., npx openapi-typescript, python pip install --user pyyaml). Those commands will download packages at runtime if the user runs the scripts. No opaque external download URLs are embedded in the skill, but the scripts will fetch code from public package registries when executed.

Credentials

The skill declares no required environment variables, credentials, or config paths. The scripts create standard test credentials in generated docker-compose (e.g., test/test DB defaults) for local integration tests; these are typical for test environments and not requests for secrets.

Persistence & Privilege

The skill writes persistent files into the project (.aegis/, contracts/, CLAUDE.md, docker-compose.integration.yml) and installs a pre-commit hook into .git/hooks if a .git repo exists. always is false and the skill does not request platform-wide elevated privileges, but repository-level changes are automatic when the provided scripts are run.

Assessment

This skill is coherent with its stated purpose but performs repository changes and may run package-tool downloads when you execute its scripts. Before running any scripts: 1) review the scripts (init-project.sh, setup-guardrails.sh, .aegis/*) to confirm you accept the changes they make (pre-commit hooks, CI workflow, new files), 2) run them in a safe environment (branch or disposable clone) so changes are easy to revert, 3) be aware the scripts may call npx and pip which fetch packages from the network, and 4) do not run them as root or in environments with sensitive/uncommitted secrets. If you want minimal impact, inspect and run only the parts you trust (for example generate-types.sh or validate-contract.sh) rather than running init/setup that install hooks and CI configs automatically.

Five-layer defense for AI-assisted software development.

Modes

Lite Mode (Default for small tasks)

• Design Brief only → straight to implementation
• Use when: solo dev, single-service feature, quick fix

Full Mode (Multi-service / team projects)

• Complete contract-first workflow
• Use when: multiple API boundaries, team collaboration, complex features

---

Phase 0: Workspace Architecture Detection

Before starting the Aegis workflow, detect the project architecture to choose the right contract strategy.

Auto-Detection

Scan the workspace for indicators:

• Both frontend//client//web/ AND backend//server//api/ directories → Monorepo
• package.json with workspaces containing both frontend and backend → Monorepo
• Only one side present (pure frontend or pure backend) → Split Workspace

If Split Workspace detected, ask the human:

Detected: This workspace contains only {frontend|backend} code.
Where does the other side live?

(a) Another repo managed by the same agent (I can access it)
(b) Another repo managed by a different agent/workspace (I cannot access it)
(c) This is actually a monorepo (I missed something)

Architecture Modes

Mode	Contract Location	Sync Method
Monorepo	contracts/ in project root	Direct (same repo)
Multi-Repo, Single Agent	Lead workspace's contracts/, copied to each repo	Copy before dispatch
Cross-Agent, Cross-Workspace	Dedicated contract repository	Git submodule / package / lead copy-sync

Cross-Workspace: Contract lives in an independent Git repo. Each agent's workspace integrates it as read-only. Contract Change Requests go through the Lead who has merge rights. See references/multi-agent-protocol.md for the full protocol.

---

Phase 1: Design

Before any non-trivial feature, create a Design Brief:

1. Read templates/design-brief.md for the template
2. Fill in: Problem Statement, Architecture Overview, Key Decisions, Module Boundaries, API Surface, Known Gaps, Testing Strategy
3. Submit for human review
4. Gate: Do not proceed to Phase 2 until Design Brief is approved

Lite Mode stops here — proceed to Phase 3 after Design Brief approval.

Phase 2: Contract (Full Mode)

Define the API contract before writing implementation code:

1. Create/update contracts/api-spec.yaml (OpenAPI 3.1) — use templates/api-spec-starter.yaml as base
2. Create/update contracts/shared-types.ts — use templates/shared-types-starter.ts as base
3. Create/update contracts/errors.yaml — use templates/errors-starter.yaml as base
4. Run bash scripts/validate-contract.sh <project-path> to check consistency
5. Gate: Contracts must be reviewed before implementation begins

Reference: references/contract-first-guide.md for the full contract-first methodology.

Phase 3: Implementation

Pre-Coding Checklist (EVERY TIME before writing code)

1. Check if contracts/ exists in the project root
2. If yes: read contracts/api-spec.yaml, contracts/errors.yaml, contracts/shared-types.ts
3. Read CLAUDE.md for project-specific constraints
4. If a Design Brief exists for your task: read docs/designs/ relevant file

Hard Rules (violation = PR rejected)

R1: Contract is the truth

• All API responses MUST conform to contracts/api-spec.yaml
• Response shapes, status codes, field names — all from the spec

R2: Shared types — import, never redefine

• import { User, ApiResponse } from '../contracts/shared-types'
• NEVER create local types that shadow contract types
• If shared-types doesn't have what you need → file a Change Request (R5)

R3: Error codes from registry only

• Use codes defined in contracts/errors.yaml
• Never invent ad-hoc error codes
• Need a new code → file a Change Request (R5)

R4: Contract tests mandatory

• Every new API endpoint MUST have a contract test
• Contract test = validate real response against OpenAPI spec schema
• Modified endpoints → update contract test

R5: Never modify contracts directly If the contract needs changes:

1. Create docs/contract-changes/CHANGE-{date}-{description}.md
2. Include: what, why, which modules affected
3. Continue implementing with the CURRENT contract
4. Human reviews and updates the contract

R6: CLAUDE.md constraints

• Read and follow all ⛔ Hard Constraints in CLAUDE.md
• These are project-specific and override general preferences

R7: Pre-commit checks are mandatory

• Run lint → type-check → format-check → contract validation before committing
• After ALL code changes, run formatters as a final step
• Never bypass with --no-verify

Quick Reference

Situation	Action
Need a new endpoint	Check api-spec.yaml first
Need a new type	Check shared-types.ts → if missing, Change Request
Need a new error code	Check errors.yaml → if missing, Change Request
API response doesn't match spec	Fix code, not spec
Spec seems wrong	Change Request, implement per current spec
No contracts/ directory	Hard rules don't apply — standard development

Phase 4: Verification

After implementation, validate quality:

1. Run contract tests — bash scripts/validate-contract.sh <project-path>
2. Run frontend tests — pnpm test (if frontend exists)
3. Run backend integration tests — HTTP E2E against real server + real DB
4. Generate gap report — bash scripts/gap-report.sh <project-path>
5. Review: are all Design Brief items implemented?
6. Review: do all endpoints have contract + integration tests?
7. Gate: All tests must pass before PR/MR

Testing Hierarchy

E2E Test          ← Playwright (real browser + real backend)
Integration Test  ← Real HTTP server + real DB (no mocks)
Contract Test     ← Validate against api-spec.yaml (NO mocking the contract)
Frontend Test     ← Vitest + React Testing Library + MSW (contract-typed mocks)
Unit Test         ← Mock external deps, test pure logic

Frontend Testing (when project has frontend)

• Stack: Vitest + React Testing Library + MSW
• Required coverage: API clients (normal/error/auth), data hooks (loading/success/error), key components
• MSW handlers: must mock every backend endpoint with data matching contracts/shared-types.ts
• CI gate: pnpm test must pass — same blocking power as backend tests

Backend Integration Testing (HTTP E2E)

• Every endpoint must have: happy path (200) + bad request (400) + not found (404) + auth failure (401)
• Real database — isolated test DB, not mocks. Transactions or migrations for clean state.
• Mutation verification — POST/PUT/DELETE → GET to confirm state change
• CI pipeline: lint → type-check → unit → frontend-test → contract → integration → build → E2E

Test Strategy = Design Artifact

Full-stack features require a complete testing strategy in the Design Brief before coding begins.

Reference: references/testing-strategy.md for the full testing pyramid and standards.

Phase 5: PM

Track progress and enforce quality gates:

1. Update docs/designs/<feature>/implementation-summary.md — use templates/implementation-summary.md
2. Mark Design Brief items as completed
3. Note any contract Change Requests filed during implementation
4. Release readiness check: all gates passed?

---

Project Setup

Initialize Aegis in any project:

bash scripts/init-project.sh /path/to/project

This creates:

• contracts/ — API spec, shared types, error codes (stack-aware)
• docs/designs/ — for Design Briefs
• .aegis/ — portable validation scripts
• CLAUDE.md — from Aegis template (if not existing)
• docker-compose.integration.yml — auto-detects your database

Set up guardrails (pre-commit hooks + CI):

bash scripts/setup-guardrails.sh /path/to/project --ci github  # or --ci gitlab

---

Multi-Agent Protocol

When multiple agents work on the same project:

• Each agent reads contracts before starting
• Contracts are the synchronization point — not code
• Change Requests prevent concurrent contract modifications

Cross-Workspace: When agents operate in separate workspaces, contract lives in a dedicated repository. Each agent integrates via submodule/package/copy-sync and treats contracts/ as read-only. Integration testing is orchestrated externally.

Reference: references/multi-agent-protocol.md

File Structure

~/.claude/skills/aegis/          # ← You are here (CC skill)
├── SKILL.md                     # This file
├── templates/                   # Project templates
│   ├── design-brief.md
│   ├── claude-md.md
│   ├── api-spec-starter.yaml
│   ├── shared-types-starter.ts
│   ├── errors-starter.yaml
│   ├── contract-test-example.ts
│   ├── docker-compose.integration.yml
│   └── implementation-summary.md
├── scripts/                     # Automation
│   ├── init-project.sh          # Initialize Aegis in a project
│   ├── setup-guardrails.sh      # Pre-commit + CI setup
│   ├── detect-stack.sh          # Auto-detect language/framework
│   ├── validate-contract.sh     # Validate contract consistency
│   ├── gap-report.sh            # Design Brief vs implementation gaps
│   └── generate-types.sh        # Generate types from OpenAPI spec
└── references/                  # Deep-dive guides
    ├── contract-first-guide.md
    ├── testing-strategy.md
    └── multi-agent-protocol.md