GanyuanRan/Aegis

# Anti-Entropy

## Overview

Use this skill when the task is not merely "change code" but "remove old paths
safely without growing entropy".

This skill chooses between:

- `delete-first` for internal code retirement
- `compat-exception` for proven external dependency boundaries
- `confirmation-first` for irreversible state or an external contract whose
  distributed consumers cannot be observed

<EXPLICIT-MODE-GATE>
If activation mode is explicit (`~/.config/aegis/config.toml` has
`activation_mode = "explicit"`, or `AEGIS_ACTIVATION_MODE=explicit` is visible
in the environment) and the current user request did not explicitly invoke
Aegis or this skill by name, exit back to the fast path: answer concisely
without this workflow's checklist, ceremony, or document requirements. If the
user explicitly named Aegis or this skill, proceed normally.
</EXPLICIT-MODE-GATE>

# Execute

→ Direct grilling or plan/design pressure-test? → Enter `Grilling Mode` below. Soft challenge intent? → Use its one-line mode confirmation. Do not start normal design artifacts, document writing, task planning, or implementation during the interview.
→ New feature, product behavior, UI/component design, architecture/contract change, or ambiguous medium/high-complexity work? → **Design first. No implementation until the needed design/spec is approved.**
  1. Explore project context → read authority docs, check for existing patterns

# Communicating Concisely

## Activation

Triggered by: "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or `/communicating-concisely`. Once active, applies to EVERY response until explicitly deactivated.

## Mode Rules

**Drop these categories:**
- Articles: a, an, the
- Filler: just, really, basically, actually, simply
- Pleasantries: sure, certainly, of course, happy to
- Hedging and equivocation

# Dispatching Parallel Agents

## Purpose

Use parallel children for two or more ad-hoc, bounded tasks only when their
independence is already credible and concurrency is worth the coordination.
Parallelism changes elapsed time; it does not relax evidence, ownership, or
completion requirements.

## Dispatch Gate

Dispatch only when all are true:

- there are `2+` distinct tasks or evidence questions;

# Establishing Project Context

## Overview

Maintain project domain language in `CONTEXT.md` so humans and agents use the
same canonical terms. This skill is the single active-modeling and write-policy
owner; it does not own passive glossary reads.

`CONTEXT.md` is terminology infrastructure, not Aegis governance, architecture,
requirements, task state, session memory, or runtime authority. Those retain
their current project owners.

## Passive Consumption vs Active Modeling

# Executing Plans

## Overview

Load plan, review critically, execute all tasks, report when complete.

**Announce at start:** "I'm using the executing-plans skill to implement this plan."

For non-trivial execution, include `Aegis Visibility`: briefly tie the active
slice to its plan, checkpoint, drift or verification boundary. At completion,
pass plan adherence, evidence, complexity and residual risk to
`verification-before-completion` for the unified receipt.

If subagents are available and the plan has genuinely independent tasks,

# Finishing a Development Branch

## Overview

Integration choice and checkout lifetime are separate. Verify first, mutate only
task-owned resources, then prove what was removed or retained.

**Core principle:** fresh evidence -> authorized integration -> ownership-aware
cleanup -> Git/path readback.

**Announce at start:** explain which branch/worktree lifecycle is being closed.

## Step 1: Environment and Ownership Detection

# First Principles Review

## Purpose

Use this as a lightweight decision review before another Aegis workflow makes a
directional choice. It is a compositional skill, not a standalone workflow.

Do not replace `brainstorming`, `systematic-debugging`, `writing-plans`,
`requesting-code-review`, or `verification-before-completion`. Use it to clean
the decision surface those skills will act on.

When this review materially changes the direction, surface `Aegis Visibility`
in natural prose: name the first principle, dropped assumption, smallest
sufficient path, or owner / retirement falsifier that changed the decision.

# Aegis Goal Framing

Use this skill to create a thin goal frame before execution. It is opt-in and
boundary-setting only.

Do not use it for tiny edits, one-command checks, or ordinary fast-path Q&A
unless the user explicitly asks for `/aegis-goal` or `Aegis goal:`.

