@codihaus/claude-skills 1.6.10 → 1.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.10",
+  "version": "1.6.12",
   "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/skills/dev-scout/SKILL.md

@@ -11,14 +11,26 @@ version: 3.0.0
 > - **After**: Use `/dev-specs` for implementation plans
 > - **Utils**: `/utils/diagram` for architecture visualization
 
-Discover and document **how the codebase works** - patterns, rules, and team conventions. Not a file inventory.
+Discover and document **how the codebase works** - patterns, rules, and team conventions for EXISTING code.
 
 ## When to Use
 
 - Understand **how the project works** before implementation
 - Document **team patterns and conventions** for new engineers
 - Discover **architectural patterns** that must be followed
-- Capture **the rules** that won't change soon
+- Capture **existing features** and how they're implemented
+
+## What Scout Does vs Doesn't
+
+**Scout documents EXISTING code:**
+- ✅ How the project currently works (patterns, conventions)
+- ✅ Complete list of existing features
+- ✅ How each feature is implemented (for understanding/extending)
+
+**Scout does NOT plan NEW features:**
+- ❌ NOT for creating implementation specs
+- ❌ NOT for planning new features
+- ❌ Use `/dev-specs` for new feature planning
 
 **Not for:** Listing files, counting components, inventorying routes (use Glob/Grep fresh instead)
 
@@ -78,37 +90,48 @@ Discover and document **how the codebase works** - patterns, rules, and team con
 
 ### Project-Level: `tech-context.md` (~150-200 lines)
 
-Answers the question: **How does this project work?**
+Answers: **How does this project work?**
 
