# Aegis Workflow Guide

Status: `Approved`

## 1. Document Position

This guide helps users and contributors understand how `Aegis Method Pack`
triggers, routes, executes, verifies, and closes engineering tasks.

This is an explanatory guide. The authority sources remain:

1. `AGENTS.md`
2. `docs/current/README.md`
3. `docs/adr/ADR-0001-aegis-method-pack-is-not-runtime-core.md`
4. Task-relevant `docs/current/*.md`
5. Host install and usage docs

This guide does not add runtime authority. It does not grant `GateDecision` or
`completion authority`.

---

## 2. Aegis In One Sentence

Aegis is currently:

> `Aegis Method Pack (runtime-ready)`

Its job is to make AI coding agent work more stable, evidence-driven, and
recoverable:

- classify task type and risk before editing
- make code-change necessity visible before adding any source-code path and
  before non-trivial source edits
- read project baselines and authority sources before acting from session memory
- split complex work into verifiable slices
- keep repair, compatibility, retirement, and verification evidence visible
- produce runtime-ready drafts, hints, and projections for a future runtime core

It does not currently own:

- final governance adjudication
- authoritative `PolicySnapshot`
- authoritative `GateDecision`
- final `completion authority`

---

## 3. Overall Flow

A standard Aegis workflow can be summarized as:

```text
startup routing
  -> task classification
  -> baseline readback
  -> problem definition
  -> investigation and approach decision
  -> plan and minimal slices
  -> TDD Route / implementation
  -> verification and regression
  -> reflection and QA closure
  -> output facts, evidence, impact scope, and residual risk
```

Not every task uses the full workflow. Simple tasks stay on the fast path;
complex tasks use the standard path.

---

## 4. Startup Routing

At the start of a task, Aegis checks whether a relevant skill should be loaded.

The typical entry point is `using-aegis`:

- it is a compact router
- it does not contain the full workflow
- it does not replace task-specific skills
- it does not absorb every trigger rule into one entry file

If the user explicitly invokes a skill, such as `aegis:systematic-debugging` or
`aegis:writing-plans`, the matching skill takes priority.

If the user starts with `/aegis-goal <task>` or `Aegis goal: <task>`, load
`goal-framing` first. It creates a thin `TaskIntentDraft` frame with goal,
success evidence, stop condition, and non-goals, then continues into the routed
workflow by default. Goal framing does not create project files by default and
does not grant completion authority. Stop at the frame only when the user
explicitly asks to only define the goal / stop condition, not execute, not
implement, not write a plan, or wait for confirmation.

Example:

```text
Aegis goal: Fix the auth refresh bug without rewriting the auth system.
```

Route from the goal frame by signal:

| Goal signal | Route |
| --- | --- |
| single-owner, low-risk, clear verification | fast path or TDD Route `light` / `skipped` |
| bug, failure, regression, unexpected behavior | `systematic-debugging` |
| ambiguous product, architecture, contract, cross-module behavior | `brainstorming` |
| approved spec, stable requirements, implementation slicing | `writing-plans` |
| multi-step, handoff, compaction-prone work | `long-task-continuation` |
| completion, release, handoff, "is this done?" | `verification-before-completion` |

If the task is small, such as a factual question, version check, or tiny wording
edit, the agent may continue after a compact routing check without creating
project workspace records.

### Semantic Project Context

For non-trivial project work, the task-owning workflow passively selects
relevant active language from root `CONTEXT.md` and, when present, the bounded
context mapped by `CONTEXT-MAP.md`. Passive reading does not load active domain
modeling. Tiny tasks perform no context ceremony.

`establishing-project-context` composes only for a resolved term, ambiguity,
conflict, rename, deprecation, or authority/code mismatch. An A/B existing fact
may update directly and minimally; an unresolved semantic decision asks one
bounded user question and does not become active truth. The first resolved term
may create the file lazily. `CONTEXT.md` stays terminology-only and does not
replace requirements, architecture baselines, ADRs, task state, or runtime
authority.

Compact, stable context can improve cache friendliness, but Aegis does not
guarantee provider cache hits, latency reduction, context-capacity reduction,
or billing savings.

---

## 5. Task Classification

Aegis chooses the execution path by complexity.

### 5.1 Fast Path

Use for:

