Canonical architectonic current-spec engine. Turn ambiguous project, architecture, implementation, or product requests into decision-complete specs whose architecture and abstractions are explicit, authority-bound, and proof-linked; operate narrowly in gate-only, challenge-only, or repair mode; validate final SGR-v2 and PSC-v1 JSON through passive Ledger definitions; default full-mode plan-ready specs to lane=spec_to_plan; and tail-call `$plan` when SGR-v2 and execution handoff authorize planning. Never emit a proposed_plan block.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Canonical architectonic current-spec engine. Turn ambiguous project, architecture, implementation, or product requests into decision-complete specs whose architecture and abstractions are explicit, authority-bound, and proof-linked; operate narrowly in gate-only, challenge-only, or repair mode; validate final SGR-v2 and PSC-v1 JSON through passive Ledger definitions; default full-mode plan-ready specs to lane=spec_to_plan; and tail-call `$plan` when SGR-v2 and execution handoff authorize planning. Never emit a proposed_plan block.
$spec-pipeline is the canonical current-spec workflow.
It converts an accepted or clarified objective into a decision-complete
implementation spec whose consequential architecture and abstractions are explicit,
authority-bound, and derivationally connected to implementation, proof, migration,
and rollback. It hands planning authority to $plan when the spec governance
receipt authorizes that transition.
$spec-pipeline owns accepted semantics and specification-local architectonic
decisions. $plan owns execution-policy synthesis, source-bounded and plan-local
architectonic refinement, task/wave ordering, policy fixed-point refinement, and
its canonical EPG-v1 output. This skill does not require $plan, ,
, or to make a complete specification. It never mutates
repository product files and never emits .
$actuating
$universalist
$reduce
<proposed_plan>
Public boundary
Use $spec-pipeline for:
creating or materially reconstructing an implementation spec;
deciding whether a brief, decision packet, architectonic thread, spec, or handoff
is ready;
making consequential architecture and abstraction explicit before implementation
planning;
running one strongest invariant challenge;
repairing only sections implicated by a blocked readiness decision, architectonic
invalidation, challenge, fresh-eyes pass, or governance result;
handing a ready spec to $plan or implementation.
Use $grill-me when unresolved user judgment is the primary task. Use
$spec-retro for historical learning across multiple prior specs, sessions,
reports, or governance receipts.
full — create or materially reconstruct a complete implementation spec.
gate-only — decide whether an existing brief, decision packet, architectonic
thread, or handoff is ready. Do not generate a spec, plan, or mutation authority.
challenge-only — return one strongest critique or invariant pressure test.
Do not authorize mutation.
repair — change only sections implicated by a prior blocked readiness decision,
architectonic invalidation, challenge, fresh-eyes pass, or governance result;
then rerun affected and downstream phases.
Choose one profile:
profile
Use when
Default subagent pattern
fast
Narrow local change, obvious proof, low ambiguity, no consequential seam.
root only
balanced
Normal implementation spec.
evidence synthesizer, invariant challenger, governance auditor as needed
strict
Public API, migration, security, performance, compatibility, architecture, abstraction, or multi-wave work.
unless the user explicitly requests spec-only/no-plan output or a material gate
blocks downstream planning.
Explicit $spec-pipeline invocation is not a request for spec_only. A user
saying $spec-pipeline, make a spec, write the spec, produce the governed spec, or equivalent asks the spec workflow to run. If the workflow finishes
complete and plan-ready, planning authority transfers to $plan through SGR-v2 and
the Execution Handoff.
Use spec_only only when a concrete blocker exists: explicit spec-only user
request, gate-only/challenge-only mode, blocked/drift/partial status, unresolved
material user judgment, plan_allowed=no, fresh-eyes drift, ready_for_plan=no,
next_owner != $plan, non-empty do_not_execute_before, or same-turn $plan being
unavailable. When $plan cannot load, emit AUTO_PLAN_HANDOFF_REQUIRED; do not
silently convert to spec_only.
Inspect available artifacts before asking questions: code, docs, specs, plans,
tests, tickets, logs, diagrams, schemas, config, session history, and supplied
reports.
For consequential architecture or abstraction, inspect real owner, representation,
construction, composition, interpretation, validation, migration, and proof paths.
Do not accept current files, classes, packages, services, or layers as the semantic
factorization without evidence.
Do not ask the user for discoverable facts. Ask only for judgment, unavailable
context, explicit authority, irreversible approval, private constraints, or
conflicts that artifacts cannot resolve.
Evidence Brief
In full mode, emit exactly:
## Evidence Brief
- Current state:
- Relevant surfaces:
- Existing behavior:
- Known constraints:
- Obvious risks:
- Proof surfaces already available:
- Facts not yet verified:
- Judgment calls still needed:
Use none only after considering the field.
Grilling
Ask 1-3 bounded questions per round only when material decisions remain. Each
question must be atomic, have a stable snake_case id, put the recommended option
first when justified, and avoid asking for discoverable facts.
Before asking more questions, compiling architectonic seams, compiling a spec, or
handing off, compare the candidate against the authoritative brief:
target
scope
non-goals
authority boundary
compatibility posture
proof bar
rollout/rollback posture
public behavior boundary
source-fixed architecture and abstraction constraints
If any changed without explicit approval, stop with:
SPEC_PIPELINE_DRIFT_WARNING
and set SGR-v2 status to drift.
Architectonic specification
Before finalizing the decision packet or running the pre-spec gate, recover an
Architectonic Thread for every consequential seam. This is a bounded
specification phase, not an unbounded architecture search and not a dependency on
another skill.
A seam is consequential when at least two plausible organizations materially differ
in persistent behavior, ownership, compatibility, migration, enforcement,
information retention, resources, or proof obligations. Otherwise preserve the
incumbent with one law and falsifier or record not consequential.
For each consequential seam:
classify authority as source_fixed, source_bounded, or
specification_local;
record one architectural axis and one typed hole;
recover live obligations, required observations, incumbent factors, owners,
compatibility, effects, resources, and host capabilities;
state the ordinary repository-native candidate first;
compare preservation, admitted-domain restriction, representation/owner
strengthening, and ablation/normalization;
classify factor obligations as live, moved, expired, duplicated,
invalid, or unknown;
factor, quotient, ablate, normalize, preserve, or introduce factors only with a
recomposition and proof account;
choose selected, evidence_conditioned, downstream_open,
underdetermined, or obstructed;
record law, falsifier, residual obligations, and invalidators.
Prefer conceptual compression: explain more live obligations and observations with
fewer independent concepts, owners, exceptions, and reconstruction paths. Raw file,
layer, or line count never proves dominance.
When the specification process and architecture change form two genuinely distinct
compositional directions, require the specification square to preserve observations,
authority, compatibility, effects, resources, and proof. Sequential derivations
paste horizontally; successive architecture changes paste vertically; interchange
requires changing-then-deriving to agree with deriving-then-transporting up to the
declared equivalence.
A governance-complete spec has no consequential seam without a lawful disposition.
An obstructed seam is lawful documentation of a blocker, not planning readiness.
It forces:
SGR-v2 status = blocked
gate.plan_allowed = no
execution_handoff.ready_for_plan = no
auto_plan_handoff.eligible = no
The receipt names the obstructed seam and blocker. Do not emit PSC-v1 or tail-call
$plan until a later governed revision clears the obstruction.
Decision packet
After recovering the Architectonic Thread and before the pre-spec gate, emit:
Open questions need owner, default, consequence, and non-blocking reason. Defaults
must be distinguishable from locked user decisions. Implementation and
architectonic choices must not be smuggled in without authority or evidence.
A downstream-open architectonic decision must name its admissible candidate space,
required deciding observations, forbidden outcomes, safe default or blocker, and
invalidators. It is not an excuse for an unspecified design.
After the decision packet contains the recovered Architectonic Thread and before
compiling a spec, complete this sentence:
We are building X, for Y, by changing Z, while explicitly not doing A/B/C, under architectonic constraints D/E, and success means P/Q/R proofs pass.
Emit:
## Gate Result
plan_allowed:
mutation_allowed: false
material_open_questions:
defaults:
deferrals:
handoff_sentence:
If the gate fails, do not produce a spec or plan. Ask at most 1-3 next material
questions and set SGR-v2 status to blocked.
Implementation spec contract
A complete implementation spec uses these sections in order:
Objective
Context / Current State
Locked Decisions
Scope
Non-Goals
Requirements
Architecture and Abstraction
Design / Implementation Approach
Dependency-Ordered Implementation Sequence
Requirement-Owner-Enforcement-Proof Traceability
Proof Commands
Risks and Edge Cases
Rollback / Abort Criteria
Binary Done-State
Open / Deferred Items
Architecture and Abstraction carries the Architectonic Thread: seam authority,
incumbent organization, ordinary and alternative candidates, selected or conditioned
organization, canonical owners, factor dispositions, laws, falsifiers, residuals,
and invalidators.
Every downstream section must be derived from that thread:
Every implementation-sequence item identifies whether it establishes, transports,
migrates, retires, proves, or removes a bypass for an architectonic factor. A
sequence that realizes a quotiented, ablated, normalized, or superseded factor is
inconsistent and must be regenerated.
Keep the implementation sequence at spec level. Do not create task rows,
iterations, execution waves, or <proposed_plan>.
Challenge phase
Run exactly one strongest project-specific challenge tied to the primary invariant.
When architecture or abstraction is consequential, attack the governing organization
rather than merely a local implementation choice. Read
challenge-contract.md.
If the challenge changes architecture, proof, scope, or risk, revise only affected
sections and rerun affected downstream phases. A changed_architecture result names
the affected seam and regenerates every implementation-spec section derived from it.
Fresh-Eyes phase
Reread the final candidate against the authoritative brief, Evidence Brief, Gate
Result, decision packet, and Architectonic Thread. Read
spec-fresh-eyes-pass.md.
Look for drift, missing non-goals, hidden consequential architecture, smuggled
implementation choices, file-shaped factorization, abstraction proliferation,
duplicated truth, reconstruction paths, superseded factors still in the sequence,
missing square witnesses, vague proof, scaffold-only proof, rollback gaps, unmapped
requirements, plan-shaped detail, and stale assumptions. If a material decision is
missing, return to gate failure rather than handing off.
Spec Pipeline Receipt
Every terminal output must include exactly one ## Spec Pipeline Receipt section
followed by one JSON object. The template below is JSON syntax; replace every
angle-bracket value with one value admitted by SGR-v2.
This single JSON object is the machine-readable truth. Mode-specific
human-readable sections remain required, but duplicated top-level receipt blocks
are not.
Before the first native Ledger command in this workflow, load $ledger and
complete $ledger ensure once.
Validate the exact final object before treating it as the current SGR-v2:
Accept only ledger-validation-result/v1 with valid: true,
definition.id = spec-pipeline/spec-governance-receipt,
definition.abi = ledger-artifact-abi/v1, and the exact definition and input
digests. Describe this only as structurally valid under the returned definition
digest. The Spec Pipeline—not Ledger—still decides the semantic receipt values,
lane, blockers, and handoff authority.
Execution handoff
Only full or a fully repaired repair mode may authorize downstream planning or
mutation.
gate-only and challenge-only do not authorize mutation or same-turn planning.
Automatic $plan tail-call
When final SGR-v2 and Execution Handoff satisfy all predicates, $spec-pipeline
must immediately continue into $plan in the same assistant turn. Do not ask the
user to invoke $plan separately.
Embed the exact structurally valid SGR-v2 object; do not replace it with a second
handoff artifact or summary. Validate the exact completed PSC-v1 before calling
Plan:
Accept only ledger-validation-result/v1 with valid: true,
definition.id = spec-pipeline/plan-source-contract,
definition.abi = ledger-artifact-abi/v1, and the exact definition and input
digests. A structural pass does not authorize the tail-call. Invoke $plan only
when Spec Pipeline's independently authored SGR-v2 and all semantic predicates
above grant that handoff.
The Architectonic Thread travels inside implementation_spec and
decision_packet; no second handoff artifact is created.
$spec-pipeline still must not emit <proposed_plan>. $plan performs its
fixed-point synthesis, validates the exact EPG through Plan's passive Ledger
definition, and emits one EPG-v1 policy in <proposed_plan>. $plan emits no
synthesis receipt or execution handoff and does not grant mutation authority.
Do not auto-run $plan when any of these are true:
user explicitly requested spec-only/no-plan output
mode is gate-only or challenge-only
status is blocked, drift, audit-only, or partial
lane is not spec_to_plan for a legal blocker recorded in the receipt
gate did not allow planning
material questions remain
a consequential architectonic seam lacks a lawful disposition
a consequential architectonic seam is obstructed
fresh-eyes returned to grill or detected drift
any subagent remains open
next_owner is not $plan
do_not_execute_before is non-empty
auto_plan_handoff.eligible = no with a concrete blocker other than "user did not separately ask for $plan"
If the runtime cannot actually load $plan, emit:
AUTO_PLAN_HANDOFF_REQUIRED
reason: same-turn tail-call unavailable in this runtime
next_owner: $plan
This marker is a failure of automation, not a failure of the spec. It must not be
replaced with spec_only merely because the tail-call could not run.
A positive packet must change a decision, architectonic seam, proof, risk, or
handoff. Otherwise it is neutral. No passing handoff with open subagents.
Retro trigger
Do not run historical retro inside every spec. Set retro.trigger_required: yes
when:
five or more full pipeline sessions occurred since the last retro;
the same readiness, architectonic, or challenge failure recurred at least twice;
execution outran readiness;
plan churn recurred;
no-grill justifications are repeatedly generic;
subagent fanout repeatedly produced no impact;
reports cannot recover phase impact.
Then set next owner to $spec-retro.
Hard rules
One canonical current-spec skill.
No <proposed_plan>.
In full mode, default to spec_to_plan unless a legal blocker exists.
Explicit $spec-pipeline is not a spec_only request.
No planning before gate pass.
No plan-ready handoff with an undispositioned consequential architectonic seam.
Architecture and abstraction must derive implementation, migration, proof,
rollback, and done-state; they are not an isolated prose section.
Do not require $universalist, $reduce, or $actuating to make the spec
architectonically complete.
No mutation before full challenge, fresh-eyes, governance receipt, and execution
handoff.
No execution handoff from gate-only or challenge-only mode.
No broad multi-challenge review by default.
No separate readiness or challenge skill invocation required.
No retro ceremony in every spec.
No complete handoff without SGR-v2.
If SGR-v2 says auto-plan is eligible, same-turn $plan tail-call is mandatory.
