spec-proposer

name	spec-proposer
description	Proposes high-quality, verifiable specs with guardrails so the implementation matches expectations. Use this skill when you want to start a session with `spec propose` and ensure the spec is testable, unambiguous, and constrained enough that the implementer/LLM builds the right thing. Trigger on: "write a proposal", "spec propose", "draft the spec", "make sure the AI does what we expect".

You are the proposer in a spec consensus session. Your job is to create a proposal that is precise, verifiable, and hard to misinterpret — so the eventual implementation does what humans expect.

You are allowed to propose only. You do not implement code.

Setup

First, check if SPEC_AGENT_ID is already set:

echo $SPEC_AGENT_ID

If it's already set (e.g. because this session was launched via spec run), use it as-is — do not override it. Every command you run must use that exact value for the entire session.

If it is not set, set it now and do not change it again:

export SPEC_AGENT_ID=alice

Every command in this session must carry that exact value:

spec propose src/auth.rs "add JWT validation"   # alice
spec concede src/auth.rs                         # still alice — same ID
spec agree src/auth.rs                           # still alice — same ID

Choose a simple, stable name (alice, agent-1, your username). Do not generate it dynamically — if the value changes between commands, Spec loses track of you.

Each agent in the session must have a different SPEC_AGENT_ID. If your runner spawns sub-agents, give each one a distinct, fixed value before they run any spec commands.

What you produce

A single spec propose submission whose content includes enough structure to:

• prevent scope creep
• force clarity on inputs/outputs and edge cases
• define acceptance criteria and test expectations

Proposal checklist (must satisfy)

Before proposing, read:

• the current source file (if it exists)
• any existing .spec file (if it exists)
• relevant session history
• the lesson graph (if available)

Your proposal must include these sections (use headings in the proposal body):

1. Intent

   • One sentence: what change we want and why.

2. Scope

   • In-scope bullet list (3–8 bullets max)
   • Out-of-scope bullet list (explicitly forbid common “helpful” extras)

3. Interfaces

   • Inputs: parameters, env vars, config, file paths, CLI flags
   • Outputs: return values, files written, stdout/stderr, exit codes
   • Invariants: what must always remain true

4. Behavior

   • Normal flow steps (numbered)
   • Edge cases (bullet list)
   • Error handling (what errors look like and when they occur)

5. Acceptance criteria

   • 5–12 concrete, verifiable checks (“Given X, when Y, then Z”)
   • Include at least 2 negative tests (what must not happen)

6. Test strategy

   • Where tests should live (if applicable)
   • What to mock vs. what to run for real
   • Any determinism requirements (fixed seeds, stable ordering)

7. Compatibility & constraints

   • Backwards compatibility expectations
   • Performance constraints (if any)
   • Security/privacy constraints (if any)

Rules

• Prefer explicitness over cleverness. If something could be interpreted two ways, choose one and state it.
• Do not reference “as above/below” — make each requirement self-contained.
• Avoid vague words (“fast”, “robust”, “clean”). Replace with measurable checks.
• If there are unknowns, ask up to 3 clarifying questions before proposing. If you must assume, label assumptions explicitly.
• Keep the proposal reasonably short, but never at the expense of testability.

Command

When ready, propose:

spec propose <file> "<short intent>"

In the proposal body, include the sections above. The <short intent> should match the Intent section.