@codihaus/claude-skills 1.0.0 → 1.3.0

package/project-scripts/graph.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""
+Knowledge Graph Generator for Plans
+
+Scans markdown files in plans/ directory, extracts [[wikilinks]],
+and generates a knowledge graph (JSON + Mermaid visualization).
+
+Usage:
+    python scripts/graph.py                      # Full scan
+    python scripts/graph.py --check-path <path>  # Only if path in plans/
+    python scripts/graph.py --json               # Output JSON to stdout
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Set, Tuple
+
+# Wikilink pattern: [[link]] or [[link|display]]
+WIKILINK_PATTERN = re.compile(r'\[\[([^\]|]+)(?:\|[^\]]+)?\]\]')
+
+# Node type detection from path/filename
+NODE_TYPES = {
+    'brd/use-cases/': 'use-case',
+    'brd/changes/': 'change-request',
+    'brd/README': 'brd',
+    'brd/context': 'context',
+    'features/': 'feature',
+    'specs/': 'spec',
+    'scout': 'scout',
+}
+
+
+def detect_node_type(filepath: str) -> str:
+    """Detect node type from file path."""
+    for pattern, node_type in NODE_TYPES.items():
+        if pattern in filepath:
+            return node_type
+    return 'document'
+
+
+def extract_node_id(filepath: str) -> str:
+    """Extract a clean node ID from filepath."""
+    path = Path(filepath)
+    # Remove plans/ prefix and .md suffix
+    rel_path = str(path).replace('plans/', '').replace('.md', '')
+    # Convert to ID: brd/use-cases/auth/UC-AUTH-001-login -> uc-auth-001
+
+    filename = path.stem.lower()
+
+    # Use case files: extract UC-XXX-NNN
+    if filename.startswith('uc-'):
+        parts = filename.split('-')
+        if len(parts) >= 3:
+            return f"{parts[0]}-{parts[1]}-{parts[2]}"
+
+    # CR files: extract CR-NNN
+    if filename.startswith('cr-'):
+        parts = filename.split('-')
+        if len(parts) >= 2:
+            return f"{parts[0]}-{parts[1]}"
+
+    # Feature README -> feature-{name}
+    if '/features/' in str(path) and filename == 'readme':
+        feature = path.parent.name
+        return f"feature-{feature}"
+
+    # Spec files
+    if '/specs/' in str(path):
+        if filename == 'readme':
+            feature = path.parent.parent.name
+            return f"specs-{feature}"
+        return filename
+
+    # Default: use filename
+    return filename
+
+
+def extract_wikilinks(content: str) -> List[str]:
+    """Extract all wikilinks from markdown content."""
+    matches = WIKILINK_PATTERN.findall(content)
+    # Normalize: lowercase, strip whitespace
+    return [m.strip().lower() for m in matches]
+
+
+def get_node_label(filepath: str, content: str) -> str:
+    """Extract a human-readable label from file."""
+    path = Path(filepath)
+
+    # Try to get title from first heading
+    for line in content.split('\n')[:10]:
+        if line.startswith('# '):
+            title = line[2:].strip()
+            # Remove UC-XXX-NNN: prefix for cleaner label
+            if ':' in title:
+                return title.split(':', 1)[1].strip()
+            return title
+
+    # Fallback to filename
+    return path.stem.replace('-', ' ').title()
+
+
+def scan_plans_directory(plans_dir: str) -> Tuple[Dict, Dict, List]:
+    """
+    Scan plans directory and build graph.
+
+    Returns:
+        nodes: Dict of node_id -> node_data
+        edges: List of (from_id, to_id, relation)
+        errors: List of error messages
+    """
+    nodes = {}
+    edges = []
+    errors = []
+
+    plans_path = Path(plans_dir)
+    if not plans_path.exists():
+        return nodes, edges, [f"Plans directory not found: {plans_dir}"]
+
+    # Scan all markdown files
+    for md_file in plans_path.rglob('*.md'):
+        # Skip docs-graph.md itself
+        if md_file.name == 'docs-graph.md':
+            continue
+
+        rel_path = str(md_file.relative_to(plans_path.parent))
+
+        try:
+            content = md_file.read_text(encoding='utf-8')
+        except Exception as e:
+            errors.append(f"Failed to read {rel_path}: {e}")
+            continue
+
+        node_id = extract_node_id(rel_path)
+        node_type = detect_node_type(rel_path)
+        label = get_node_label(rel_path, content)
+
+        # Add node
+        nodes[node_id] = {
+            'id': node_id,
+            'type': node_type,
+            'label': label,
+            'path': rel_path,
+            'mtime': md_file.stat().st_mtime,
+        }
+
+        # Extract links
+        links = extract_wikilinks(content)
+        for link in links:
+            link_id = link.lower().replace(' ', '-')
+            edges.append({
+                'from': node_id,
+                'to': link_id,
+                'relation': 'links_to',
+            })
+
+    return nodes, edges, errors
+
+
+def generate_mermaid(nodes: Dict, edges: List) -> str:
+    """Generate Mermaid flowchart from graph."""
+    lines = [
+        "```mermaid",
+        "flowchart TB",
+    ]
+
+    # Group nodes by type
+    type_groups = {}
+    for node_id, node in nodes.items():
+        node_type = node['type']
+        if node_type not in type_groups:
+            type_groups[node_type] = []
+        type_groups[node_type].append(node)
+
+    # Type display names and styles
+    type_names = {
+        'brd': 'BRD',
+        'use-case': 'Use Cases',
+        'change-request': 'Changes',
+        'feature': 'Features',
+        'spec': 'Specs',
+        'scout': 'Scout',
+        'context': 'Context',
+        'document': 'Documents',
+    }
+
+    # Node shapes by type
+    type_shapes = {
+        'brd': ('[[', ']]'),          # Stadium
+        'use-case': ('[', ']'),        # Rectangle
+        'change-request': ('{{', '}}'), # Hexagon
+        'feature': ('([', '])'),       # Pill
+        'spec': ('[/', '/]'),          # Parallelogram
+        'scout': ('[(', ')]'),         # Cylinder
+        'context': ('(', ')'),         # Rounded
+        'document': ('[', ']'),        # Rectangle
+    }
+
+    # Generate subgraphs
+    for node_type, type_nodes in type_groups.items():
+        display_name = type_names.get(node_type, node_type.title())
+        shape = type_shapes.get(node_type, ('[', ']'))
+
+        lines.append(f"    subgraph {node_type}[{display_name}]")
+        for node in type_nodes:
+            safe_id = node['id'].replace('-', '_')
+            label = node['label'][:30]  # Truncate long labels
+            lines.append(f"        {safe_id}{shape[0]}\"{label}\"{shape[1]}")
+        lines.append("    end")
+
+    # Generate edges (only for nodes that exist)
+    node_ids = set(nodes.keys())
+    for edge in edges:
+        from_id = edge['from'].replace('-', '_')
+        to_id = edge['to'].replace('-', '_')
+
+        # Only add edge if both nodes exist
+        if edge['from'] in node_ids and edge['to'] in node_ids:
+            lines.append(f"    {from_id} --> {to_id}")
+
+    lines.append("```")
+    return '\n'.join(lines)
+
+
+def save_graph(plans_dir: str, nodes: Dict, edges: List, errors: List):
+    """Save graph to JSON and Mermaid files."""
+    plans_path = Path(plans_dir)
+
+    # Build graph data
+    graph_data = {
+        'generated': datetime.now().isoformat(),
+        'node_count': len(nodes),
+        'edge_count': len(edges),
+        'nodes': nodes,
+        'edges': edges,
+        'errors': errors,
+    }
+
+    # Save JSON
+    json_path = plans_path / 'docs-graph.json'
+    with open(json_path, 'w', encoding='utf-8') as f:
+        json.dump(graph_data, f, indent=2)
+
+    # Generate and save Mermaid
+    mermaid = generate_mermaid(nodes, edges)
+    md_content = f"""# Documentation Graph
+
+> **Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+> **Nodes**: {len(nodes)} | **Edges**: {len(edges)}
+
+## Graph
+
+{mermaid}
+
+## Node Index
+
+| ID | Type | Label | Path |
+|----|------|-------|------|
+"""
+
+    for node_id, node in sorted(nodes.items()):
+        md_content += f"| {node_id} | {node['type']} | {node['label']} | [{node['path']}](./{node['path'].replace('plans/', '')}) |\n"
+
+    if errors:
+        md_content += "\n## Errors\n\n"
+        for error in errors:
+            md_content += f"- {error}\n"
+
+    md_path = plans_path / 'docs-graph.md'
+    with open(md_path, 'w', encoding='utf-8') as f:
+        f.write(md_content)
+
+    return json_path, md_path
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate knowledge graph from plans/')
+    parser.add_argument('--check-path', type=str, help='Only run if path is in plans/')
+    parser.add_argument('--json', action='store_true', help='Output JSON to stdout')
+    parser.add_argument('--plans-dir', type=str, default='plans', help='Plans directory path')
+    args = parser.parse_args()
+
+    # If check-path provided, only run if it's in plans/
+    if args.check_path:
+        if not args.check_path.startswith('plans/') and '/plans/' not in args.check_path:
+            # Not a plans file, exit silently
+            sys.exit(0)
+
+    # Find plans directory
+    plans_dir = args.plans_dir
+    if not os.path.isabs(plans_dir):
+        # Look in current directory and parent directories
+        cwd = Path.cwd()
+        for parent in [cwd] + list(cwd.parents)[:3]:
+            candidate = parent / plans_dir
+            if candidate.exists():
+                plans_dir = str(candidate)
+                break
+
+    if not Path(plans_dir).exists():
+        print(f"Plans directory not found: {plans_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    # Scan and build graph
+    nodes, edges, errors = scan_plans_directory(plans_dir)
+
+    if args.json:
+        # Output JSON to stdout
+        print(json.dumps({
+            'nodes': nodes,
+            'edges': edges,
+            'errors': errors,
+        }, indent=2))
+    else:
+        # Save to files
+        json_path, md_path = save_graph(plans_dir, nodes, edges, errors)
+        print(f"Graph updated: {len(nodes)} nodes, {len(edges)} edges")
+        print(f"  → {json_path}")
+        print(f"  → {md_path}")
+
+        if errors:
+            print(f"  ⚠ {len(errors)} errors (see graph.md)")
+
+
+if __name__ == '__main__':
+    main()

package/skills/_registry.md

@@ -104,12 +104,15 @@ During each skill, consider suggesting:
 - After: Informs `/dev-specs` with decisions
 
 ### /dev-scout
+- Outputs: `scout.md` (codebase) + `stack.md` (HOW project works)
+- `stack.md` captures: API layer, SDK, patterns, validation, services
 - After: "Ready for implementation? Use `/dev-specs` to plan"
 - If patterns unclear: "Use `/utils/diagram` to visualize architecture"
 
 ### /dev-specs
 - Before: Ensure `/debrief` completed (BRD exists)
 - During: Calls `/dev-arch` for patterns and decisions
+- **Critical**: Reads `stack.md` to use correct SDK, patterns, validation
 - Reads: `_quality-attributes.md` for spec-level checklists
 - After: "Use `/dev-coding` to implement"
 
@@ -168,6 +171,64 @@ Quality attributes covered:
 - **Reliability** - doesn't break
 - **Testability** - can verify
 
+## Stack & Domain Knowledge
+
+Skills reference platform and business knowledge for accurate output.
+
+> **Location**: `knowledge/` folder (separate from `skills/`)
+> - `skills/` = Invocable workflows (user runs `/dev-coding`)
+> - `knowledge/` = Reference material (loaded by skills)
+
+### Stack Knowledge (`knowledge/stacks/`)
+
+Technical knowledge - HOW to build with specific tools:
+
+| Stack | Folder | Type |
+|-------|--------|------|
+| Directus | `stacks/directus/` | Backend BaaS |
+| Nuxt.js | `stacks/nuxt/` | Vue + SSR Framework |
+| Next.js | `stacks/nextjs/` | React + SSR Framework |
+
+**Folder structure:**
+```
+stacks/{name}/
+├── _index.md       # Main knowledge
+├── references/     # Detailed docs
+└── assets/         # Code templates
+```
+
+**How it works:**
+1. `/dev-scout` detects stack → writes `stack.md`
+2. `/dev-specs` reads `stack.md` → loads `stacks/{name}/_index.md`
+3. Uses "For /dev-specs" section for correct patterns
+4. Deep patterns in `references/`, templates in `assets/`
+
+### Domain Knowledge (`knowledge/domains/`)
+
+Business knowledge - WHAT to build:
+
+| Domain | Folder | Description |
+|--------|--------|-------------|
+| SaaS | `domains/saas/` | Subscriptions, multi-tenancy, billing |
+| E-commerce | `domains/ecommerce/` | Products, carts, orders, fulfillment |
+| Insurance | Planned | Policies, claims |
+
+**Folder structure:**
+```
+domains/{name}/
+├── _index.md       # Main knowledge
+├── references/     # Detailed docs
+└── assets/         # Code templates
+```
+
+Domain knowledge captures:
+- Business terminology
+- Common entities and workflows
+- State machines and lifecycles
+- Domain-specific validation rules
+
+See `knowledge/stacks/_index.md` and `knowledge/domains/_index.md` for details.
+
 ## Skill Awareness Protocol
 
 Every skill should:

package/skills/dev-coding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-coding
 description: Implement features from specs with backend and frontend skills
-version: 1.2.0
+version: 1.3.0
 ---
 
 # /dev-coding - Implementation Skill
@@ -59,17 +59,28 @@ Updates to specs:
 2. Read scout for patterns
    → plans/features/{feature}/scout.md OR plans/scout/README.md
 
-3. Read architecture decisions
+3. Read stack.md and stack knowledge (CRITICAL)
+   → plans/scout/stack.md
+   → Check "Stack Knowledge References" section
+   → Read each referenced knowledge/stacks/*.md file
+   → Use "For /dev-coding" sections for implementation patterns
+
+   Examples:
+   - Directus project → Read knowledge/stacks/directus/_index.md
+   - Nuxt project → Read knowledge/stacks/nuxt/_index.md
+   - Next.js project → Read knowledge/stacks/nextjs/_index.md
+
+4. Read architecture decisions
    → plans/features/{feature}/architecture.md
 
-4. Read quality attributes (Implementation Level)
+5. Read quality attributes (Implementation Level)
    → skills/_quality-attributes.md
    → Focus on: query efficiency, memory, concurrency, error handling
 
-5. Read docs-graph for dependencies
+6. Read docs-graph for dependencies
    → plans/docs-graph.json
 
-6. Check: Are dependencies complete?
+7. Check: Are dependencies complete?
    → If UC depends on another UC, verify it's done
    → Warn if not, let user decide to proceed
 ```