Specification Session

Specification Session

Purpose

Run only the specification checkpoint for one task-local session. This wrapper makes spec-ready input, the autonomous clarification gate, allowed writes, handoff, and stop conditions explicit; it does not run specification review, assemble design/, produce tasks.md, or start implementation.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Use When

• the task already has an accepted Phase 0 intake brief and enough evidence or bounded assumptions to support an honest spec.md
• prior workflow routing says the next session starts with specification
• research, challenge, or direct local analysis already narrowed the open questions enough that stable Decisions can now be written
• candidate decisions are ready for either inline lean Risk Challenge or required formal spec-clarification-challenge before specification-review handoff
• task-local spec.md, triggered workflow-plan.md, or triggered workflow-plans/specification.md is missing, stale, or inconsistent and the active session should repair the specification checkpoint only

Skip When

• the work is tiny enough that AGENTS.md allows an inline local path and a dedicated specification session would be ceremony
• lean-local specification can be completed in the same local pass with compact spec.md, inline Risk Challenge, and no separate phase-control value
• the task is still at Phase 0 intake, workflow planning, or research, or the current evidence is not yet spec-ready
• the task has already moved into technical design or later and the current session should not reopen specification casually
• the request tries to combine specification with design/, tasks.md, or implementation output in one session

Required Inputs

Need only the minimum phase-ready inputs from earlier work:

• accepted Phase 0 intake brief or equivalent confirmed framing
• framed task goal, scope, non-goals, constraints, risk hotspots, and success checks
• current workflow routing and task-local artifact location
• the latest upstream phase output that made specification the next checkpoint
• relevant research findings, comparison notes, or explicit rationale for why more research is not needed
• dependency/OSS due-diligence evidence when a new runtime dependency, custom infrastructure, or meaningful helper/abstraction is plausible
• Pattern Fit Diligence evidence when architecture, workflow, integration, resilience, consistency, data-flow, or abstraction patterns could change candidate decisions
• candidate decisions compact enough to give a read-only clarification challenger a useful input bundle
• unresolved assumptions, blockers, or challenge outcomes that still affect spec honesty
• existing spec.md, if this is a continuation or repair rather than a fresh pass

If a required fact is missing, record it as an assumption, blocker, or reopen point instead of inventing detail.

What Counts As Spec-Ready Input

Treat the session as spec-ready only when all of the following are true:

• the behavior delta and scope cuts are explicit enough to write stable Decisions
• material constraints, risks, and validation expectations are visible
• the current evidence is strong enough to avoid fiction, or the remaining uncertainty is small enough to live honestly in Open Questions / Assumptions
• prior research or direct analysis already answered the must-answer-now questions, or the workflow plan explicitly records why more research is not required
• dependency/OSS due diligence is complete or explicitly not applicable when candidate decisions would otherwise add a dependency, build custom infrastructure, or introduce a meaningful helper/abstraction
• Pattern Fit Diligence is complete or explicitly not applicable when candidate decisions would otherwise invent architecture, workflow, integration, resilience, consistency, data-flow, or abstraction shape
• for lean-local work, the inline Risk Challenge can be recorded as PASS or CONCERNS; for full-orchestrated or protected-domain work, the formal spec-clarification-challenge gate can be run and reconciled before spec.md is marked review-ready
• the task can hand off to specification review without reopening core framing by default
• the session distinguishes what technical design must decide next from what can remain an explicit constraint, proof obligation, or follow-up note

If those conditions are not met, do not force review-readiness. Reopen the right upstream phase instead.

Read First

Always read:

• AGENTS.md
• docs/spec-first-workflow.md
• .agents/skills/spec-document-designer/SKILL.md
• .agents/skills/spec-clarification-challenge/SKILL.md

Then read current phase context in this order:

1. task-local workflow-plan.md, if present
2. task-local workflow-plans/specification.md, if present
3. the smallest upstream artifact that explains why specification is next:

• workflow-plans/research.md
• workflow-plans/workflow-planning.md
• accepted Phase 0 intake brief when preserved in workflow-control
• approved framing notes or equivalent task-local context

