tranhieutt/spec-driven-development
.claude/skills/spec-driven-development/SKILL.md
Enforces the creation of a clear, actionable specification before any implementation code is written. Prevents hallucinations and architectural drift.
$ install --global
skillsauthnpx skillsauth add tranhieutt/software_development_department spec-driven-developmentInstall 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: Apr 15, 2026, 11:49 PM4.5s1 file scanned
SKILL.md
- name:
- spec-driven-development
- type:
- workflow
- description:
- Enforces the creation of a clear, actionable specification before any implementation code is written. Prevents hallucinations and architectural drift.
- argument-hint:
- [feature-description-or-issue]
- user-invocable:
- true
- allowed-tools:
- Read, Glob, Grep, WebSearch
- effort:
- 3
- agent:
- lead-programmer
- when_to_use:
- When starting a new feature, doing major architectural refactoring, receiving a complex prompt, or when the user invokes /spec.
Spec-Driven Development
Purpose
This skill forces the agent to pause, analyze, and agree upon a specification before jumping into implementation code. Drafting a spec first prevents hallucinations, scopes down overly ambitious changes, and protects the codebase's existing architecture.
Workflow (Strict Process)
ABSOLUTE DIRECTIVE: You are an Agent. You MUST NOT start writing implementation files (.ts, .js, .py, etc.) until you have completed this workflow.
1. Context Analysis
- Review relevant files using
Read,Glob, orGrepto understand the system boundaries. - Identify how the proposed feature fits into the current architecture.
2. Draft the Spec
- Provide the user with a concise summary (1-3 paragraphs) containing:
- Core Objective
- Proposed Data/UI Flow
- Files to Modify & Files to Create
3. Task Breakdown
- Break the feature into granular, atomic checklist items:
[ ] Task 1: ...[ ] Task 2: ...
4. Approval Gate
- End your response by asking the user for explicit approval: "Do you approve of this specification and task sequence? Please permit me to begin Task 1 (TDD)."
Anti-Rationalizations
Be aware of lazy logic that an Agent typically uses to skip this step. If a thought on the left occurs, YOU MUST apply the rebuttal on the right:
| Excuse (Agent's Lazy Rationalization) | Rebuttal & Correct Action | | :--- | :--- | | "This is a tiny change, no need for a massive spec." | REJECTED. Even a 1-line change needs a quick confirmation. Reply with: "I will modify X to do Y. Shall I proceed?" | | "The user is rushing and wants code immediately." | REJECTED. Hasty code causes bugs and frustrates users more. Write a "Fast-Spec" with just 3 bullet points outlining the action and side-effects. | | "I understand the request perfectly. I'll just write all 3 files at once in this single turn." | REJECTED. High complexity requires phased execution. Write the spec, break it down, and execute sequentially focusing on one atomic task at a time. |
Verification Gates
Do not conclude your first interaction turn unless you have fulfilled the following:
- [ ] Displayed the Spec structure and Task Checklist to the user.
- [ ] Explicitly checked for side-effect risks on the existing infrastructure.
- [ ] Requested strict explicit approval from the user to proceed.
Edge Cases
- [Massive Feature Request]: If the feature requires touching >10 files, immediately raise a RED FLAG. Stop and request a scope reduction from the user before finalizing the spec.
- [Architectural Violation]: If the user's request violates underlying framework patterns (e.g., securely calling a database from a Next.js Client Component), stop and suggest a corrected architectural spec.
Related Skills
test-driven-development— Invoked immediately after the Spec is approved to implement Task 1 using the Red-Green-Refactor cycle.planning-and-task-breakdown— Used for ultra-large epics that need more project management rather than technical specs.
Related Skills
tranhieutt/visual-engineer
testing
VerifiedTrustedCommunity
Generates high-fidelity architecture diagrams, sequence flows, and component maps for SDD projects. Use when finalizing a design phase, documenting system architecture, or visualizing agentic workflows. Default style: Style 6 (Claude Official).
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/vector-database-engineer
data-ai
VerifiedTrustedCommunity
Provides vector database and semantic search patterns for Pinecone, Weaviate, Qdrant, Milvus, and pgvector in RAG and recommendation systems. Use when implementing vector search or when the user mentions vector database, semantic search, embeddings, or similarity search.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/update-codemap
development
VerifiedTrustedCommunity
Updates docs/technical/CODEMAP.md by scanning the current codebase structure. Run after a significant feature merge, refactor, or when CODEMAP feels stale.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/unfreeze
development
VerifiedTrustedCommunity
Unlocks the codebase after a release freeze or incident freeze period to resume normal development. Use when a freeze period ends or when the user mentions unfreezing or lifting the code freeze.
60SKILL.mdUpdated Apr 15, 2026