spec-mode 1.0.0

package/examples/sample-spec.md

@@ -0,0 +1,263 @@
+# Sample Spec - User Export Feature
+
+This is a complete example of the three-piece specification output.
+
+---
+
+## spec.md
+
+```markdown
+# User Export Feature Spec
+
+## Why
+
+Users need to export their data for external analysis and record-keeping. Currently there is no way to export user data, which limits data portability and compliance with data export requirements.
+
+## What Changes
+
+- Add CSV export endpoint for user data
+- Add export button to user management page
+- Add rate limiting to prevent abuse
+- **BREAKING:** Users without `export` permission cannot access the new endpoint
+
+## Impact
+
+- **Systems:** User management module, Authentication system
+- **Files:** 
+  - `src/api/users.ts` (new export endpoint)
+  - `src/components/UserTable.tsx` (add export button)
+  - `src/permissions.ts` (add export permission)
+- **Users:** Admin users will see new export functionality
+
+## ADDED Requirements
+
+### Export User Data as CSV
+
+**Scenario:** Admin user wants to export all users for external analysis
+
+**Acceptance Criteria:**
+- Export includes: id, name, email, created_at, last_login
+- File is downloaded as `users-export-YYYY-MM-DD.csv`
+- Export completes within 30 seconds for up to 10,000 users
+
+### Rate Limiting
+
+**Scenario:** Prevent abuse of export functionality
+
+**Acceptance Criteria:**
+- Maximum 5 exports per user per hour
+- Clear error message when limit exceeded
+- Rate limit reset after 1 hour
+
+## MODIFIED Requirements
+
+### User List Pagination
+
+**Before:** User list shows 50 users per page
+
+**After:** User list shows 100 users per page (to reduce export frequency)
+
+**Scenario:** Admin viewing user list
+
+**Acceptance Criteria:**
+- Default page size changed to 100
+- Existing bookmarks to specific pages still work
+
+## REMOVED Requirements
+
+### None
+
+No requirements are being removed in this change.
+```
+
+---
+
+## tasks.md
+
+```markdown
+# Implementation Tasks
+
+## Task Overview
+
+| ID | Task | Dependencies | Estimated |
+|----|------|--------------|-----------|
+| T1 | Add export permission | None | 15 min |
+| T2 | Create CSV export endpoint | T1 | 45 min |
+| T3 | Add rate limiting | T2 | 30 min |
+| T4 | Add export button to UI | T2 | 30 min |
+| T5 | Write integration tests | T2, T3 | 30 min |
+
+---
+
+## Tasks
+
+### Task T1: Add Export Permission
+
+**Files:**
+- Modify: `src/permissions.ts:10-25`
+- Modify: `src/types/permissions.ts:5-10`
+
+**Steps:**
+
+1. Add `export` to Permission type
+2. Add `EXPORT_DATA` constant
+3. Update permission validation
+
+**Verification:**
+- [ ] TypeScript compiles without errors
+- [ ] Permission appears in admin permission list
+
+---
+
+### Task T2: Create CSV Export Endpoint
+
+**Files:**
+- Create: `src/api/users/export.ts`
+- Modify: `src/api/users/index.ts:1-20`
+
+**Steps:**
+
+1. Create export handler function
+2. Generate CSV from user data
+3. Set proper headers for download
+4. Register route in user router
+
+**Verification:**
+- [ ] Endpoint returns 200 with CSV data
+- [ ] CSV format is correct
+- [ ] Headers trigger file download
+
+---
+
+### Task T3: Add Rate Limiting
+
+**Files:**
+- Modify: `src/middleware/rateLimit.ts`
+- Modify: `src/api/users/export.ts`
+
+**Steps:**
+
+1. Add export-specific rate limit rule
+2. Apply middleware to export endpoint
+3. Add error response for limit exceeded
+
+**Verification:**
+- [ ] 6th export within 1 hour returns 429
+- [ ] Error message is user-friendly
+
+---
+
+### Task T4: Add Export Button to UI
+
+**Files:**
+- Modify: `src/components/UserTable.tsx:50-100`
+
+**Steps:**
+
+1. Add export button component
+2. Add click handler to call export endpoint
+3. Add loading state during export
+4. Add error handling
+
+**Verification:**
+- [ ] Button visible to admin users
+- [ ] Button hidden for non-admin users
+- [ ] Download starts on click
+
+---
+
+### Task T5: Write Integration Tests
+
+**Files:**
+- Create: `tests/api/users/export.test.ts`
+
+**Steps:**
+
+1. Test successful export
+2. Test rate limiting
+3. Test permission denied
+4. Test large dataset
+
+**Verification:**
+- [ ] All tests pass
+- [ ] Code coverage > 80%
+```
+
+---
+
+## checklist.md
+
+```markdown
+# Verification Checklist
+
+## Pre-Implementation
+
+- [ ] spec.md is complete and approved
+- [ ] tasks.md is complete with clear verification steps
+- [ ] All stakeholders have reviewed the specification
+- [ ] Change ID is assigned: `add-user-export`
+
+## Implementation
+
+### Code Quality
+
+- [ ] All new code follows project conventions
+- [ ] All tests pass (existing and new)
+- [ ] No linting errors introduced
+- [ ] Code is properly commented where necessary
+
+### Functionality
+
+- [ ] Export endpoint returns CSV data
+- [ ] Export includes all required fields
+- [ ] Rate limiting works correctly (5/hour)
+- [ ] Export button visible to admins only
+- [ ] Permission check works correctly
+
+### Testing
+
+- [ ] Unit tests for export function
+- [ ] Integration tests for endpoint
+- [ ] Rate limit tests
+- [ ] Permission tests
+- [ ] Error handling tests
+
+### Documentation
+
+- [ ] API documentation updated
+- [ ] Component documentation added
+- [ ] CHANGELOG updated
+
+## Post-Implementation
+
+### Verification
+
+- [ ] All checklist items from tasks.md are complete
+- [ ] Manual testing completed
+- [ ] Performance tested with 10,000 users
+
+### Cleanup
+
+- [ ] Temporary files removed
+- [ ] Debug code removed
+- [ ] Unused imports removed
+- [ ] Code formatted with prettier
+
+### Deployment
+
+- [ ] Changes committed with clear messages
+- [ ] Pull request created
+- [ ] Deployment plan documented
+
+## Sign-off
+
+- [ ] Developer sign-off
+- [ ] Reviewer sign-off
+- [ ] Product owner approval
+
+---
+
+**Change ID:** add-user-export
+**Date Completed:** 2024-01-15
+**Status:** Complete
+```

