Skip to content

Getting started

This guide takes you from a fresh clone to your first set of business artifacts.

Requirements

  • An agent host: VS Code with GitHub Copilot Chat in Agent mode, or Claude Code.
  • Python 3.10 or later.
  • Git.

1. Install

git clone https://github.com/nishant-tamilselvan/AEGIS.git
cd AEGIS
python -m venv .venv
.venv/Scripts/activate            # Windows
# source .venv/bin/activate       # macOS / Linux
pip install -e .

Check the tooling works:

python -m artifact_tools --help

This guide uses a clone of AEGIS. Two other options:

  • Claude Code plugin (preview): install AEGIS into your own repository instead. See AEGIS as a Claude Code plugin; commands then carry an aegis: prefix, such as /aegis:start-ideation.
  • CLI only: pip install aegis-sdlc installs the artifact-tools command without the agents, for example for CI. See the CLI reference.

2. Open the workspace

GitHub Copilot: open the AEGIS folder in VS Code. Copilot Chat picks up the repository's customizations automatically:

Folder Gives you
.github/agents/ The AEGIS agents in the agent picker.
.github/prompts/ Slash commands such as /start-ideation.
.github/skills/ Skills the agents load on demand.
.github/copilot-instructions.md Rules every agent follows.
.github/hooks/ The implementation guard and automatic validation.

Claude Code: run claude in the AEGIS folder. See Using AEGIS with Claude Code for what it loads and how to check it.

The rest of this guide works the same on both platforms.

3. Connect your standards (optional)

AEGIS works without a standards library, but it asks fewer questions with one. To try it with the included sample standards:

pip install -r examples/enterprise-standards-server/requirements.txt
cp .vscode/mcp.example.json .vscode/mcp.json   # GitHub Copilot
cp .mcp.example.json .mcp.json                 # Claude Code

In VS Code, open .vscode/mcp.json and start enterprise-standards-server. In Claude Code, restart and approve the project server. The Enterprise Standards setup guide explains how to use your own standards instead.

4. Run ideation (phase 1)

In Copilot Chat or Claude Code, run:

/start-ideation customer-portal A self-service portal where customers track orders and raise support tickets

The Ideation Orchestrator works through the idea one small phase at a time. Answer its questions, and confirm each recap before it moves on. When the phase ends, docs/artifacts/customer-portal/ holds six business artifacts:

  • product requirements (PR-*)
  • functional requirements (FR-*)
  • non-functional requirements (NFR-*)
  • user journey map (UJ-*)
  • system blueprint (BP-*)
  • executive briefing (RISK-*)

Check the set at any time:

python -m artifact_tools validate docs/artifacts/customer-portal

5. Run architecture (phase 2)

/start-architecture customer-portal

The Architecture Orchestrator guides you through interfaces, data, security, deployment and observability. It records significant choices as ADRs. This adds five technical artifacts, the architecture-decisions/ folder and the interfaces/ contract store.

6. Run implementation (phase 3)

Implementation writes code into a separate target repository. Pass its absolute path:

/start-implementation customer-portal /path/to/target-repository

A read-only readiness gate runs first. It blocks until:

  • every artifact has status: approved;
  • no open decision is marked as blocking;
  • every interface has a native contract file;
  • the standards review is verified;
  • the target repository has discoverable conventions.

The orchestrator then plans bounded work packages (WP-*). Each needs your approval, an independent review and recorded evidence before it can complete.

Check the implementation guard once

The guard is what keeps implementation agents inside their work package. It runs as a hook, so confirm that your agent host actually runs it before you rely on it:

  1. Approve the first work package and let the orchestrator move it to in-progress.
  2. Ask the orchestrator: "As a guard test, have the package's implementer create one file outside the package's target paths. Do not retry."
  3. The write must be denied with "… is outside the active work package's declared target paths."

If the write goes through, the hooks are not running:

Host Where the hooks are configured What to check
GitHub Copilot .github/hooks/validate-artifacts.json Your VS Code and Copilot Chat versions support agent hooks, and hooks are enabled for this workspace.
Claude Code .claude/settings.json /hooks lists the PreToolUse hook, and you trusted the folder interactively. See Using AEGIS with Claude Code.

On both hosts, python on your PATH must be able to import PyYAML, because the hooks run python scripts/implementation_guard.py.

Other prompts

Prompt Use it to
/add-requirement Add or change a requirement and update every affected artifact.
/run-review-cycle Run the critic's self-correction loop over the artifacts.
/add-adr Record an architectural decision.
/resume-implementation Pick up phase 3 where you left off.
/implementation-status See progress, blockers and the next work package.
/run-implementation-review Run the independent review of a package or the release.
/add-implementation-decision Record a tactical choice or escalate a material one.

Next steps