spec-add

# Spec Add Command ## Overview Unified command for adding specs one at a time. Supports both interactive wizard mode and direct CLI mode. **Key Features**: - Supports both project specs and personal specs - Scope selection (global vs project) for personal specs - Category-based organization for workflow stages - Interactive wizard mode with smart defaults - Direct CLI mode with auto-detection of type and category - Auto-confirm mode (`-y`/`--yes`) for scripted usage ## Use Cases 1. **During Session**: Capture important decisions as they're made 2. **After Session**: Reflect on lessons learned before archiving 3. **Proactive**: Add team conventions or architectural rules 4. **Interactive**: Guided wizard for adding rules with full control over dimension, scope, and category ## Usage ```bash $spec-add # Interactive wizard (all prompts) $spec-add --interactive # Explicit interactive wizard $spec-add "Use async/await instead of callbacks" # Direct mode (auto-detect type) $spec-add -y "No direct DB access" --type constraint # Auto-confirm, skip confirmation $spec-add --scope global --dimension personal # Create global personal spec (interactive) $spec-add --dimension specs --category exploration # Project spec in exploration category (interactive) $spec-add "Cache invalidation requires event sourcing" --type learning --category architecture ``` ## Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `rule` | string | Yes (unless `--interactive`) | - | The rule, convention, or insight to add | | `--type` | enum | No | auto-detect | Type: `convention`, `constraint`, `learning` | | `--category` | string | No | auto-detect / `general` | Category for organization (see categories below) | | `--dimension` | enum | No | Interactive | `specs` (project) or `personal` | | `--scope` | enum | No | `project` | `global` or `project` (only for personal dimension) | | `--interactive` | flag | No | - | Launch full guided wizard for adding rules | | `-y` / `--yes` | flag | No | - | Auto-categorize and add without confirmation | ### Type Categories **convention** - Coding style preferences (goes to `conventions` section) - Subcategories: `coding_style`, `naming_patterns`, `file_structure`, `documentation` **constraint** - Hard rules that must not be violated (goes to `constraints` section) - Subcategories: `architecture`, `tech_stack`, `performance`, `security` **learning** - Session-specific insights (goes to `learnings` array) - Subcategories: `architecture`, `performance`, `security`, `testing`, `process`, `other` ### Workflow Stage Categories (for `--category`) | Category | Use Case | Example Rules | |----------|----------|---------------| | `general` | Applies to all stages | "Use TypeScript strict mode" | | `exploration` | Code exploration, debugging | "Always trace the call stack before modifying" | | `planning` | Task planning, requirements | "Break down tasks into 2-hour chunks" | | `execution` | Implementation, testing | "Run tests after each file modification" | ## Execution Process ``` Input Parsing: |- Parse: rule text (positional argument, optional if --interactive) |- Parse: --type (convention|constraint|learning) |- Parse: --category (subcategory) |- Parse: --dimension (specs|personal) |- Parse: --scope (global|project) |- Parse: --interactive (flag) +- Parse: -y / --yes (flag) Step 1: Parse Input Step 2: Determine Mode |- If --interactive OR no rule text -> Full Interactive Wizard (Path A) +- If rule text provided -> Direct Mode (Path B) Path A: Interactive Wizard |- Step A1: Ask dimension (if not specified) |- Step A2: Ask scope (if personal + scope not specified) |- Step A3: Ask category (if not specified) |- Step A4: Ask type (convention|constraint|learning) |- Step A5: Ask content (rule text) +- Continue to Step 3 Path B: Direct Mode |- Step B1: Auto-detect type (if not specified) using detectType() |- Step B2: Auto-detect category (if not specified) using detectCategory() |- Step B3: Default dimension to 'specs' if not specified +- Continue to Step 3 Step 3: Determine Target File |- specs dimension -> .ccw/specs/coding-conventions.md or architecture-constraints.md +- personal dimension -> ~/.ccw/personal/ or .ccw/personal/ Step 4: Validate and Write Spec |- Ensure target directory and file exist |- Check for duplicates |- Append rule to appropriate section +- Run ccw spec rebuild Step 5: Display Confirmation +- If -y/--yes: Minimal output +- Otherwise: Full confirmation with location details ``` ## Implementation ### Step 1: Parse Input ```javascript // Parse arguments const args = "$ARGUMENTS" const argsLower = args.toLowerCase() // Extract flags const AUTO_YES = argsLower.includes('--yes') || argsLower.includes('-y') const isInteractive = argsLower.includes('--interactive') // Extract named parameters const hasType = argsLower.includes('--type') const hasCategory = argsLower.includes('--category') const hasDimension = argsLower.includes('--dimension') const hasScope = argsLower.includes('--scope') let type = hasType ? args.match(/--type\s+(\w+)/i)?.[1]?.toLowerCase() : null let category = hasCategory ? args.match(/--category\s+(\w+)/i)?.[1]?.toLowerCase() : null let dimension = hasDimension ? args.match(/--dimension\s+(\w+)/i)?.[1]?.toLowerCase() : null let scope = hasScope ? args.match(/--scope\s+(\w+)/i)?.[1]?.toLowerCase() : null // Extract rule text (everything before flags, or quoted string) let ruleText = args .replace(/--type\s+\w+/gi, '') .replace(/--category\s+\w+/gi, '') .replace(/--dimension\s+\w+/gi, '') .replace(/--scope\s+\w+/gi, '') .replace(/--interactive/gi, '') .replace(/--yes/gi, '') .replace(/-y\b/gi, '') .replace(/^["']|["']$/g, '') .trim() // Validate values if (scope && !['global', 'project'].includes(scope)) { console.log("Invalid scope. Use 'global' or 'project'.") return } if (dimension && !['specs', 'personal'].includes(dimension)) { console.log("Invalid dimension. Use 'specs' or 'personal'.") return } if (type && !['convention', 'constraint', 'learning'].includes(type)) { console.log("Invalid type. Use 'convention', 'constraint', or 'learning'.") return } if (category) { const validCategories = [ 'general', 'exploration', 'planning', 'execution', 'coding_style', 'naming_patterns', 'file_structure', 'documentation', 'architecture', 'tech_stack', 'performance', 'security', 'testing', 'process', 'other' ] if (!validCategories.includes(category)) { console.log(`Invalid category. Valid categories: ${validCategories.join(', ')}`) return } } ``` ### Step 2: Determine Mode ```javascript const useInteractiveWizard = isInteractive || !ruleText ``` ### Path A: Interactive Wizard ```javascript if (useInteractiveWizard) { // --- Step A1: Ask dimension (if not specified) --- if (!dimension) { if (AUTO_YES) { dimension = 'specs' // Default to project specs in auto mode } else { const dimensionAnswer = functions.request_user_input({ questions: [{ header: "Dimension", id: "dimension", question: "What type of spec do you want to create?", options: [ { label: "Project Spec(Recommended)", description: "Coding conventions, constraints, quality rules for this project (stored in .ccw/specs/)" }, { label: "Personal Spec", description: "Personal preferences and constraints that follow you across projects (stored in ~/.ccw/specs/personal/ or .ccw/specs/personal/)" } ] }] }) // BLOCKS (wait for user response) dimension = dimensionAnswer.answers.dimension.answers[0] === "Project Spec(Recommended)" ? "specs" : "personal" } } // --- Step A2: Ask scope (if personal + scope not specified) --- if (dimension === 'personal' && !scope) { if (AUTO_YES) { scope = 'project' // Default to project scope in auto mode } else { const scopeAnswer = functions.request_user_input({ questions: [{ header: "Scope", id: "scope", question: "Where should this personal spec be stored?", options: [ { label: "Global(Recommended)", description: "Apply to ALL projects (~/.ccw/specs/personal/)" }, { label: "Project-only", description: "Apply only to this project (.ccw/specs/personal/)" } ] }] }) // BLOCKS (wait for user response) scope = scopeAnswer.answers.scope.answers[0] === "Global(Recommended)" ? "global" : "project" } } // --- Step A3: Ask category (if not specified) --- if (!category) { if (AUTO_YES) { category = 'general' // Default to general in auto mode } else { const categoryAnswer = functions.request_user_input({ questions: [{ header: "Category", id: "category", question: "Which workflow stage does this spec apply to?", options: [ { label: "General(Recommended)", description: "Applies to all stages (default)" }, { label: "Exploration", description: "Code exploration, analysis, debugging" }, { label: "Planning", description: "Task planning, requirements gathering" } ] }] }) // BLOCKS (wait for user response) const categoryLabel = categoryAnswer.answers.category.answers[0] category = categoryLabel.includes("General") ? "general" : categoryLabel.includes("Exploration") ? "exploration" : categoryLabel.includes("Planning") ? "planning" : "execution" } } // --- Step A4: Ask type (if not specified) --- if (!type) { if (AUTO_YES) { type = 'convention' // Default to convention in auto mode } else { const typeAnswer = functions.request_user_input({ questions: [{ header: "Rule Type", id: "rule_type", question: "What type of rule is this?", options: [ { label: "Convention", description: "Coding style preference (e.g., use functional components)" }, { label: "Constraint", description: "Hard rule that must not be violated (e.g., no direct DB access)" }, { label: "Learning", description: "Insight or lesson learned (e.g., cache invalidation needs events)" } ] }] }) // BLOCKS (wait for user response) const typeLabel = typeAnswer.answers.rule_type.answers[0] type = typeLabel.includes("Convention") ? "convention" : typeLabel.includes("Constraint") ? "constraint" : "learning" } } // --- Step A5: Ask content (rule text) --- if (!ruleText) { if (AUTO_YES) { console.log("Error: Rule text is required in auto mode. Provide rule text as argument.") return } const contentAnswer = functions.request_user_input({ questions: [{ header: "Content", id: "content", question: "Enter the rule or guideline text:", options: [ { label: "Type in Other", description: "Enter your rule text via the Other input field" } ]