package/install.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Spec Mode Skill Installer
+# Compatible with OpenCode, Cursor, Windsurf, Copilot
+
+set -e
+
+echo "🚀 Installing Spec Mode Skill..."
+
+# Determine the skills directory based on the AI assistant
+SKILLS_DIR=""
+
+if [ -n "$OPENCODE_CONFIG" ]; then
+  SKILLS_DIR="$HOME/.config/opencode/skills"
+elif [ -n "$CURSOR_CONFIG" ]; then
+  SKILLS_DIR="$HOME/.cursor/skills"
+elif [ -n "$WINDSURF_CONFIG" ]; then
+  SKILLS_DIR="$HOME/.windsurf/skills"
+elif [ -n "$COPILOT_CONFIG" ]; then
+  SKILLS_DIR="$HOME/.copilot/skills"
+else
+  # Default to OpenCode
+  SKILLS_DIR="$HOME/.config/opencode/skills"
+fi
+
+# Create skills directory if it doesn't exist
+mkdir -p "$SKILLS_DIR"
+
+# Get the script's directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Destination directory
+DEST_DIR="$SKILLS_DIR/spec-mode"
+
+# Remove existing installation if present
+if [ -d "$DEST_DIR" ]; then
+  echo "⚠️  Removing existing installation..."
+  rm -rf "$DEST_DIR"
+fi
+
+# Create destination directory
+mkdir -p "$DEST_DIR"
+
+# Copy skill files (excluding .git and other unnecessary files)
+echo "📁 Copying skill files to $DEST_DIR/"
+
+# Copy core files
+cp "$SCRIPT_DIR/SKILL.md" "$DEST_DIR/"
+cp "$SCRIPT_DIR/README.md" "$DEST_DIR/" 2>/dev/null || true
+cp "$SCRIPT_DIR/LICENSE" "$DEST_DIR/" 2>/dev/null || true
+
+# Copy directories
+for dir in examples prompts references templates tests; do
+  if [ -d "$SCRIPT_DIR/$dir" ]; then
+    cp -r "$SCRIPT_DIR/$dir" "$DEST_DIR/"
+  fi
+done
+
+# Verify installation
+if [ -f "$SKILLS_DIR/spec-mode/SKILL.md" ]; then
+  echo "✅ Spec Mode Skill installed successfully!"
+  echo ""
+  echo "📖 Usage:"
+  echo '   Say "spec", "specification", "spec-mode", "写规范", or "写 specs"'
+  echo ""
+  echo "📁 Installed to: $SKILLS_DIR/spec-mode/"
+else
+  echo "❌ Installation failed. Please check the error messages above."
+  exit 1
+fi

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "spec-mode",
+  "version": "1.0.0",
+  "description": "An AI skill that creates standardized specification documents before implementation. Specs first, code second.",
+  "main": "SKILL.md",
+  "keywords": [
+    "skill",
+    "ai",
+    "opencode",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "specification",
+    "spec",
+    "documentation",
+    "development"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GlacierXiaowei/spec-mode.git"
+  },
+  "author": {
+    "name": "Glacier Xiaowei",
+    "email": "glacier_xiaowei@163.com",
+    "url": "https://github.com/GlacierXiaowei"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/GlacierXiaowei/spec-mode/issues"
+  },
+  "homepage": "https://github.com/GlacierXiaowei/spec-mode#readme"
+}

