midnightntwrk/midnight-passport-sdk/spec-author

spec-author — write the spec, then hand off

The upstream of the mn-passport-skills spine (docs/development-workflow.md, "The skills"). spec-driver begins by reading a spec (its plan phase, step 1); this skill produces that spec. It turns one or more deliverables into a full, derivable per-feature spec grounded in the source-of-truth docs.

Inputs

• The target deliverables (D…) from

docs/proposals/2026-09-25-sdk-deliverables.md.

• Source of truth: docs/sdk-requirements.md (what/why), docs/architecture.md

(how).

• Sequencing, dependencies, and the beta cut: docs/roadmap/roadmap.md.
• Provider / proving-service detail: docs/provider-integration.md.

Hard rules

1. Derive, do not invent. Every normative statement — a MUST, an interface,

a decision — must trace to a section of the source docs. Where the docs are silent or contradictory, record it under open questions and flag mn-passport-skills:doc-sync; never freestyle a normative decision into a spec.

1. Name the issue. The finished spec must name its GitHub issue from

midnightntwrk/passport. If none is known, STOP and ask the user before finishing. This is the same gate spec-driver enforces, pulled forward so planning never stalls.

1. Respect the normative rules in docs/sdk-requirements.md ("Normative

rules"): among them the ceremony gate (rule 1), the prover disclosure (rule 2), deposit-not-address (rule 3), no owner in connect or mn-passport-agent (rule 4), the two version axes (rule 5), and owner keys only in the Passport app (rules 11 and 12). The spec must not contradict them.

1. Author only. Do not decide the final gated tranche boundaries (that

is spec-driver's plan phase), do not write code, and never perform outward actions. Produce a proposed tranche outline for spec-driver to finalise against its size budget.

Steps

1. Read the target deliverables and every backing doc section they name.
2. Expand it into a full spec with these parts:

• Objective and scope (in / out).
• Decisions — each with a one-line rationale and a doc citation.
• Surface & interfaces — concrete types and signatures (finalise the

brief's indicative sketches).

• Flow — the sequence this feature performs; reference

provider-integration.md where the provider or the proving & settlement service are involved.

• Dependencies — internal feature specs and the external gate (the

provider, the proving & settlement service, the contract team), noting what is mockable now versus what waits on a gate.

• Acceptance criteria — observable.
• Verify plan — what mn-passport-skills:verify will drive end-to-end, and the

mocks that stand in for an unready gate.

• Proposed tranches — an ordered outline, each a single reviewable

concern, sized with the ≤ 400-net-line budget in mind (a proposal, not the final gated plan).

• Open questions and the GitHub issue.

1. Where the source docs cannot answer a normative question, add it to open

questions and hand to mn-passport-skills:doc-sync rather than guessing.

1. Write the spec as one file per feature spec under

docs/roadmap/specs/, named after its deliverables (e.g. docs/roadmap/specs/D2-account-client.md). Present it to the human.

1. On approval, hand off to mn-passport-skills:spec-driver (plan phase), which confirms

the issue, finalises the gated tranches, and loops.

Boundaries

• Finalising gated tranches and looping implementation → mn-passport-skills:spec-driver.
• Correcting the source docs → mn-passport-skills:doc-sync.
• No branches, pushes, or PRs — ever.