Technical Design Session

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
• Source: Dankosik/go-service-template-rest
• License: MIT

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