@codihaus/claude-skills 1.6.2 → 1.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {

package/skills/debrief/references/change-request-template.md

@@ -20,6 +20,7 @@ Examples:
 > **Status**: Draft | Under Review | Approved | Rejected | Implemented
 > **Requestor**: {Customer name or internal}
 > **Priority**: Low | Medium | High | Critical
+> **Affected Features**: [[feature-xxx]], [[feature-yyy]]
 
 ## Request Summary
 {One-line summary of what is being requested}
@@ -35,17 +36,17 @@ Examples:
 ### New Use Cases
 | ID | Title | Priority |
 |----|-------|----------|
-| [UC-XXX-NNN](../use-cases/UC-XXX-NNN-slug.md) | {Title} | Must/Should/Could |
+| [[uc-xxx-nnn]] | {Title} | Must/Should/Could |
 
 ### Modified Use Cases
 | ID | Current | Proposed Change |
 |----|---------|-----------------|
-| [UC-XXX-001](../use-cases/UC-XXX-001-slug.md) | {Current behavior} | {New behavior} |
+| [[uc-xxx-001]] | {Current behavior} | {New behavior} |
 
 ### Deprecated Use Cases
 | ID | Reason |
 |----|--------|
-| UC-XXX-NNN | {Why being removed} |
+| [[uc-xxx-nnn]] | {Why being removed} |
 
 ### Affected Features
 | Feature | Impact |
@@ -99,8 +100,8 @@ When CR is created, add to BRD README.md:
 
 | CR | Title | Date | Status |
 |----|-------|------|--------|
-| [CR-001](./changes/CR-001-add-sso.md) | Add SSO | 2024-01-20 | Approved |
-| [CR-002](./changes/CR-002-update-tiers.md) | Update Tiers | 2024-01-25 | Draft |
+| [[cr-001]] | Add SSO | 2024-01-20 | Approved |
+| [[cr-002]] | Update Tiers | 2024-01-25 | Draft |
 ```
 
 ## Updating Changelog
@@ -109,9 +110,9 @@ When CR is implemented:
 
 ```markdown
 ## 2024-01-20 - CR-001 Implemented
-- Added SSO authentication ([CR-001](./changes/CR-001-add-sso.md))
-- New use cases: UC-AUTH-004, UC-AUTH-005
-- Modified: UC-AUTH-001 (added SSO option)
+- Added SSO authentication ([[cr-001]])
+- New use cases: [[uc-auth-004]], [[uc-auth-005]]
+- Modified: [[uc-auth-001]] (added SSO option)
 ```
 
 ## Linking from Use Cases
@@ -120,5 +121,5 @@ In modified use cases, add reference:
 
 ```markdown
 ## Change History
-- [CR-001](../changes/CR-001-add-sso.md): Added SSO as login option
+- [[cr-001]]: Added SSO as login option
 ```

package/skills/debrief/references/use-case-template.md

@@ -15,8 +15,8 @@ Examples:
 ```markdown
 # UC-{GROUP}-{NNN}: {Title}
 
-> **Group**: [{Group Name}](../README.md#{group-anchor})
-> **Related**: [UC-XXX-NNN](./UC-XXX-NNN-slug.md)
+> **Feature**: [[feature-{name}]]
+> **Related**: [[uc-xxx-nnn]], [[uc-xxx-nnn]]
 > **Priority**: Must | Should | Could
 > **Status**: Draft | Confirmed | Updated
 
@@ -97,8 +97,8 @@ so that {benefit}.
 ```markdown
 # UC-PAY-001: Checkout
 
-> **Group**: [Payments](../README.md#payments)
-> **Related**: [UC-PAY-002](./UC-PAY-002-apply-coupon.md)
+> **Feature**: [[feature-billing]]
+> **Related**: [[uc-pay-002]], [[uc-cart-001]]
 > **Priority**: Must
 > **Status**: Draft
 

package/src/utils/config.js

@@ -41,70 +41,86 @@ const DEFAULT_SETTINGS = {
       "Edit(*)"
     ],
     deny: []
+  },
+  hooks: {
+    PostToolUse: [
+      {
+        matcher: "Write|Edit",
+        hooks: [
+          {
+            type: "command",
+            command: "jq -r '.tool_input.file_path // empty' | xargs -I {} bash .claude/scripts/safe-graph-update.sh '{}'"
+          }
+        ]
+      }
+    ]
   }
 };
 
-/**
- * Hooks for automatic graph updates
- *
- * IMPORTANT: Hooks should be resilient and fail gracefully.
- * - Use `|| true` to prevent hook failures from blocking Claude
- * - Add retry limits to prevent infinite loops
- * - Keep hooks fast (< 2 seconds) to avoid slowing down workflow
- */
-const DEFAULT_HOOKS = {
-  postToolUse: [
-    {
-      matcher: {
-        toolName: "Write|Edit",
-        path: "plans/**/*.md"     // Only trigger on .md files in plans/
-      },
-      command: "bash .claude/scripts/safe-graph-update.sh $PATH",
-      // Retry configuration (Claude Code built-in support)
-      retries: {
-        maxAttempts: 3,           // Max 3 attempts total
-        backoff: "exponential",    // Wait longer between retries
-        failureAction: "warn"      // Show warning but don't block
-      },
-      timeout: 5000  // 5 second timeout per attempt
-    }
-  ]
-};
+// Hooks are now configured in settings.json (see DEFAULT_SETTINGS)
 
 /**
  * Set up Claude Code settings
+ * Creates TWO files:
+ * - settings.json (with hooks, checked into git)
+ * - settings.local.json (with permissions, gitignored)
  */
 export async function setupSettings(projectPath, options = {}) {
   const claudePath = path.join(projectPath, '.claude');
-  const settingsPath = path.join(claudePath, 'settings.local.json');
+  const settingsPath = path.join(claudePath, 'settings.json');
+  const settingsLocalPath = path.join(claudePath, 'settings.local.json');
 
   await fs.ensureDir(claudePath);
 
-  let settings = DEFAULT_SETTINGS;
+  // Create settings.json with hooks (for team, checked in)
+  const settingsJsonContent = {
+    hooks: DEFAULT_SETTINGS.hooks
+  };
+
+  await fs.writeJson(settingsPath, settingsJsonContent, { spaces: 2 });
+
+  // Create/update settings.local.json with permissions (personal, gitignored)
+  let localSettings = {
+    permissions: DEFAULT_SETTINGS.permissions
+  };
 
   // Merge with existing if present
-  if (await fs.pathExists(settingsPath)) {
+  if (await fs.pathExists(settingsLocalPath)) {
     try {
-      const existing = await fs.readJson(settingsPath);
-      settings = mergeSettings(existing, settings);
+      const existing = await fs.readJson(settingsLocalPath);
+      localSettings = {
+        permissions: {
+          allow: [...new Set([
+            ...(existing.permissions?.allow || []),
+            ...(DEFAULT_SETTINGS.permissions?.allow || [])
+          ])],
+          deny: [...new Set([
+            ...(existing.permissions?.deny || []),
+            ...(DEFAULT_SETTINGS.permissions?.deny || [])
+          ])]
+        }
+      };
     } catch (e) {
       // Invalid JSON, use defaults
     }
   }
 
-  await fs.writeJson(settingsPath, settings, { spaces: 2 });
+  await fs.writeJson(settingsLocalPath, localSettings, { spaces: 2 });
 
-  return { path: settingsPath, settings };
+  return {
+    settingsPath,
+    settingsLocalPath,
+    settings: { ...settingsJsonContent, ...localSettings }
+  };
 }
 
 /**
- * Set up hooks
+ * Set up hook scripts (hooks config is in settings.json)
  */
 export async function setupHooks(projectPath, options = {}) {
   if (options.noHooks) return null;
 
   const claudePath = path.join(projectPath, '.claude');
-  const hooksPath = path.join(claudePath, 'hooks.json');
   const claudeScriptsPath = path.join(claudePath, 'scripts');
 
   await fs.ensureDir(claudePath);
@@ -124,27 +140,14 @@ export async function setupHooks(projectPath, options = {}) {
     }
   }
 
-  let hooks = DEFAULT_HOOKS;
-
-  // Merge with existing if present
-  if (await fs.pathExists(hooksPath)) {
-    try {
-      const existing = await fs.readJson(hooksPath);
-      hooks = mergeHooks(existing, hooks);
-    } catch (e) {
-      // Invalid JSON, use defaults
-    }
-  }
+  // Copy graph.py to .claude/scripts/ (for docs-graph hook)
+  const graphSource = path.join(__dirname, '../../project-scripts/graph.py');
+  const graphDest = path.join(claudeScriptsPath, 'graph.py');
 
-  // Update command to use safe wrapper if it exists
-  if (hooks.postToolUse && hooks.postToolUse[0]) {
-    if (await fs.pathExists(wrapperDest)) {
-      hooks.postToolUse[0].command = "bash .claude/scripts/safe-graph-update.sh $PATH";
-    }
+  if (await fs.pathExists(graphSource)) {
+    await fs.copy(graphSource, graphDest);
   }
 
-  await fs.writeJson(hooksPath, hooks, { spaces: 2 });
-
   // Copy hooks guide documentation
   const hooksGuideSource = path.join(TEMPLATES_PATH, 'hooks-guide.md');
   const hooksGuideDest = path.join(claudePath, 'hooks-guide.md');
@@ -153,7 +156,7 @@ export async function setupHooks(projectPath, options = {}) {
     await fs.copy(hooksGuideSource, hooksGuideDest);
   }
 
-  return { path: hooksPath, hooks };
+  return { scriptsPath: claudeScriptsPath };
 }
 
 /**
@@ -292,32 +295,4 @@ export async function updateGitignore(projectPath) {
   return { action: 'created' };
 }
 
-/**
- * Merge settings objects
- */
-function mergeSettings(existing, defaults) {
-  return {
-    permissions: {
-      allow: [...new Set([
-        ...(existing.permissions?.allow || []),
-        ...(defaults.permissions?.allow || [])
-      ])],
-      deny: [...new Set([
-        ...(existing.permissions?.deny || []),
-        ...(defaults.permissions?.deny || [])
-      ])]
-    }
-  };
-}
-
-/**
- * Merge hooks objects
- */
-function mergeHooks(existing, defaults) {
-  // For now, just use defaults if hooks exist
-  // More sophisticated merging could be added
-  return {
-    ...defaults,
-    ...existing
-  };
-}
+// mergeSettings and mergeHooks removed - settings split into settings.json and settings.local.json

package/templates/hooks-guide.md

@@ -52,10 +52,10 @@ Always append `|| true` to prevent hook failures from blocking:
 
 ```bash
 # Good - fails gracefully
-python3 scripts/graph.py --check-path $PATH || true
+python3 .claude/scripts/graph.py --check-path $PATH || true
 
 # Bad - failure blocks Claude
-python3 scripts/graph.py --check-path $PATH
+python3 .claude/scripts/graph.py --check-path $PATH
 ```
 
 ### 3. Add Timeout Guards
@@ -64,7 +64,7 @@ Protect against hanging commands:
 
 ```json
 {
-  "command": "timeout 10s python3 scripts/graph.py --check-path $PATH || true",
+  "command": "timeout 10s python3 .claude/scripts/graph.py --check-path $PATH || true",
   "timeout": 15000
 }
 ```
@@ -138,7 +138,7 @@ Check if required tools exist before running:
 
 ```json
 {
-  "command": "command -v python3 >/dev/null 2>&1 && python3 scripts/graph.py --check-path $PATH || true"
+  "command": "command -v python3 >/dev/null 2>&1 && python3 .claude/scripts/graph.py --check-path $PATH || true"
 }
 ```
 
@@ -153,12 +153,12 @@ if ! command -v python3 &> /dev/null; then
   exit 0
 fi
 
-if [ ! -f "scripts/graph.py" ]; then
+if [ ! -f ".claude/scripts/graph.py" ]; then
   echo "graph.py not found, skipping"
   exit 0
 fi
 
-timeout 10s python3 scripts/graph.py --check-path "$1" || true
+timeout 10s python3 .claude/scripts/graph.py --check-path "$1" || true
 ```
 
 Then in hooks.json:
@@ -182,7 +182,7 @@ Choose the right `failureAction` based on hook criticality:
 **Example - Non-critical hook:**
 ```json
 {
-  "command": "python3 scripts/graph.py --check-path $PATH || true",
+  "command": "python3 .claude/scripts/graph.py --check-path $PATH || true",
   "retries": {
     "maxAttempts": 3,
     "failureAction": "warn"
@@ -209,7 +209,7 @@ If a hook keeps failing:
 
 Claude Code logs hook output. Look for:
 ```
-[Hook Failed] postToolUse: python3 scripts/graph.py
+[Hook Failed] postToolUse: python3 .claude/scripts/graph.py
 Exit code: 1
 Stderr: ModuleNotFoundError: No module named 'networkx'
 ```
@@ -219,7 +219,7 @@ Stderr: ModuleNotFoundError: No module named 'networkx'
 Run the hook command directly:
 ```bash
 cd /path/to/project
-python3 scripts/graph.py --check-path plans/brd/README.md
+python3 .claude/scripts/graph.py --check-path plans/brd/README.md
 ```
 
 ### 3. Common Issues
@@ -244,7 +244,7 @@ To temporarily disable a problematic hook:
         "toolName": "Write|Edit",
         "path": "plans/**/*"
       },
-      "command": "python3 scripts/graph.py --check-path $PATH || true",
+      "command": "python3 .claude/scripts/graph.py --check-path $PATH || true",
       "enabled": false
     }
   ]
@@ -287,10 +287,10 @@ set -e
 command -v python3 >/dev/null 2>&1 || exit 0
 
 # Exit early if script missing
-[ -f "scripts/graph.py" ] || exit 0
+[ -f ".claude/scripts/graph.py" ] || exit 0
 
 # Run with timeout and graceful failure
-timeout 10s python3 scripts/graph.py --check-path "$1" || {
+timeout 10s python3 .claude/scripts/graph.py --check-path "$1" || {
   echo "Graph update failed (non-critical), continuing..."
   exit 0
 }
@@ -304,7 +304,7 @@ timeout 10s python3 scripts/graph.py --check-path "$1" || {
 {
   "postToolUse": [{
     "matcher": { "toolName": "Write|Edit", "path": "plans/**/*" },
-    "command": "python3 scripts/graph.py --check-path $PATH"
+    "command": "python3 .claude/scripts/graph.py --check-path $PATH"
   }]
 }
 ```

package/templates/scripts/safe-graph-update.sh

@@ -13,7 +13,7 @@ set -e
 
 # Configuration
 TIMEOUT_SECONDS=10
-GRAPH_SCRIPT="scripts/graph.py"
+GRAPH_SCRIPT=".claude/scripts/graph.py"
 MAX_RETRIES=0  # Let Claude Code handle retries
 
 # Colors for output (optional)