## Authority Boundary

Current owner:

- Method Pack task framing

# Long Task Continuation

## Overview

Keep long work checkpointed, resumable, drift-aware, and evidence-gated. This
protocol does not execute plans, dispatch subagents, run tests, or grant
completion authority.

## Authority Boundary

The Method Pack owns continuation discipline only. It does not own the parent
plan, host retry/watchdog behavior, authoritative `GateDecision`, evidence
sufficiency, requirement acceptance, or completion.

# Code Review Reception

## Overview

Code review requires technical evaluation, not emotional performance.

**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.

## The Response Pattern

```
WHEN receiving code review feedback:

1. READ: Complete feedback without reacting

# Recording Architecture Decisions

## Purpose

Record durable architecture decisions without losing the current-state baseline
closure. An ADR records why a decision was made; a baseline records what the
architecture is after that decision.

This skill is a lazy, task-specific workflow. It does not replace
`verification-before-completion`, does not grant completion authority, and does
not make authoritative `GateDecision` or `PolicySnapshot` outputs.

## Required Read Set

# Requesting Code Review

Dispatch a reviewer subagent using the canonical `code-reviewer.md` template to
catch issues before they cascade. The reviewer gets precisely crafted context
for evaluation — never your session's history. This keeps the reviewer focused
on the work product, not your thought process, and preserves your own context
for continued work.

This skill is the canonical review-request workflow for method-pack implementation work. Use it to request review only after you have enough evidence, enough context, and a clear authority boundary for what the reviewer is being asked to assess.

**Core principle:** Review early, review often.

**Findings First:** Reviews lead with concrete findings before summary. Use
bugs first, risk first, tests first. Strengths and general assessment are still

# Execute

→ Have an implementation plan with independent tasks? → **Fresh subagent per task + two-stage review.**
  1. Read plan, extract all tasks, create TodoWrite
  2. Per task: dispatch implementer → answer questions → implementer completes
  3. Review stage 1 (spec compliance) → fix gaps → re-review until ✅
  4. Review stage 2 (code quality) → fix issues → re-review until ✅
  5. Coordinator verifies, commits the coherent task, updates checkpoint/drift → next task
→ All tasks done: final review → verification receipt; branch finishing only when needed.

# Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

# Execute

Bug, failure, or unexpected behavior:

1. **Isolate** — read error, reproduce, inspect the diff, and drill upward through diagnostic layers:
   L1 symptom → L2 logic → L3 system → L4 architecture → L5 cross-system
   contract → L6 platform → L7 spec gap. Layers are observation altitudes,
   not one causal chain; the causal shape at the stop altitude is classified
   explicitly before any root claim. Stop only when causal proof accounts
   for the recurrence generator or reaches a T-class boundary.
2. **Identify owner** — compare working behavior, trace the bad value, locate the
   canonical owner, and treat duplicate owners as a finding.
3. **Decide before editing** — Before fixing, run Patch-Shape Triage and Ripple Signal Triage when shared logic,
   contracts, fallbacks, adapters, producer/consumer seams, or source-of-truth

# Execute

→ False-positive entry on a native-direct-skill host? → **Exit immediately unless the user explicitly asked for TDD or the conversation already contains `TDD Route: strict`.**
  In `off` mode, do not start RED / GREEN / REFACTOR from generic bugfix, contract, shared-module, or risky-code wording alone.
  Hand control back to `using-aegis`, `systematic-debugging`, `writing-plans`, or the fast path with verification.
→ Implementing a feature or bugfix under TDD Route `strict`? → **No production code without a failing test first.**
  Gate: medium/high complexity? → route to brainstorming or writing-plans first.
  Mode: default `off` disables automatic TDD, not completion verification; `auto` chooses strict/light/skipped by risk.
  Change Necessity: before strict RED/GREEN enters production edits, confirm the slice really needs a code change.
  Cycle: RED (write test → watch it fail) → GREEN (minimal code → watch it pass) → REFACTOR (clean up → keep green)
  Regression: shared module → related tests. contract change → producer + consumer. core logic → old + new tests.
  Ripple signal hit → cover producer+consumer or real user path before claiming green.
  GREEN proves the currently expressed behavior slice only.
  GREEN does not by itself prove parent-task acceptance, business-value completion, or final completion.

<EXPLICIT-MODE-GATE>
If activation mode is explicit and this request names neither Aegis nor this
skill, return to the fast path without this workflow's rules or ceremony.
Explicit invocation proceeds normally.
</EXPLICIT-MODE-GATE>

# UI/UX Governance

## Purpose and ownership

Apply experience rules as a compositional skill. Keep design approval,
implementation, review dispatch, and completion with the existing task owner.
For direct requests, deliver the requested scoped design/review; authorized
implementation continues through its appropriate workflow.

# Update Aegis

Update the installed Aegis Method Pack for the current AI coding host.

This skill is host maintenance. Do not edit the target project just because the
user asked to update Aegis.

## Default Semantics

- `aegis:update` updates the current host's registered Aegis installation.
- Updating every registered host requires an explicit `--all` request.
- If more than one host is registered and the current host cannot be identified,
  ask one concrete question before updating.
- Do not update a development checkout when the installed method-pack root is a

<SUBAGENT-STOP>Skip for subagents.</SUBAGENT-STOP>

<EXPLICIT-MODE-GATE>
If activation mode is explicit and this request did not explicitly invoke Aegis or a named skill, stay on the fast path; do not route to any Aegis skill. Explicit invocation proceeds normally.
</EXPLICIT-MODE-GATE>

<EXTREMELY-IMPORTANT>
You have Aegis. Load explicit/relevant Aegis skill before response/action;
otherwise proceed normally.
</EXTREMELY-IMPORTANT>

## Outcome Anchor

Understand the requested object, scope, actions, conditions, and deliverables

# Using Git Worktrees

## Overview

A worktree is an exception for simultaneously checking out another Git history,
not a general safety badge. Prefer the current workspace and reuse an existing
suitable worktree. A branch decision and a worktree decision are separate.

**Core principle:** create only with necessity and ownership evidence; pair every
created worktree with a cleanup path.

**Announce at start:** explain which concrete checkout conflict requires a
worktree.

<EXPLICIT-MODE-GATE>
If `activation_mode = "explicit"` or `AEGIS_ACTIVATION_MODE=explicit` is visible
and the request names neither Aegis nor this skill, return to the fast path
without checklist/ceremony; otherwise continue.
</EXPLICIT-MODE-GATE>

# Execute

Before success claim: classify destructive permission; read sufficient current
evidence and run a fresh falsifying check when it is missing or invalidated;
read the complete result/scope; select L0/L1/L2. Downgrade for partial,
stale, failing, or narrower evidence; never claim complete then verify later.

This pack grants no `GateDecision`, `PolicySnapshot`, evidence sufficiency,

<EXPLICIT-MODE-GATE>
If activation mode is explicit (`~/.config/aegis/config.toml` has
`activation_mode = "explicit"`, or `AEGIS_ACTIVATION_MODE=explicit` is visible
in the environment) and the current user request did not explicitly invoke
Aegis or this skill by name, exit back to the fast path: answer concisely
without this workflow's checklist, ceremony, or document requirements. If the
user explicitly named Aegis or this skill, proceed normally.
</EXPLICIT-MODE-GATE>

# Execute

→ Existing parent plan/spec and a tiny execution slice? → **Use Planless Slice Lane.**
→ Mechanical or bounded change with no durable boundary (no new owner,
  contract, schema, public API, migration, or compat surface)? → **Use

# Writing Skills

## Purpose

Create the smallest reusable skill that changes decisions or improves task
execution without constraining unrelated work. Skill changes use behavior
validation, not a code TDD route. This validation does not require loading `aegis:test-driven-development`.

## Default Path

### 1. Establish Need And Ownership

- Name the reusable behavior gap, intended users/hosts, and non-goals.
- Check whether an existing skill, project rule, host adapter, or automated