# Specification Session

> Own a session dedicated only to specification for this repository when a distinct specification checkpoint is triggered. Use when the orchestrator already has an accepted Phase 0 task brief plus enough researched or explicitly bounded input to make `spec.md` review-ready, must run inline lean `Risk Challenge` or formal spec-clarification challenge as triggered before review handoff, and must upda…

- **Type:** Skill
- **Install:** `agentstack add skill-dankosik-go-service-template-rest-specification-session`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Dankosik](https://agentstack.voostack.com/s/dankosik)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Dankosik](https://github.com/Dankosik)
- **Source:** https://github.com/Dankosik/go-service-template-rest/tree/main/.agents/skills/specification-session

## Install

```sh
agentstack add skill-dankosik-go-service-template-rest-specification-session
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
4. relevant `research/*.md`, when present
5. 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](https://github.com/Dankosik)
- **Source:** [Dankosik/go-service-template-rest](https://github.com/Dankosik/go-service-template-rest)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dankosik-go-service-template-rest-specification-session
- Seller: https://agentstack.voostack.com/s/dankosik
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.