- simple Q&A
- clear small configuration changes
- low-risk single-file edits
- tasks that do not touch contracts, architecture, cross-module behavior, or
  shared logic

Requirements:

- confirm the intent briefly
- read only the evidence needed
- act directly
- run risk-matched verification
- report the result, evidence, and remaining unknowns

### 5.2 Standard Path

Use for:

- bug diagnosis
- feature work
- refactoring
- architecture work
- performance work
- contract, schema, shared-module, or cross-module behavior changes

Requirements:

- define the problem and acceptance method first
- read relevant baseline and authority docs
- identify owner, impact scope, compatibility boundary, and non-goals
- plan minimal slices
- verify, regress, and close quality after implementation

### 5.3 High-Complexity Path

Use for:

- unclear goals or wide solution space
- possible architecture boundary changes
- multiple producers or consumers
- public API, schema, persistence, cache, export, or source-of-truth impact
- work that needs user confirmation before implementation

Requirements:

- write a Spec Brief or Design Spec first
- plan before execution
- create `docs/aegis/work/` records when needed
- do not package inferences as conclusions before user confirmation or clear
  authority sources

---

## 6. Baseline First

Before non-trivial execution, read the smallest relevant baseline.

Inside the Aegis repository, common starting points are:

- `docs/current/README.md`
- `docs/adr/ADR-0001-aegis-method-pack-is-not-runtime-core.md`
- task-relevant `docs/current/*.md`

In a target project, candidate baselines include:

- project `AGENTS.md`
- README
- ADRs
- `docs/current/`
- `docs/aegis/baseline/`
- architecture, contract, test, or run docs

If no usable baseline exists, Aegis performs a bounded index-first scan: file
index, README, manifests, entry points, key modules, and tests. It initializes a
project baseline only when evidence is sufficient.

---

## 7. Standard Execution Loop: DIVE

The minimum standard-path cycle is `DIVE`.

### 7.1 Define

Make the task concrete:

- what needs to be solved
- who is affected
- what the current environment is
- where the issue reproduces
- why it matters now
- how it should be approached
- how success will be accepted

### 7.2 Investigate

Find the real owner and cause:

- where the data comes from and where it goes
- who the canonical owner is
- whether compatibility boundaries are involved
- whether fallbacks, adapters, duplicate owners, or historical patches exist
- whether a local bug has escalated into architecture or contract territory

### 7.3 Validate

Confirm the judgment and implementation with evidence:

- whether evidence supports the current conclusion
- whether the change meets acceptance criteria
- whether new risk, drift, or hidden dependencies were introduced
- whether tests cover real user paths and critical boundaries

### 7.4 Evolve

Decide whether to close or continue:

- can the current task end
- should the work keep iterating
- should the problem definition escalate
- should baseline, ADR, plan, or verification strategy change

---

## 8. Reflection And QA Gate

Every standard task round uses the minimum reflection shape:

```text
Goal:
DeeperCause:
Evidence:
Risk/Unknown:
Decision:
```

QA closure is not "it seems to work." Before closing, state:

- what was verified
- which behavior the evidence covers
- which risks remain
- where the rollback boundary is
- whether old owners, fallbacks, adapters, or compatibility paths were removed
  or explicitly retained

---

## 9. Dual-Track Governance

For bug fixes, architecture refactors, contract adjustments, and governance
cleanup, Aegis uses dual-track governance by default.

### 9.1 Repair Track

Answer:

- what the true root cause is
- who the unique canonical owner is
- what the minimum necessary change is
- where the compatibility boundary is
- how verification will be performed

### 9.2 Retirement Track

Answer:

- where old logic, duplicate owners, fallbacks, or historical patches are
- whether they are still active on the main path
- whether they can be deleted in the current slice
- if not deleted, why they are retained, how they will be observed, and when
  they should retire
- how deletion or retention is verified without lingering references or damage

Default rule: when adding the repair, account for the old logic in the same
slice. Do not add new branches without explaining the old branches.

Anti-Entropy default:

- internal code retirement should prefer `delete-first`
- external compatibility retention requires active dependency evidence
- `persistent-state` or irreversible source-of-truth deletion requires
  `confirmation-first`

Mentioning destructive guardrails does not authorize destructive execution.
Without explicit scoped user confirmation, do not execute irreversible
deletion, do not emit a runnable destructive command as the next action, and do
not treat generic assent as confirmation.