1. relevant research/*.md, when present
2. existing spec.md, only to continue or normalize it in this session

Rules:

• follow AGENTS.md if other guidance conflicts
• read the master workflow-plan.md before the phase-local file when both exist
• load only the smallest evidence set needed to decide whether the task is truly spec-ready
• if phase context shows the task already advanced past specification, stop instead of casually reopening an earlier phase

Lazy Reference Routing

References are compact rubrics and example banks, not exhaustive checklists, documentation dumps, or second authorities. Load at most one reference by default: choose the narrowest file whose symptom matches the active decision pressure. Load more than one only when the session clearly spans independent pressures, such as readiness uncertainty plus a separate clarification-gate result. If a reference would not change a decision, do not load it. These references calibrate this wrapper; they do not override AGENTS.md, docs/spec-first-workflow.md, spec-document-designer, or spec-clarification-challenge.

| Symptom | Reference | Behavior Change | | --- | --- | --- | | Phase ownership is unclear, the input looks under-researched, or the caller asks to approve spec.md from partial decisions. | references/specification-session-readiness.md | Choose a spec-ready check, bounded assumption, or reopen/block decision instead of approving by momentum. | | The session is about to edit files, or the request pressures it toward design/, tasks.md, tests, migrations, or implementation. | references/allowed-writes-and-stop-rules.md | Keep writes specification-only and record the boundary instead of creating downstream starter artifacts. | | Non-trivial spec.md review-readiness depends on running, reconciling, blocking, or marking the clarification gate not expected after shape reclassification. | references/spec-clarification-gate-flow.md | Reconcile spec-clarification-challenge outcomes into final decisions instead of treating the gate as optional, pasting transcripts, or deferring approval blockers to later review. | | workflow-plan.md or workflow-plans/specification.md needs repair or handoff updates. | references/workflow-plan-specification-updates.md | Keep master routing separate from phase-local orchestration instead of duplicating spec.md, adding implementation order, or leaving state in chat. | | spec.md cannot honestly become review-ready because of under-framed input, contradictory evidence, unresolved challenge questions, product-only policy, or phase drift. | references/blocked-specification-examples.md | Leave spec.md draft or blocked with a precise reopen target instead of inventing decisions or punting approval-changing gaps to specification review. | | spec.md is review-ready or near review-ready and the next session route is being chosen. | references/handoff-to-specification-review.md | Record a clean specification-review handoff and stop instead of starting review, design work, or hiding assumptions in chat. |

Allowed Writes

This session may write or update only:

• task-local spec.md
• task-local workflow-plan.md
• task-local workflow-plans/specification.md
• the workflow-plans/ directory only when it must be created to hold the phase-local file

Prohibited Actions

Do not:

• write research/*.md except by handing the task back to a research checkpoint instead of continuing here
• assemble or edit design/
• write tasks.md, test-plan.md, or rollout.md
• start implementation, tests, migrations, review, or validation work
• use planning or implementation skills as a backdoor into later phases
• turn workflow-plans/specification.md into a second spec.md, a design bundle, or a task list
• mark spec.md review-ready when the input is still under-evidenced, contradictory, or idea-shaped
• mark lean-local spec.md review-ready before inline Risk Challenge is recorded, or mark full-orchestrated/protected-domain spec.md review-ready before formal clarification is complete and reconciled
• silently continue into triggered technical design once the spec feels close enough

Core Defaults

• this is an orchestrator-facing wrapper, not a domain specialist
• AGENTS.md owns the workflow contract; docs/spec-first-workflow.md owns the artifact mechanics
• this wrapper owns specification-session protocol only and must not redefine spec shape, design rules, or planning behavior
• use spec-document-designer as the deeper method for writing or normalizing spec.md
• for lean-local work, record inline Risk Challenge; for full-orchestrated, high-risk, protected-domain, or otherwise triggered work, run formal clarification according to docs/spec-first-workflow/phases/specification.md, preferably with challenger-agent using spec-clarification-challenge
• broad formal clarification uses distinct lenses rather than one generic challenger; the specification phase owns the default lens set and scoped-down rationale shape
• formal clarification is not waivable while the work remains full-orchestrated, protected-domain, high-risk, hard-to-reverse, cross-domain, or user-requested deep challenge; if the trigger no longer applies, record shape reclassification with trigger-matrix evidence before marking the formal gate not expected
• Missing explicit subagent authorization is not a valid scoped-down or local-only clarification rationale. If required clarification lanes are blocked only because the current prompt lacks explicit subagent/delegation authorization, leave the specification gate blocked and return a next-session prompt with Subagent authorization:.
• the clarification subagent returns questions for orchestrator reconciliation; it never edits files or makes final decisions
• keep the wrapper focused on session readiness, allowed writes, handoff, and stop rules
• a finished specification session ends at review-ready spec.md and routes the next session to specification review unless an earlier recorded direct-path waiver makes spec.md unnecessary

Boundary With spec-document-designer

• spec-document-designer owns the deeper spec.md authoring method: section choice, decision placement, artifact ownership, and design-checkpoint handoff quality
• specification-session owns when that method may run inside a dedicated session, what phase inputs are required, what files may be changed, how workflow-plan.md and workflow-plans/specification.md must be updated, and why the session must stop
• do not duplicate the full spec-document-designer section guidance here; reuse it after the phase boundary is confirmed
• if the real need is only local spec shaping without session routing, use spec-document-designer directly instead of this wrapper

Workflow

1. Confirm This Session Owns Specification Only

• check the master workflow plan and current phase context first
• if the task is still at Phase 0 intake, workflow planning, or research, hand it back to the correct upstream phase instead of spec-writing by momentum
• if the task is already at technical design or later, stop and point to the correct reopen point
• if the work is tiny enough for an inline local path, say so directly and stop rather than forcing this wrapper

2. Check Spec Readiness

• verify that the task has enough framing, evidence, and bounded unknowns to support an honest decision record
• separate must-answer-now gaps from acceptable open questions
• if a missing answer can change scope, correctness, or ownership, reopen research or challenge instead of writing around it

3. Reuse spec-document-designer For The Actual Spec Pass

• once the boundary is confirmed, use spec-document-designer to draft or normalize spec.md
• keep stable decisions in Decisions, visible unknowns in Open Questions / Assumptions, and validation hooks explicit
• record dependency/OSS due diligence in spec.md when relevant so technical design and planning do not have to rerun open-ended library selection
• record Pattern Fit Diligence in spec.md or link preserved research/pattern-fit.md when relevant so technical design and planning do not have to rerun open-ended pattern selection
• label material unknowns in Open Questions / Assumptions by unblock path, such as [assumption], [accepted_risk], [requires_user_decision], [targeted_research], [defer_to_design], or [reopen_spec_if_false]
• for non-obvious research-backed decisions, link to the preserved research/*.md note or source surface when provenance would help a later session trust or revisit the decision; do not copy the evidence narrative into Decisions
• keep technical detail out of spec.md when it belongs in a triggered later design/ artifact; lean local may include compact affected-surface, ownership, and sequence/failure answers in Compact Design
• keep execution sequencing out of spec.md; that belongs to later planning
• record downstream domain effects only to the level needed for the design-checkpoint handoff; do not turn visible consequences into premature design tasks when no new decision is required yet

4. Run The Autonomous Clarification Gate

• for lean local with no escalation trigger, record inline Risk Challenge in spec.md and classify it as PASS, CONCERNS, or FULL_REQUIRED
• Risk Challenge=CONCERNS alone does not trigger formal multi-challenger clarification; inspect whether the concern exposes unresolved scope, ownership, proof, or escalation gaps that cannot be honestly closed inline
• for full-orchestrated, high-risk, protected-domain, or otherwise triggered work, prepare a compact input bundle: problem frame, scope and non-goals, candidate decisions, constraints, val

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.