nw-design
Establishes durable architecture, reuse, boundaries, cross-layer algebra, residual stress behavior, paradigm, and prefactoring decisions for deterministic minimal handover construction.
Install / Use
npx skills add nWave-ai/nWave --skill nw-designInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of nw-design
nw-design scores 88/100 on our quality scale, 2007th of 4,702 Development & Engineering skills we index (top 43%).
Its SKILL.md is 21 KB long, well organised into 29 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
It has 617 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so nw-design is actively maintained.
- Our last check on 2026-11-01 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
nw-design compared with similar skills
All 4 of these similar skills score higher than nw-design; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| nw-design (this skill)by nWave-ai | 88 | 617 | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.3k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.4k | 3d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.9k | 8d ago | CLAUDE.md |
Frequently asked questions
- How do I install nw-design?
- Run
npx skills add nWave-ai/nWave --skill nw-design. The install tabs above show the steps for each supported agent. - Which AI agents does nw-design work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is nw-design safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is nw-design still maintained?
- The repository was last updated about 2 months ago, so nw-design is actively maintained.
Skill content
View source on GitHubname: nw-design description: "Designs system architecture with C4 diagrams and technology selection. Routes to the right architect based on design scope (system, domain, application, or full stack). Two interaction modes: guide (collaborative Q&A) or propose (architect presents options with trade-offs)." user-invocable: true argument-hint: '[component-name] - Optional: --residuality --paradigm=[auto|oop|fp]'
NW-DESIGN: Architecture Design
Wave: DESIGN (wave 3 of 6) | Agents: Morgan (nw-solution-architect), nw-system-designer, nw-ddd-architect | Command: *design-architecture
Overview
Execute DESIGN wave through discovery-driven architecture design. The command starts with two interactive decisions:
- Design Scope — routes to the right architect: system-level (@nw-system-designer), domain-level (@nw-ddd-architect), application-level (@nw-solution-architect), or full stack (all three in sequence).
- Interaction Mode — guide (architect asks questions, you decide together) or propose (architect reads requirements, presents 2-3 options with trade-offs).
All architects write to docs/product/architecture/brief.md (SSOT), each in its own section. Analyzes existing codebase, evaluates open-source alternatives, produces C4 diagrams (Mermaid) as mandatory output.
Output Tiers (per D2)
Provenance: feature lean-wave-documentation — D2 (schema-typed sections), D10 (one-line expansion descriptions). Tier-1 [REF] sections (always emitted) + Tier-2 EXPANSION CATALOG items (lazy, on-demand) are the two output bands. Full contract: nWave/skills/nw-density-resolution-contract/SKILL.md.
Tier-1 [REF] — always emitted
Under ## Wave: DESIGN / [REF] <Section> headings:
- DDD list — D-numbered design decisions with verdicts and one-line rationale
- Component decomposition — table of components with paths and change types
- Driving ports — inbound surfaces (CLI, skill, HTTP) named per the C4 contract
- Driven ports + adapters — outbound side-effects with adapter mapping
- Technology choices — pinned languages/frameworks/runtime versions
- Decisions table — DDD-N row per locked decision (no rationale prose)
- Reuse Analysis table — every overlapping component classified EXTEND or CREATE NEW
- Open questions — items deliberately deferred to DISTILL/DELIVER
Tier-2 EXPANSION CATALOG — lazy, on-demand (per D10)
Rendered under ## Wave: DESIGN / [WHY|HOW] <Section> only when requested via --expand <id> (DDD-2), the broad wave-end menu (expansion_prompt = "ask"), a declared trigger under expansion_prompt = "ask-intelligent", mode = "full" auto-expansion, or an ad-hoc user request mid-session.
| Expansion ID | Tier label | One-line description |
|---|---|---|
| trade-off-analysis | [WHY] | Quality-attribute trade-off matrix with prioritization rationale |
| rejected-alternatives | [WHY] | Architectures weighed and rejected with one-paragraph reason per option |
| c4-narrative | [HOW] | Long-form C4 walkthrough: System Context → Container → Component prose |
| evolution-scenarios | [WHY] | Hypothetical future stress vectors and how the design absorbs them |
| paradigm-rationale | [WHY] | Why FP/OOP was selected; comparison vs the alternative for this domain |
| reuse-analysis-deep-dive | [WHY] | Per-row justification for every EXTEND vs CREATE NEW decision in the Reuse table |
| c4-component-diagrams | [HOW] | Component-level C4 diagrams for complex subsystems (Mermaid) |
| expansion-catalog-rationale | [WHY] | Why this set of expansions, why these defaults, why D10 enforces one-line descriptions |
Density resolution (per D12)
Call resolve_density(global_config) from scripts/shared/density_config.py after reading ~/.nwave/global-config.json (missing/malformed = empty dict). Returns mode ("lean" | "full") + expansion_prompt ("ask" | "ask-intelligent" | "always-skip" | "always-expand" | "smart") per the D12 cascade (resolver-internal, DDD-5 — do NOT replicate locally). Branch on density.mode for what to emit; branch on density.expansion_prompt at wave end for menu behaviour. DESIGN declares no ask-intelligent triggers: emit no menu and the shared-contract no-trigger skip event; do not invent triggers. Full cascade detail, branch semantics, ad-hoc override workflow: nWave/skills/nw-density-resolution-contract/SKILL.md.
Telemetry (per D4 + DDD-6)
Every expansion choice emits a DocumentationDensityEvent (dataclass at src/des/domain/telemetry/documentation_density_event.py) via event.to_audit_event() → JsonlAuditLogWriter().log_event(...). Schema fields per D4: feature_id, wave, expansion_id, choice, timestamp. For this wave the schema declares "wave": "DESIGN". Use helper scripts/shared/telemetry.py:write_density_event(...) — do NOT write JSONL directly.
Wave-specific signal: DEVOPS/DISTILL consuming a lean DESIGN feature-delta — downstream --expand requests for trade-off or evolution scenarios indicate the [REF] baseline was insufficient. Full emission rules: nWave/skills/nw-density-resolution-contract/SKILL.md.
Prior Wave Consultation
Before beginning DESIGN work, read SSOT and prior wave artifacts in this order:
- Read SSOT architecture (if
docs/product/exists) — readdocs/product/architecture/brief.md(extend, not recreate),docs/product/architecture/adr-*.md(existing decisions),docs/product/journeys/{name}.yaml(journey schema for port identification). Gate: all existing files read or confirmed missing. - Read DISCUSS artifacts (primary input) — read from
docs/feature/{feature-id}/discuss/:wave-decisions.md(decision summary),user-stories.md(scope, requirements, acceptance criteria),story-map.md(walking skeleton and release slicing),outcome-kpis.md(quality attributes). Gate: all four files read or confirmed missing. - Read SPIKE findings (if spike was run) — read from
docs/feature/{feature-id}/spike/:findings.md(validated assumptions, performance measurements, what didn't work). This informs your architecture constraints. Gate: file read if present, marked as not found if absent. - Output confirmation checklist — after reading, output
✓ {file}for each read,⊘ {file} (not found)for each missing. Gate: checklist produced before any architecture work begins. - Check for contradictions — identify any DESIGN decisions that would contradict DISCUSS requirements or SPIKE findings. Flag contradictions and resolve with user before proceeding. Example: DISCUSS requires "real-time updates" but DESIGN chooses batch processing; or SPIKE found performance budget can't be met. Gate: zero unresolved contradictions.
- Migration gate check — if
docs/product/does not exist butdocs/feature/has existing features, STOP. Guide the user todocs/guides/migrating-to-ssot-model/README.md. If greenfield, proceed — DESIGN will bootstrapdocs/product/architecture/. Gate: migration status confirmed.
Note: DISCOVER evidence is already synthesized into DISCUSS — read DISCOVER only if wave-decisions.md flags something architecturally significant.
Document Update (Back-Propagation)
When DESIGN decisions change assumptions from prior waves:
- Document the change — add a
## Changed Assumptionssection at the end of the affected DESIGN artifact. Gate: section present in artifact. - Reference the original — quote the original assumption from the prior-wave document, with file path. Gate: original quoted verbatim with source.
- State the new assumption — write the replacement assumption and its rationale. Gate: new assumption and rationale present.
- Propagate upstream if needed — if architecture constraints require changes to user stories or acceptance criteria, write them to
docs/feature/{feature-id}/design/upstream-changes.mdfor the product owner to review. Gate: upstream-changes.md created if any story/criteria changes needed.
Discovery Flow
Architecture decisions are driven by quality attributes, not pattern shopping. Execute these steps in order:
-
Understand the Problem — review JTBD artifacts from DISCUSS. Ask: What are we building? For whom? Which quality attributes matter most? (scalability|maintainability|testability|time-to-market|fault tolerance|auditability). Gate: quality attribute priorities ranked.
-
Understand Constraints — ask: Team size/experience? Timeline? Existing systems to integrate? Regulatory requirements? Operational maturity (CI/CD, monitoring)? Gate: constraints list documented.
-
Map Team Structure (Conway's Law) — ask: How many teams? Communication patterns? Does proposed architecture match org chart? Gate: team-architecture alignment confirmed.
-
Select Development Paradigm — identify primary language(s) from constraints, then: FP-native (Haskell|F#|Scala|Clojure|Elixir) → recommend Functional; OOP-native (Java|C#|Go) → recommend OOP; Multi-paradigm (TypeScript|Kotlin|Python|Rust|Swift) → present both, let user choose. After confirmation, ask user permission to write paradigm to project CLAUDE.md: FP:
This project follows the **functional programming** paradigm. Use @nw-functional-software-crafter for implementation.OOP:This project follows the **object-oriented** paradigm. Use @nw-software-crafter for implementation.Default if user declines/unsure: OOP. Gate: paradigm selected and optionally written to CLAUDE.md. -
Reuse Analysis (MANDATORY — RCA F-1 fix) — before designing ANY new component, search the existing codebase for components with overlapping responsibilities. For each overlap, decide "extend existing" or "justify new". Output a table:
| Existing Component | File | Overlap | Decision | Justification | |-------------------|------|---------|----------|---------------| | WorkflowExecutor | src/des/application/zero_trust/workflow_executor.py | Phase iteration, gate eval | EXTEND | Adding dispatch branch is ~15 LOC vs 200 LOC new class |Rules:
- If the design creates a new class that does something an existing class already does (iterate phases, evaluate gates, dispatch agents, handle retry), the default is EXTEND, not CREATE NEW.
- CREATE NEW requires evidence that extending is impossible or creates unacceptable coupling (not just "it's complex").
- "The existing class has too many dependencies" is NOT a valid justification — simplify the existing class instead (see F-4: strategy pattern extraction).
- The reviewer MUST verify this table exists and challenge every "CREATE NEW" decision.
- Gate: Reuse Analysis table present with zero unjustified CREATE NEW decisions.
-
Recommend Architecture Based on Drivers — recommend based on quality attribute priorities|constraints|paradigm from steps 1-5. Default: modular monolith with dependency inversion (ports-and-adapters). Overrides require evidence. If functional paradigm: apply types-first design, composition pipelines, pure core / effect shell, effect boundaries as ports, immutable state — in architecture document only, no code snippets. Gate: architecture pattern selected with written rationale.
-
Stress Analysis (HIDDEN —
--residualityflag only) — when activated: apply complexity-science-based stress analysis (stressors|attractors|residues|incidence matrix|resilience modifications) using thestress-analysisskill. When not activated: skip entirely, do not mention. Gate: activated only when flag present. -
Produce Deliverables — write architecture document with component boundaries|tech stack|integration patterns. Produce C4 System Context diagram (Mermaid) — mandatory. Produce C4 Container diagram (Mermaid) — mandatory. Produce C4 Component diagrams (Mermaid) — only for complex subsystems. Write ADRs for significant decisions. Gate: mandatory C4 diagrams present, ADRs written.
Outcome Collision Check (per DISCUSS#D-5 grain)
Provenance: feature outcomes-registry — DISCUSS#
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.3kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.4kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Claude-Code-Game-Studios
39.9kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
