# Deep Design

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-npow-claude-skills-deep-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [npow](https://agentstack.voostack.com/s/npow)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [npow](https://github.com/npow)
- **Source:** https://github.com/npow/claude-skills/tree/main/deep-design

## Install

```sh
agentstack add skill-npow-claude-skills-deep-design
```

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

## About

# Deep Design Skill

## When to use deep-design vs --spec mode

- **deep-design** (default): Multi-agent adversarial workflow — stress-tests designs with parallel critics. Use for complex systems. Outputs battle-tested design doc.
- **deep-design --spec**: Single-session lightweight spec writer. Outputs SDD-compatible `spec.md` with User Scenarios & Testing (prioritized P1/P2/P3), Functional Requirements (FR-###), Success Criteria (SC-###), Key Entities, Assumptions, and Edge Cases. Creates `specs/{NNN-feature}/spec.md` and `checklists/requirements.md`. Ready for `deep-plan` to consume.

Adversarially stress-test a design. Given a concept, validate input, draft a spec, attack it with parallel critic agents across orthogonal dimensions, fix discovered flaws using independent judge agents, and repeat until coverage is saturated. Output is a battle-tested design document with an honest coverage report.

## Execution Model

All operations use Claude Code primitives. The following contracts are non-negotiable:

- **All data passed to agents via files, never inline.** Spec content, dedup lists, angle definitions, fact sheets — all written to disk before the agent prompt. Inline data is silently truncated.
- **State written before agent spawn, not after.** `spawn_time_iso` is written to state.json before the Agent tool call. Spawn failure records `spawn_failed` status. Resume uses persisted state, never in-memory reconstruction.
- **Structured output is the contract; free-text is ignored.** Every judge and checker produces machine-parseable structured lines as the final lines of output. Coordinator reads only structured fields. Unparseable output triggers fail-safe classification (critical or conflict). Critic output files MUST contain `STRUCTURED_OUTPUT_START`/`STRUCTURED_OUTPUT_END` markers; files without these markers are treated as failed (not partially consumed).
- **No coordinator self-review of anything load-bearing.** Fact sheets, severity classifications, cross-fix checks, form-switch dedup, section-impact scores — all delegated to independent agents. The coordinator orchestrates; it does not evaluate.
- **Termination labels are honest.** "Conditions Met" or "Max Rounds Reached" — never "no critical flaws remain." Coverage fraction includes the denominator caveat. Unverified sections are listed explicitly.
- **Coverage completeness is a hard invariant — not a judgment call.** All 5 required dimension categories (correctness, usability_ux, economics_cost, operability, security_trust) MUST have `explored_count >= 1` before any run (in-session or sagaflow) can proceed to final synthesis. If a category has zero explored angles, the coordinator MUST spawn critics targeting that category — not skip it, not label it "out of scope," not cite context constraints. "Context is running low" is NOT a valid reason to skip required categories; the coordinator MUST either (a) use sagaflow durable execution to avoid context limits, (b) run coverage extension rounds, or (c) label the run `INCOMPLETE — uncovered: {list}` and refuse to present it as finished work. A run that declares completion while listing known uncovered categories is a protocol violation, not a judgment call.

**Shared contracts:** this skill inherits the six execution-model contracts (files-not-inline, state-before-agent-spawn, structured-output, independence-invariant, coverage-completeness, sagaflow-first-routing) from [`_shared/execution-model-contracts.md`](../_shared/execution-model-contracts.md). The items listed above are the skill-specific elaborations; the shared file is authoritative for the base contracts.

**Cross-finding coherence:** this skill applies the coherence-integrator pattern from [`_shared/cross-finding-coherence.md`](../_shared/cross-finding-coherence.md) at Step 5, after all critics complete and BEFORE severity judges are spawned. The integrator reads all deduped critic output files simultaneously and annotates each flaw with cross-finding relationships (contradictions, emergent patterns, coverage gaps). These annotations are included in judge input files so judges see the cross-finding context when classifying severity.

**Subagent watchdog:** every `run_in_background=true` spawn (parallel critics, severity judges, rebuttal agents) MUST be armed with a staleness monitor per [`_shared/subagent-watchdog.md`](../_shared/subagent-watchdog.md). Use Flavor A with thresholds `STALE=5 min`, `HUNG=20 min` for Sonnet critics; `STALE=3 min`, `HUNG=10 min` for Haiku judges. `TaskOutput` status is not evidence of progress — output-file mtime is. Contract inheritance: `timed_out_heartbeat` joins this skill's per-angle termination vocabulary; `stalled_watchdog` / `hung_killed` join `angles.{id}.status`. A watchdog-killed critique angle is reported as coverage-lost in the final coverage fraction — never silently dropped.

## Philosophy

Good design survives adversarial scrutiny. This skill treats design as a **generate-then-break** loop: draft a design, attack it from every angle, fix the flaws, then attack again. Each critic agent is an expert in one dimension (balance, UX, edge cases, narrative, technical feasibility, etc.) trying to find holes. Flaws discovered in one round feed redesign in the next.

## Workflow

### Step 0: Input Validation Gate

Before any work begins, validate the concept. **Batch any clarifying questions** — if multiple questions surface in this step (concept rubric ambiguity, core-claim confirmation, alternatives selection), present ALL of them as a single numbered batch in one message. Never serially. The user answers once, then Step 1 begins.

**Concept rubric** — reject if any of these apply:
- Too vague to critique ("make a good app") — request specificity
- Already fully specified (more of an implementation request than a design) — offer to run critique-only mode
- Requests harmful design (weapon, exploit, manipulation system) — decline

**Core claim extraction:**
1. Read the concept and extract a 1-2 sentence core claim: the specific thing this design does that similar designs do not
2. Run the **specificity test**: "Would this claim be true of a system that does [X] instead of [Y]?"
   - Select **2 domain-adjacent alternatives** in the same problem class as the concept but with different primary mechanisms
   - For `deep-design`, valid alternatives: collaborative (not adversarial) review, single-pass critique, sequential-agent critique
   - The claim must **fail** to apply to both alternatives before passing the specificity test
   - If interactive mode: show user the claim + 2 alternatives, ask for confirmation
   - If claim passes: set `core_claim_calibrated: true`, store `core_claim` and `core_claim_sha256` in state.json
   - If claim fails after 2 attempts: set `core_claim_calibrated: false`; Layer 2 drift checks run in **degraded mode** (tighter threshold + DRIFT_CHECK_DEGRADED tag) — do NOT skip them

**Concept summary field:** The concept summary sent to all critics is the core claim text verbatim as extracted and locked at this step. The coordinator may append context but cannot replace or paraphrase the locked text.

**Print:** `Starting deep design on: {concept} [run: {run_id}]`

### Step 1: Initialize

- Generate run ID: `$(date +%Y%m%d-%H%M%S)` — e.g., `20260314-153022`
- Create directory structure:
  - `deep-design-{run_id}/state.json` — run state (see STATE.md for schema)
  - `deep-design-{run_id}/critiques/` — one file per critique angle
  - `deep-design-{run_id}/specs/` — versioned spec files
  - `deep-design-{run_id}/logs/` — `frontier_pop_log.jsonl` and `coverage_gaps.jsonl`
  - `deep-design-{run_id}/spec.md` — final output (written at Step 8)
- Write initial state.json with `core_claim`, `core_claim_sha256`, `core_claim_calibrated` from Step 0
- The spec template must include `CORE_MECHANISM_START` / `CORE_MECHANISM_END` delimiters enclosing the section describing the core mechanism. These delimiters are the reference boundary for Layer 1 drift comparison and must not be removed or moved by any agent.

### Step 2: Initial Design Draft

- Analyze the concept to understand core intent, target audience, and constraints
- Write `deep-design-{run_id}/specs/v0-initial.md` — a structured first-pass design covering:
  - Core concept & elevator pitch
  - Key mechanics/features
  - User/player flow
  - High-level technical approach
  - Known open questions
- This is deliberately a FAST draft — good enough to critique, not polished

### Step 3: Dimension Discovery (see DFS.md Phase 3a-3c)

- Enumerate CRITIQUE DIMENSIONS using the design-specific framework
- Required dimension categories (at least one angle per category must be explored):
  - **correctness** — does the design work as claimed?
  - **usability/UX** — can users actually use it?
  - **economics/cost** — is it affordable/sustainable?
  - **operability** — can it be operated/maintained?
  - **security/trust** — can it be abused or corrupted?
- Generate 2-4 critique angles per dimension; cap frontier at 40 angles total
- Depth-diversity rule: when displacing to stay under cap, cannot displace a dimension's only remaining depth-0 OR depth-1 angle
- **Each angle definition written to state.json at discovery time with:** `{angle_id, dimension, question, discovery_source: "coordinator_initial|critic_suggested", discovery_round, rationale}`. Angle definitions are immutable once written.
- **Frontier pop decisions logged** in `deep-design-{run_id}/logs/frontier_pop_log.jsonl`: `{angle_id, round, timestamp, score, reason}`
- **Stability trigger:** "no new DIMENSION CATEGORIES for 2 consecutive rounds" (not merely "no new angles")
- Build exhaustion map; populate frontier with all critique angles, priority-ordered
- Write state file

### Step 4: Critique Round

**Prospective gate (fires BEFORE spawning critics):**

The coordinator outputs a gate summary and STOPS. The user continues the conversation to proceed. This is the standard Claude Code turn-boundary interaction model — there is no blocking `[y/N]` prompt.

Gate content:
> Round {N+1}: up to {agents} agent calls × ~{token_estimate}k tokens/agent = structural bound ~${bound}. Spent so far: ~${cumulative}. Projected total to max_rounds: ~${projection}.

Projection includes: 6 spec-derived critics + 1 outside-frame critic + (estimated flaws × 2 judge calls) + 1 redesign agent (estimated at 3× critic cost) + 1 invariant-validation agent, with spec growth factor.

If any flaw is in `pending_user_acknowledgment` state, the gate prominently displays the proposed tension and requests explicit acknowledgment before proceeding.

User options at gate: continue the conversation (proceed), stop (triggers final synthesis), or redirect focus via message.

Stall handling: if no user response at a gate for 2 or more consecutive turns, the run auto-proceeds to final synthesis (not continuation).

**Autonomous mode:** Gate is skipped. `max_rounds` defaults to 3. Hard budget cap = $10 total. If budget is exceeded mid-round, that round completes, then the run terminates. CORE_TENSION flaws remain in `pending_user_acknowledgment` state in the final spec and cannot be silently reclassified.

**Spawn critics:**
- Pop up to 6 (`max_agents_per_round`) highest-priority critique angles from frontier using the declared scoring function. Selection policy is explicit and auditable via `logs/frontier_pop_log.jsonl`.
- **Also spawn 1 outside-frame critic (slot #7)** seeded from the original concept description ONLY (not the current spec). See "Outside-Frame Critic Prompt Template" section below.
- **Concept summary field sent to all critics = core claim text verbatim** (locked, not paraphrased). Coordinator may append context but cannot replace or paraphrase the locked text.
- Write all required data to files before spawning: latest spec, known-flaw-titles file (with flaw IDs), angle definitions
- For each angle, write angle to state.json with `spawn_time_iso` set **before** calling Agent tool
- Spawn background Agent (subagent_type: general-purpose) with file paths — not inline content
- Critic output files are content-addressed at `critiques/{angle_id}-{critic_agent_id}.md` — coordinator CANNOT overwrite these files
- If Agent tool returns an error (tool limit, spawn refused): record `status: "spawn_failed"`, `spawn_time_iso: null` in state.json; do NOT record as "spawned"; resume retries spawn

**Quorum:** Round complete if ≥ 4 of 6 spec-derived critics return parseable output within timeout. Outside-frame critic is tracked separately and does not affect quorum denominator.

**Timeout scaling:** 120s base; 180s for rounds 3+; ×1.5 for specs exceeding 3,000 words.

**Output integrity:** Critic output files MUST contain `STRUCTURED_OUTPUT_START`/`STRUCTURED_OUTPUT_END` markers. Files without these markers are treated as failed (not partially consumed).

**Circuit breaker:** If ≥ 3 consecutive rounds have any critic failures, halt immediately, log `SYSTEM_FAILURE_ROUND`, notify user at turn boundary, allow retry or abort.

**After completion:**
- For each completed agent: read critique file, extract flaws, new angles, dedup, update state
- **Spec-derived critics may suggest at most 1 new angle per round** (not 1-3). New angles are logged with `discovery_source: "critic_suggested"` and are immutable once written.
- **Severity classification delegated to independent judge agent** — coordinator does not classify; unparseable judge output → fail-safe critical
- **Section-impact scores assigned by independent agent** — not coordinator; prevents self-serving deflation of foundational section scores
- **Form-switch dedup check performed by consistency checker** — not coordinator
- Run coverage evaluation: identify uncritiqued dimensions, generate new angles if needed
- Update running synthesis
- Increment round

### Step 5: Synthesis with Independent Judges

For each round's flaws before redesign:

**Fact sheet agent (independent):**
- Spawn a fact-sheet agent that reads the current spec and produces structured output:
  ```
  RECOVERY_BEHAVIORS: [{"component": "", "behavior": ""}, ...]
  ```
  This must be the **final structured line** of the agent's output. Coordinator reads ONLY this line; unparseable = empty list (not coordinator fallback text).
- When evaluating `RECOVERY_MECHANISM_CITED` in judge output: the component field must appear in the RECOVERY_BEHAVIORS list. Names not in the list are treated as hallucinated → `mechanism_applies: false`.

**Cross-finding coherence integrator (fires after critics complete, before severity judges):**

Per [`_shared/cross-finding-coherence.md`](../_shared/cross-finding-coherence.md):

1. Collect all parseable critic output files from this round (post-dedup).
2. Write integrator input manifest to `deep-design-{run_id}/coherence/round-{N}-input.md`.
3. Spawn Sonnet coherence-integrator agent. Output: `deep-design-{run_id}/coherence/round-{N}-coherence.md`. Timeout: 120s.
4. Parse structured annotations. Attach `FINDING|{id}|{annotation}` to each flaw in state.json as `flaws.{id}.coherence_annotation`.
5. Feed `GAP` lines into frontier as CRITICAL-priority angles for the next round.
6. Store `PATTERN` lines in `state.json.emergent_patterns[]` for Step 8 final spec.
7. If unparseable/timed out: proceed in degraded mode (judges run without annotations). Log `COHERENCE_DEGRADED`.

**Severity judge (independent) — two-pass blind severity protocol:**
1. The coordinator strips the `SEVERITY_CLAIM` block from the raw critic file to produce `judge_input/{flaw_id}.md`. The original critic file remains immutable. The stripping is recorded in state.json as `judge_input_stripped: true`.
2. A judge agent receives: `{flaw_id, judge_input_file_path, fact_sheet_path, coherence_annotation}` — a strict schema enforced by a validator before spawn. The coherence_annotation (from the integrator) gives the judge cross-finding context: PATTERN_MEMBER suggests aggregate severity consideration; CONTRA

…

## Source & license

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

- **Author:** [npow](https://github.com/npow)
- **Source:** [npow/claude-skills](https://github.com/npow/claude-skills)
- **License:** Apache-2.0

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:** yes
- **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-npow-claude-skills-deep-design
- Seller: https://agentstack.voostack.com/s/npow
- 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%.