SkillAgentSearch skills...

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-design

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

88/100

Supported Platforms

Universal

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.

Substance
30/30
Structure
17/20
Description
15/15
Adoption
12/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
nw-design (this skill)by nWave-ai886172mo agoSKILL.md
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.3ktodayCLAUDE.md
claude-howtoby luongnv8910047.4k3d agoCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.9k8d agoCLAUDE.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.

name: 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:

  1. 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).
  2. 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:

  1. Read SSOT architecture (if docs/product/ exists) — read docs/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.
  2. 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.
  3. 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.
  4. Output confirmation checklist — after reading, output ✓ {file} for each read, ⊘ {file} (not found) for each missing. Gate: checklist produced before any architecture work begins.
  5. 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.
  6. Migration gate check — if docs/product/ does not exist but docs/feature/ has existing features, STOP. Guide the user to docs/guides/migrating-to-ssot-model/README.md. If greenfield, proceed — DESIGN will bootstrap docs/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:

  1. Document the change — add a ## Changed Assumptions section at the end of the affected DESIGN artifact. Gate: section present in artifact.
  2. Reference the original — quote the original assumption from the prior-wave document, with file path. Gate: original quoted verbatim with source.
  3. State the new assumption — write the replacement assumption and its rationale. Gate: new assumption and rationale present.
  4. 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.md for 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:

  1. 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.

  2. Understand Constraints — ask: Team size/experience? Timeline? Existing systems to integrate? Regulatory requirements? Operational maturity (CI/CD, monitoring)? Gate: constraints list documented.

  3. Map Team Structure (Conway's Law) — ask: How many teams? Communication patterns? Does proposed architecture match org chart? Gate: team-architecture alignment confirmed.

  4. 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.

  5. 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.
  6. 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.

  7. Stress Analysis (HIDDEN — --residuality flag only) — when activated: apply complexity-science-based stress analysis (stressors|attractors|residues|incidence matrix|resilience modifications) using the stress-analysis skill. When not activated: skip entirely, do not mention. Gate: activated only when flag present.

  8. 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

View on GitHub
GitHub Stars617
CategoryDevelopment
Updated2mo ago
Forks63

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions