Standard

APIS — AI-Proof Issue Spec

APIS is Olympus's standard for writing issues that AI agents can't game. Every issue includes verification criteria and anti-patterns, so completed work is provably done — not just "looks done."

The Problem

Why APIS exists

AI coding agents close issues when they believe the work is done. Without structured verification, they can:

Commit placeholder code (TODO, "not implemented", empty functions)
Close issues with code that compiles but doesn't actually work
Write modules that nothing uses — technically "done" but not integrated
Satisfy the letter of a requirement while missing the intent

APIS prevents all of this by requiring runnable verification criteria that prove completion and anti-patterns that catch common failure modes.

The Format

What every issue includes

Section	Purpose
Summary	What needs to happen and why — with a Pantheon Module icon if a specific Pantheon Module is affected
Current state	What exists today — specific file paths, function names, and what's missing
Requirements	Numbered concrete steps, each independently verifiable — no ambiguity
Verification	Runnable commands with expected output — the acceptance criteria
Anti-patterns	What the implementation must NOT do — catches hardcoding, dead code, skipped error handling
Closure policy	Athena validates intent match before merge — only `INTENT_MATCHED` allows closure

Verification

Proving the work is done

Every APIS issue includes runnable commands that prove completion. The AI agent must run these commands and paste the output in the PR. This is what separates "it compiles" from "it works."

Rules for verification

Must be runnable from the project root
Must produce deterministic output
Must check behavior, not just existence
Must cover the critical path (not just the happy path)
At least 2 verification commands per issue

Anti-patterns

Catching common AI failure modes

Every issue explicitly lists what the implementation must NOT do. This catches the most common ways AI agents produce work that looks complete but isn't:

Hardcoding values that should be configurable
Writing code that compiles but is never called (dead code)
Skipping error handling
Using TODO or FIXME as implementation
Modifying files the issue doesn't cover
Deleting tests instead of fixing them

Enforcement

How Athena enforces APIS

Athena checks APIS compliance at two points:

Before work begins

Issue validation

Issues missing verification commands or anti-patterns are flagged and blocked from being worked on until they're complete.

Before merge

Completion validation

Athena reads the PR diff, checks for stub code, runs anti-pattern detection, and verifies the work matches the original intent. Only INTENT_MATCHED allows closure.

Example

What an APIS issue looks like

## Summary

🛡️(Aegis): The RBAC package is fully implemented but not wired
into the init command. CODEOWNERS generation is dead code.

## What exists today

- `src/internal/rbac/codeowners.go` (217 lines) — complete implementation
- `WriteCodeowners()`, `GenerateSection()`, `MergeIntoCodeowners()`
- Zero imports — nothing calls this code

## What needs to happen

1. In the init command, call `rbac.WriteCodeowners(repoRoot, cfg)`
2. Make admin team configurable via project settings
3. Print which paths were added during init

## Verification

```bash
# RBAC is imported by the init command
grep -r "internal/rbac" src/cmd/ --include="*.go" | grep -v _test
# Should return at least 1 match

# Generated CODEOWNERS contains the managed section
grep "BEGIN olympus-governance RBAC" CODEOWNERS
# Should match
```

## Anti-patterns

- Do not call WriteCodeowners without checking if RBAC is enabled
- Do not overwrite user's existing CODEOWNERS entries
- Do not silently skip generation without logging why

## Closure policy

PR must include pasted output of all verification commands passing.
Athena validates intent match before merge.