package/prompts/standard.md

@@ -0,0 +1,30 @@
+# Spec Mode - Standard Prompt
+
+You are in Spec Mode. Your task is to write and output three files: `spec.md`, `tasks.md`, and `checklist.md`.
+
+## Requirements
+
+1. **Only produce these three documents** - No code changes, no other files
+2. **Language must match user's language** (currently Chinese)
+3. **Output directory:** `<project-root>/.specs/<change-id>/`
+   - `<change-id>` must be verb-first, hyphen-separated (e.g., `add-user-export`, `refactor-auth-middleware`)
+4. **spec.md structure:**
+   - `Why` - 1-2 sentences explaining the purpose
+   - `What Changes` - Bullet list of changes (mark **BREAKING** changes where applicable)
+   - `Impact` - Affected systems and key files
+   - `ADDED Requirements` - New requirements with scenarios
+   - `MODIFIED Requirements` - Changed requirements with scenarios
+   - `REMOVED Requirements` - Removed requirements with scenarios
+5. **tasks.md:** Map changes to small, verifiable work items
+   - Break into subtasks when necessary
+   - Mark dependencies and parallelizable items
+   - Include verification method (test/tool/run)
+6. **checklist.md:** List must-pass checkpoints
+   - Itemized and checkable
+   - Aligned with tasks.md
+
+## After Completion
+
+**Prompt user for review. Do NOT proceed to implementation.**
+
+Wait for user approval before moving to implementation phase.

package/prompts/workflow.md