---

## 10. TDD And Test Iron Law

TDD is the implementation discipline. It is not the first entry point for every
complex task.

TDD Mode defaults to `off` and has two values:

- `off`: do not automatically require TDD; explicit TDD requests still apply
- `auto`: choose TDD Route `strict`, `light`, or `skipped` by task risk

TDD Mode controls test-first discipline, not completion evidence.
`verification-before-completion` still applies in both modes.

Before implementation, confirm:

- the requirement or issue is defined
- owner and impact scope are identified
- required baselines have been read
- code change is necessary versus no-change, docs/config-only, or clarification
- the task can be split into verifiable slices

This check does not depend on the user naming a keyword. Whenever Aegis is
about to add any source-code path, or enter a non-trivial source edit, it should
naturally state why a non-code path is insufficient, what the minimum change
boundary is, and why the decision is `code-change`. Tiny helpers, small guards,
new branches, fallbacks, adapters, and owners are not exempt merely because
they look small.

Test iron law:

- if code is wrong, fix the code
- if the test is wrong, fix the test
- do not change tests to hide business defects
- do not change business code to satisfy incorrect tests
- the final target is correct business behavior and accurate test expectations

---

## 11. Trigger Health Diagnosis

If Aegis is installed but the expected skill does not reliably trigger, do not
first stuff more keywords into a skill description.

Diagnose the trigger chain:

1. install and version visibility
2. host skill discovery
3. activation mode and bootstrap entry
4. `using-aegis` router entry
5. task-to-skill routing
6. skill execution depth
7. context pressure and re-entry
8. false positive over-triggering

Common checks:

- verify the install root and version
- verify the host can discover the current `skills/`
- verify whether the host needs restart or reload
- verify whether activation mode is `auto` or `explicit`
- explicitly invoke `aegis:using-aegis` or the target skill for comparison

See `docs/current/AEGIS_TRIGGER_HEALTH_BASELINE.md` for the diagnostic layers.

---

## 12. Long Tasks And Workspace Records

Aegis supports a lazy project workspace.

Do not create `docs/aegis/` by default for:

- global install or version queries
- simple Q&A
- tiny wording edits
- low-risk fast-path tasks

Create or use `docs/aegis/` when the workflow needs:

- baseline bootstrap
- Spec Brief / Design Spec
- medium or high complexity planning
- ripple triage
- long-task continuation
- a recoverable evidence trail
- completion-time ADR backfill from durable architecture decisions

Typical structure:

```text
docs/aegis/
├── README.md
├── INDEX.md
├── BASELINE-GOVERNANCE.md
├── adr/
├── baseline/
├── specs/
├── plans/
└── work/
```

These records are method-layer evidence and handoff material, not final runtime
adjudication.

### 12.1 ADR Auto Backfill

ADR Auto Backfill runs near completion, not before execution.

When completed work changes a durable architecture surface, Aegis should check
whether to create, amend, supersede, or skip an ADR. It reads the strongest
available source:

```text
work -> plan -> spec -> git / verification evidence
```

Examples of durable architecture surfaces include owners, public contracts,
dependency direction, source-of-truth ownership, host compatibility strategy,
runtime-ready artifact boundaries, and retained or retired fallback paths.

ADR and baseline records are linked:

```text
ADR records why.
Baseline records current state.
```

When an ADR changes or confirms current architecture state, Aegis must run a
baseline sync check. If the baseline is not updated, the ADR or reflection
should state why the existing baseline still holds.

See `docs/current/AEGIS_ADR_AUTO_BACKFILL.md`.

---

## 13. Common Skill Responsibilities

`using-aegis`
: Decide whether to enter an Aegis workflow and select the right skill.

`brainstorming`
: Clarify new features, product behavior, UI, architecture, contract, or
medium/high-complexity direction. Its optional `Grilling Mode` starts only
when the user asks to grill or pressure-test an idea, plan, or design (for
example, `grill me`, `grill this plan`, `审问我`, `盘问我`, or `拷问我`). Softer
challenge language first asks whether to enter Grill or use normal
brainstorming; PRs, diffs, and current-code reviews remain code-review work.
The one-time opening card makes the target, question path, and pace visible.
Deep pace asks one dependent decision at a time; user-requested fast pace may
batch up to three independent questions. It does not plan or implement until
the user leaves the interview and completes the normal design gate.

