@codihaus/claude-skills 1.6.9 → 1.6.11

package/package.json

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

package/skills/_registry.md

@@ -22,9 +22,10 @@ Central registry of all available skills. Reference this to suggest relevant ski
 | Skill | Purpose | Called By |
 |-------|---------|-----------|
 | `/utils/diagram` | Create/validate Mermaid diagrams | `/dev-scout`, `/dev-specs`, `/dev-arch` |
-| `/utils/docs-graph` | View documentation relationships | `/debrief`, `/dev-specs`, `/dev-arch` |
 | `/utils/gemini` | Large context scanning (1M tokens) | `/dev-scout` for large codebases |
 
+**Note:** Documentation graph (`docs-graph.json`) is automatically updated by Claude Code hook, not a skill.
+
 ## Skill Flow
 
 ```
@@ -66,9 +67,6 @@ Need to document what was built?
 
 Need to visualize something?
     → /utils/diagram (usually called by other skills)
-
-Need to see doc relationships?
-    → /utils/docs-graph (usually called by other skills)
 ```
 
 ## Trigger Phrases
@@ -86,7 +84,6 @@ When user says... → Suggest skill
 | "review my code", "check this PR" | `/dev-review` |
 | "what was built", "summarize changes", "document implementation" | `/dev-changelog` |
 | "create diagram", "architecture diagram", "flow chart" | `/utils/diagram` |
-| "what links to this", "doc relationships" | `/utils/docs-graph` |
 
 ## Cross-Skill Suggestions
 
@@ -147,11 +144,6 @@ During each skill, consider suggesting:
 - Called by other skills, not typically invoked directly
 - Used for: architecture diagrams, flow charts, ERD
 
-### /utils/docs-graph
-- Utility skill for documentation relationships
-- Called by other skills to understand dependencies
-- Auto-updated by Claude Code hooks
-
 ## Quality Attributes
 
 All skills reference `skills/_quality-attributes.md` for their respective level:

package/skills/debrief/SKILL.md

@@ -10,7 +10,7 @@ version: 3.9.0
 > - **Before**: Use `/dev-scout` if existing codebase
 > - **During**: Calls `/dev-arch` to validate architecture feasibility
 > - **After**: Use `/dev-specs` for implementation plans
-> - **Utils**: `/utils/docs-graph` for relationships
+> - **Auto**: `docs-graph.json` updated by hook for relationships
 
 Create and maintain the unified BRD for a project. Handles initial requirements and feature additions.
 

package/templates/hooks-guide.md

@@ -158,13 +158,15 @@ if [ ! -f ".claude/scripts/graph.py" ]; then
   exit 0
 fi
 
