@codihaus/claude-skills 1.6.7 → 1.6.8

package/skills/dev-review/SKILL.md

@@ -69,250 +69,75 @@ Reviews can be based on:
 - Clean separation of concerns
 ```
 
-## Workflow
+## Expected Outcome
+
+Review report with verdict and categorized issues.
+
+**Report includes:**
+- Verdict (Approve/Request Changes/Needs Discussion)
+- Issues found (by severity: critical/important/suggestion)
+- Issues by file
+- Positives (acknowledge good work)
+- Spec compliance (if UC provided)
+
+## Success Criteria
+
+- Security risks identified
+- Quality issues found
+- Spec compliance verified
+- Conventions checked
+- Constructive feedback with suggested fixes
+- Clear verdict given
+
+## Review Focus Areas
+
+### Security
+- Input validation (sanitized, injection prevented, XSS prevented)
+- Authentication (required where needed, tokens validated, sessions secure)
+- Authorization (permissions checked, data access restricted, admin protected)
+- Data protection (passwords hashed, sensitive data not logged, no secrets in code)
+- API security (rate limiting, CORS, no sensitive data in URLs)
+
+### Quality
+- Error handling (caught, user-friendly messages, logged, not swallowed)
+- Performance (no N+1 queries, pagination on lists, async heavy ops, no memory leaks)
+- Maintainability (readable, functions not too long, no magic values, DRY)
+- Testing (new code tested, edge cases covered, meaningful tests)
+
+### Conventions
+- Naming (variables, files, components per scout)
+- Structure (correct location, follows patterns, organized imports)
+- Style (matches configs, consistent, no linting errors)
+- Git (proper commit format, no unrelated changes, no debug code)
 
-### Phase 1: Gather Context
-
-```
-1. Get changes to review
-   → git diff (uncommitted)
-   → git diff --staged (staged only)
-   → Read specific files
-
-2. Read project conventions
-   → plans/scout/README.md (Conventions section)
-   → CLAUDE.md
-   → .eslintrc, tsconfig.json
-
-3. Read stack.md and stack knowledge
-   → plans/scout/stack.md
-   → Check "Stack Knowledge References" section
-   → Read each referenced knowledge/stacks/*.md file
-   → Use "For /dev-review" sections for review checklists
-
-   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 related spec (if UC provided)
-   → plans/features/{feature}/specs/{UC}/README.md
-```
-
-### Phase 1.5: Load Quality Attributes
-
-Load ALL levels from `_quality-attributes.md` for comprehensive verification:
-
-```
-1. Architecture Level
-   → Were architecture decisions followed?
-   → Any deviations from architecture.md?
-
-2. Specification Level
-   → Does implementation match spec?
-   → API patterns correct?
-
-3. Implementation Level
-   → Code quality checks
-   → Security, performance, reliability
-
-4. Review Level (meta)
-   → Can a new developer understand this?
-   → Would you want to maintain this?
-```
-
-### Phase 2: Analyze Changes
-
-For each changed file:
-
-```
-1. Understand the change
-   - What was added/modified/removed?
-   - What is the intent?
-
-2. Check against spec (if available)
-   - Does implementation match spec?
-   - Any missing requirements?
-
-3. Check against architecture (if exists)
-   - Does it follow architecture.md patterns?
-   - Any undocumented architecture decisions?
-
-4. Run through quality attribute checklists
-   - Scalability
-   - Maintainability
-   - Performance
-   - Security
-   - Reliability
-   - Testability
-```
-
-### Phase 3: Security Review
-
-```markdown
-## Security Checklist
-
-[ ] **Input Validation**
-    - User input sanitized?
-    - SQL/NoSQL injection prevented?
-    - XSS prevented (HTML escaped)?
-
-[ ] **Authentication**
-    - Auth required where needed?
-    - Token validated correctly?
-    - Session handled securely?
-
-[ ] **Authorization**
-    - Permissions checked?
-    - Can't access others' data?
-    - Admin functions protected?
-
-[ ] **Data Protection**
-    - Passwords hashed?
-    - Sensitive data not logged?
-    - No secrets in code?
-
-[ ] **API Security**
-    - Rate limiting present?
-    - CORS configured?
-    - No sensitive data in URLs?
-```
-
-**Common Security Issues:**
-
-```typescript
-// BAD: SQL injection
-const query = `SELECT * FROM users WHERE id = ${userId}`;
-
-// GOOD: Parameterized
-const query = `SELECT * FROM users WHERE id = $1`;
-await db.query(query, [userId]);
-
-// BAD: XSS vulnerable
-element.innerHTML = userInput;
-
-// GOOD: Escaped
-element.textContent = userInput;
-
-// BAD: Hardcoded secret
-const apiKey = "sk-1234567890";
-
-// GOOD: Environment variable
-const apiKey = process.env.API_KEY;
-```
-
-### Phase 4: Quality Review
-
-```markdown
-## Quality Checklist
-
-[ ] **Error Handling**
-    - Errors caught and handled?
-    - User-friendly error messages?
-    - Errors logged for debugging?
-    - No swallowed errors?
-
-[ ] **Performance**
-    - No N+1 queries?
-    - Large lists paginated?
-    - Heavy operations async?
-    - No memory leaks?
-
-[ ] **Maintainability**
-    - Code readable?
-    - Functions not too long?
-    - No magic numbers/strings?
-    - DRY (no unnecessary duplication)?
-
-[ ] **Testing**
-    - New code has tests?
-    - Edge cases covered?
-    - Tests actually test something?
-```
-
-**Common Quality Issues:**
-
-```typescript
-// BAD: N+1 query
-const posts = await getPosts();
-for (const post of posts) {
-  post.author = await getUser(post.authorId); // Query per post!
-}
-
-// GOOD: Batch query
-const posts = await getPosts({ include: { author: true } });
-
-// BAD: Swallowed error
-try {
-  await doSomething();
-} catch (e) {
-  // Nothing - error disappears!
-}
-
-// GOOD: Handle or rethrow
-try {
-  await doSomething();
-} catch (e) {
-  logger.error('Failed to do something', e);
-  throw new AppError('Operation failed', e);
-}
-
-// BAD: Magic number
-if (retries > 3) { ... }
-
-// GOOD: Named constant
-const MAX_RETRIES = 3;
-if (retries > MAX_RETRIES) { ... }
-```
-
-### Phase 5: Convention Review
-
-```markdown
-## Convention Checklist (from scout)
-
-[ ] **Naming**
-    - Variables: {convention from scout}
-    - Files: {convention from scout}
-    - Components: {convention from scout}
-
-[ ] **Structure**
-    - File in correct location?
-    - Follows project patterns?
-    - Imports organized?
-
-[ ] **Style**
-    - Matches .prettierrc / .eslintrc?
-    - Consistent with codebase?
-    - No linting errors?
-
-[ ] **Git**
-    - Commit message format correct?
-    - No unrelated changes?
-    - No debug code / console.log?
-```
-
-### Phase 6: Spec Compliance (if UC provided)
-
-```markdown
-## Spec Compliance
+### Spec Compliance
+- Requirements met (all implemented)
+- Requirements not met (missing items)
+- Not in spec (unauthorized additions)
 
-### Requirements Met
-- [x] Login endpoint created
-- [x] Returns token on success
-- [x] Returns error on invalid credentials
+### Stack-Specific
+Read stack knowledge files (knowledge/stacks/) for stack-specific review checklists.
 
-### Requirements Not Met
-- [ ] Rate limiting not implemented (spec said 5 attempts/min)
+Examples:
+- Directus: Check for proper collection usage, field types, permissions
+- Nuxt: Check for composables, server routes, nitro patterns
+- Next.js: Check for App Router patterns, server components, actions
 
-### Not in Spec
-- Added "remember me" checkbox (is this approved?)
-```
+## Context Sources
 
-### Phase 7: Generate Review
+**Read to understand what was changed:**
+- git diff (uncommitted or staged)
+- Specific files (if provided)
 
-Compile findings into review output format.
+**Read to understand standards:**
+- tech-context.md - Project conventions
+- stack knowledge files - Stack-specific patterns
+- architecture.md - Architecture decisions
+- spec - Requirements (if UC provided)
+- _quality-attributes.md - ALL levels (Architecture, Specification, Implementation, Review)
+- Config files (.eslintrc, tsconfig.json)
 
-**Severity Levels:**
+## Severity Levels
 
 | Level | Icon | Meaning | Action |
 |-------|------|---------|--------|
@@ -321,7 +146,7 @@ Compile findings into review output format.
 | Suggestion | 🔵 | Style, improvements | Nice to have |
 | Positive | ✅ | Good practice noted | Encouragement |
 
-**Review Verdicts:**
+## Verdicts
 
 | Verdict | When |
 |---------|------|

package/skills/dev-scout/SKILL.md

@@ -74,74 +74,101 @@ Discover and document **how the codebase works** - patterns, rules, and team con
 - Tech stack info (already documented)
 - Code conventions (already documented)
 
-## Discovery Method
+## Expected Outcome
 
-### Project-Level (Full Discovery)
+### Project-Level: `tech-context.md` (~150-200 lines)
 
-**Medium Mode:**
-1. Read project docs (CLAUDE.md, README, CONTRIBUTING)
-2. Detect tech stack (package.json, configs)
-3. Sample 2-3 files per category to discover patterns
-4. Read configs for conventions
+Answers the question: **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)
+
+**Does NOT capture (volatile):**
+- File trees (use Glob fresh)
+- Component/route lists (discover when needed)
+- File counts (meaningless)
+- Exhaustive inventories (stale immediately)
+
+### Feature-Level: `codebase-context.md`
+
+Answers the question: **How does THIS feature work?**
+
+**Prerequisite:** MUST have `tech-context.md` first (patterns already documented)
+
+**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
+
+**Does NOT repeat:**
+- Project-wide patterns (already in tech-context.md)
+- Tech stack info (already documented)
+- Code conventions (already documented)
+
+## Success Criteria
+
+- New engineer can follow patterns from output
+- Patterns shown with examples, not theory
+- Rules captured, not procedures
+- No file inventories or counts
+- Feature scout reuses patterns from tech-context.md
+- ~150-200 lines for tech-context.md
+
+## Discovery Approach
+
+### Project-Level
+
+**Medium Mode (default):**
+- Read project docs (CLAUDE.md, README, configs)
+- Detect tech stack from package.json, configs
+- Sample 2-3 files per category to discover patterns
+- Extract conventions from configs
 
 **Deep Mode:**
-Medium + deeper pattern analysis:
-1. API pattern deep dive
-2. Data access pattern
-3. Code convention detection (from configs + sampling)
-4. Git & team process
-
-### Feature-Level (Reuse Patterns)
-
-**IMPORTANT:** Feature scout is lightweight - it READS patterns from tech-context.md, not rediscover them.
-
-1. **Check prerequisite:** `tech-context.md` exists?
-   - No → Run project-level scout first
-   - Yes → Continue
-
-2. **Read patterns:** Load `tech-context.md`
-   - Now you know: API pattern, data access, conventions
-   - Don't rediscover these
-
-3. **Focus on feature:**
-   - Find files for this feature (Glob/Grep)
-   - Read 2-3 key files to understand flow
-   - Identify entry points
-   - Note integration points
-
-4. **Document:**
-   - How THIS feature implements the patterns
-   - Where the code lives
-   - How to extend it
-   - Feature-specific gotchas
-
-**Don't:**
-- ❌ Rediscover API pattern (already in tech-context.md)
-- ❌ Re-document tech stack (already documented)
-- ❌ Repeat code conventions (already known)
-
-### Strategy
-- **Small (<100 files):** Sequential discovery
-- **Medium (100-500):** Parallel by concern (API, data, UI, conventions)
-- **Large (500+):** Use `/utils/gemini` first, then focused Claude analysis
+- All of Medium +
+- Deeper pattern analysis (API, data access)
+- Code convention detection
+- Git & team process
+
+### Feature-Level
+
+**Lightweight approach - reads patterns, not rediscovering:**
+
+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
 
 ## Pattern Discovery Rules
 
-1. **Sample, don't exhaustive:** Read 2-3 representative files, not all
-2. **Find abstractions:** Wrappers, base classes, shared utilities
-3. **Capture with example:** Show the pattern, not document everything
-4. **Ask "what's the rule?"** not "what files exist?"
+1. **Sample, don't exhaust** - Read 2-3 representative files, not all
+2. **Find abstractions** - Wrappers, base classes, shared utilities
+3. **Capture with example** - Show the pattern in action
+4. **Ask "what's the rule?"** - Not "what files exist?"
 
-## Key Checks
+## Strategy by Codebase Size
 
-**Pre-flight:**
-- If feature-level scout requested, check if `tech-context.md` exists
-- If not, run project-level scout first
+| Size | Strategy |
+|------|----------|
+| Small (<100 files) | Sequential discovery |
+| Medium (100-500) | Parallel by concern (API, data, UI, conventions) |
+| Large (500+) | Use `/utils/gemini` first, then focused Claude analysis |
 
-**Existing Scout:**
+## Version Management
+
+**When tech-context.md exists:**
 - Move current to `history/tech-context-{date}.md`
 - Note what changed (pattern changes, not file changes)
 
+**When feature scout requested:**
+- Check tech-context.md exists first
+- If not, run project-level scout first
+
 ## Output Template
 
 See `references/output-template.md` for structure.

package/skills/dev-specs/SKILL.md

@@ -65,50 +65,94 @@ plans/features/{feature}/
     └── UC-XXX-001-slug.md       # Lean spec per UC (~150 lines)
 ```
 
-## Workflow
-
-### Phase 0: Check & Prepare
-1. Verify BRD exists
-2. Verify feature folder exists
-3. Check `tech-context.md` exists (run scout if not)
-4. Check `codebase-context.md` exists (run feature scout if not)
-5. Read docs-graph.json for dependencies
-
-### Phase 1: Gather Context
-1. Read BRD use cases for feature
-2. Read `tech-context.md` (HOW to implement)
-3. Read `codebase-context.md` (existing implementation)
-4. Read architecture.md (patterns - call `/dev-arch` if missing)
-5. Read quality attributes (Specification Level)
-6. Ask user: scope, additional context, testing approach
-
-### Phase 2: Analyze Impact
-For each UC:
-- What's new? (files to create)
-- What changes? (files to modify)
-- What's shared? (reusable across UCs)
-- Dependencies? (what must exist first)
+## Expected Outcome
 
-### Phase 3: Generate Shared Specs
-Create `specs/shared/`:
-- `data-model.md` - Schema changes, entities
-- `patterns.md` - Pattern references (not pseudocode)
-- `security.md` - Auth, validation rules
+**Lean specs** (~150 lines per UC) that define **WHAT to build**, not HOW.
+
+**Output structure:**
+```
+plans/features/{feature}/
+├── codebase-context.md          # From /dev-scout
+└── specs/
+    ├── README.md                # Index, implementation order
+    ├── shared/                  # Shared across UCs
+    │   ├── data-model.md
+    │   ├── patterns.md
+    │   └── security.md
+    └── UC-XXX-001-slug.md       # Lean spec per UC
+```
 
-### Phase 4: Generate UC Specs (Lean Format)
-For each UC, create `specs/UC-XXX-NNN-slug.md` (~150 lines):
-- Context & links
+**Each UC spec includes:**
 - Requirements (bulleted, testable)
 - Technical constraints (stack-aware from tech-context.md)
-- Acceptance criteria (testable)
-- Files to modify
+- Acceptance criteria (testable outcomes)
+- Files to modify (where to work)
 - API contract (if applicable)
-- Test checklist
-- Dependencies
+- Dependencies (what must exist first)
 - Implementation notes (DO/DON'T)
 
-### Phase 5: Generate Index
-Create `specs/README.md` with implementation order and dependencies.
+**Each UC spec does NOT include:**
+- Pseudocode (gets stale)
+- Detailed implementation steps
+- Code examples (reference existing patterns instead)
+
+## Success Criteria
+
+- Engineer knows WHAT to build
+- Engineer knows WHERE to build it (file checklist)
+- Engineer can verify success (acceptance criteria)
+- Specs reference existing patterns, don't rewrite them
+- Stack-aware (uses tech-context.md patterns)
+- ~150 lines per UC spec max
+
+## Prerequisites
+
+Auto-checked and resolved:
+1. `plans/brd/` exists with use cases
+2. `plans/features/{feature}/` exists
+3. `plans/brd/tech-context.md` exists (auto-runs project scout if missing)
+4. `plans/features/{feature}/codebase-context.md` exists (auto-runs feature scout if missing)
+
+## Context Sources
+
+**Read these to understand HOW:**
+- `tech-context.md` - Project patterns (API, data, structure)
+- `codebase-context.md` - Feature-specific implementation
+- `architecture.md` - Architecture decisions (call `/dev-arch` if missing)
+- `_quality-attributes.md` - Specification Level checklist
+
+**Read these to understand WHAT:**
+- `plans/brd/use-cases/{feature}/*.md` - Business requirements
+- `plans/docs-graph.json` - Dependencies between UCs
+
+## User Questions
+
+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
+
+## Impact Analysis
+
+For each UC, identify:
+- What's new? (files to create)
+- What changes? (files to modify)
+- What's shared? (reusable across UCs → specs/shared/)
+- Dependencies? (what must exist first)
+
+## Shared Specs
+
+Create `specs/shared/` for cross-UC concerns:
+- `data-model.md` - Schema changes, entities, relationships
+- `patterns.md` - Pattern references (not pseudocode)
+- `security.md` - Auth, permissions, validation rules
+
+## Index Generation
+
+Create `specs/README.md` with:
+- Implementation order
+- Dependencies between specs
+- Quick reference to all UCs
 
 ## Stack Awareness