`writing-plans`
: Convert an existing spec or requirement into verifiable executable tasks.

`executing-plans`
: Execute a written plan and keep review checkpoints between phases.

`systematic-debugging`
: Trace bugs, test failures, or unexpected behavior from symptom to root cause.

`test-driven-development`
: Use tests to drive minimal implementation and regression coverage before
feature or bugfix code.

`first-principles-review`
: Use when direction is complex, repeated fixes are accumulating, fallbacks are
growing, owners are duplicated, or the user explicitly asks for first
principles. Before risky approach selection or task decomposition, it can
escalate to a decision hygiene review covering first-principles invariants,
owner / retirement, and falsification checks.

`requesting-code-review`
: Check behavioral risks, regressions, and missing tests after important work.

`verification-before-completion`
: Require fresh verification evidence before claiming done, fixed, passing,
release-ready, or handoff-ready. For medium/high work that touched durable
architecture surfaces, also run the ADR Auto Backfill check. When goal framing
exists, include Goal Closure: goal status, success evidence, stop state, and
whether non-goals were respected.

`long-task-continuation`
: Maintain checkpoints, resume hints, and drift checks for long, cross-session,
or handoff-prone work.

---

## 14. Final Output Ordering

Aegis user-facing output should usually present evidence-backed facts before
interpretation, and interpretation before recommendations, decisions, or
completion claims:

```text
Facts -> Inferences -> Conclusions
```

This is an ordering principle, not a mandatory top-level template. It must not
override workflow-owned semantic slots or task-specific output contracts such
as findings-first code review, verification evidence slots, the unified
`Aegis Impact and Safety Receipt`, governance closure,
`Execution Readiness View`, `Aegis Visibility`, or on-demand `Trace Digest`.

For non-trivial tasks, keep the attention anchors that make the relevant logic
auditable:

- Facts
- Evidence
- Recommendation / Approach
- Impact Scope

Extend by task type:

- Diagnosis: reproduction, root cause, blockers
- Feature work: acceptance criteria, interface or data contract changes
- Architecture work: option comparison, trade-offs, ADR references
- Refactoring: hotspots, test safety net, complexity changes
- Performance: baseline, bottleneck, gains
- Risk and rollback: trigger conditions, rollback steps, feature flags

When Aegis materially shapes a non-trivial task, final completion should use a
compact impact/safety receipt by default. The receipt should show the decision
Aegis changed, likely misfixes it avoided, boundaries it held, baseline
alignment, complexity control, evidence strength, uncovered risk, and the next
most valuable verification. Individual cards such as Baseline Alignment,
Complexity Delta, Readiness Summary, Goal Closure, Retirement Closure, and ADR
Backfill Check remain available as expanded details for risk, release, audit,
or user request; they should not each become separate default completion
formats.

When the user asks for white-box auditability, use an on-demand `Trace Digest`
instead of a default process log. It may summarize execution trace, evidence
chain, retrieval chain, static rules evaluated, rule effects, skill-call
stability, tool / command trace, verification trace, value signals, host
capability gaps, unavailable fields, and redaction. It must not expose raw
internal reasoning or claim runtime authority.

---

## 15. Boundary Reminder

Aegis can make a host work more like a rigorous engineering agent, but this
repository is still a `Method Pack`.

Aegis can currently produce:

- `TaskIntentDraft`
- `BaselineReadSetHint`
- `BaselineUsageDraft`
- `ImpactStatementDraft`
- `EvidenceBundleDraft`
- `GateInputPack`
- `SubagentContextPacket`
- `TodoCheckpointDraft`
- `ResumeStateHint`
- `DriftCheckDraft`

It can also produce an on-demand `Trace Digest` as an advisory white-box
summary. `Trace Digest` is not an authoritative `GateDecision`, `PolicySnapshot`,
or completion authority.

It may also render an `Execution Readiness View` from existing drafts and plans
as a human-readable execution handoff. This view is not a new authoritative
artifact type, `GateDecision`, `PolicySnapshot`, or completion authority.

These are drafts, hints, or projection inputs. They can help a future runtime
core make decisions, but they must not be written as final authority already
owned by this repository.