SuperAPI AI Directory

author

Coding & development

View repository

Updated 11-14 08:09

About this skill

Master Spec Authoring

Author the canonical spec for $ARGUMENTS and decompose it into ordered phases for execution by execute-phase. Run once at project inception. Choose sane defaults; do not stop for input except at the architecture checkpoint (step 2) or a HALT CONDITION.

Preconditions

  • A project brief exists: a path via $ARGUMENTS, the current conversation, or a notes doc. If the brief is too thin to derive a defensible scope and architecture, that is a genuine HALT — ask for the missing intent rather than inventing a project.
  • The /codex-review skill (Codex CLI) and ultracode workflow support are available — the review gates hard-require both. If either is missing, HALT; do not substitute an ad-hoc review and mark the gate passed.
  • Working tree clean or understood; note branch (likely a fresh repo).
  • Identify the project's handoff/state layout (Agent Handoff System) and existing conventions. Conform to them. If greenfield, this skill establishes the minimal layout the sibling skill expects.

Orchestration model

  • Main session model: Opus (authoring + architecture judgment + synthesis).
  • Review allocation (same philosophy as execute-phase): exactly ONE ultracode workflow panel pass on the raw artifact, then /codex-review to convergence. Workflow workers Sonnet; Opus only for genuinely complex sub-tasks (e.g. validating the phase dependency graph against the spec). State the routing explicitly in each trigger.
  • The master spec is the highest-leverage artifact in the system: a flaw propagates into every phase spec and all phase code. It receives phase-gate rigor applied to BOTH the spec content and the phase decomposition.

References

Shared standards live in ${CLAUDE_PLUGIN_ROOT}/references/. They are the rubric for both authoring and the review gate.

  • Spec construction — core: ${CLAUDE_PLUGIN_ROOT}/references/spec-construction.md
  • Spec construction — master delta: ${CLAUDE_PLUGIN_ROOT}/references/spec-construction-master.md

When this skill writes or reviews the master spec, the standard is the core PLUS the master delta (read both). The master delta governs the master's obligations: id'd cross-cutting decisions, the phase decomposition, scope coverage (every requirement → exactly one phase), and delegation of exhaustive detail to named planning artifacts.

This standard supersedes any external authoring skill. Do NOT invoke Superpowers brainstorming or writing-plans during autonomous steps — this skill provides its own process and this standard is the authority. (The architecture checkpoint in step 2 is this skill's own deliberate human gate, not Superpowers'.)

Validator gates (specpipe)

Structural gates run through the bundled specpipe CLI (a plain stdlib package — the invocation never writes into the plugin tree):

PYTHONPATH="${CLAUDE_PLUGIN_ROOT}/scripts/specpipe" uv run --no-project python -B -m specpipe <subcommand> …

(Below, specpipe <subcommand> abbreviates that invocation.) Errors (exit 1) MUST be fixed and the validator re-run clean BEFORE the gate's workflow/Codex pass — the deterministic pass is free; do not spend panel review on structural defects. Warnings may be accepted with a one-line recorded justification in the artifact. Validator failures are NOT halt conditions: fix and re-run.

Path convention: specpipe is layout-agnostic — every subcommand takes explicit paths. Examples below use the greenfield default docs/handoff/; if the project keeps its state elsewhere, resolve paths per that project's convention (the audit file always sits beside the phase plan in an audit/ subdirectory, and init-project accepts --handoff-dir).

Pipeline

1. Intake

  • Read the brief. Establish, choosing sane defaults aligned with project and toolchain conventions (do not stop on resolvable choices):
    • Problem statement; goals; explicit non-goals.
    • Target environment(s) and dependency boundaries (runtime, OS/platform support, external services).
    • Language/toolchain (default Python: uv, ruff, BasedPyright strict, pytest + coverage.py; FastAPI / Pydantic v2 / Typer as applicable).
    • Hard constraints (performance, security, offline operation, data).
  • Discover existing repo conventions and handoff layout; conform rather than invent.

2. Architecture & scope draft

  • Define the system boundary, major components, key technical decisions (with the one defensible default chosen for each), and the data/interface shape.
  • Draft the proposed phase breakdown — titles + one-line objectives only at this stage.
  • HUMAN CHECKPOINT (the single deliberate stop): present scope boundary + architecture + proposed phase list for confirmation before authoring the full spec. These are the architectural, big-picture decisions the director owns; everything downstream drafts autonomously. To run fully unattended, skip this checkpoint by prior agreement.

3. Master spec authoring

  • Instantiate ${CLAUDE_PLUGIN_ROOT}/templates/master-spec.md (its headings are the canonical grammar specpipe validates) and write the canonical spec per the spec construction standard — core + master delta (see References), formatted for LLM/agent consumption (structured, not narrative prose). Sections:
    • Overview / problem / goals / non-goals
    • Architecture (components, boundaries, key decisions + rationale)
    • Data model / domain types
    • Interfaces (CLI / API / contracts)
    • Behavior & rules (per component)
    • Error handling & failure modes
    • Testing strategy (what TDD targets; high-level logic-bearing vs glue boundaries)
    • Acceptance criteria (system-level)
    • Out of scope
  • Write so any single phase's slice is cleanly extractable: the sibling derives each per-phase spec from this document.

