# Tech Design Generation

> >

- **Type:** Skill
- **Install:** `agentstack add skill-tercel-spec-forge-tech-design-generation`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tercel](https://agentstack.voostack.com/s/tercel)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tercel](https://github.com/tercel)
- **Source:** https://github.com/tercel/spec-forge/tree/main/skills/tech-design-generation

## Install

```sh
agentstack add skill-tercel-spec-forge-tech-design-generation
```

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

## About

# Tech Design Generation Skill

## What Is a Technical Design Document?

A Technical Design Document (TDD) is the engineering blueprint that translates product requirements into a concrete, implementable architecture. It sits between the Software Requirements Specification (SRS) and the actual code, serving as the contract between the engineering team and the rest of the organization about how a system will be built. A well-crafted TDD reduces implementation risk, surfaces architectural trade-offs early, and provides a lasting record of why specific technical decisions were made.

The Google Design Doc tradition emphasizes that design documents are not just about documenting a decision after the fact -- they are a tool for thinking through a problem rigorously before committing to code. The RFC (Request for Comments) tradition adds the dimension of structured peer review, ensuring that designs benefit from collective expertise. Uber and Meta engineering standards contribute a focus on scalability, operational readiness, and production-grade thinking from day one.

This skill combines all three traditions. Every generated Technical Design Document presents at least two alternative solutions, evaluates them against explicit criteria, and documents the rationale behind the chosen approach. The document covers architecture, API design, data modeling, security, performance, observability, and deployment -- everything an engineering team needs to move from design to implementation with confidence.

## Seven-Step Workflow

Every Technical Design Document generated by this skill follows a disciplined seven-step process. Each step must be completed before moving to the next.

> **Sub-agent boundary**: Steps 1-3 are performed by the orchestrator (`commands/tech-design.md`) in the main context. Steps 4-7 are performed by a generation sub-agent (`Task(subagent_type="general-purpose")`) that reads `references/generation-instructions.md`, `references/template.md`, and `references/checklist.md` directly. The sub-agent operates in an isolated context and receives a structured prompt with all Step 1-3 outputs.

### Step 1 -- Deep Scan Codebase

Before writing anything, perform a thorough scan of the current project to build deep technical understanding.

@../shared/project-context.md

Execute the full Project Context Protocol (PC.1 through PC.6):

1. **PC.1 Project Discovery** — project structure, README, existing docs
2. **PC.2 Tech Stack Detection** — language, framework, database, test framework, CI/CD
3. **PC.3 Project Profile** — Web API, CLI, Frontend, AI Agent, etc.
4. **PC.4 Architecture Awareness** — module boundaries, architectural pattern (MVC, layered, clean, microservices), dependency direction, key abstractions (interfaces, traits)
5. **PC.5 Existing Test Infrastructure** — test framework, coverage assessment

Additionally:
6. **Identify infrastructure patterns** by scanning for Kubernetes manifests, Terraform files, CloudFormation templates, or serverless configuration.
7. **Scan for ADRs** (Architecture Decision Records) in `docs/adr/` or `docs/decisions/` — existing decisions constrain the design.

This scanning ensures the generated design document is grounded in the real architecture. The detected project profile and architecture pattern inform which design sections need the most depth (e.g., a microservices project needs API contract design; a monolith needs module boundary design).

### Step 1.5 -- Doc-First Discipline (Mandatory)

Before locating upstream documents or writing any design content, the doc-first discipline applies. Read the existing documentation, identify what already covers the architecture, components, decisions, or interfaces, and decide for each section whether to **REUSE** (reference existing), **EXTEND** (edit existing in place), or **NEW** (genuinely missing). The default for any topic that already has coverage in an existing tech-design or ADR is to extend in place — never to create parallel `tech-design-v2.md` files, never to append `## Update` blocks, never to leave superseded ADRs strikethrough'd inside the active doc.

The full discipline, the four rules, the pre-generation checklist, and the anti-patterns to avoid:

@../shared/doc-first.md

**You MUST run the pre-generation checklist (the five questions) from doc-first.md before proceeding to Step 2.** If existing docs already cover any of the topics this tech design will discuss, you must:

1. List the existing files and sections that overlap (with `file:line` references) — this includes ADRs in `docs/adr/` or `docs/decisions/`
2. Decide REUSE / EXTEND / NEW for each section (architecture, API design, data model, security, deployment)
3. Bias toward EXTEND — opening the existing tech-design and modifying it — over NEW
4. **Respect ADR immutability.** ADRs are decision records: an old decision is not deleted when superseded. Instead, the old ADR is marked `Status: Superseded by ADR-NNN` and a new ADR is added that references it. This is the *only* exception to the no-strikethrough rule, because ADRs are explicitly historical artifacts.
5. Identify which existing component names, interface contracts, and module boundaries must remain stable to preserve compatibility with code and downstream specs
6. Surface any downstream documents (feature specs, test-cases, README) this generation will affect

If the project shows signs of doc drift (multiple `tech-design-*.md` files, contradictory architecture diagrams in different docs, obvious duplication), warn the user before proceeding and recommend they run `/spec-forge:analyze` or `/spec-forge:propagate` first.

If a usable existing tech-design already covers most of what the user is asking for, the right action is **edit it in place**, not generate a new file.

---

### Step 2 -- Find Upstream Documents

Search for matching upstream documents that feed into this design. Determine the operating mode:

- **Upstream mode**: PRD and/or SRS found → design will trace to formal requirement IDs. If BOTH an idea draft and a PRD exist, the PRD takes precedence as the source of truth (it is a formalized version of the idea). Read the idea draft only for supplementary context that the PRD may not cover.
- **Idea-first mode**: Idea draft found at `ideas//draft.md`, no PRD/SRS → §3.5 User Scenarios, §3.6 Acceptance Criteria, and §3.7 Success Metrics are derived from the idea draft's problem statement, MVP scope, and demand validation results. If the idea draft scenarios are vague or generic, ask clarifying questions to make them concrete enough for §3.5.
- **Standalone mode**: No upstream documents → these sections are populated from user clarification answers

**Upstream mode search:**
1. **Search for PRD files** matching `docs/*/prd.md` related to the feature being designed. Read all found PRD documents to extract product goals, user stories, and success metrics.
2. **Search for SRS files** matching `docs/*/srs.md` related to the feature. Read all found SRS documents to extract functional requirements (FR-XXX-NNN), non-functional requirements (NFR-XXX-NNN), data models, and interface definitions.
3. **Summarize upstream context** including the requirement IDs that this design must address.

If no PRD/SRS found, check for idea draft at `ideas//draft.md`.

### Step 3 -- Clarify Questions

Present the user with targeted clarifying questions. These questions fill gaps that cannot be inferred from the codebase or upstream documents. Typical areas include:

- Architecture preference and any mandated patterns to follow.
- Technical constraints or forbidden technology choices.
- Performance targets for latency, throughput, and scalability.
- Data strategy including new databases, tables, or migration needs.
- Integration points with external services, APIs, or message queues.
- Security requirements including authentication method and data sensitivity.
- Deployment strategy including cloud provider, orchestration, and environment topology.
- Timeline constraints that might affect technical decisions.
- **Agent consumers**: Are there programmatic consumers for this system (API clients, automation tools, other services integrating programmatically)? If yes, describe their integration patterns (REST API, async events, webhooks, SDK) and key workflows. Agent-facing systems need explicit API contracts, machine-verifiable response schemas, and structured error codes designed for programmatic consumption — not just human-friendly error messages.

Do not proceed to generation until the user has answered enough questions to inform the core design sections.

### Step 4 -- Generate Design

Using the template at `references/template.md`, generate the complete Technical Design Document. Key requirements for this step:

- Present at least two alternative solutions with a structured comparison matrix.
- Recommend one solution and provide explicit rationale for the decision.
- Use Mermaid syntax for all diagrams following the C4 model levels.
- Design APIs with complete endpoint specifications, request/response schemas, and error codes.
- Define database schemas with ER diagrams, index strategies, and migration plans.
- Address security as a first-class concern with authentication, authorization, encryption, and audit logging.
- Set specific, measurable performance targets with caching and optimization strategies.
- Plan observability with logging, monitoring, and alerting.
- Define deployment strategy with environments, CI/CD pipeline, and rollback procedures.

### Step 5 -- Traceability

If upstream documents (PRD and SRS) were found:

- Map each SRS functional requirement to the technical components that implement it.
- Map each SRS non-functional requirement to the architecture decisions that satisfy it.
- Verify that all FR and NFR items from the SRS are addressed somewhere in the design.
- Document any requirements that are intentionally deferred with justification.

This traceability ensures no requirements fall through the cracks between specification and design.

### Step 6 -- Quality Check

Validate the completed tech-design document AND all generated feature specs in `docs/features/` against every item in `references/checklist.md`. Fix any issues before presenting the final document to the user. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped with justification.

### Step 7 -- Feature Spec Generation

After the main Technical Design Document passes the quality check, automatically generate individual feature specs for each component identified in Section 8 (Detailed Design). The tech-design produces both the architecture document and the implementation-ready feature specs in a single pass.

#### 7.1 Identify Components

Extract all components from the Component Overview table in §8.1. Each row in the table becomes one feature spec file.

#### 7.2 Generate Feature Specs

For each component, create a feature spec at `docs/features/{component-name}.md` using the template below. The feature spec contains the **implementation-level detail** that was traditionally written in §8 of the tech-design — method signatures, logic steps, field mappings, state machines, and error handling specifics.

**Feature Spec Template:**

> **No numbering**: Feature spec titles and filenames use the component slug only (e.g., `auth-service.md`, NOT `01-auth-service.md` or `F-01 Auth Service`). Do NOT prefix titles with numbers, IDs, or order indicators. Execution order is defined exclusively in `docs/features/overview.md`.

```markdown
# {Component Name}

> Feature spec for code-forge implementation planning.
> Source: extracted from docs/{project}/tech-design.md §8
> Created: {date}

| Field | Value |
|-------|-------|
| Component | {component-slug} (same as filename without `.md`) |
| Priority | {P0 / P1 / P2, derived from requirement priorities} |
| SRS Refs | {mapped from traceability matrix, e.g., FR-XXX-001..005} |
| Tech Design | §8.1 — {component row reference} |
| Depends On | {component slugs this depends on, or "—" if none} |
| Blocks | {component slugs this blocks, or "—" if none} |

## Purpose

{One paragraph describing what this component does and why it exists. Derived from the Component Overview table.}

## Scope

**Included:**
- {responsibility 1}
- {responsibility 2}

**Excluded:**
- {explicitly out of scope}

## Core Responsibilities

1. **{Responsibility name}** — {brief description}
2. ...

## Interfaces

### Inputs
- **{input name}** ({source}) — {description}

### Outputs
- **{output name}** ({destination}) — {description}

### Dependencies
- **{module/system name}** — {what it provides}

## Data Flow

{Mermaid diagram if 3+ steps}

## Key Behaviors

{Implementation-level detail: method signatures, logic steps, field mapping tables, state machines, algorithms. This is where the depth of the traditional §8 detailed design lives.}

### {Behavior 1}
{Detailed description with logic steps, code signatures, data structure transformations}

### {Behavior 2}
{Detailed description}

## Constraints

- **{constraint type}**: {description}

## Acceptance Criteria

[Map back to AC-IDs from tech-design §3.6 where applicable. Add component-specific criteria not covered at the feature level.]

> **This table is the acceptance standard.** When no SRS or test-cases document exists, `code-forge:review`'s Acceptance Gate reconciles every **P0/P1** row here against a named passing test and hard-blocks merge on any P0 row with no passing test. Therefore every row must be (a) a single mechanically-testable condition with a concrete Expected Result, (b) tagged with a Priority, and (c) the set must cover — for every P0 behavior — not just the happy path but its boundary, error, and negative conditions. A happy-path-only AC set is the #1 cause of "passes review but is only a demo" and is rejected by the Step 6 quality check.

| AC-ID | Priority | Criterion | Expected Result | Verification Method |
|-------|----------|-----------|-----------------|---------------------|
| AC-{nnn} | P0 | {Given … When … — a single testable happy-path condition} | {Exact observable outcome: return value / status code / persisted state} | {Unit / Integration / E2E — name what to call and what to assert} |
| AC-{nnn} | P0 | {boundary or error condition for the SAME behavior — invalid input, limit exceeded, missing precondition} | {Specific rejection / error code / message — never "fails"} | {…} |
| AC-{nnn} | P1 | {negative — what must NOT happen for this component} | {Behavior that should NOT occur is absent} | {…} |

## Error Handling

{Component-specific error handling: which exceptions, error codes, sanitization rules}

## File Structure

```
{src-root}/
└── {module-path}/
    ├── {component-name}.{ext}        # Main implementation
    ├── {component-name}.test.{ext}   # Unit tests (co-located)
    └── {sub-module}/
        └── {file}.{ext}              # Sub-module files if applicable
```

{Use the actual project source root (e.g., `src/`, `lib/`, `app/`), the actual file extension, and the actual module path. Do NOT write a placeholder — look at the project structure and derive the real path.}

## Test Module

**Test file**: `{exact/path/to/component-name.test.ext}`

**Test scope**:
- **Unit**: {Specific functions/methods to unit test, e.g., `processPayment()`, `validateCard()`}
- **Integration**: {Integration points to test: API endpoints, DB operations, external services}
- **Fixtures / Mocks**: {What to mock or set up, e.g., "mock Stripe client", "seed user with active subscription"}
```

#### 7.3 Generate Overview

Create or update `docs/features/overview.md`:

```markdown
# Feature Overview

> Auto-generated from tech-design. See docs/{project}/tech-design.md for architecture context.
> Updated: {date}

## Features

| # | Feature | Description | Dependencies | Priority | Status |
|---|---------|-------------|--------------|----------|--------|
| 1 | [{name}](./{na

…

## Source & license

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

- **Author:** [tercel](https://github.com/tercel)
- **Source:** [tercel/spec-forge](https://github.com/tercel/spec-forge)
- **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-tercel-spec-forge-tech-design-generation
- Seller: https://agentstack.voostack.com/s/tercel
- 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%.