@codihaus/claude-skills 1.6.12 → 1.6.14

package/package.json

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

package/project-scripts/graph.py

@@ -2,8 +2,11 @@
 """
 Knowledge Graph Generator for Plans
 
-Scans markdown files in plans/ directory, extracts [[wikilinks]],
-and generates a knowledge graph (JSON + Mermaid visualization).
+Scans markdown files in plans/ directory, extracts relationships from:
+- [[wikilinks]] - Internal references
+- [text](path.md) - Markdown links to other docs
+
+Generates a knowledge graph (JSON + Mermaid visualization).
 
 Usage:
     python scripts/graph.py                      # Full scan
@@ -23,6 +26,9 @@ from typing import Dict, List, Set, Tuple
 # Wikilink pattern: [[link]] or [[link|display]]
 WIKILINK_PATTERN = re.compile(r'\[\[([^\]|]+)(?:\|[^\]]+)?\]\]')
 
+# Markdown link pattern: [text](path.md)
+MARKDOWN_LINK_PATTERN = re.compile(r'\[([^\]]+)\]\(([^)]+\.md)\)')
+
 # Node type detection from path/filename
 NODE_TYPES = {
     'brd/use-cases/': 'use-case',
@@ -87,6 +93,51 @@ def extract_wikilinks(content: str) -> List[str]:
     return [m.strip().lower() for m in matches]
 
 
+def extract_markdown_links(content: str, source_path: str) -> List[str]:
+    """
+    Extract markdown links and resolve them to node IDs.
+
+    Args:
+        content: Markdown content
+        source_path: Path to the source file (relative to repo root)
+
+    Returns:
+        List of target node IDs
+    """
+    matches = MARKDOWN_LINK_PATTERN.findall(content)
+    node_ids = []
+
+    for text, link_path in matches:
+        # Skip external links
+        if link_path.startswith('http://') or link_path.startswith('https://'):
+            continue
+
+        # Skip anchors
+        if '#' in link_path:
+            link_path = link_path.split('#')[0]
+            if not link_path:  # Pure anchor link
+                continue
+
+        # Resolve relative path
+        source_dir = Path(source_path).parent
+        target_path = (source_dir / link_path).resolve()
+
+        # Make relative to repo root
+        try:
+            repo_root = Path.cwd()
+            rel_target = target_path.relative_to(repo_root)
+
+            # Only process if it's in plans/
+            if str(rel_target).startswith('plans/'):
+                node_id = extract_node_id(str(rel_target))
+                node_ids.append(node_id)
+        except (ValueError, Exception):
+            # Path resolution failed, skip
+            continue
+
+    return node_ids
+
+
 def get_node_label(filepath: str, content: str) -> str:
     """Extract a human-readable label from file."""
     path = Path(filepath)
@@ -148,14 +199,23 @@ def scan_plans_directory(plans_dir: str) -> Tuple[Dict, Dict, List]:
             'mtime': md_file.stat().st_mtime,
         }
 
-        # Extract links
-        links = extract_wikilinks(content)
-        for link in links:
+        # Extract wikilinks
+        wikilinks = extract_wikilinks(content)
+        for link in wikilinks:
             link_id = link.lower().replace(' ', '-')
             edges.append({
                 'from': node_id,
                 'to': link_id,
-                'relation': 'links_to',
+                'relation': 'wikilink',
+            })
+
+        # Extract markdown links
+        md_links = extract_markdown_links(content, rel_path)
+        for target_id in md_links:
+            edges.append({
+                'from': node_id,
+                'to': target_id,
+                'relation': 'markdown_link',
             })
 
     return nodes, edges, errors

package/skills/dev-specs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-specs
 description: Generate lean implementation specifications from BRD use cases
-version: 2.0.0
+version: 2.0.1
 ---
 
 # /dev-specs - Lean Implementation Specifications
@@ -83,18 +83,20 @@ plans/features/{feature}/
 ```
 
 **Each UC spec includes:**
-- Requirements (bulleted, testable)
-- Technical constraints (stack-aware from tech-context.md)
-- Acceptance criteria (testable outcomes)
-- Files to modify (where to work)
-- API contract (if applicable)
-- Dependencies (what must exist first)
-- Implementation notes (DO/DON'T)
+- **Requirements** - WHAT to achieve (testable outcomes)
+- **Acceptance Criteria** - HOW to verify it works
+- **Technical Constraints** - Stack patterns to use (reference tech-context.md)
+- **Work Area** - General location (e.g., "auth feature area", NOT specific files)
+- **API Contract** - If external interface
+- **Dependencies** - What must exist first
 
 **Each UC spec does NOT include:**
-- Pseudocode (gets stale)
-- Detailed implementation steps
-- Code examples (reference existing patterns instead)
+- ❌ Specific file names to create/modify
+- ❌ DO/DON'T implementation lists
+- ❌ Pseudocode or step-by-step instructions
+- ❌ "How to code" details
+
+**Engineer figures out:** File names, implementation approach, code structure
 
 ## Success Criteria
 
@@ -125,12 +127,25 @@ Auto-checked and resolved:
 - `plans/brd/use-cases/{feature}/*.md` - Business requirements
 - `plans/docs-graph.json` - Dependencies between UCs
 
-## User Questions
+## Scope Inference
+
+**Analyze UC to determine what's needed** (don't ask user):
 
-Ask via `AskUserQuestion`:
-1. **Scope:** Backend only | Frontend only | Full-stack | API/Service | Mobile
-2. **Additional Context:** API specs | DB schema | Design files | Docs
-3. **Testing:** Unit only | Unit + Integration | Unit + Integration + E2E | No tests
+From UC content, infer:
+- **UI needed?** → UC mentions forms, pages, views, user sees/clicks/enters
+- **API needed?** → UC mentions data operations, persistence, validation
+- **Both?** → Full-stack (most common)
+- **Testing level** → From `_quality-attributes.md` or project standards
+
+**Example:**
+- UC: "User can login via email/password form" → Full-stack (form + API + validation)
+- UC: "System sends daily report email" → Backend only (cron job + email service)
+- UC: "User sees loading spinner during API calls" → Frontend only (UI state)
+
+**Only ask user for additional context if helpful:**
+- API specs (Swagger, OpenAPI) if integrating external API
+- Design files (Figma) if complex UI
+- DB schema if existing database
 
 ## Impact Analysis
 
@@ -181,13 +196,6 @@ See `references/spec-template.md` for structure.
 **Focus:** Requirements + acceptance criteria
 **No:** Pseudocode or detailed HOW
 
-## Quality Questions
-
-Ask user for:
-1. **Scope:** Backend only | Frontend only | Full-stack | API/Service | Mobile
-2. **Additional Context:** API specs | DB schema | Design files | Docs
-3. **Testing:** Unit only | Unit + Integration | Unit + Integration + E2E | No tests
-
 ## Tools
 
 | Tool | Purpose |
@@ -195,7 +203,7 @@ Ask user for:
 | `Read` | BRD, tech-context, codebase-context, architecture |
 | `Glob` | Find related files |
 | `Write` | Create spec files |
-| `AskUserQuestion` | Clarify scope |
+| `AskUserQuestion` | Ask for additional context (API specs, design files) if needed |
 | `Context7` | Look up API/library patterns |
 
 ## Philosophy

package/skills/dev-specs/references/spec-template.md

@@ -2,8 +2,8 @@
 
 ## Principle
 
-**Include:** Requirements (testable), technical constraints, acceptance criteria, file checklist
-**Exclude:** Pseudocode, detailed HOW, code examples (reference patterns instead)
+**Include:** Requirements (testable), technical constraints, acceptance criteria, work area guidance
+**Exclude:** Pseudocode, detailed HOW, specific file lists, DO/DON'T lists (reference patterns instead)
 **Length:** ~150 lines max per UC
 
 ---
@@ -47,10 +47,10 @@
 - Validation: {where schemas go}
 - Forms: {which library}
 
-**Code Location:**
-- Primary location: `{path}`
-- Related files: `{paths}`
-- Follow pattern: `{reference file}`
+**Work Area:**
+- General location: {feature area, e.g., "auth feature", "billing system"}
+- Pattern reference: See tech-context.md → {section}
+- Integration points: {what this connects to}
 
 **External Dependencies:**
 {if applicable}
@@ -69,17 +69,6 @@
 **Edge Cases:**
 - [ ] Given {edge}, When {action}, Then {behavior}
 
-## Files to Modify
-
-**New Files:**
-- [ ] `{path}` - {purpose}
-
-**Modified Files:**
-- [ ] `{path}` - {what changes}
-
-**Reference Pattern:**
-- See `{existing file}` for similar implementation
-
 ## API Contract (if applicable)
 
 **Endpoint:** `{METHOD} {path}`
@@ -123,24 +112,23 @@
 **Blocks:**
 - [ ] [[uc-{group}-{nnn}]] - {why}
 
-## Implementation Notes
-
-**DO:**
-- {guidance}
+## Notes
 
-**DON'T:**
-- {anti-pattern}
+**Context:**
+{any additional context that helps understand the requirements}
 
-**Watch Out For:**
-- {gotcha}
+**Edge Cases:**
+{known edge cases or gotchas to be aware of}
 ```
 
 ---
 
 ## Key Rules
 
-1. **No pseudocode** - requirements and constraints only
-2. **Reference patterns** - don't rewrite them
-3. **Testable criteria** - every requirement maps to a test
-4. **Stack-aware** - uses tech-context.md for correct approach
-5. **Scannable** - read in 2-3 minutes
+1. **WHAT, not HOW** - define outcomes, not implementation steps
+2. **No specific file lists** - general work area only, engineer determines files
+3. **No DO/DON'T lists** - reference patterns instead
+4. **No pseudocode** - requirements and constraints only
+5. **Testable criteria** - every requirement maps to a test
+6. **Stack-aware** - uses tech-context.md for correct approach
+7. **Scannable** - read in 2-3 minutes