n4m3z/DesignSpec
skills/DesignSpec/SKILL.md
Write a formal design spec from brainstorming output or requirements. USE WHEN design approved, write spec, formalize design, spec document.
$ install --global
skillsauthnpx skillsauth add n4m3z/forge-core DesignSpecInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 14, 2026, 6:09 AM141.4s2 files scanned
SKILL.md
- name:
- DesignSpec
- version:
- 0.1.0
- description:
- Write a formal design spec from brainstorming output or requirements. USE WHEN design approved, write spec, formalize design, spec document.
DesignSpec
Produce a formal design specification from approved brainstorming output or direct requirements. The spec is the contract between design and implementation — WritePlan and DeveloperSprint consume it.
- Gather input — read the approved design (from Brainstorming output or user description)
- Write the spec — structured markdown covering all sections below
- Self-review — run the checklist before presenting
- Save — write to
docs/specs/YYYY-MM-DD-<topic>-design.md - User review — present for approval. No implementation until approved.
Spec Structure
Scale sections to complexity. Simple specs skip sections that don't apply.
- Problem Statement — what exists today, why it's insufficient
- Proposed Approach — what we're building, key design decisions
- API / Interface Design — public surface, data shapes, commands
- Data Flow — how data moves through the system
- Edge Cases — known boundary conditions and how they're handled
- Test Strategy — what to test, how to verify correctness
- Out of Scope — what this spec explicitly does NOT cover
Self-Review Checklist
Before presenting the spec, verify:
| Check | Question | | ------------ | ---------------------------------------------------------- | | Completeness | Could someone implement this without asking questions? | | Consistency | Do all sections agree with each other? | | Clarity | Is every term unambiguous? No "should", "might", "maybe"? | | Scope | Does this solve the stated problem without gold-plating? | | YAGNI | Is every feature justified by a stated requirement? |
Red Flags
| Thought | Reality | | -------------------------------------------- | -------------------------------------------------------------- | | "The design is clear enough, skip the spec" | If it's clear, the spec writes fast. If not, you need it more. | | "I'll fill in the details during coding" | That's not a spec, it's a wish list. | | "Edge cases can wait" | Edge cases found during coding cost 10x more to handle. | | "The user already approved the design" | Design approval is not spec approval. Write it down. | | "This spec is too short" | Short specs for simple problems are correct. Don't pad. |
Constraints
- Every section must be concrete — no placeholders, TBD, or TODO
- Spec must be saved as a file, not just presented in conversation
- User must approve the spec before implementation begins
- Hand off to WritePlan or DeveloperSprint after approval
Sources
- https://github.com/obra/superpowers
Related Skills
n4m3z/Wtf
development
VerifiedTrustedCommunity
Reactive correction and root-cause fix. USE WHEN something went wrong, user is frustrated, demands a correction, says wtf, what the hell, why did you, that's wrong, this is broken, no not that, stop. Executes the immediate fix, then hunts the upstream artifact that caused it and creates a corrective change.
4SKILL.mdUpdated May 28, 2026
n4m3z/ResearchTopic
development
VerifiedTrustedCommunity
Decompose a research question into sub-queries, spawn parallel WebResearcher agents per angle, synthesize findings with citations and explicit confidence. USE WHEN the user asks to research, investigate, look online, look up, dig into, find sources, gather evidence, or survey what's known about a topic. Single-pass; for multi-round adversarial research use ResearchCouncil in forge-council.
4SKILL.mdUpdated May 27, 2026
n4m3z/WriteDocs
tools
VerifiedTrustedCommunity
Author project documentation that future humans (and AI sessions) actually read. Covers TLDRs for tools, READMEs, runbooks, journals. USE WHEN write documentation, create tldr, tool one-pager, document a cli, write readme, runbook, journal entry, capture knowledge about a tool, distill a session into reusable notes.
4SKILL.mdUpdated May 25, 2026
n4m3z/StagedReview
development
VerifiedTrustedCommunity
Review your own staged changes via a code-review TUI before triggering a commit. USE WHEN about to commit, walking through your own staged diff, self-reviewing before approval, tuicr, revdiff, git diff cached.
4SKILL.mdUpdated May 25, 2026