-timeout 10s python3 .claude/scripts/graph.py --check-path "$1" || true
+# Full regeneration (scans all files in plans/)
+timeout 180s python3 .claude/scripts/graph.py || true
 ```
 
 Then in settings.json:
 ```json
 {
-  "command": "bash .claude/scripts/safe-graph-update.sh $PATH"
+  "command": "bash .claude/scripts/safe-graph-update.sh $PATH",
+  "timeout": 180000
 }
 ```
 
@@ -182,7 +184,8 @@ Choose the right `failureAction` based on hook criticality:
 **Example - Non-critical hook:**
 ```json
 {
-  "command": "python3 .claude/scripts/graph.py --check-path $PATH || true",
+  "command": "timeout 180 python3 .claude/scripts/graph.py || true",
+  "timeout": 180000,
   "retries": {
     "maxAttempts": 3,
     "failureAction": "warn"

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

@@ -5,18 +5,17 @@
 # This script provides resilient execution of graph.py with:
 # - Dependency checking
 # - Graceful failure handling
-# - Timeout protection
-# - Clear error messages
+# - Timeout protection (3 minutes)
+# - Full regeneration of graph from all files in plans/
 #
 
 set -e
 
 # Configuration
-TIMEOUT_SECONDS=10
+TIMEOUT_SECONDS=180  # 3 minutes
 # Get the directory where this script is located
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 GRAPH_SCRIPT="$SCRIPT_DIR/graph.py"
-MAX_RETRIES=0  # Let Claude Code handle retries
 
 # Colors for output (optional)
 RED='\033[0;31m'
@@ -49,8 +48,8 @@ if [[ ! "$FILE_PATH" =~ ^plans/.*\.md$ ]]; then
     exit 0
 fi
 
-# Run graph.py with timeout
-if timeout "$TIMEOUT_SECONDS" python3 "$GRAPH_SCRIPT" --check-path "$FILE_PATH" 2>/dev/null; then
+# Run full graph regeneration (no --check-path, scans all files)
+if timeout "$TIMEOUT_SECONDS" python3 "$GRAPH_SCRIPT" 2>/dev/null; then
     # Success - silent
     exit 0
 else

package/skills/utils/docs-graph/SKILL.md

@@ -1,204 +0,0 @@
----
-name: utils/docs-graph
-description: View and query the documentation knowledge graph
-version: 1.2.0
----
-
-# /utils/docs-graph - Documentation Graph Viewer
-
-> **Skill Awareness**: See `skills/_registry.md` for all available skills.
-> - **Auto-updated**: By Claude Code hook on Write/Edit to plans/
-> - **Called by**: `/dev-specs`, `/debrief`, `/dev-arch` for relationships
-> - **Note**: Utility skill, typically called by other skills
-
-View and query relationships between planning documents.
-
-## When to Use
-
-- See overview of all plans and their relationships
-- Find related documents before making changes
-- Check impact of changes (what links to this?)
-- Verify graph is up-to-date
-
-## Usage
-
-```
-/utils/docs-graph                    # Show graph summary
-/utils/docs-graph auth               # Show nodes related to "auth"
-/utils/docs-graph --regenerate       # Force regenerate graph
-/utils/docs-graph --check            # Verify all links resolve
-```
-
-## How It Works
-
-The graph is automatically updated via Claude Code hooks whenever files in `plans/` are created or modified. This skill provides on-demand viewing and querying.
-
-### Automatic Updates
-
-PostToolUse hook triggers on Write/Edit to plans/:
-1. Hook detects file path contains `plans/`
-2. Runs `python3 scripts/graph.py --check-path <path>`
-3. Graph files updated before next Claude action
-
-### Graph Files
-
-```
-plans/
-├── docs-graph.json    # Machine-readable graph data
-└── docs-graph.md      # Mermaid visualization
-```
-
-## Workflow
-
-### Phase 1: Load Graph
-
-1. Check if `plans/docs-graph.json` exists
-2. If not, run `python3 scripts/graph.py` to generate
-3. Read graph data
-
-### Phase 2: Display or Query
-
-**Summary mode (default):**
-- Show node count by type
-- Show edge count
-- Display mermaid diagram from docs-graph.md
-- List any errors
-
-**Query mode (with argument):**
-- Filter nodes matching query
-- Show incoming links (what references this)
-- Show outgoing links (what this references)
-
-**Regenerate mode (--regenerate):**
-- Force full rescan of plans/
-- Update docs-graph.json and docs-graph.md
-- Show diff if changes detected
-
-**Check mode (--check):**
-- Verify all wikilinks resolve to existing nodes
-- Report broken links
-- Suggest fixes
-
-### Phase 3: Output
-
-Display results with:
-- Mermaid diagram (if summary)
-- Table of matching nodes (if query)
-- Broken link report (if check)
-
-## Wikilink Convention
-
-Documents use `[[wikilinks]]` to reference each other:
-
-```markdown
-# UC-AUTH-001: Login
-
-> **Feature**: [[feature-auth]]
-> **Related**: [[uc-auth-002]], [[uc-auth-003]]
-> **Spec**: [[spec-auth-001]]
-```
-
-**Link ID format:**
-- Use cases: `[[uc-auth-001]]` (lowercase, no slug)
-- Features: `[[feature-auth]]`
-- Specs: `[[spec-auth-001]]`
-- Change requests: `[[cr-001]]`
-
-## Node Types
-
-| Type | Source | Shape (Mermaid) |
-|------|--------|-----------------|
-| brd | `brd/README.md` | Stadium `[[]]` |
-| use-case | `brd/use-cases/**/*.md` | Rectangle `[]` |
-| change-request | `brd/changes/*.md` | Hexagon `{{}}` |
-| feature | `features/*/README.md` | Pill `([])` |
-| spec | `features/*/specs/**/*.md` | Parallelogram `[//]` |
-| scout | `**/scout.md` | Cylinder `[()]` |
-
-## Example Output
-
-### Summary
-
-```
-Documentation Graph Summary
-===========================
-Nodes: 12 | Edges: 18
-
-By Type:
-  use-case: 5
-  feature: 2
-  spec: 4
-  brd: 1
-
-View full graph: plans/docs-graph.md
-```
-
-### Query: `/utils/docs-graph auth`
-
-```
-Nodes matching "auth": 4
-
-uc-auth-001 (use-case) - Login
-  ← feature-auth, spec-auth-001
-  → feature-auth
-
-uc-auth-002 (use-case) - Signup
-  ← feature-auth
-  → uc-auth-001, feature-auth
-
-feature-auth (feature) - Authentication
-  ← uc-auth-001, uc-auth-002, uc-auth-003
-  → (none)
-
-spec-auth-001 (spec) - Login Spec
-  ← (none)
-  → uc-auth-001
-```
-
-### Check: `/utils/docs-graph --check`
-
-```
-Link Check Results
-==================
-✓ 16 valid links
-✗ 2 broken links
-
-Broken:
-  plans/brd/use-cases/auth/UC-AUTH-001-login.md:5
-    [[uc-auth-004]] - node not found
-
-  plans/features/auth/specs/UC-AUTH-001/README.md:12
-    [[feature-billing]] - node not found
-
-Suggestions:
-  - uc-auth-004: Did you mean uc-auth-003?
-  - feature-billing: Create plans/features/billing/README.md
-```
-
-## Tools Used
-
-| Tool | Purpose |
-|------|---------|
-| `Bash` | Run graph.py script |
-| `Read` | Read docs-graph.json, docs-graph.md |
-| `Glob` | Find plan files |
-
-## Integration
-
-| Skill | Relationship |
-|-------|--------------|
-| `/debrief` | Creates use cases with wikilinks |
-| `/dev-specs` | Creates specs linking to use cases |
-| `/dev-scout` | Creates scout.md for features |
-
-## Troubleshooting
-
-**Graph not updating:**
-- Check hook is in `.claude/settings.local.json`
-- Verify `jq` is installed
-- Run `/utils/docs-graph --regenerate` to force update
-
-**Broken links:**
-- Run `/utils/docs-graph --check` to find issues
-- Update wikilinks to match node IDs
-- Node IDs are lowercase, no slug (e.g., `uc-auth-001` not `UC-AUTH-001-login`)