-**Captures (stable patterns):**
-- How we make API calls (wrapper, pattern, error handling)
-- How we access data (ORM, queries, abstractions)
-- How we structure code (folders, naming, organization)
-- What our conventions are (naming, formatting, git workflow)
-- Tech stack choices (framework, libraries, tools)
+**For new developers, provide:**
+- **Patterns** - How we make API calls, access data, structure code (with file/location references)
+- **Conventions** - Team standards for naming, formatting, git workflow
+- **Stack** - Tech choices and why
+- **All existing features** - Complete list (important: don't miss any!)
 
-**Does NOT capture (volatile):**
-- File trees (use Glob fresh)
-- Component/route lists (discover when needed)
-- File counts (meaningless)
-- Exhaustive inventories (stale immediately)
+**Format:** Overview + location reference, NOT do/don't lists
+
+**Example:**
+```markdown
+### API Communication
+**Pattern:** All API calls go through `lib/api/client.ts` wrapper
+**Location:** See `lib/api/client.ts` for implementation
+**Usage:** Import `apiClient` and call methods
+```
+
+NOT:
+```markdown
+✅ DO: Use apiClient
+❌ DON'T: Use fetch directly
+```
 
 ### Feature-Level: `codebase-context.md`
 
-Answers the question: **How does THIS feature work?**
+Answers: **How does THIS already-implemented feature work?**
 
-**Prerequisite:** MUST have `tech-context.md` first (patterns already documented)
+**Purpose:** Document existing implementation for understanding/extending, NOT create specs
+
+**Prerequisite:** MUST have `tech-context.md` first
 
 **Captures:**
-- How this feature implements the patterns (not the patterns themselves)
-- Where the key files are (entry points, core logic)
-- How to extend this feature
-- Feature-specific gotchas
+- How this feature uses the patterns (reference tech-context.md)
+- Where key files are (locations, entry points)
+- How it currently works (flow, architecture)
+- How to extend it (what to modify where)
 
-**Does NOT repeat:**
-- Project-wide patterns (already in tech-context.md)
-- Tech stack info (already documented)
-- Code conventions (already documented)
+**Does NOT:**
+- Create implementation specs (this is for EXISTING code)
+- Repeat patterns (reference tech-context.md instead)
+- Include do/don't lists (show pattern usage with locations)
 
 ## Success Criteria
 
@@ -128,6 +151,7 @@ Answers the question: **How does THIS feature work?**
 - Detect tech stack from package.json, configs
 - Sample 2-3 files per category to discover patterns
 - Extract conventions from configs
+- **Discover ALL existing features** (don't miss any - scan routes, pages, API endpoints)
 
 **Deep Mode:**
 - All of Medium +
@@ -135,14 +159,22 @@ Answers the question: **How does THIS feature work?**
 - Code convention detection
 - Git & team process
 
+**Output:** `tech-context.md` with patterns + complete feature list
+
 ### Feature-Level
 
-**Lightweight approach - reads patterns, not rediscovering:**
+**Purpose:** Document existing implementation for understanding/extending
+
+**NOT FOR:** Creating specs or planning new features
+
+**Lightweight approach:**
 
 1. **Check prerequisite:** tech-context.md exists? If not, run project-level first
 2. **Read patterns:** Load tech-context.md (now you know API pattern, data access, conventions)
 3. **Focus on feature:** Find files (Glob/Grep), read 2-3 key files, identify entry points
-4. **Document:** How THIS feature uses the patterns, where code lives, how to extend
+4. **Document existing code:** How it works NOW, where files are, how to extend
+
+**Output:** `codebase-context.md` describing current implementation
 
 ## Pattern Discovery Rules
 

package/skills/dev-scout/references/output-template.md

@@ -39,23 +39,32 @@
 
 ## Architecture Patterns (How We Build)
 
+**Format:** Overview + location reference (NOT do/don't lists)
+
 ### 1. API Communication
-**How:** {pattern description}
-**Rule:** {what must be followed}
-**Example:** {code example showing pattern}
-**Why:** {reason}
+**Pattern:** {description of approach}
+**Location:** `{file/folder}` - {what's there}
+**Usage Example:** {short code snippet showing usage}
 
 ### 2. Data Access
-{same structure}
+**Pattern:** {description}
+**Location:** `{file/folder}`
+**Usage Example:** {snippet}
 
 ### 3. Client-Side Data Fetching
-{same structure}
+**Pattern:** {description}
+**Location:** `{file/folder}`
+**Usage Example:** {snippet}
 
 ### 4. Validation & Forms
-{same structure}
+**Pattern:** {description}
+**Location:** `{file/folder}`
+**Usage Example:** {snippet}
 
 ### 5. State Management
-{same structure}
+**Pattern:** {description}
+**Location:** `{file/folder}`
+**Usage Example:** {snippet}
 
 ## Code Conventions (Team Standards)
 
@@ -94,6 +103,16 @@
 ### Available MCPs
 {what they provide}
 
+## Existing Features (Complete List)
+
+**IMPORTANT:** List ALL features found in codebase, don't sample.
+
+| Feature | Status | Location | Key Files |
+|---------|--------|----------|-----------|
+| {feature} | Complete | `{folder}` | `{main files}` |
+
+**Discovery method:** Scan routes, pages, components, API endpoints
+
 ## Project Structure (High-Level)
 
 {core directories only, not exhaustive}
@@ -131,7 +150,8 @@
 ## 2. Feature-Level: codebase-context.md
 
 **Location:** `plans/features/{feature}/codebase-context.md`
-**Purpose:** How THIS feature works (implementation details, not patterns)
+**Purpose:** Document how THIS already-implemented feature works (for understanding/extending)
+**NOT FOR:** Creating specs or planning new features (use /dev-specs for that)
 **Prerequisite:** MUST read tech-context.md first (patterns already documented)
 **Length:** ~100-150 lines
 
@@ -186,35 +206,27 @@
 
 ## Integration Points
 
-**Where to add new code:**
-{location + pattern}
-
-**What to extend:**
-{existing abstraction}
-
 **Dependencies:**
 {what must exist}
 
 **Used By:**
 {what depends on this}
 
-## Patterns to Follow
-
-**✅ DO:**
-{feature-specific guidance}
-
-**❌ DON'T:**
-{feature-specific anti-pattern}
+## How to Extend
 
-## Gotchas
+**To add new functionality:**
+1. Location: `{file/folder}`
+2. Pattern reference: See tech-context.md → {section}
+3. Example: {how similar functionality was added}
 
-{feature-specific issues}
+**To modify behavior:**
+1. Location: `{file}`
+2. Pattern reference: See tech-context.md → {section}
+3. Note: {what to watch out for}
 
-## For Implementation
+## Gotchas & Notes
 
-**Start here:** `{file}` - {why}
-**Follow pattern:** See tech-context.md → {section}
-**Watch out:** {warning}
+{feature-specific issues, edge cases, known limitations}
 ```
 
 ---

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

@@ -1,177 +0,0 @@
----
-name: utils/docs-graph
-description: View and query the documentation knowledge graph
-version: 1.3.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 links are valid
-
-## Usage
-
-```
-/utils/docs-graph                    # Show graph summary
-/utils/docs-graph auth               # Show nodes related to "auth"
-/utils/docs-graph --check            # Verify all links resolve
-```
-
-## How It Works
-
-**Automatic Updates:**
-- PostToolUse hook triggers on Write/Edit to `plans/`
-- Regenerates entire graph from all files in `plans/`
-- Updates `plans/docs-graph.json` and `plans/docs-graph.md`
-- Timeout: 3 minutes
-
-**Graph Files:**
-```
-plans/
-├── docs-graph.json    # Machine-readable graph data
-└── docs-graph.md      # Mermaid visualization
-```
-
-## Expected Outcome
-
-**Summary mode (default):**
-- Node count by type
-- Edge count
-- Mermaid diagram from docs-graph.md
-
-**Query mode (with argument like "auth"):**
-- Matching nodes
-- Incoming links (what references this)
-- Outgoing links (what this references)
-
-**Check mode (--check):**
-- Report broken links
-- Suggest fixes
-
-## 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`)