# AO Skill Index

Complete index of all AO skills with descriptions, direct links, tier definitions, invocation rules, and installation groups.

---

## Skills location

**IMPORTANT** The skills are located in `.ao/skills` in the root of the project. The links in this folder is *relative* to that folder.

### Groups

| Group | Skills | Use Case |
|-------|--------|----------|
| **core** (default) | Constitution → Baseline → Planning → Implementation → Testing → Validation → Critical-Review → Retrospective | Simple projects, getting started |
| **state** (+) | ao-state, ao-focus-scan, ao-housekeeping, ao-tools | Full workflow with issue tracking |
| **utility** (+) | ao-interview, ao-task, ao-spec, ao-docs, ao-dependencies, ao-guide, ao-debugging | Team collaboration, documentation |
| **git** (+) | ao-git, ao-recovery, ao-git-analysis, ao-git-story, branch operations | Active development with version control |
| **analysis** (+) | ao-context-map, ao-improvement-discovery, code review, project analysis | Large projects, code review focus |
| **full** | Everything above + extended/special skills | Maximum flexibility |

---

## Workflow Order

```
Constitution → Baseline → Plan → Implement → Test → Validate → Review → Retrospective
```

**Step clarifications:**
- **Test** (`ao-testing`) — Write and run tests (TDD cycle) after implementation
- **Validate** (`ao-validation`) — Run full build/lint/test suite, compare against baseline
- **Review** (`ao-critical-review`) — Deep code review for correctness, security, design

> `ao-review` = automated subagent review (lighter, optional during implementation).
> `ao-critical-review` = deep post-implementation review (the "Review" step above).

---

## Invocation Rules

### Rule 1: Precondition Enforcement

Before invoking a skill, verify its preconditions are met:

```
IF skill.preconditions NOT satisfied:
    STOP
    Identify missing precondition
    Invoke prerequisite skill OR ask user
```

### Rule 2: State File Contract

Each skill declares which state files it reads and writes:

```yaml
state_files:
  read: [constitution.md, baseline.md, ...]
  write: [focus.json, issues/*, ...]
```

Skills MUST:
- Read declared files before proceeding
- Write only to declared files
- Use `ao-state` for consistent updates

### Rule 3: Skill Chaining

When a skill needs another skill's capability:
1. Note the need in focus.json
2. Invoke the required skill (or delegate to it)
3. Wait for completion
4. Continue with original skill

### Rule 4: Tier Escalation

When a lower-tier skill encounters issues:
```
Tier 5 → Tier 4 (recovery)
Tier 4 → Tier 3 (ask user via interview)
Tier 3 → Tier 2 (update state)
Tier 2 → Tier 1 (may need replanning)
Tier 1 → User (explicit approval)
```

### Rule 5: Confidence-Based Invocation

| Confidence | Planning Iterations | Approval Gates | Review Depth | Batch Size | Hard Stop | Coverage Req |
|------------|---------------------|----------------|--------------|------------|-----------|---------------|
| LOW | 3+ | Hard (wait) | Exhaustive | 1 issue | After EACH issue | ≥90% line, ≥85% branch |
| NORMAL | 2 | Soft (ask, continue) | Standard | Up to 3 | Soft (report) | ≥80% line, ≥70% branch |
| HIGH | 1 or skip | Minimal | Quick | Up to 5 | None | Tests pass |

### Compliance Model

**Advisory Enforcement**: Skill tier rules are advisory, not enforced at runtime. LLM agents are expected to follow these guidelines as best practices.

**Self-Audit Checklist** before invoking a skill:
- [ ] **Tier 1 order**: Am I following constitution → baseline → planning → implementation?
- [ ] **Preconditions met**: Does the skill's prerequisite state exist?
- [ ] **State files current**: Have I read the relevant `.agent/ops/` files?
- [ ] **Confidence level**: Am I applying the correct rigor for the confidence level?

### Special Modes

