# Spec Document Designer

> Design and normalize repository-native `spec.md` documents for this workflow. Use when the orchestrator has an accepted Phase 0 task brief or synthesized research and needs to turn it into a stable direct/lean/full-shaped review-ready `spec.md` with the right section depth, decision placement, inline `Risk Challenge` or formal clarification-gate reconciliation, audit trail, and handoff before man…

- **Type:** Skill
- **Install:** `agentstack add skill-dankosik-go-service-template-rest-spec-document-designer`
- **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/spec-document-designer

## Install

```sh
agentstack add skill-dankosik-go-service-template-rest-spec-document-designer
```

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

## About

# Spec Document Designer

## Purpose
Turn a framed request or synthesized research into a repository-native `spec.md` that is honest, stable, and ready to hand off into mandatory specification review without turning it into a PRD, a design bundle, or a task list.

## 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.

## Scope
- draft a fresh `spec.md` when the task is mature enough for specification
- normalize existing drafts that are too thin, too bloated, or shaped like a foreign template
- choose the right section depth for the task while staying inside the repository's artifact model
- translate useful coverage prompts from external spec workflows into repo-native sections
- keep blockers, assumptions, inline `Risk Challenge` or clarification outcomes, validation hooks, and handoff links visible before specification review
- keep the handoff focused on the current decision frontier: record downstream consequences that matter, but do not promote every visible consequence into a new design decision inside `spec.md`
- for replacement or cleanup-discipline work, name known legacy surfaces and the expected remove/refactor/retain semantics before tasking begins
- for REST/API, generated contract, event payload, or material internal-interface work, record the behavior/contract delta and whether later system/integration design must run the triggered contract-design checkpoint
- for non-trivial custom implementation, new runtime dependencies, or meaningful helper/abstraction choices, record dependency/OSS due diligence before tasking begins
- for non-trivial architecture, system-design, workflow, integration, resilience, consistency, data-flow, or abstraction choices, record Pattern Fit Diligence before tasking begins or route to research/technical design when the pattern comparison is not ready

## Boundaries
Do not:
- refine a raw product idea; use `idea-refine`
- perform engineering framing on an under-shaped request; use Phase 0 intake or `spec-first-brainstorming`
- absorb unresolved cross-domain design contradictions that belong in `go-design-spec` or specialist `*-spec` skills
- assemble a triggered split `design/` bundle; that belongs to `go-design-spec`
- produce task breakdown, execution sequencing, or coder instructions; that belongs to `planning-and-task-breakdown`
- silently skip triggered `technical design` by smuggling split-design detail into `spec.md`; lean-local compact design answers are allowed when their trigger rationale is explicit
- mark lean-local `spec.md` review-ready without inline `Risk Challenge`, or mark full-orchestrated/protected-domain `spec.md` review-ready while the formal `spec-clarification-challenge` gate is unresolved or blocked
- copy BMAD, Spec Kit, Superpowers, or SDD templates directly into this repository's `spec.md`

## Escalate When
Escalate if:
- the request is still idea-shaped, solution-led, missing its behavior delta, or lacks an accepted Phase 0 intake brief
- current external guidance materially affects the design and has not been researched yet
- the draft still contains unresolved domain contradictions that would make `spec.md` dishonest
- the clarification challenge returns `blocks_spec_approval`, `blocks_specific_domain`, or `requires_user_decision` items that the orchestrator has not reconciled
- the work is tiny enough that a separate spec pass would be ceremony instead of risk reduction
- non-trivial work still lacks a stable decisions record that `go-design-spec` can carry into `design/` without reopening core framing