4. Phase decomposition

Decompose the spec into an ordered phase plan. Rules:

  • Each phase is independently executable in a single execute-phase session.
  • Prefer VERTICAL slices that deliver testable behavior over horizontal layers (all-models-then-all-logic). Vertical slices make per-phase TDD meaningful and keep the logic-vs-glue classification honest.
  • Phase 1 establishes the foundation: project skeleton, toolchain config (uv, ruff, BasedPyright strict, pytest, coverage.py), and CI scaffolding — so every later phase has a working test harness for RED→GREEN. Do not defer the test harness.
  • Order by dependency; a phase may depend only on earlier phases. The dependency graph must be acyclic.
  • Size each phase to the per-phase cost envelope: when run, each phase triggers two doc-review workflow passes + codex convergence + TDD + a final codex review. If a phase's spec would be too large to review in one workflow pass, or its implementation too large for one session, split it.
  • Each phase entry uses this stable schema (consumed by execute-phase step 1), written to the phase-plan file instantiated from ${CLAUDE_PLUGIN_ROOT}/templates/phase-plan.md:
    • id (stable integer) — title — status: pending
    • objective (one line)
    • scope: in / out
    • depends_on: [phase ids]
    • spec slice: which master-spec sections this phase implements
    • acceptance criteria (phase-level, testable)
    • size note

5. Review (spec + phase plan)

  • VALIDATOR GATE: run specpipe validate spec --kind master <spec-path> and specpipe validate phase-plan <plan-path>; fix all errors and re-run until clean before the workflow pass.
  • WORKFLOW PASS (exactly one — do NOT loop to convergence): ultracode: comprehensively review the master spec at <path> against the spec construction standard (core + master delta) AND the phase plan at <path>. Use Sonnet worker subagents; Opus only for genuinely complex sub-tasks (dependency-graph soundness, scope-coverage completeness). Independently verify each finding before reporting. Beyond prose quality the panel MUST verify: (a) every spec requirement is covered by exactly one phase — no orphaned or duplicated scope; (b) the dependency order is acyclic and correct; (c) each phase is independently executable and testable; (d) phase 1 establishes the test harness. Apply all justified fixes from this single pass.
  • CODEX CONVERGENCE: run /codex-review against the spec and phase plan. Apply justified fixes and re-run until either (a) a pass yields zero justified fixes, or (b) 3 rounds are reached. On hitting the cap, record remaining open findings and proceed. Count rounds deterministically: run specpipe rounds .spec-pipeline/state.json --gate spec --increment before each round; a cap-exceeded exit (1) ends the loop.

6. Initialize handoff / state

  • Run specpipe init-project to scaffold the minimal layout (docs/handoff/phase-plan.md from template, docs/handoff/audit/, .spec-pipeline/ gitignored); pass --handoff-dir when the project's existing state layout is not docs/handoff/. It is idempotent and never overwrites existing handoff files.
  • Seed the project's handoff state (Agent Handoff System layout) so execute-phase can resolve "next phase" (= first phase with status: pending), track completion, and carry context across sessions.
  • Write the phase-plan file with per-phase status fields. The master spec's build-plan section is DEFINITIONAL (ids, objectives, scope, dependencies); the plan file is its status-tracking projection — statuses live in the file, definitions in the master, and on conflict the master governs. Location: the project's existing handoff convention; greenfield default docs/handoff/phase-plan.md.
  • Establish state.md / handoff scaffolding per the project's layout. If greenfield, create the minimal layout the sibling skill expects.

7. Close out

  • Commit the master spec, phase plan, and handoff scaffolding with a clear imperative message.
  • Push to the current branch's remote.

Contract with execute-phase

This skill produces exactly what the sibling consumes:

  • Master spec — source of truth for every per-phase spec (sibling step 2).
  • Phase plan — ordered, status-tracked projection of the master's build-plan section (definitions stay in the master). Sibling step 1 resolves "next phase" = first entry with status: pending; sibling step 2 then expands that entry into a per-phase spec.
  • Handoff/state scaffolding — sibling reads/writes phase outcomes here at close-out.

Phase ids are STABLE: the sibling references phases by plan id across sessions. Never renumber a phase once execution has begun; append or split instead.

HALT CONDITIONS

  • /codex-review or ultracode workflow support is unavailable — the review gates hard-require them (see Preconditions).
  • The brief is too thin to derive a defensible scope/architecture — ask for the missing intent.
  • The architecture checkpoint (step 2) — the single deliberate stop, unless running fully unattended by prior agreement.
  • An architectural decision is genuinely irreversible AND has no defensible default.
  • Convergence would exceed the 3-round Codex cap with errors (not warnings) unresolved.
  • Push fails for an auth/remote reason requiring human intervention.

Output

Brief report:

  • Master spec path; phase count.
  • Phase plan summary: id → title → depends_on → status.
  • Scope coverage confirmation (no orphaned or duplicated requirements; phase 1 establishes the harness).
  • Codex rounds consumed; open/deferred items.
  • Commit SHA(s) pushed.