@@ -0,0 +1,58 @@
+# Spec Mode - Workflow Prompt
+
+You are now in Spec Mode. Your goal is to produce the standardized three-piece specification for the user's change request: `spec.md`, `tasks.md`, and `checklist.md`.
+
+## Rules to Follow
+
+### 1. Scope and Language
+- Only create the three documents above
+- Do NOT modify code or create other files
+- Document language must match the user's current language (Chinese)
+
+### 2. Path and Naming
+- Target directory: `<project-root>/.specs/<change-id>/`
+- Alternative: `<project-root>/docs/specs/<change-id>/`
+- `<change-id>` uses verb-first, hyphen-separated format (e.g., `refactor-auth-middleware`, `add-user-export`)
+
+### 3. Document Structure
+
+**spec.md:**
+- Fixed structure: Why / What Changes / Impact / ADDED / MODIFIED / REMOVED
+- Include scenarios for each requirement
+- Mark **BREAKING** changes where applicable
+
+**tasks.md:**
+- Small, verifiable work items
+- Mark dependencies and parallelizable tasks
+- Include verification method (test/tool/run)
+
+**checklist.md:**
+- List all must-pass checkpoints
+- Itemized and checkable
+- Aligned with tasks.md
+
+### 4. Process and Rules
+- Only output documents during spec phase
+- After completion, prompt user for review and approval
+- Only proceed to implementation after user approval
+- During implementation, reference the above documents as the single source of truth
+
+### 5. Exploration and Research
+- Start with high-level investigation: goals, scope, constraints, key modules
+- Drill down gradually: interfaces, data flow, boundary conditions, security and compatibility
+- Converge to the three-piece documents after covering key points
+
+### 6. Subagent/Parallel (Optional)
+- If platform supports: Execute independent tasks in parallel (e.g., document generation and link summary); merge and verify together
+- If platform doesn't support: Execute same expectations and verification sequentially
+
+### 7. Content Quality
+- Focus on verifiability and user-visible progress
+- Prioritize minimum viable implementation (MVP), avoid over-engineering
+- Ensure each work item is independently verifiable and progress is observable
+
+## After Completion
+
+**Prompt user for review. Do NOT proceed to implementation.**
+
+Wait for user confirmation before moving to implementation phase. During implementation, use the specification documents as the single source of truth.

package/references/common-mistakes.md

@@ -0,0 +1,39 @@
+# Common Mistakes in Spec Mode
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "This is too urgent for specs" | Specs save time by preventing rework. Even 5-minute specs help. |
+| "I already wrote half the code" | Stop. Write specs for what remains. Fix mismatches before continuing. |
+| "The user/manager said skip docs" | Specs are for you too. They prevent mistakes. Offer simplified version, not skip. |
+| "This project is too small" | Small projects break too. Specs scale to project size. |
+| "I'm experienced, I don't need specs" | Experience prevents bugs. Specs prevent miscommunication. Both matter. |
+| "I'll write specs after, same thing" | Specs-after = "what did I do?" Specs-before = "what should I do?" Different purposes. |
+| "The user just asked to implement, I should add specs" | NO! User must explicitly request specs. Don't add specs uninvited. |
+
+## Red Flags - STOP and Start Over
+
+If you catch yourself doing any of these, **stop immediately** and return to Spec Mode:
+
+- ❌ Writing code before specs are approved
+- ❌ "I already manually tested it"
+- ❌ "The user wants code now, specs later"
+- ❌ "This is different because..."
+- ❌ "It's about spirit not ritual"
+
+**All of these mean: Stop. Return to Spec Mode. Write specs first.**
+
+## Why These Mistakes Happen
+
+1. **Urgency bias** - Feeling pressured to deliver quickly
+2. **Overconfidence** - Assuming you know what the user wants
+3. **Sunk cost** - Already started coding, don't want to stop
+4. **Rationalization** - Finding excuses to skip discipline
+
+## How to Avoid
+
+1. **Pause** - When you feel the urge to skip specs, pause
+2. **Ask** - Remember: specs save time by preventing rework
+3. **Start small** - Even a 5-minute spec is better than none
+4. **Trust the process** - The workflow exists for a reason

package/references/cross-platform.md