## Core Defaults
- `spec.md` is the canonical decisions artifact.
- For lean-local work, the handoff path is `spec.md` with compact design answers, recorded subagent gate decision, and inline `Risk Challenge` -> specification review -> `tasks.md`.
- For full-orchestrated or protected-domain work, the handoff path is `spec.md -> specification review -> system-integration-design -> go-code-ownership-design -> technical design review -> tasks.md`, with compact design collapse only when explicitly justified, and formal `spec-clarification-challenge` is required before the spec is review-ready.
- For dedicated specification sessions, this pass ends at review-ready `spec.md`; specification review begins in a new session unless the task is direct-path and no `spec.md` is required.
- Use the repository's default section set unless merging sections makes the file clearer.
- Treat external frameworks as coverage prompts, not as headings to copy.
- Put stable decisions in `spec.md`, lean compact design answers in `spec.md` or one `design/overview.md`, split task-local technical context in `design/` when triggered, execution order and task detail in `tasks.md`, and preserved evidence in `research/*.md`.
- Keep client-visible contract meaning explicit enough for review: `spec.md` owns the behavior/contract delta and final scope constraints, while triggered `system-integration-design` owns detailed contract shape in `design/contracts/` or a compact-sufficient rationale before OpenAPI, handlers, generated clients, or tests are tasked.
- For replacement specs, record known old identifiers, routes, configs, commands, generated outputs, fixtures, docs, skills, agents, or mirrors and decide whether each is removed, refactored into the active path, or retained with owner, reason, proof, and exit condition.
- For dependency-sensitive specs, record selected and rejected stdlib, established repository-pattern, mature OSS, and custom-code options with current evidence. Missing dependency/OSS due diligence blocks review-readiness when the task would otherwise add a dependency, build custom infrastructure, or introduce a meaningful helper/abstraction.
- For pattern-sensitive specs, record selected and rejected design or system-design patterns with current source descriptions, real-use examples, task applicability, Go/repository fit, and custom-design justification when no known pattern fits. Missing Pattern Fit Diligence blocks review-readiness when the task would otherwise invent architecture, workflow, integration, resilience, consistency, data-flow, or abstraction shape.
- Prefer short explicit bullets over template sludge.
- Omit empty sections instead of padding the document for completeness theater.
- Deep coverage is good, but `spec.md` should close only the decisions needed before technical design. Later-domain consequences that do not require a new decision now should stay as constraints, proof obligations, or explicit `no new decision required` notes.

## Context Intake (Dynamic Loading)

Rule: load the smallest sufficient set of artifacts. Do not bulk-load folders by default.

Always load:
- `AGENTS.md`
- `docs/spec-first-workflow.md`

Load by trigger:
- existing spec rewrite or continuation: the active `spec.md`
- triggered workflow control: the matching `workflow-plan.md`
- research-backed synthesis: the relevant `research/*.md`
- formal spec review-readiness: `.agents/skills/spec-clarification-challenge/SKILL.md` when full-orchestrated, high-risk, protected-domain, or otherwise triggered
- task-breakdown drift check: the matching `tasks.md` when it exists
- existing design bundle nearby: `design/overview.md` and only the smallest set of affected design artifacts needed to confirm ownership boundaries, not to author triggered split design in this pass

Conflict resolution:
- repository contract beats the reference file
- the more specific artifact beats generic guidance
- if a foreign template conflicts with repo artifact ownership, keep the repo model and translate the useful idea instead

Unknowns:
- if critical facts are missing, mark them as `[assumption]` or escalate

## Reference Files Selector

References are compact rubrics and example banks, not exhaustive checklists. Load at most one reference by default after core context. Load more than one only when the task clearly spans independent decision pressures, such as both clarification-gate reconciliation and validation closeout.

Before loading a reference, use this behavior-change thesis test: "When loaded for symptom X, this file makes the model choose Y instead of likely mistake Z." If no row below matches that sentence, do not load a reference.

| Symptom | Behavior change | Load |
|---|---|---|
| Foreign-template pressure, framework vocabulary, or coverage gaps without a narrower symptom | Translate only behavior-changing coverage concerns into repo-native sections instead of copying PRD, BMAD, Spec Kit, Superpowers, or SDD headings | `references/spec-patterns.md` |
| A spec is too thin, too bloated, or hard to size | Choose risk-proportional section depth instead of writing either "add X, test it" or a full PRD/design bundle | `references/spec-section-depth-examples.md` |
| `spec.md` mixes final decisions with research, design detail, tasks, or transcripts | Move each fact to its owning artifact instead of using `spec.md` as an all-purpose dump | `references/decision-placement-and-artifact-ownership.md` |
| The draft has `TODO`, `TBD`, blockers, soft assumptions, or user-only decisions | Label and route uncertainty by unblock path instead of inventing certainty or hiding blockers in `Decisions` | `references/open-questions-and-assumptions.md` |
| A `spec-clarification-challenge` pass returned findings, or non-trivial spec review-readiness is questionable | Reconcile findings into final spec sections and gate status instead of pasting transcripts or marking review-ready through blockers | `references/clarification-gate-reconciliation.md` |
| Validation language is vague, acceptance criteria need proof shaping, or `Outcome` is being written | Separate forward-looking proof obligations from evidence-backed outcome claims instead of writing "run tests" or "done" | `references/validation-and-outcome-sections.md` |
| A non-trivial spec is at `spec.md -> design/` handoff, or design detail leaks into the spec | Keep `spec.md` at behavior-decision level with explicit handoff and reopen conditions instead of stuffing component maps, sequences, ownership maps, or task lists into the spec | `references/spec-handoff-to-design-checkpoints.md` |

