# Technical Design Session

> Own one session dedicated only to a task-local technical design checkpoint for this repository when separate design depth is triggered. Use when specification-review-approved `spec.md` must advance through `system-integration-design` or `go-code-ownership-design`, producing or repairing the relevant `design/` context and workflow-control handoff without drifting into technical design review, test…

- **Type:** Skill
- **Install:** `agentstack add skill-dankosik-go-service-template-rest-technical-design-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/technical-design-session

## Install

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

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

## About

# Technical Design Session

## Purpose
Run only one design checkpoint for one task-local session.
This wrapper makes the `specification-review-approved spec.md -> system-integration-design -> go-code-ownership-design -> technical design review -> triggered test-design -> planning` handoff explicit: it produces or updates the active task-local design checkpoint, updates workflow control artifacts, and then stops before the next checkpoint or mandatory review gate.

Use `.agents/skills/go-design-spec/SKILL.md` as the deeper integrated design method when cross-domain reconciliation or simplification work is needed.
Do not turn this wrapper into a duplicate of `go-design-spec`; this skill owns session protocol, allowed writes, stop rules, and technical-design-review handoff only.

## 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
- specification-review-approved or explicitly waived direct-path `spec.md` exists and trigger-based design depth is needed before test design or planning
- the active workflow phase is `system-integration-design` or `go-code-ownership-design`
- lean-local `design/overview.md` or full split `design/` is missing, stale, partial, or internally inconsistent after being triggered
- master `workflow-plan.md` needs the active design checkpoint completed or updated before the next design checkpoint or technical-design-review stage
- the task needs triggered design artifacts, triggered conditional artifacts, a `test-design` trigger decision, or a clean design handoff for `planning-and-task-breakdown`
- the session should stay bounded to technical design instead of spilling into `tasks.md` or code

## Skip When
- the work is tiny or direct-path and already has an explicit design-skip rationale
- lean-local `spec.md` already contains enough `Compact Design` context for test design or planning and records why separate design is not expected
- `spec.md` is missing, unstable, contradictory, unreviewed, failed specification review, or still needs research, challenge reconciliation, or specification work
- the task is already in `planning` or a later phase and does not intentionally need design repair
- approved compact or split design context already exists and the real next step is technical design review, test design, planning, or execution
- the request tries to combine technical design with technical design review, test design, writing `tasks.md`, implementation, tests, migrations, or post-code review execution

## Required Inputs
Need only the minimum phase-ready inputs:
- specification-review-approved `spec.md`
- specification-review result when non-trivial `spec.md` exists, including accepted risks and proof obligations when status is `CONCERNS`
- current task-local artifact location
- current `workflow-plan.md`, if present
- current `workflow-plans/system-integration-design.md` or `workflow-plans/go-code-ownership-design.md`, if present
- existing compact or split `design/` artifacts when this is a continuation or repair pass
- known blockers, assumptions, and specialist outputs that still affect design integrity
- for `system-integration-design`, contract-design trigger evidence when REST resources, OpenAPI/generated contracts, event payloads, client-visible status/error/idempotency/retry/async/freshness/compatibility semantics, or material internal interfaces are plausible
- for `go-code-ownership-design`, affected source responsibility evidence or the source targets that must be audited before owner package/file decisions
- approved dependency/OSS due-diligence decisions or blockers when design selects a new dependency, custom infrastructure, or material helper/abstraction
- approved Pattern Fit Diligence decisions, preserved `research/pattern-fit.md`, or blockers when design selects an architecture, workflow, integration, resilience, consistency, data-flow, or abstraction pattern

If a planning-critical input is missing, record it as a blocker or reopen condition instead of inventing detail.

## Read First
Always read:
- `AGENTS.md`
- `docs/spec-first-workflow.md`
- task-local `workflow-plan.md`, if present
- task-local `workflow-plans/system-integration-design.md` or `workflow-plans/go-code-ownership-design.md`, if present
- specification-review-approved `spec.md`

Load `docs/repo-architecture.md` when at least one is true:
- this is a fresh non-trivial design-checkpoint pass
- the design touches repository boundaries, ownership seams, runtime flow, new or changed packages, transport/app/infra edges, async behavior, data flow, or dependency direction
- the session must rebuild task-local design from `spec.md` rather than only polishing a small existing artifact
- current design artifacts do not already capture the stable repository baseline needed for this change

It is acceptable to skip `docs/repo-architecture.md` only for a narrow continuation where the current approved design bundle already captures the relevant repository baseline and the session is editing one local seam rather than rebuilding design context.

Then load only the smallest task-local context needed to finish this phase:
- `design/overview.md` first when a design bundle already exists
- `design/system-integration.md` when the active checkpoint is system/integration design or Go code ownership must consume its decisions
- `design/go-code-ownership.md` when the active checkpoint is Go code ownership design or repair
- the smallest affected existing design artifacts
- targeted `research/*.md` or specialist outputs only when they change design integrity, test-design readiness, or planning readiness
- canonical contract or schema sources only when needed to design around them, while keeping those runtime sources authoritative

Rules:
- follow `AGENTS.md` if workflow guidance conflicts
- read the master `workflow-plan.md` before the phase-local file when both exist
- do not broad-read unrelated repository areas when the design questions are narrower
- do not reopen framing casually; if the design cannot be completed honestly, route back to `specification`

## Reference Files
Keep this `SKILL.md` as the technical-design-session wrapper protocol. References are compact rubrics and example banks, not exhaustive checklists, source-link collections, or substitutes for repo-local authority.

Default loading rule:
- Load at most one reference by default.
- Load a second reference only when the task clearly spans multiple independent decision pressures, such as uncertain entry readiness plus closing handoff, or required artifact shaping plus conditional artifact triggers.
- Do not load the full `references/` directory by default.
- Check repo-local authority first: `AGENTS.md`, `docs/spec-first-workflow.md`, task-local workflow files, reviewed `spec.md`, specification-review result, and `docs/repo-architecture.md` when triggered.
- Do not copy examples blindly; bind them to the current task's phase, artifacts, blockers, and approved decisions.
- If a reference exposes a missing decision, route back to `specification`. If it exposes missing execution sequencing, record it for the technical-design-review handoff instead of writing `tasks.md`.

Routing table:

| Reference | Load When The Symptom Is | Behavior Change |
| --- | --- | --- |
| [references/technical-design-entry-readiness.md](references/technical-design-entry-readiness.md) | `spec.md`, current phase, allowed writes, or user-requested phase mixing is unclear before design-checkpoint writes. | Blocks, reopens, or narrows the write surface instead of starting design from a draft spec, chat momentum, or an obvious implementation path. |
| [references/repo-architecture-loading-rules.md](references/repo-architecture-loading-rules.md) | Repository boundaries, runtime flow, ownership seams, new packages, dependency direction, generated contracts, async work, data flow, or bootstrap/app/infra edges are in scope. | Loads or cites `docs/repo-architecture.md` before boundary decisions instead of relying on memory or treating generated/runtime surfaces as authority. |
| [references/required-design-artifact-examples.md](references/required-design-artifact-examples.md) | The core design bundle needs creation, repair, or boundary cleanup across overview, component map, sequence, or ownership map. | Splits task-local technical context into the four required artifacts instead of writing one design dump or hiding design content in workflow files. |
| [references/conditional-design-artifact-triggers.md](references/conditional-design-artifact-triggers.md) | Optional design artifacts, `test-design`, or `rollout.md` might be needed, or an existing conditional artifact looks like filler. | Creates only artifacts or phase triggers with real pressure and records `not expected` otherwise instead of creating all optional files or skipping planning-critical context. |
| [references/workflow-plan-technical-design-updates.md](references/workflow-plan-technical-design-updates.md) | Workflow-control files need design artifact status, blocker, repair, reopen, session-boundary, or next-session updates. | Records master and phase-local routing state instead of leaving state in chat, duplicating design content, or letting workflow files disagree. |
| [references/planning-handoff-and-stop-rules.md](references/planning-handoff-and-stop-rules.md) | Technical design is being closed, marked review-ready, blocked, or pressured to continue into review, test design, planning, or implementation. | Hands off to the mandatory technical-design-review stage or reopen target instead of drafting `test-plan.md`, `tasks.md`, code, tests, migrations, generated files, or review output. |

## Allowed Writes
This session may write or update only:
- task-local `design/overview.md`
- task-local `design/system-integration.md`
- task-local `design/go-code-ownership.md`
- task-local `design/component-map.md`
- task-local `design/sequence.md`
- task-local `design/ownership-map.md`
- task-local `design/overview.md` as the only design artifact when lean-local design context needs one file
- task-local conditional design artifacts when triggered:
  - `design/data-model.md`
  - `design/dependency-graph.md`
  - `design/contracts/`
- task-local `rollout.md` when migration, backfill/verify choreography, mixed-version compatibility, or failback notes are planning-critical
- task-local `workflow-plan.md`
- task-local `workflow-plans/system-integration-design.md`
- task-local `workflow-plans/go-code-ownership-design.md`
- the `design/`, `design/contracts/`, or `workflow-plans/` directories only when they must be created to hold those artifacts

## Prohibited Actions
Do not:
- reopen problem framing casually or rewrite approved scope just because design is hard
- rewrite `spec.md` instead of escalating back to `specification`
- write `tasks.md`
- start technical design review, test design, implementation, tests, migrations, contract generation, or post-code review execution
- use planning or implementation skills as a backdoor into later phases
- let design phase-control files become a second design bundle or second `tasks.md`
- treat `design/contracts/` as a runtime source of truth; it is design-only task context and canonical runtime sources still win
- create placeholder design files "just in case" when their trigger is not real

## Core Defaults
- this is an orchestrator-facing wrapper, not a replacement for specialist design skills
- `AGENTS.md` owns the workflow contract; `docs/spec-first-workflow.md` is the router; design phase docs own artifact mechanics
- `spec.md` owns final decisions, lean `Compact Design` or triggered `design/` owns task-local technical context, and `tasks.md` comes later in a different session
- separate design depth proceeds through `system-integration-design` before `go-code-ownership-design`; the latter consumes the system decision and must reopen system design or specification if code placement would change observable behavior
- use `go-design-spec` as the deeper design-integrity method when you need integration, contradiction cleanup, or simplification beyond simple artifact upkeep
- for non-trivial work, this session ends at a completed or explicitly blocked active design checkpoint; technical design review begins only after all triggered design checkpoints are complete or explicitly not expected, and test design begins only after technical design review permits it
- for non-trivial triggered technical design, first identify independent planning-critical questions for the active checkpoint and run or record narrow read-only specialist fan-out before the integrated design pass
- for `system-integration-design`, treat REST/API, OpenAPI/generated, event payload, webhook/callback, or material internal-interface changes as a contract-design trigger decision: create `design/contracts/`, record compact contract design as sufficient, record `not expected` with trigger evidence, or block/reopen. The decision must close caller/audience, selected shape, status/error semantics, retry/idempotency/concurrency, async/freshness/consistency when relevant, compatibility, runtime source, generated outputs, proof, and reopen trigger. Use an API/contracts lane with `api-contract-designer-spec` for client-visible REST/OpenAPI behavior unless an eligible local-only rationale closes that lens.
- review-ready handoff is invalid unless the active workflow surface records checkpoint-scoped `Design fan-out: complete | scoped_down | local_only | blocked` with lane summaries, candidate-lane analysis, or blocker state
- if design specialist fan-out is skipped, record `Design fan-out rationale:` in the active design phase-control file with the reason no independent lane would materially improve correctness
- Missing explicit subagent authorization is not a valid `Design fan-out rationale:`. If required design lanes are blocked only because the current prompt lacks explicit subagent/delegation authorization, record `Design fan-out: blocked` and return a next-session prompt with `Subagent authorization:`.
- a single integrated local design pass is eligible only when the reviewed `spec.md` is stable, the current decision frontier has one primary design question, no adjacent domain has an unresolved live fork, and API/data/security/reliability/observability/QA effects can be recorded as `constraint_only`, `proof_only`, `follow_up_only`, or `no new decision required` without changing ownership, contracts, persistence, failure semantics, validation, or rollout
- for `system-integration-design`, compact or local design is eligible only when the selected or preserved system mechanisms, source-of-truth owners, rejected live alternatives, proof carriers, and reopen triggers are explicit enough for Go code ownership design to proceed without inventing system behavior
- Go code ownership design may stay local only when owner package/file placement, responsibility boundaries,

…

## 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-technical-design-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%.