@paths.design/caws-cli 8.1.0 → 8.2.1

package/dist/templates/.claude/hooks/simplification-guard.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# CAWS Simplification Guard Hook
+# Detects when files are being stubbed out (large deletions + stub content)
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check Edit operations (modifications to existing files)
+if [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Get relative path (portable — macOS realpath lacks --relative-to)
+if [[ "$FILE_PATH" == "$PROJECT_DIR"/* ]]; then
+  REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Only check code files
+case "$REL_PATH" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs|*.py|*.rs|*.go|*.java|*.kt|*.swift|*.rb|*.php|*.c|*.cpp|*.h)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Check if the file exists in git (skip new files)
+if ! git show "HEAD:$REL_PATH" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Compare staged version with HEAD
+if command -v node >/dev/null 2>&1; then
+  SIMP_CHECK=$(node -e "
+    const { execFileSync } = require('child_process');
+    try {
+      const headContent = execFileSync('git', ['show', 'HEAD:$REL_PATH'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const currentContent = require('fs').readFileSync('$FILE_PATH', 'utf8');
+
+      const countLOC = (c) => c.split('\\n').filter(l => l.trim() && !l.trim().startsWith('//') && !l.trim().startsWith('#')).length;
+      const headLOC = countLOC(headContent);
+      const currentLOC = countLOC(currentContent);
+
+      if (headLOC < 10) { console.log('ok'); process.exit(0); }
+
+      const decrease = (headLOC - currentLOC) / headLOC;
+
+      // Check for stub patterns in new content
+      const stubPatterns = [/^\\s*pass\\s*$/m, /^\\s*\\.\\.\\.\\s*$/m, /raise\\s+NotImplementedError/,
+        /throw\\s+new\\s+Error.*not implemented/i, /\\/\\/\\s*TODO\\s*$/m, /#\\s*TODO\\s*$/m];
+      const hasStubs = stubPatterns.some(p => p.test(currentContent));
+
+      if (decrease >= 0.3 && hasStubs) {
+        console.log('simplified:' + Math.round(decrease * 100) + ':' + headLOC + ':' + currentLOC);
+      } else {
+        console.log('ok');
+      }
+    } catch (error) {
+      console.log('ok');
+    }
+  " 2>&1)
+
+  if [[ "$SIMP_CHECK" == simplified:* ]]; then
+    IFS=':' read -r _ PERCENT OLD_LOC NEW_LOC <<< "$SIMP_CHECK"
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "WARNING: This edit would reduce '"$REL_PATH"' by '"$PERCENT"'% ('"$OLD_LOC"' → '"$NEW_LOC"' LOC) and introduces stub patterns (pass, TODO, NotImplementedError). This looks like a simplification — implementations should be modified, not replaced with stubs. Please confirm this is intentional."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# Allow the edit
+exit 0

package/dist/templates/.cursor/README.md

@@ -156,9 +156,6 @@ ls -la .cursor/hooks/
 # Install CAWS CLI
 npm install -g @caws/cli
 
-# Or use bundled version (VS Code extension)
-code --install-extension caws.caws-vscode-extension
-
 # Verify PATH
 which caws
 ```

package/dist/templates/.github/copilot-instructions.md

@@ -0,0 +1,82 @@
+# CAWS Integration Instructions for GitHub Copilot
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured AI-assisted development.
+
+## CAWS Project Detection
+
+Check if current project uses CAWS:
+- Look for `.caws/working-spec.yaml` file
+- Check for `caws` commands in package.json scripts
+- Verify CAWS CLI availability: `caws --version`
+
+## Working Specifications
+
+Working specs define project requirements and constraints:
+
+```yaml
+id: PROJ-001
+title: "Feature implementation"
+risk_tier: 2  # 1=Critical, 2=Standard, 3=Low risk
+mode: feature  # feature|refactor|fix|chore
+change_budget:
+  max_files: 25
+  max_loc: 1000
+scope:
+  in: ["src/", "tests/"]
+  out: ["node_modules/", "dist/"]
+```
+
+Always validate working specs: `caws validate`
+
+## Quality Workflow
+
+1. **Before implementation**: `caws agent iterate --current-state "describe what you're about to do"`
+2. **During implementation**: `caws agent evaluate --quiet`
+3. **Before commit**: `caws validate && caws agent evaluate`
+
+## Quality Gates by Risk Tier
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+## Key Rules
+
+1. Stay within `scope.in` boundaries -- do not edit files in `scope.out`
+2. Respect `change_budget.max_files` and `change_budget.max_loc` limits
+3. No shadow files -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*` copies
+4. Write tests before implementation when possible
+5. Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+
+## Waivers
+
+If you need to bypass a quality gate, create a waiver:
+
+```bash
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
+
+## Common Patterns
+
+### Feature Development
+1. Validate working spec: `caws validate`
+2. Get implementation guidance: `caws agent iterate`
+3. Implement with quality checks: `caws agent evaluate --quiet`
+4. Run full validation: `caws validate && npm test`
+
+### Bug Fixes
+1. Assess risk tier and impact
+2. Write failing test that reproduces the bug
+3. Implement minimal fix
+4. Run quality validation: `caws validate`
+
+## Troubleshooting
+
+- **Working spec invalid**: Run `caws validate --suggestions`
+- **Scope violations**: Update `.caws/working-spec.yaml` scope or create waiver
+- **Quality gate failures**: Address root cause rather than creating waivers

package/dist/templates/.junie/guidelines.md

@@ -0,0 +1,73 @@
+# Junie Guidelines - CAWS Project
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured development.
+
+## Working Spec
+
+Before making changes, read `.caws/working-spec.yaml`. It defines:
+
+- **Risk tier**: Quality requirements (T1: 90%+ coverage, T2: 80%+, T3: 70%+)
+- **Scope**: `scope.in` lists files you may edit, `scope.out` is off-limits
+- **Change budget**: Maximum files and lines of code per change
+- **Acceptance criteria**: What "done" means for this task
+
+## CAWS Commands
+
+```bash
+caws validate                    # Validate the working spec
+caws agent iterate               # Get implementation guidance
+caws agent evaluate              # Evaluate quality compliance
+caws waivers create --reason ... # Create waiver for justified exceptions
+```
+
+## Key Rules
+
+1. **Stay in scope** -- only edit files listed in `scope.in`
+2. **Respect change budgets** -- stay within `max_files` and `max_loc`
+3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. **Tests first** -- write failing tests before implementation
+5. **Deterministic code** -- inject time, random, and UUID generators for testability
+6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. **Conventional commits** -- use `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` prefixes
+
+## Quality Gates
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+## Code Style
+
+- Prefer `const` over `let`
+- Use guard clauses and early returns over deep nesting
+- Single responsibility: one reason to change per module
+- Depend on abstractions, not concretions
+- Extension points over editing internals (open/closed principle)
+- Max cyclomatic complexity per function: 10
+- Max cognitive complexity: 15
+- Max nesting depth: 4
+- Max function length: 50 lines
+- Max file length: 1000 lines
+- Max parameters: 5
+- No emojis in production code or logs
+- Check if a server/process is already running before starting another
+
+### Naming
+
+Forbidden file name modifiers: enhanced, unified, better, new, next, final, copy, revamp, improved. Prefer in-place edits with a merge-then-delete strategy for refactors.
+
+## Build & Test
+
+```bash
+npm install          # Install dependencies
+npm test             # Run tests
+npm run lint         # Lint code
+npm run typecheck    # Type check (if TypeScript)
+caws validate        # Validate CAWS spec
+```

package/dist/templates/.vscode/launch.json

@@ -1,33 +1,6 @@
 {
   "version": "0.2.0",
   "configurations": [
-    {
-      "name": "Run CAWS Extension",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension"],
-      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
-    },
-    {
-      "name": "Run CAWS Extension (Host Workspace)",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/caws-vscode-extension", "${workspaceFolder}"],
-      "outFiles": ["${workspaceFolder}/packages/caws-vscode-extension/out/**/*.js"],
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:watch"
-    },
-    {
-      "name": "Debug CAWS Extension",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/packages/caws-vscode-extension/out/extension.js",
-      "args": ["--inspect=6009"],
-      "env": {
-        "CAWS_DEBUG": "true"
-      },
-      "preLaunchTask": "${workspaceFolder}/packages/caws-vscode-extension:compile"
-    },
     {
       "name": "Debug MCP Server",
       "type": "node",

package/dist/templates/.windsurf/rules/caws-quality-standards.md

@@ -0,0 +1,54 @@
+# CAWS Quality Standards
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured development.
+
+## Working Spec
+
+Always check `.caws/working-spec.yaml` before making changes. It defines:
+
+- **Risk tier**: T1 (critical, 90%+ coverage), T2 (standard, 80%+), T3 (low risk, 70%+)
+- **Scope boundaries**: `scope.in` (allowed files), `scope.out` (off-limits)
+- **Change budget**: `max_files` and `max_loc` limits per change
+- **Acceptance criteria**: Definition of done
+
+## Key Rules
+
+1. Stay within scope boundaries defined in the working spec
+2. Respect change budgets -- split large changes into smaller PRs
+3. No shadow files: never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. Write tests before implementation when possible
+5. Deterministic code -- inject time, random, and UUID generators for testability
+6. No fake implementations -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. Prove claims -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. No marketing language in docs -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. Ask first for risky changes -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+11. Run `caws validate` before committing
+
+## Quality Commands
+
+```bash
+caws validate                    # Validate working spec
+caws agent iterate               # Get implementation guidance
+caws agent evaluate              # Evaluate quality compliance
+caws waivers create --reason ... # Create waiver for justified exceptions
+```
+
+## Code Style
+
+- Prefer `const` over `let`
+- Use guard clauses and early returns over deep nesting
+- Single responsibility: one reason to change per module
+- Depend on abstractions, not concretions
+- Extension points over editing internals (open/closed principle)
+- Max cyclomatic complexity per function: 10
+- Max nesting depth: 4
+- Max function length: 50 lines
+- Max file length: 1000 lines
+- Max parameters: 5
+- No emojis in production code or logs
+- Check if a server/process is already running before starting another
+
+## Naming
+
+Forbidden file name modifiers: enhanced, unified, better, new, next, final, copy, revamp, improved. Use in-place edits with merge-then-delete strategy for refactors.

package/dist/templates/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This project uses CAWS (Coding Agent Working Standard) for quality-assured AI-assisted development.
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Type check (if TypeScript)
+npm run typecheck
+
+# Run all quality gates
+caws validate
+```
+
+## CAWS Workflow
+
+Before writing code, check the working spec:
+
+```bash
+# Validate the working spec
+caws validate
+
+# Get iteration guidance
+caws agent iterate --current-state "describe what you're about to do"
+
+# After implementation, evaluate quality
+caws agent evaluate
+```
+
+### Working Spec
+
+The project spec lives at `.caws/working-spec.yaml`. It defines:
+
+- **Risk tier**: Quality requirements (T1: critical, T2: standard, T3: low risk)
+- **Scope**: Which files you can edit (`scope.in`) and which are off-limits (`scope.out`)
+- **Change budget**: Max files and lines of code per change
+- **Acceptance criteria**: What "done" means
+
+Always stay within scope boundaries and change budgets.
+
+### Quality Gates
+
+Quality requirements are tiered:
+
+| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
+|------|---------------|----------------|----------------|
+| Test coverage | 90%+ | 80%+ | 70%+ |
+| Mutation score | 70%+ | 50%+ | 30%+ |
+| Contracts | Required | Required | Optional |
+| Manual review | Required | Optional | Optional |
+
+### Key Rules
+
+1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
+2. **Respect change budgets** -- stay within `max_files` and `max_loc` limits
+3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
+4. **Tests first** -- write failing tests before implementation
+5. **Deterministic code** -- inject time, random, and UUID generators for testability
+6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
+7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence, not assertions.
+8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade"
+9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion first
+10. **Conventional commits** -- use `feat:`, `fix:`, `refactor:`, `docs:`, `chore:` prefixes
+
+### Waivers
+
+If you need to bypass a quality gate, create a waiver with justification:
+
+```bash
+caws waivers create --reason emergency_hotfix --gates coverage_threshold
+```
+
+Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
+
+## Project Structure
+
+```
+.caws/
+  working-spec.yaml   # Project spec (risk tier, scope, acceptance criteria)
+  policy.yaml         # Quality policy overrides (optional)
+  waivers.yml         # Active waivers
+```
+
+## Hooks
+
+This project has Claude Code hooks configured in `.claude/settings.json`:
+
+- **PreToolUse**: Blocks dangerous commands, scans for secrets, enforces scope
+- **PostToolUse**: Runs quality checks, validates spec, checks naming conventions
+- **Session**: Audit logging for provenance tracking
+
+See `.claude/README.md` for hook details.