Initial commit

2025-11-30 08:54:26 +08:00
commit 3562b3d6a4
27 changed files with 16593 additions and 0 deletions
--- a/commands/spec.md
+++ b/commands/spec.md
@@ -0,0 +1,584 @@
+---
+description: Product discovery and specification generation from requirements, images, documents, or Jira issues
+argument-hint: [jira-id|description] [--input FILE1 FILE2...] [--output PATH] [--no-file] [--quiet] [--post-to-jira] [--work-dir PATH]
+allowed-tools: ["Read", "Write", "Grep", "Glob", "Task", "mcp__jira__*", "mcp__jetbrains__*", "Bash", "AskUserQuestion"]
+---
+
+# Product Specification Generator
+
+You are **creating a product specification** that defines WHAT to build, WHY it's needed, and FOR WHOM. This is the discovery phase - focusing on requirements, user needs, and product decisions (NOT technical implementation).
+
+---
+
+## ⚙️ PHASE 1: INPUT PROCESSING & WORK FOLDER SETUP
+
+### Step 1.1: Parse Command Arguments
+
+**Input Received**: $ARGUMENTS
+
+Parse to extract:
+
+**Primary Input** (first non-flag argument):
+- **Jira Issue ID**: Pattern `[A-Z]+-\d+` (e.g., EC-1234)
+- **Text Description**: Free-form product idea or requirement
+- **Empty**: Interactive mode (will prompt for requirements)
+
+**Input Files** (supporting materials):
+- **`--input FILE1 FILE2...`**: Images, PDFs, documents to analyze
+  - Examples: wireframes, mockups, PRD, requirements.pdf
+  - Supports multiple files
+  - File types: .png, .jpg, .pdf, .md, .txt, .doc, .docx
+
+**Output Flags**:
+- **`--output PATH`**: Save spec to specific file path (default: `.WIP/[identifier]/01-spec.md`)
+- **`--no-file`**: Skip file output, terminal only
+- **`--quiet`**: Skip terminal output, file only
+- **`--post-to-jira`**: Post spec as Jira comment (requires Jira ID)
+- **`--work-dir PATH`**: Use specific work folder (default: auto-generate)
+
+**Flag Validation**:
+- `--output` and `--no-file` cannot be used together → Error
+- `--post-to-jira` without Jira ID → Warning, skip posting
+- `--work-dir` overrides auto-generation → Use as specified
+
+**Store parsed values** for later phases:
+```
+problemInput = [jira-id or description or empty]
+inputFiles = [list of file paths]
+outputPath = [path or null]
+noFile = [boolean]
+quiet = [boolean]
+postToJira = [boolean]
+workDir = [path or null]
+jiraId = [extracted jira id or null]
+```
+
+### Step 1.2: Resolve or Create Work Folder
+
+Use lib/work-folder.md:
+
+```
+Configuration:
+  mode: "auto-detect"
+
+  identifier: [jiraId from Step 1.1, or null]
+  description: [problemInput from Step 1.1]
+
+  workflow_type: "full"
+  current_step: "spec"
+
+  custom_work_dir: [workDir from Step 1.1, or null]
+
+Output (store for later phases):
+  work_folder: [path from library, e.g., ".WIP/EC-1234-feature"]
+  metadata_file: [path from library, e.g., ".WIP/EC-1234-feature/.metadata.json"]
+  output_file: [path from library, e.g., ".WIP/EC-1234-feature/01-spec.md"]
+  identifier: [identifier from library]
+  is_new: [true/false from library]
+```
+
+**Store the returned values for later phases.**
+
+**Note**: The work-folder library creates `.WIP/[identifier]/` with metadata. Workflow type "full" means: spec → analyze → plan → implement.
+
+### Step 1.3: Copy Supporting Materials to Context Folder
+
+If `--input` files provided:
+
+```bash
+for file in $inputFiles; do
+  # Copy to context folder
+  cp "$file" "[work_folder from Step 1.2]/context/$(basename $file)"
+
+  # Read file if it's readable (images, PDFs, text)
+  # Use Read tool to load content for analysis
+done
+```
+
+**Update metadata.files.context** with list of copied files.
+
+---
+
+## ⚙️ PHASE 2: GATHER REQUIREMENTS & CONTEXT
+
+### Step 2.1: Fetch External Context (if Jira)
+
+If Jira ID detected in Step 1.1:
+
+**Use jira-analyzer subagent**:
+```
+Task tool:
+  subagent_type: "schovi:jira-auto-detector:jira-analyzer"
+  prompt: "Fetch and summarize Jira issue [jira-id]"
+  description: "Fetching Jira context"
+```
+
+Extract from summary:
+- Issue title
+- Issue type (Story, Epic, Bug)
+- Description (full text)
+- Acceptance criteria
+- Comments and discussion points
+
+### Step 2.2: Analyze Supporting Materials
+
+For each file in context/:
+
+**Images (wireframes, mockups, screenshots)**:
+- Use Read tool to view images
+- Extract UI elements, user flows, visual design
+- Identify screens, components, interactions
+
+**Documents (PDFs, text files)**:
+- Use Read tool to extract text
+- Parse requirements, user stories, constraints
+- Identify stakeholder needs, success metrics
+
+**Existing markdown/text**:
+- Read directly
+- Extract structured requirements if present
+
+### Step 2.3: Interactive Discovery (if needed)
+
+If requirements are vague or incomplete, ask clarifying questions:
+
+**Use AskUserQuestion tool** to gather:
+
+1. **Core Requirements**:
+   - What problem are we solving?
+   - Who are the users?
+   - What's the expected outcome?
+
+2. **User Experience**:
+   - What are the key user journeys?
+   - What actions will users perform?
+   - What edge cases exist?
+
+3. **Scope & Constraints**:
+   - What's IN scope vs OUT of scope?
+   - Any technical constraints to be aware of?
+   - Any compliance or security requirements?
+
+4. **Success Criteria**:
+   - How will we know this is successful?
+   - What metrics matter?
+   - What are the acceptance criteria?
+
+**Example Questions**:
+```
+1. Who is the primary user for this feature? (e.g., end users, admins, developers)
+
+2. What's the main problem this solves? (1-2 sentences)
+
+3. What are the key user actions? (e.g., "User logs in, sees dashboard, filters data")
+
+4. Are there any known constraints? (e.g., must work on mobile, needs to support 10k users)
+
+5. What's explicitly OUT of scope for v1? (helps clarify boundaries)
+```
+
+**Generate identifier now** if not done in Step 1.2.3:
+- Take first sentence of problem description
+- Generate slug
+- Update work folder name if needed
+
+---
+
+## ⚙️ PHASE 3: GENERATE PRODUCT SPECIFICATION
+
+### Step 3.1: Structure Specification Outline
+
+Create structured specification with these sections:
+
+```markdown
+# Product Specification: [Title]
+
+## 📋 Overview
+[What, Why, For Whom - 3-4 sentences]
+
+## 👥 Target Users
+[Primary, secondary users]
+
+## 🎯 Problem Statement
+[What problem we're solving, current pain points]
+
+## 💡 Proposed Solution
+[High-level solution approach, key features]
+
+## 📖 User Stories
+
+### Story 1: [Title]
+**As a** [user type]
+**I want to** [action]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+**Edge Cases**:
+- [Edge case 1]
+- [Edge case 2]
+
+[Repeat for each major user story]
+
+## 🎨 User Experience
+
+### User Journey 1: [Journey Name]
+1. User starts at [point]
+2. User performs [action]
+3. System responds with [response]
+4. User sees [outcome]
+
+[Repeat for key journeys]
+
+## ✅ Product Acceptance Criteria
+
+### Must Have (v1)
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Should Have (v1)
+- [ ] Criterion 1
+
+### Nice to Have (Future)
+- [ ] Criterion 1
+
+## 🔍 Scope & Decisions
+
+### In Scope ✅
+- Feature A
+- Feature B
+
+### Out of Scope ❌
+- Feature X (reason: future iteration)
+- Feature Y (reason: complexity)
+
+### Product Decisions Made
+- **Decision 1**: [Why we chose this]
+- **Decision 2**: [Why we chose this]
+
+## 🔗 Dependencies & Constraints
+
+### External Dependencies
+- [Third-party service, API, etc.]
+
+### User Constraints
+- [Browser support, device requirements]
+
+### Business Constraints
+- [Timeline, budget, compliance]
+
+### Known Limitations
+- [Technical or product limitations to be aware of]
+
+## 📊 Success Metrics
+
+### Key Performance Indicators
+- Metric 1: [target]
+- Metric 2: [target]
+
+### User Success Metrics
+- [How users measure success]
+
+## 🗂️ Related Resources
+
+### Context Files
+[List files in context/ folder]
+- wireframe.png - [brief description]
+- requirements.pdf - [brief description]
+
+### External References
+- Jira: [link]
+- Design doc: [link]
+- Discussion: [link]
+
+---
+
+**Next Steps**: Run `/schovi:analyze` to explore technical implementation options.
+```
+
+### Step 3.2: Write Specification Content
+
+Follow the outline above, filling in content based on:
+- Jira context (if available)
+- Supporting materials (images, docs)
+- Interactive answers (if gathered)
+
+**Key Principles**:
+1. **Non-technical** - No file:line references, no code mentions
+2. **User-focused** - Describe features from user perspective
+3. **Clear scope** - Explicit about what's IN vs OUT
+4. **Actionable criteria** - Testable acceptance criteria
+5. **Decision record** - Document why we chose this approach
+
+**Quality Check**:
+- [ ] Clear problem statement (why we're building this)
+- [ ] Defined target users
+- [ ] At least 2-3 user stories with acceptance criteria
+- [ ] Clear scope boundaries (in/out)
+- [ ] Success metrics defined
+- [ ] All supporting materials referenced
+
+---
+
+## ⚙️ PHASE 4: OUTPUT HANDLING
+
+### Step 4.1: Determine Output Path
+
+**Priority**:
+1. If `--output` flag: Use specified path
+2. If `--no-file`: Skip file output (terminal only)
+3. Default: Use `output_file` from Step 1.2 (work-folder library)
+
+```bash
+if [ -n "$outputPath" ]; then
+  final_output_file="$outputPath"
+elif [ "$noFile" = true ]; then
+  final_output_file=""  # Skip file output
+else
+  final_output_file="[output_file from Step 1.2]"  # e.g., .WIP/EC-1234/01-spec.md
+fi
+```
+
+### Step 4.2: Write Specification File
+
+If file output enabled:
+
+**Use Write tool**:
+- file_path: [final_output_file from Step 4.1]
+- content: [Full specification from Phase 3]
+
+### Step 4.3: Update Metadata
+
+**If work_folder exists and file was written:**
+
+Read current metadata:
+```bash
+cat [metadata_file from Step 1.2]
+```
+
+Update fields:
+```json
+{
+  ...existing fields,
+  "workflow": {
+    ...existing.workflow,
+    "completed": ["spec"],
+    "current": "spec"
+  },
+  "files": {
+    "spec": "01-spec.md",
+    "context": ["wireframe.png", "requirements.pdf"]
+  },
+  "timestamps": {
+    ...existing.timestamps,
+    "lastModified": "[current timestamp]"
+  }
+}
+```
+
+Get current timestamp:
+```bash
+date -u +"%Y-%m-%dT%H:%M:%SZ"
+```
+
+Write updated metadata:
+```
+Write tool:
+  file_path: [metadata_file from Step 1.2]
+  content: [updated JSON]
+```
+
+### Step 4.4: Post to Jira (if requested)
+
+If `--post-to-jira` flag AND Jira ID present:
+
+**Use mcp__jira__add_comment**:
+- issue_key: [jira-id]
+- comment: [Specification markdown or link to spec file]
+
+Format comment:
+```
+Product Specification Generated
+
+Specification saved to: .WIP/[identifier]/01-spec.md
+
+Key highlights:
+- [Target user]
+- [Core problem]
+- [Proposed solution]
+
+Next step: Run /schovi:analyze to explore technical implementation.
+```
+
+### Step 4.5: Display Results to User
+
+If not `--quiet`, show terminal output:
+
+```
+✅ Product specification complete!
+
+📁 Work folder: .WIP/[identifier]/
+📄 Specification: 01-spec.md
+📂 Supporting materials: [count] files in context/
+
+📋 Specification Summary:
+• Target Users: [primary user types]
+• Problem: [one-sentence problem]
+• Solution: [one-sentence solution]
+• User Stories: [count] stories defined
+• Acceptance Criteria: [count] criteria
+
+🎯 Scope:
+✅ In Scope: [count] features
+❌ Out of Scope: [count] items
+
+📊 Success Metrics:
+• [Metric 1]
+• [Metric 2]
+
+---
+
+📍 What You Have:
+✓ Product specification with user stories and acceptance criteria
+✓ Clear scope boundaries and product decisions
+✓ Success metrics defined
+
+🚀 Next Steps:
+1. Review spec: cat .WIP/[identifier]/01-spec.md
+2. Explore technical approaches: /schovi:analyze --input .WIP/[identifier]/01-spec.md
+3. Or iterate on spec if requirements change
+
+💡 Tip: The spec is non-technical - it focuses on WHAT and WHY.
+        Run analyze next to explore HOW to implement it.
+```
+
+If `--post-to-jira` succeeded:
+```
+✅ Posted to Jira: [jira-url]
+```
+
+---
+
+## 🔍 VALIDATION CHECKLIST
+
+Before completing, ensure:
+
+- [ ] Work folder created: `.WIP/[identifier]/`
+- [ ] Metadata initialized with workflow.type = "full"
+- [ ] Specification written to `01-spec.md`
+- [ ] Supporting materials copied to `context/`
+- [ ] Metadata updated with completed = ["spec"]
+- [ ] Clear problem statement and target users defined
+- [ ] At least 2-3 user stories with acceptance criteria
+- [ ] Scope boundaries (in/out) clearly defined
+- [ ] Success metrics specified
+- [ ] Next steps communicated to user
+
+---
+
+## 💡 USAGE EXAMPLES
+
+### Example 1: Spec from Jira Issue
+
+```bash
+/schovi:spec EC-1234
+
+# Workflow:
+# 1. Fetches Jira issue details
+# 2. Creates .WIP/EC-1234-[title-slug]/
+# 3. Generates spec from Jira description and acceptance criteria
+# 4. Saves to 01-spec.md
+# 5. Shows summary
+```
+
+### Example 2: Spec from Wireframes and Description
+
+```bash
+/schovi:spec "Build user dashboard" --input wireframe.png design-doc.pdf
+
+# Workflow:
+# 1. Creates .WIP/build-user-dashboard/
+# 2. Copies wireframe.png and design-doc.pdf to context/
+# 3. Analyzes images and documents
+# 4. Asks clarifying questions about requirements
+# 5. Generates comprehensive spec
+# 6. Saves to 01-spec.md with references to context files
+```
+
+### Example 3: Interactive Spec Generation
+
+```bash
+/schovi:spec
+
+# Workflow:
+# 1. Prompts for problem description
+# 2. Asks about target users
+# 3. Asks about key user actions
+# 4. Asks about scope and constraints
+# 5. Generates spec based on interactive answers
+# 6. Creates work folder with generated identifier
+# 7. Saves to 01-spec.md
+```
+
+### Example 4: Spec with Custom Output
+
+```bash
+/schovi:spec EC-1234 --output ~/docs/product-specs/auth-spec.md
+
+# Custom output location, not in .WIP/ folder
+```
+
+---
+
+## 🚫 ERROR HANDLING
+
+### No Requirements Found
+```
+❌ Cannot generate specification without requirements
+
+No Jira ID, description, or input files provided.
+
+Please provide ONE of:
+- Jira Issue: /schovi:spec EC-1234
+- Description: /schovi:spec "Build user authentication"
+- Files: /schovi:spec --input requirements.pdf wireframe.png
+- Interactive: /schovi:spec (will prompt for details)
+```
+
+### Invalid File Type
+```
+⚠️  Warning: Unsupported file type: file.xyz
+
+Supported types: .png, .jpg, .pdf, .md, .txt, .doc, .docx
+
+Skipping file.xyz...
+```
+
+### Jira Not Found
+```
+❌ Jira issue EC-9999 not found
+
+Please check:
+- Issue key is correct
+- You have access to the issue
+- MCP Jira server is configured
+
+Tip: Continue without Jira using description:
+/schovi:spec "Description of the feature"
+```
+
+---
+
+## 🎯 KEY PRINCIPLES
+
+1. **Product Focus** - This is about WHAT to build, not HOW
+2. **User-Centric** - Describe features from user perspective
+3. **Non-Technical** - No code, no files, no implementation details
+4. **Clear Boundaries** - Explicit scope (in/out)
+5. **Actionable** - Criteria should be testable
+6. **Decision Record** - Document why we chose this approach
+7. **Workflow Foundation** - Sets up analyze → plan → implement chain
+
+**Remember**: This is the first step in a full workflow. The spec should be detailed enough for the analyze command to explore technical approaches.