Initial commit

2025-11-30 08:45:31 +08:00
commit ca9b85ccda
35 changed files with 10784 additions and 0 deletions
--- a/skills/spec-author/SKILL.md
+++ b/skills/spec-author/SKILL.md
@@ -0,0 +1,464 @@
+---
+name: Spec Author
+description: Create, validate, and improve specification documents. Use this when writing business requirements, technical requirements, design documents, data models, API contracts, components, plans, milestones, flow schematics, deployment procedures, or configuration schemas.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# Spec Author Skill
+
+Create and validate specification documents following project standards. This skill creates specs for users based on their requests while ensuring proper structure, completeness, and quality.
+
+## How This Skill Works
+
+When a user asks for a spec to be created:
+
+1. **Clarify Requirements** - Use AskUserQuestion to understand scope, audience, and detail level
+2. **Research Context** - Read related specs, codebase, and existing documentation
+3. **Read the Guide** - Always consult `guides/{spec-type}.md` for detailed instructions
+4. **Generate from Template** - Use `scripts/generate-spec.sh` to create the initial structure
+5. **Fill Content Properly** - Follow template structure and guide instructions precisely
+6. **Validate & Fix** - Run validation tools and fix all issues before completion
+7. **Review for Quality** - Ensure all sections have meaningful, user-written content
+
+## 11 Specification Types
+
+| Type | ID Format | Purpose | Read Guide When |
+|------|-----------|---------|-----------------|
+| **Business Requirement** | `brd-XXX` | Capture business problems, value, and user needs | Planning a new feature from business perspective |
+| **Technical Requirement** | `prd-XXX` | Translate business needs into technical specs | Defining how to build what business requires |
+| **Design Document** | `des-XXX` | Detailed architecture and technical design | Making major architectural decisions |
+| **Component** | `cmp-XXX` | Specify individual services/components | Documenting a microservice or major component |
+| **API Contract** | `api-XXX` | Define REST endpoints and data formats | Designing API for parallel frontend/backend work |
+| **Data Model** | `data-XXX` | Define entities, fields, relationships | Planning database schema or data structure |
+| **Plan** | `pln-XXX` | Implementation roadmap with phases and timeline | Organizing work into phases for execution |
+| **Milestone** | `mls-XXX` | Define delivery checkpoints with success criteria | Setting specific completion targets |
+| **Flow Schematic** | `flow-XXX` | Document workflows and process flows | Illustrating user/system interactions |
+| **Deployment Procedure** | `deploy-XXX` | Step-by-step production deployment instructions | Creating operational runbooks |
+| **Configuration Schema** | `config-XXX` | Document all configurable parameters | Defining how system is configured |
+
+## Quick Start
+
+```bash
+# 1. Create spec from template
+scripts/generate-spec.sh <type> <id>
+# Example: scripts/generate-spec.sh business-requirement brd-001-export
+
+# 2. Read the corresponding guide
+# Example: guides/business-requirement.md
+
+# 3. Fill in sections following the guide
+
+# 4. Validate completeness
+scripts/validate-spec.sh docs/specs/<type>/<id>.md
+
+# 5. Fix any issues
+scripts/check-completeness.sh docs/specs/<type>/<id>.md
+```
+
+**Note:** Specs are now organized in folders by type under `docs/specs/`:
+- `docs/specs/business-requirement/` - Business requirement documents
+- `docs/specs/technical-requirement/` - Technical requirement documents
+- `docs/specs/design-document/` - Design documents
+- And so on for each spec type...
+
+## How Specs Connect
+
+Specs flow together when implementing a feature:
+
+```
+Business Requirement (BRD)
+  ↓ answers "what problem?"
+Technical Requirement (PRD)
+  ↓ answers "what to build technically?"
+Design Document (DES)
+  ↓ answers "how to architect this?"
+  ├→ Data Model (DATA) - what data structure?
+  ├→ API Contract (API) - what endpoints?
+  └→ Component (CMP) - what services?
+
+Plan (PLN)
+  ↓ answers "how to execute?"
+Milestone (MLS) - specific checkpoints
+Flow Schematic (FLOW) - how it works
+Deployment Procedure (DEPLOY) - how to launch
+Configuration Schema (CONFIG) - how to configure
+```
+
+**Key interactions:**
+- BRD → PRD: Business problem becomes technical requirement
+- PRD → DES: Technical spec becomes architectural design
+- DES → {DATA, API, CMP}: Architecture drives data/API/component specs
+- DES → PLN: Design informs implementation plan
+- PRD + DES → FLOW: Requirements and design inform workflows
+- CMP + CONFIG → DEPLOY: Component and config specs inform deployment
+
+## CLI Tools
+
+### Get Next Available ID
+```bash
+scripts/next-id.sh <spec-type>
+scripts/next-id.sh <spec-type> --with-slug <slug>
+```
+Determines the next available ID number for a spec type. Useful before creating a new spec.
+
+Examples:
+- `scripts/next-id.sh business-requirement` → `brd-002`
+- `scripts/next-id.sh api-contract --with-slug notifications` → `api-002-notifications`
+
+### Generate Spec
+```bash
+# Manual ID
+scripts/generate-spec.sh <spec-type> <spec-id>
+
+# Auto-generate next ID
+scripts/generate-spec.sh <spec-type> --next <slug>
+scripts/generate-spec.sh <spec-type> --next
+```
+Creates new spec in `docs/specs/{spec-type}/{spec-id}.md` from template.
+
+**When to use `--next`:**
+- Creating the first spec of a type (auto-assigns ID 001)
+- Don't know what the next number should be
+- Want to ensure no ID conflicts
+
+Examples:
+- `scripts/generate-spec.sh business-requirement brd-001-export` (manual ID)
+- `scripts/generate-spec.sh business-requirement --next export` (auto ID: brd-002-export)
+- `scripts/generate-spec.sh milestone --next` (auto ID: mls-001)
+
+### Validate Spec
+```bash
+scripts/validate-spec.sh docs/specs/<type>/<id>.md
+```
+Returns: ✓ PASS | ⚠ WARNINGS | ✗ ERRORS
+
+### Check Completeness
+```bash
+scripts/check-completeness.sh docs/specs/<type>/<id>.md
+```
+Shows completion %, TODO items, missing sections.
+
+### List Templates
+```bash
+scripts/list-templates.sh
+```
+Shows all 11 available specification templates.
+
+## Tool Usage Guide
+
+**When creating a new spec, use this workflow:**
+
+1. **First, determine the next ID:**
+   ```bash
+   scripts/next-id.sh <spec-type>
+   ```
+
+2. **Then generate with that ID:**
+   ```bash
+   scripts/generate-spec.sh <spec-type> --next <slug>
+   ```
+
+**Or combine in one step:**
+```bash
+scripts/generate-spec.sh <spec-type> --next <descriptive-slug>
+```
+
+This ensures sequential numbering and prevents ID conflicts.
+
+## Step-by-Step Spec Creation Process
+
+### Step 1: Clarify Requirements (MANDATORY)
+
+Before creating any spec, use AskUserQuestion to gather:
+
+**Question 1: Scope & Purpose**
+- What problem/feature/system are we documenting?
+- What's the primary goal of this specification?
+- What should be included vs. excluded?
+
+**Question 2: Audience & Detail Level**
+- Who will read/use this spec? (developers, stakeholders, operations team)
+- How technical should it be? (high-level overview, detailed implementation)
+- Are there specific sections that need extra detail?
+
+**Question 3: Context & Dependencies**
+- Are there related specs or systems to reference?
+- What existing documentation should inform this spec?
+- What constraints or requirements exist?
+
+### Step 2: Research Phase (REQUIRED)
+
+Before filling the template:
+
+1. **Read the corresponding guide** - `guides/{spec-type}.md` contains critical instructions
+2. **Search for related specs** - Use Glob to find specs that might be referenced
+3. **Review codebase context** - Grep for relevant code if documenting existing systems
+4. **Check template structure** - Read `templates/{spec-type}.md` to understand required sections
+
+### Step 3: Generate Spec Structure
+
+**Determine the next ID and generate:**
+```bash
+# Option 1: Auto-generate with slug (RECOMMENDED)
+scripts/generate-spec.sh <spec-type> --next <descriptive-slug>
+
+# Option 2: Check ID first, then generate
+scripts/next-id.sh <spec-type>
+scripts/generate-spec.sh <spec-type> <full-id-with-slug>
+```
+
+This creates the file with proper template structure at `docs/specs/{spec-type}/{spec-id}.md`.
+
+**Why use `--next`?**
+- Automatically determines the next sequential ID
+- Prevents ID conflicts
+- No need to manually check existing specs
+- Ensures consistent numbering
+
+### Step 4: Fill Content Following Guide
+
+**Critical Rules:**
+- Follow the guide's section-by-section instructions exactly
+- Replace ALL template placeholders with real content
+- Write meaningful, specific content - no generic text
+- Include concrete examples, not abstract descriptions
+- Reference related specs using `[spec-id]` format
+- Complete every required section before validation
+
+**Section Writing Approach:**
+1. Read guide instructions for the section
+2. Gather specific information from research
+3. Write clear, concise content
+4. Add examples or diagrams if helpful
+5. Ensure it answers the section's core question
+
+### Step 5: Validation & Quality Check
+
+Run both validation scripts:
+```bash
+# Check structure and completeness
+scripts/validate-spec.sh docs/specs/<id>.md
+
+# Find TODOs and incomplete sections
+scripts/check-completeness.sh docs/specs/<id>.md
+```
+
+**Fix all issues:**
+- ✗ ERRORS must be resolved (missing required sections)
+- ⚠ WARNINGS should be addressed (incomplete content)
+- Remove all TODO markers
+- Ensure no template guidance text remains
+
+### Step 6: Final Review
+
+Before considering the spec complete:
+
+✓ All required sections have meaningful content
+✓ No template placeholders or TODOs remain
+✓ Related specs are properly referenced
+✓ Examples and specifics are included
+✓ Validation passes with no errors
+✓ Content matches user's requirements from Step 1
+
+## Instruction Guides
+
+Comprehensive guides in `guides/` directory. **Always read the guide for your spec type before starting.**
+
+Each guide includes:
+- **Quick Start** - Get going in 5 minutes
+- **Research Phase** - How to research context and related specs
+- **Structure & Content** - Detailed walkthrough of each section
+- **Writing Tips** - Best practices and examples
+- **Validation & Fixes** - How to use tools and fix issues
+- **Decision Framework** - Questions to guide your thinking
+
+**Start here:** `guides/README.md` - Master guide with complete end-to-end workflows showing how all 11 specs connect.
+
+## Common Mistakes to Avoid
+
+❌ **DON'T:**
+- Skip asking clarifying questions - assumptions lead to wrong specs
+- Leave template guidance text or TODOs in final spec
+- Write generic/abstract content instead of specific details
+- Ignore the guide for the spec type
+- Skip validation before considering spec complete
+- Create specs without researching related specs and context
+- Fill sections without understanding their purpose
+
+✅ **DO:**
+- Always use AskUserQuestion before starting
+- Read the spec-type guide thoroughly
+- Research related specs and codebase
+- Write specific, concrete content with examples
+- Validate and fix all issues
+- Ensure every section answers its core question
+- Reference related specs using proper format
+
+## Quality Standards for Specs
+
+Every completed spec must meet these standards:
+
+**Content Quality:**
+- Specific and concrete (not abstract or generic)
+- Includes real examples, not placeholder text
+- All sections fully completed with meaningful content
+- Technical accuracy verified against codebase/requirements
+- Clear and understandable by target audience
+
+**Structural Integrity:**
+- Proper ID format: `type-number-descriptive-slug`
+- All required sections present and complete
+- Follows template structure exactly
+- Related specs properly referenced with `[spec-id]`
+- No TODO markers or template guidance text
+
+**Validation Status:**
+- ✓ PASS from `validate-spec.sh`
+- 100% completion from `check-completeness.sh`
+- No errors or warnings
+- All user requirements from clarification phase met
+
+## Validation Rules
+
+**All specs require:**
+- Properly formatted ID (type-number-slug)
+- Clear overview/description
+- Key content sections (varies by type)
+
+**Spec type specifics:** See `./templates/{type}.md` for required sections.
+
+## Naming Convention
+
+Format: `<type>-<number>-<descriptive-slug>`
+
+Types: brd, prd, des, api, data, cmp, pln, mls, flow, deploy, config
+
+Examples:
+- `brd-001-bulk-export`
+- `prd-001-export-async-api`
+- `des-001-microservices-architecture`
+
+## Validation Levels
+
+- **✓ PASS** - Production-ready, all sections complete
+- **⚠ WARNINGS** - Usable but incomplete TODOs or optional sections
+- **✗ ERRORS** - Critical sections missing, not ready
+
+## When to Use This Skill
+
+- Create new specs for features, systems, or components
+- Validate existing specs for completeness and quality
+- Review specs and provide feedback
+- Understand spec structure and content requirements
+- See how specs connect and inform each other
+- Get step-by-step guidance through spec writing process
+
+When creating a spec, always ask clarifying questions about:
+- Who will use this specification (audience)
+- What level of detail is needed
+- What's in scope vs. out of scope
+- Which aspects are highest priority
+
+## What Each Component Does
+
+### Templates (`templates/`)
+Starting structure for each spec type. Used by `generate-spec.sh`.
+
+### Guides (`guides/`)
+**Read these.** Comprehensive how-to for each spec type with research guidance, structure details, writing tips, and decision frameworks.
+
+### Scripts (`scripts/`)
+- `generate-spec.sh` - Create from template
+- `validate-spec.sh` - Check completeness
+- `check-completeness.sh` - Find TODOs
+- `list-templates.sh` - List types
+
+### Docs (`docs/specs/`)
+Location where all generated specs are stored, organized by type into folders:
+- `business-requirement/` - BRD specs
+- `technical-requirement/` - PRD specs
+- `design-document/` - Design specs
+- `api-contract/` - API specs
+- `data-model/` - Data model specs
+- `component/` - Component specs
+- `plan/` - Plan specs
+- `milestone/` - Milestone specs
+- `flow-schematic/` - Flow specs
+- `deployment-procedure/` - Deployment specs
+- `configuration-schema/` - Config specs
+
+## Workflow Examples
+
+### Example 1: User Requests "Create a BRD for export feature"
+
+**Step 1: Clarify** (Use AskUserQuestion)
+- Q: "What's the export feature scope - what data, for whom, why needed?"
+- Q: "Who's the audience - developers, product team, or executives?"
+- Q: "Detail level - business justification only or include user stories?"
+
+**Step 2: Research**
+- Read `guides/business-requirement.md`
+- Glob search: `docs/specs/business-requirement/brd-*.md` for related BRDs
+- Grep: Search codebase for existing export functionality
+
+**Step 3: Generate**
+```bash
+# Use --next to auto-generate the next ID
+scripts/generate-spec.sh business-requirement --next export-feature
+# This will auto-assign brd-002-export-feature (or next available)
+```
+
+**Step 4: Fill Content**
+- Follow guide's section-by-section instructions
+- Problem Statement: Specific pain points from user research
+- Business Value: Concrete metrics and ROI
+- User Stories: Real scenarios with acceptance criteria
+- Success Metrics: Measurable KPIs
+
+**Step 5: Validate**
+```bash
+scripts/validate-spec.sh docs/specs/business-requirement/brd-002-export-feature.md
+scripts/check-completeness.sh docs/specs/business-requirement/brd-002-export-feature.md
+```
+
+**Step 6: Review**
+- ✓ All sections have specific, real content
+- ✓ No TODOs or template text
+- ✓ Validation passes
+- ✓ Matches user's requirements from clarification
+
+### Example 2: User Requests "Document the API for notifications"
+
+**Step 1: Clarify**
+- Q: "Is this for a new API design or documenting existing?"
+- Q: "Who will use this - frontend developers, mobile team, third parties?"
+- Q: "What endpoints - all CRUD operations or specific flows?"
+
+**Step 2: Research**
+- Read `guides/api-contract.md`
+- Read existing notification service code
+- Check for related specs in relevant folders:
+  - `docs/specs/technical-requirement/prd-*-notification.md`
+  - `docs/specs/design-document/des-*-notification.md`
+
+**Step 3-6: Generate, Fill, Validate, Review**
+- Create specific endpoint definitions with real request/response examples
+- Include authentication, error codes, rate limits
+- Document actual data models from codebase
+- Validate all examples are syntactically correct
+
+## Critical Reminders
+
+🎯 **Every spec creation MUST start with AskUserQuestion** - No assumptions!
+
+🔢 **Use `--next` to auto-generate IDs** - Prevents numbering conflicts and ensures sequential IDs
+
+📚 **Always read the guide** - `guides/{spec-type}.md` contains essential instructions
+
+🔍 **Research before writing** - Understand context, related specs, and codebase
+
+✍️ **Write concrete content** - Real examples, specific details, no placeholders
+
+✅ **Validate before completion** - Fix all errors and warnings
+
+🎓 **Quality over speed** - A complete, accurate spec is worth the extra time