ags-epic-contracts

name	ags-epic-contracts
description	Lock minimal API contracts for stub-mode systems in the active epic. Writes Contracts section in EPIC.md and pre-registers stubs in stubs.md.
argument-hint	[epic-slug]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Edit, AskUserQuestion

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Phase 0: Prerequisites

Artifact	Created by	If missing
.ags/project/stage.md (Phase = production)	/ags-gate-check production	STOP. "Not in production phase. Run /ags-gate-check production first."
Active .ags/project/epics/[slug]/EPIC.md	/ags-create-epics	STOP. "No active epic. Run /ags-create-epics first."
.ags/project/stubs.md (creates if missing)	/ags-stub-track or this skill	If missing, this skill creates it from t_stubs.md template — not a STOP.

If any STOP triggers, exit with verdict BLOCKED — missing prerequisite.

---

Phase 1: Resolve Active Epic

If [epic-slug] argument provided, use it. Otherwise read .ags/project/stage.md to find the active epic ID.

Read .ags/project/epics/[slug]/EPIC.md. Verify Status is designing or planned. If status is done or rolled-back, use AskUserQuestion with prompt "Epic status is [X]. Contracts already locked. Re-lock anyway?" options: Re-lock / Cancel.

If epic file missing or unreadable, stop. Verdict: FAIL — no active epic. Run /ags-create-epics first.

---

Phase 2: Identify Stub Systems

Parse the Systems in Scope table in EPIC.md. Collect rows where Mode = stub.

If no stub rows, no contracts needed. Output: "No stub systems in this epic — contracts not required." Verdict: COMPLETE — nothing to do.

---

Phase 3: Read GDD Context

For each stub system:

• Read the linked GDD section (column GDD Section).
• Read GDDs of new and revise systems in the same epic — they are the consumers that need the stub interface.
• Identify what data and methods consumers require from the stub system.

If consumer needs are unclear, ask the user one question per stub system before drafting.

---

Phase 4: Draft Contracts

For each stub system, draft:

• Interface signature — minimal API consumers need (method names, parameters, return types in engine-language syntax).
• Default behavior — NotImplementedException, empty collection, sane default value, or no-op.
• Stub ID — STUB-NNN where NNN is the next free integer in .ags/project/stubs.md Open + Closed + Migrated tables. Numbering is global across the project.
• Owner Epic — which future epic is expected to close this stub. Use TBD if unknown.

Present draft contracts to the user as a structured block per stub system.

---

Phase 5: User Review and Edits

Use AskUserQuestion with prompt "Any edits to interfaces, defaults, or owner-epic assignments?" and options:

• Approve as drafted — proceed to internal review
• Edit interfaces — user describes changes free-form, redraft
• Cancel — stop with verdict BLOCKED

Apply edits, redraft, present again. Loop until user approves.

---

Phase 5b: Internal Review Loop

Spawn lead-programmer (and optionally technical-director) via Task to review the drafted contracts against existing ADRs, registry stances, and stubs.md.

Loop exit condition. Single iteration where every spawned reviewer returns clean (no critical/high/medium findings). Non-clean → user revises affected interfaces / defaults, re-spawn the reviewers. No iteration cap.

Record iteration count.

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. The internal review section above runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/[type]-[slug]-iter[N]-draft.md.
3. Spawn in one message, in parallel (multiple Task calls + one Bash invocation):
   • All internal reviewer Tasks listed above.
   • /ags-external-review [type] [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (producer by default; skill-designated lead where the skill specifies one) merges findings from internal + external, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically. Record final iteration count for the decisions-log entry written at skill completion.

---

Phase 6: Approval

Use AskUserQuestion with prompt "May I write contracts to EPIC.md and pre-register stubs in stubs.md?" and options:

• Yes — write both files
• No — cancel

If declined, stop. Verdict: BLOCKED — user declined write.

---

Phase 7: Write

1. EPIC.md — Edit the ## Contracts (Stub Interfaces) section. Replace placeholder content with one subsection per stub system. Edit the ## Stubs Introduced table — append rows for each new STUB-ID.

2. stubs.md — Append rows to ## Open Stubs table. One row per new stub. Columns: ID, System, Interface, Introduced (epic), Owner Epic, Reason, Notes.

3. decisions-log.md — Append entry:

## [YYYY-MM-DD HH:MM] — Lock contracts for epic-[id]

**Type**: architecture
**Context**: Epic [name] introduces stub neighbors.
**Decision**: API contracts locked for [list of stub systems].
**Rationale**: [user-provided one-sentence reason]
**Refs**: .ags/project/epics/[slug]/EPIC.md, .ags/project/stubs.md
**Decided by**: human

Verdict: COMPLETE — contracts locked, stubs registered.

---

Phase 8: Next Steps

Suggest:

• /ags-create-stories [epic-slug] — break epic into stories.
• /ags-dev-story — implement stories with stubs marked // TODO(epic-[id]):.

---

Rules

• Contracts are stable across epics. Changing a locked contract requires a new ADR or a new epic.
• Every stub registered here MUST appear in code with a // TODO(epic-[id]): marker once implementation starts.
• /ags-stub-track reconciles code markers with this registry.