@@ -0,0 +1,57 @@
+# Cross-Platform Notes
+
+## Directory Flexibility
+
+Spec Mode works with any directory structure. Choose what fits your project:
+
+| Option | Path | Use Case |
+|--------|------|----------|
+| **Default** | `<project-root>/.specs/<change-id>/` | Standard location |
+| **Alternative** | `<project-root>/docs/specs/<change-id>/` | Projects with docs folder |
+| **Custom** | Any directory | Keep three-file structure |
+
+## Naming Convention
+
+`<change-id>` uses:
+- **Verb-first** format
+- **Hyphen-separated** words
+- **Lowercase** letters
+
+**Examples:**
+- `add-user-export`
+- `refactor-auth-middleware`
+- `fix-login-bug`
+- `update-homepage-ui`
+
+## Editor Support
+
+Spec Mode works in any AI environment:
+
+- ✅ Claude Code
+- ✅ Cursor
+- ✅ VS Code extensions
+- ✅ Any SKILL.md-compatible agent
+
+**No tool-specific dependencies** - The skill is pure markdown instructions.
+
+## Subagent Support
+
+| Scenario | Behavior |
+|----------|----------|
+| **Parallel tasks available** | Use subagents for independent tasks |
+| **Sequential only** | Execute tasks one by one |
+
+Subagent support is **optional** - the skill works without it.
+
+## Three-File Structure
+
+Regardless of directory, always maintain:
+
+```
+<change-id>/
+├── spec.md       # What & Why
+├── tasks.md      # How to implement
+└── checklist.md  # Verification checkpoints
+```
+
+This structure is the **core invariant** of Spec Mode.

package/references/workflow-details.md

@@ -0,0 +1,94 @@
+# Workflow Details
+
+## Complete Step-by-Step Flow
+
+### Phase 1: Understand & Scan
+
+1. **Understand user goal** - Analyze the user's request
+2. **Scan context** - Read relevant files, code structure, existing conventions
+3. **Make inferences** - If you can reasonably infer details, proceed with assumptions
+
+### Phase 2: Ask Questions (Only If Necessary)
+
+**Ask ONLY when:**
+- Cannot reliably infer after scanning context
+- AND the uncertainty affects spec/implementation direction/scope/result
+
+**Typical cases (only 3 types):**
+1. **Vague requirements** - e.g., "optimize homepage" without specifying visual/performance/interaction
+2. **Multiple valid approaches** - e.g., permission system design (role-based vs resource-level)
+3. **Unclear scope** - e.g., frontend only / backend only / both
+
+**Do NOT ask about:**
+- Minor details (e.g., button color) → Make reasonable assumptions
+- Implementation technical choices → Decide yourself
+
+### Phase 3: Create Spec Documents
+
+1. **spec.md** - Define why, what changes, impact, requirements
+2. **tasks.md** - Break down into small, verifiable work items
+3. **checklist.md** - List must-pass checkpoints
+
+### Phase 4: User Confirmation
+
+**After creating all three documents:**
+
+```
+✅ 已完成规范文档：
+- .specs/<change-id>/spec.md
+- .specs/<change-id>/tasks.md
+- .specs/<change-id>/checklist.md
+
+[简要总结关键内容]
+
+请审阅。确认后我开始实现。
+```
+
+**Then STOP** - Wait for user confirmation before proceeding.
+
+### Phase 5: Implementation
+
+**After user confirms:**
+
+1. **Start implementation directly** - No more questions
+2. **Make judgments on uncertainties** - Decide yourself
+3. **Report after completion** - Unified summary at the end
+4. **Only interrupt for major deviations** - Critical issues only
+
+**WRONG:** Asking about every small decision during implementation
+**RIGHT:** Execute completely after confirmation → Report when done
+
+## Workflow Diagram
+
+```
+User Request
+     ↓
+Scan Context
+     ↓
+Can Infer? ──no,critical──→ Ask Questions ──┐
+     │                                      ↓
+     │yes/minor                          Create spec.md
+     ↓                                      ↓
+Make Assumption ────────────────────────────┘
+     ↓
+Create tasks.md
+     ↓
+Create checklist.md
+     ↓
+Notify User
+     ↓
+User Review ──changes needed──→ Revise Specs ──┐
+     │                                        ↓
+     │approved                                 └──→ (back to User Review)
+     ↓
+Implementation
+     ↓
+Complete & Report
+```
+
+## Key Principles
+
+1. **Scan before asking** - Never ask before scanning context
+2. **Assume when reasonable** - Don't ask about minor details
+3. **Notify, don't question** - Use notification format for confirmation
+4. **Execute without interruption** - After confirmation, no more questions