For specific contexts, apply reference documents from [`.ao/reference/](.ao/reference/):

| Mode | Document | When to Apply |
|------|----------|---------------|
| **API Review** | `api-guidelines.md` | Implementing or reviewing APIs |
| **Cautious Reasoning** | `cautious-reasoning.md` | Complex decisions with high uncertainty |
| **Code Review** | `code-review-framework.md` | Deep code reviews, quality audits |

---

## Skill Selection Decision Tree

```
START
│
├─ New project / install AO? → ao-install
│
├─ Need to set up project? → ao-constitution
│
├─ Need baseline before changes? → ao-baseline
│
├─ Work on issues autonomously? → ao-auto
│
├─ Need to plan work?
│   ├─ Task unclear? → ao-task (refine) → ao-planning (with brainstorming and multiple choice interview) |
│   └─ Task clear? → ao-planning (with brainstorming and multiple choice interview) |
│   └─ No plan? → ao-planning first (with brainstorming) |
│
├─ Need to validate before commit? → ao-validation
│
├─ Ready to complete issue? → ao-complete (Gate Function verification)
│
├─ Multiple independent issues? → ao-parallel (concurrent agent dispatch)
│
├─ Implementation done? → ao-critical-review → ao-retrospective
│
├─ Something broke?
│   ├─ Build/test failure? → ao-recovery
│   └─ Git issue? → ao-git
│
├─ Need user input? → ao-interview
│
├─ Need to understand codebase? → ao-context-map
│
├─ Looking for improvements? → ao-improvement-discovery
│
└─ Managing dependencies? → ao-dependencies
```

---

## Tier 1: Core Workflow

These skills form the main development workflow and should be followed in order for standard work.

| Skill | Preconditions | Link |
|-------|---------------|------|
| `ao-init` | None | [SKILL.md](skills/ao-init/SKILL.md) - Creates all issue priority files including backlog.md |
| `ao-constitution` | Repository exists | [SKILL.md](skills/ao-constitution/SKILL.md) |
| `ao-baseline` | Constitution confirmed | [SKILL.md](skills/ao-baseline/SKILL.md) |
| `ao-planning` | Baseline exists (mandatory LOW, recommended NORMAL, optional HIGH) | [SKILL.md](skills/ao-planning/SKILL.md) |
| `ao-implementation` | Plan approved | [SKILL.md](skills/ao-implementation/SKILL.md) |
| `ao-execute` | Plan exists with 6+ tasks | [SKILL.md](skills/ao-execute/SKILL.md) - Batch execution with checkpoints |
| `ao-parallel` | Multiple independent issues | [SKILL.md](skills/ao-parallel/SKILL.md) |
| `ao-testing` | Test command confirmed (TDD cycle) | [SKILL.md](skills/ao-testing/SKILL.md) |
| `ao-review` | Unified code review (--depth quick|standard|deep) | [SKILL.md](skills/ao-review/SKILL.md) |
| `ao-validation` | Run full suite, compare baseline | [SKILL.md](skills/ao-validation/SKILL.md) |
| `ao-complete` | Issue ready for completion | [SKILL.md](skills/ao-complete/SKILL.md) |
| `ao-critical-review` | Deep post-implementation review (**alias**: ao-review --depth standard) | [SKILL.md](skills/ao-review/SKILL.md) |
| `ao-retrospective` | Review complete | [SKILL.md](skills/ao-retrospective/SKILL.md) |
| `ao-plan-preview` | Plan exists | [SKILL.md](skills/ao-plan-preview/SKILL.md) |

---

## Tier 2: State Management

Cross-cutting skills for managing `.agent/ops/` state files. Can be invoked at any time.

| Skill | When to Use | Link |
|-------|-------------|------|
| `ao-state` | All skills, session start, after steps | [SKILL.md](skills/ao-state/SKILL.md) |
| `ao-focus-scan` | Session start, between tasks | [SKILL.md](skills/ao-focus-scan/SKILL.md) |
| `ao-auto` | Autonomous work on multiple issues | [SKILL.md](skills/ao-auto/SKILL.md) |
| `ao-housekeeping` | After milestones, periodically | [SKILL.md](skills/ao-housekeeping/SKILL.md) |
| `ao-tools` | Session start, detect available tools | [SKILL.md](skills/ao-tools/SKILL.md) |

---

## Tier 3: Utility Skills

Supporting skills invoked by other skills or on demand.

| Skill | Typically Invoked By | Link |
|-------|---------------------|------|
| `ao-interview` | constitution, planning, tasks | [SKILL.md](skills/ao-interview/SKILL.md) |
| `ao-task` | User request, planning, focus-scan | [SKILL.md](skills/ao-task/SKILL.md) |
| `ao-spec` | Planning, critical-review | [SKILL.md](skills/ao-spec/SKILL.md) |
| `ao-docs` | Implementation, critical-review | [SKILL.md](skills/ao-docs/SKILL.md) |
| `ao-dependencies` | Implementation, improvement-discovery | [SKILL.md](skills/ao-dependencies/SKILL.md) |
| `ao-guide` | User request (/ao-help) | [SKILL.md](skills/ao-guide/SKILL.md) |
| `ao-debugging` | Systematic debugging approaches | [SKILL.md](skills/ao-debugging/SKILL.md) |
| `markdown-to-jira` | User request | [SKILL.md](skills/ao-markdown-jira/SKILL.md) |
| `ao-issue-merge` | Git merge conflicts | [SKILL.md](skills/ao-issue-merge/SKILL.md) |
| `ao-llm-export` | User request | [SKILL.md](skills/ao-llm-export/SKILL.md) |
| `ao-skills-advisor` | External skills recommendations from skills.sh | [SKILL.md](skills/ao-skills-advisor/SKILL.md) |
| `ao-gh-actionable-comments` | PR review comment analysis via gh CLI | [SKILL.md](skills/ao-gh-actionable-comments/SKILL.md) |
| `ao-review-response` | Receiving and responding to code review feedback | [SKILL.md](skills/ao-review-response/SKILL.md) |

---

## Tier 4: Git & Recovery

Safety-critical skills for source control and error recovery.

| Skill | When to Use | Link |
|-------|-------------|------|
| `ao-git` | Session start, before commits | [SKILL.md](skills/ao-git/SKILL.md) |
| `ao-recovery` | Build failures, test regressions, stuck states | [SKILL.md](skills/ao-recovery/SKILL.md) |
| `ao-git-analysis` | Repository insights | [SKILL.md](skills/ao-git-analysis/SKILL.md) |
| `ao-git-story` | Narrative summaries from git history | [SKILL.md](skills/ao-git-story/SKILL.md) |
| `ao-branch-workflow` | Branch creation, type detection | [SKILL.md](skills/ao-branch-workflow/SKILL.md) |
| `ao-git-worktree` | Worktree management | [SKILL.md](skills/ao-git-worktree/SKILL.md) |
| `ao-selective-branch` | PR preparation | [SKILL.md](skills/ao-selective-branch/SKILL.md) |
| `ao-selective-merge` | PR preparation | [SKILL.md](skills/ao-selective-merge/SKILL.md) |

---

## Tier 5: Analysis

On-demand analysis skills for understanding and improving the codebase.

| Skill | When to Use | Link |
|-------|-------------|------|
| `ao-context-map` | New project, major refactors | [SKILL.md](skills/ao-context-map/SKILL.md) |
| `ao-improvement-discovery` | Discovery phase, roadmap planning | [SKILL.md](skills/ao-improvement-discovery/SKILL.md) |
| `ao-review-domain` | Domain-specific reviews (--domain api\|docker\|meta) | [SKILL.md](skills/ao-review-domain/SKILL.md) |
| `ao-project-sections` | Context scoping, architecture docs | [SKILL.md](skills/ao-project-sections/SKILL.md) |
| `ao-potential-discovery` | Evaluating libraries, specs, PRs | [SKILL.md](skills/ao-potential-discovery/SKILL.md) |
| `ao-dogfood` | Doc-based project baseline | [SKILL.md](skills/ao-dogfood/SKILL.md) |
| `ao-article-verification` | Pre-publication review, content audits | [SKILL.md](skills/ao-article-verification/SKILL.md) |
| `ao-reality-audit` | Evidence-based project audit | [SKILL.md](skills/ao-reality-audit/SKILL.md) |
| `ao-prove-your-worth` | Feature justification audit | [SKILL.md](skills/ao-prove-your-worth/SKILL.md) |
| `ao-intent-drift` | Implementation intent validation | [SKILL.md](skills/ao-intent-drift/SKILL.md) |
| `ao-plan-review-import` | PR review parsing | [SKILL.md](skills/ao-plan-review-import/SKILL.md) |
| `ao-shadow-plan` | Blind spot exposure | [SKILL.md](skills/ao-shadow-plan/SKILL.md) |
| `ao-adversary` | Adversarial code review, attack vectors, failure modes | [SKILL.md](skills/ao-adversary/SKILL.md) |
| `ao-calibrator` | Confidence calibration, miscalibration detection | [SKILL.md](skills/ao-calibrator/SKILL.md) |
| `ao-postmortem` | Blameless failure analysis, root cause identification | [SKILL.md](skills/ao-postmortem/SKILL.md) |

---

## Extended / Special Purpose

Skills for specific workflows and tooling.

| Skill | When to Use | Link |
|-------|-------------|------|
| `ao-install` | New project setup | [SKILL.md](skills/ao-install/SKILL.md) |
| `ao-update` | Update AO to newer version | [SKILL.md](skills/ao-update/SKILL.md) |
| `ao-create-skill` | Skill ecosystem | [SKILL.md](skills/ao-create-skill/SKILL.md) |
| `ao-create-python-project` | Python project scaffolding | [SKILL.md](skills/ao-create-python-project/SKILL.md) |
| `ao-migrate` | Project mergers, monorepo consolidation | [SKILL.md](skills/ao-migrate/SKILL.md) |
| `ao-build` | Language-aware build orchestration | [SKILL.md](skills/ao-build/SKILL.md) |
| `ao-idea` | Raw concept enrichment | [SKILL.md](skills/ao-idea/SKILL.md) |
| `ao-impl-details` | Implementation planning | [SKILL.md](skills/ao-impl-details/SKILL.md) |
| `ao-optimize-instructions` | Context overflow | [SKILL.md](skills/ao-optimize-instructions/SKILL.md) |
| `ao-report` | Issue reporting | [SKILL.md](skills/ao-report/SKILL.md) |
| `ao-time-report` | View accumulated time-tracking data | [SKILL.md](skills/ao-time-report/SKILL.md) |
| `ao-research` | Topic investigation | [SKILL.md](skills/ao-research/SKILL.md) |
| `ao-github` | GitHub Issues sync | [SKILL.md](skills/ao-github/SKILL.md) |
| `ao-skills-sh` | External skill discovery | [SKILL.md](skills/ao-skills-sh/SKILL.md) |

---

## Documentation Skills

| Skill | When to Use | Link |
|-------|-------------|------|
| `ao-versioning` | Release management | [SKILL.md](skills/ao-versioning/SKILL.md) |
| `ao-mkdocs` | MkDocs sites | [SKILL.md](skills/ao-mkdocs/SKILL.md) |
| `ao-astro-docs` | Astro documentation sites | [SKILL.md](skills/ao-astro-docs/SKILL.md) |
| `ao-create-technical-docs` | Codebase documentation | [SKILL.md](skills/ao-create-technical-docs/SKILL.md) |

---

## Uncategorized / In Development

Skills without proper metadata or still in development:

- `ao-cognitive-load` — Measure cognitive load of tasks
- `ao-confidence-decay` — Track confidence decay over time
- `ao-junior-explain` — Explain code for junior developers
- `ao-lint-instructions` — Lint instruction files
- `ao-narrative-audit` — Audit narrative quality
- `ao-skill-fatigue` — Detect skill fatigue
- `ao-temporal-risk` — Assess temporal risks

---

## Reference Documents

See [`.ao/reference/`](.ao/reference/) for:
- `api-guidelines.md` — API development checklist
- `cautious-reasoning.md` — Epistemic reasoning framework
- `code-review-framework.md` — Code review methodology
- `confidence.md` — Canonical confidence definitions
- `completion-gate.md` — What must pass before closing