Neighboring-reference rule:
- For mixed-content cleanup, prefer `decision-placement-and-artifact-ownership.md`.
- For final handoff readiness or design leakage at review-readiness time, prefer `spec-handoff-to-design-checkpoints.md`.
- For foreign-template sprawl plus depth problems, prefer `spec-section-depth-examples.md` if the main decision is sizing; prefer `spec-patterns.md` if the main decision is translating framework concerns.
- Do not load a broad reference when a narrower row already matches the symptom.

## Hard Skills

### Mission
Make `spec.md` stable enough for mandatory specification review while preserving the repository's single-source-of-truth discipline.

### Default Posture
- decision-first
- artifact-disciplined
- minimum sufficient structure
- no placeholder tolerance

### Spec Shape Competency
- Start from the repository's default sections:
  - `Context`
  - `Scope / Non-goals`
  - `Constraints`
  - `Decisions`
  - `Open Questions / Assumptions`
  - `Task Breakdown / Handoff Link`
  - `Validation`
  - `Outcome`
- For lean-local specs, prefer the compact shape from `docs/spec-first-workflow.md`: `Intent`, `Scope / Non-goals`, `Behavior / Contract Delta`, `Decisions`, `Dependency / OSS Due Diligence`, `Compact Design`, `Subagent Gate Decision`, `Risk Challenge`, `Task Handoff`, `Validation`, and `Outcome`.
- Merge sections only when it makes the document clearer.
- Expand depth based on task risk and ambiguity, not on habit.

### Coverage Competency
- Capture the behavior delta, affected actors, scope cuts, edge semantics, validation expectations, and material constraints.
- Capture dependency/OSS due diligence when relevant: current Go stdlib fit, established repo pattern fit, OSS candidates, maintenance/release activity, adoption such as stars or domain-equivalent signals, license, security posture, transitive dependency cost, API stability, repository-boundary fit, selected option, rejected options, and custom-code justification.
- Capture Pattern Fit Diligence when relevant: known candidate patterns, concise source descriptions, real-use examples, why the pattern forces match or do not match this task, Go/repository fit, selected pattern, rejected patterns, and custom-design justification.
- When the behavior delta replaces an old path, capture the legacy-surface delta explicitly: what old surfaces are gone, what is refactored into the active path, what remains intentionally retained, and what proof will make that claim auditable.
- Ask and answer before review-readiness: `Does this change replace an existing path?` If yes, list known old code, tests, fixtures, configs, docs, generated outputs, skills, agents, or mirrors. If no, record `No known replacement surface`.
- Use these external patterns only as coverage lenses:
  - independently testable slices
  - user journeys or demoable units
  - measurable success criteria
  - selective NFRs
  - proof artifacts
  - repository standards
  - rejected alternatives when they materially affect planning
- If a pattern adds no execution value for this task, leave it out.

### Artifact Ownership Competency
- Stable decisions belong in `Decisions`.
- Evidence history, comparisons, and raw external research belong in `research/*.md`.
- Research-backed decisions should link to the specific preserved research note or source surface when the provenance would help a later session trust or revisit the decision; keep the link short and do not copy the evidence narrative into `Decisions`.
- Task-local technical design context belongs in `design/`.
- Task sequencing and execution detail belong in `tasks.md`.
- Unresolved but visible gaps belong in `Open Questions / Assumptions`.
- Label `Open Questions / Assumptions` by unblock path when the uncertainty affects later sessions: `[assumption]` for bounded proceed-and-revisit assumptions, `[accepted_risk]` for deliberate risk with limits or proof obligations, `[requires_user_decision]` for external product or policy choices, `[targeted_research]` for repository evidence still needed, `[defer_to_design]` only for design-owned details after behavior is decided, and `[reopen_spec_if_false]` for downstream discoveries that would invalidate a spec-level assumption.
- Do not force `go-design-spec` or the planner to recover ownership, sequence, or execution order from `spec.md` when separate artifacts are warranted; for lean local, make those compact answers explicit in `spec.md`.

### Technical-Design Handoff Competency
- A full-orchestrated or design-triggered spec must let `go-design-spec` derive the task-local `design/` bundle without silently reopening core problem framing.
- A spec with REST/API, generated contract, event payload, or material internal-interface changes must name the contract-d

…

## 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-spec-document-designer
- 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%.