@codihaus/claude-skills 1.5.1 → 1.6.1

package/package.json

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

package/skills/debrief/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: debrief
 description: Analyze customer requirements and deliver market research, tiered proposals, and recommendations
-version: 3.8.0
+version: 3.9.0
 ---
 
 # /debrief - Business Requirements Document (BRD)
@@ -490,7 +490,7 @@ Gather all open questions from:
 If open questions exist, generate customer questionnaire:
 
 ```bash
-python scripts/generate_questionnaire.py {output_path} questions.json
+python .claude/skills/debrief/scripts/generate_questionnaire.py {output_path} questions.json
 ```
 
 **Output location** (contextual, with date for revision tracking):
@@ -516,10 +516,13 @@ Output summary:
 
 **Next steps suggestions:**
 - Send questionnaire to customer (if generated)
-- Run `/dev-scout` for codebase analysis
-- Run `/dev-scout {feature}` for targeted analysis
 - Review use cases with stakeholders
-- Run `/dev-specs {feature}` when ready
+- For new projects: Run `/dev-specs {feature}` (will auto-scout)
+- For existing codebases:
+  - First time: Run `/dev-scout` (project-level analysis) OR let `/dev-specs` auto-scout
+  - Subsequent: Run `/dev-specs {feature}` directly (auto-scouts feature if needed)
+
+**Note**: `/dev-specs` automatically runs both project-level and feature-level scouts if they don't exist, so you typically don't need to run `/dev-scout` manually unless you want to review the codebase analysis separately first.
 
 ---
 
@@ -616,7 +619,7 @@ Output:
 Generate dynamic questionnaire based on open questions identified during debrief:
 
 ```bash
-python scripts/generate_questionnaire.py output.xlsx questions.json
+python .claude/skills/debrief/scripts/generate_questionnaire.py output.xlsx questions.json
 ```
 
 **Input:** JSON file with collected open questions (see Phase 7)
@@ -630,7 +633,7 @@ python scripts/generate_questionnaire.py output.xlsx questions.json
 **Example:**
 ```bash
 # After debrief creates questions.json
-python scripts/generate_questionnaire.py plans/brd/questionnaire.xlsx /tmp/questions.json
+python .claude/skills/debrief/scripts/generate_questionnaire.py plans/features/{feature}/questionnaire-{date}.xlsx /tmp/questions.json
 ```
 
 The questionnaire only contains questions we couldn't answer from:

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.3.0
+version: 1.7.0
 ---
 
 # /dev-coding - Implementation Skill
@@ -50,7 +50,81 @@ Updates to specs:
 
 ## Workflow
 
-### Phase 0: Load Context
+### Phase 0: Determine Scope & Select UCs
+
+**Before starting, determine which use cases to implement.**
+
+```
+Parse user input:
+- /dev-coding UC-AUTH-001 → Specific UC (skip to Phase 1)
+- /dev-coding auth        → Feature-level (need UC selection)
+```
+
+**If user specified feature name (not specific UC), show UC selection:**
+
+1. **List available UCs:**
+   ```
+   Available Use Cases for auth:
+     1. UC-AUTH-001: User Login
+     2. UC-AUTH-002: User Signup
+     3. UC-AUTH-003: Password Reset
+     4. UC-AUTH-004: Email Verification
+     5. UC-AUTH-005: Two-Factor Authentication
+   ```
+
+2. **Ask implementation mode** (use AskUserQuestion):
+   - **One by one (Recommended)**: Implement 1 UC, test, then ask for next
+   - **Multiple (custom selection)**: Select specific UCs (e.g., "1,3-5,7")
+   - **All at once**: Implement all UCs in sequence
+
+3. **Process selection:**
+   - **One by one**: Implement → Test → Ask to continue (safest, recommended)
+   - **Multiple**: Implement → Test each UC → Auto-continue (no prompts between)
+   - **All at once**: Implement → Test each UC → Auto-continue (no prompts)
+
+**Parsing examples:**
+| Input | Result |
+|-------|--------|
+| `1,3,5` | UCs 1, 3, 5 |
+| `1-3` | UCs 1, 2, 3 |
+| `1,3-5,7` | UCs 1, 3, 4, 5, 7 |
+| `all` | All UCs |
+
+**After selection, store plan:**
+```
+implementationPlan = {
+  mode: "one-by-one" | "multiple" | "all",
+  ucs: [UC-AUTH-001, UC-AUTH-003, ...],
+  currentIndex: 0
+}
+```
+
+**Flow Visualization:**
+
+```
+Mode: ONE BY ONE (Recommended)
+─────────────────────────────
+UC #1: Implement → Test → ✓ Pass → [ASK USER: Continue?]
+                                         ↓ Yes
+UC #2: Implement → Test → ✓ Pass → [ASK USER: Continue?]
+                                         ↓ Yes
+UC #3: Implement → Test → ✓ Pass → Done
+
+
+Mode: MULTIPLE / ALL AT ONCE
+────────────────────────────
+UC #1: Implement → Test → ✓ Pass → [Auto-continue]
+                                         ↓
+UC #2: Implement → Test → ✓ Pass → [Auto-continue]
+                                         ↓
+UC #3: Implement → Test → ✓ Pass → Done
+```
+
+**Key Point:** Testing (Phase 7) is a checkpoint after each UC in ALL modes.
+- "One by one": Test passes → Ask user before next UC
+- "Multiple/All": Test passes → Automatically start next UC
+
+### Phase 1: Load Context
 
 ```
 1. Read UC spec
@@ -85,7 +159,7 @@ Updates to specs:
    → Warn if not, let user decide to proceed
 ```
 
-### Phase 1: Determine Work Type
+### Phase 2: Determine Work Type
 
 Based on spec, determine what's needed:
 
@@ -103,7 +177,7 @@ Read spec → Extract:
 - Pages/routes needed?
 ```
 
-### Phase 2: Load Sub-Skills
+### Phase 3: Load Sub-Skills
 
 **If backend work needed:**
 ```
@@ -127,7 +201,7 @@ Tech detected from scout:
 - react → react.md
 ```
 
-### Phase 3: Execute Backend (if needed)
+### Phase 4: Execute Backend (if needed)
 
 Follow dev-coding-backend workflow:
 
@@ -154,7 +228,7 @@ Follow dev-coding-backend workflow:
    - Request/response shapes
    - Auth requirements
 
-### Phase 4: Execute Frontend (if needed)
+### Phase 5: Execute Frontend (if needed)
 
 Follow dev-coding-frontend workflow:
 
@@ -174,7 +248,7 @@ Follow dev-coding-frontend workflow:
    - Visual check (Playwright screenshot or manual)
    - Interaction test
 
-### Phase 5: Integration Test
+### Phase 6: Integration Test
 
 End-to-end verification:
 
@@ -240,7 +314,9 @@ Run through `_quality-attributes.md` Implementation Level checklists:
 
 ### Phase 7: Auto-Test
 
-**Automatically run testing to verify implementation:**
+**CRITICAL: Testing runs after EVERY UC implementation (all modes).**
+
+Testing verifies each UC before proceeding to the next:
 
 ```
 1. Load dev-test skill
@@ -250,19 +326,36 @@ Run through `_quality-attributes.md` Implementation Level checklists:
    → From project config or spec
    → Default: http://localhost:3000/{path}
 
-3. Run E2E test
+3. Run E2E test for CURRENT UC
    → Navigate to page
    → Execute user flow from spec
    → Capture errors
 
-4. Analyze results
+4. Run regression tests (if previous UCs exist)
+   → Quick smoke test of previously completed UCs
+   → Ensures new UC didn't break existing functionality
+   → Example: UC-AUTH-002 (Signup) shouldn't break UC-AUTH-001 (Login)
+
+   Regression approach:
+   - If only 1-2 previous UCs: Full test
+   - If 3+ previous UCs: Critical path only (login flow, main actions)
+   - Skip if UCs are completely independent
+
+5. Analyze results
    → Console errors?
    → Network failures?
    → Visual issues?
+   → Regression failures?
+
+6. Handle results:
+   - All pass (current + regression) → Proceed to Phase 8 (Complete)
+   - Current UC fails → Fix current UC and re-test
+   - Regression fails → Fix regression issue (may need to update previous UC)
 
-5. Handle results:
-   - All pass → Proceed to Phase 8
-   - Issues found → Report and fix
+   IMPORTANT: Do NOT proceed to next UC until:
+   - Current UC passes all tests
+   - Previous UCs still work (regression pass)
+   This ensures quality and prevents cascading failures.
 ```
 
 **Test Flow:**
@@ -300,12 +393,14 @@ if (hasErrors) {
 
 ### Phase 8: Complete
 
+**This phase runs after each UC is implemented AND tested.**
+
 1. **Update spec status**
    ```markdown
    <!-- In specs/{UC-ID}/README.md -->
    > **Status**: Complete
    > **Completed**: {date}
-   > **Tested**: ✓ Pass
+   > **Tested**: ✓ Pass (Phase 7)
    ```
 
 2. **Document changes**
@@ -330,15 +425,56 @@ if (hasErrors) {
 
 3. **Update docs-graph** (automatic via hook)
 
-4. **Suggest next action**
-   ```markdown
-   ✅ **Implementation complete and tested.**
-
-   💡 **Suggestions:**
-   - Run `/dev-review` to review changes before commit
-   - UC-AUTH-002 (Signup) is now unblocked
+4. **Continue with next UC (if applicable)**
+   ```
+   IMPORTANT: This step only runs if Phase 7 (Testing) passed.
+   If tests fail, fix issues and re-test before continuing.
+
+   Check implementationPlan from Phase 0:
+
+   If more UCs remaining:
+     Mode "one-by-one":
+       → Show: "✓ UC-AUTH-001 implemented and tested successfully!"
+       → Show: "Remaining: UC-AUTH-002, UC-AUTH-003, UC-AUTH-004"
+       → Ask (AskUserQuestion): "Continue with UC-AUTH-002?"
+          Options:
+          - Yes (continue with next UC)
+          - No (stop here, can resume later)
+          - Select different UCs (return to Phase 0)
+       → Yes: currentIndex++, restart from Phase 1
+       → No: Show summary, stop
+       → Select: Return to Phase 0 for new selection
+
+     Mode "multiple" or "all":
+       → Show: "✓ UC-AUTH-001 implemented and tested successfully!"
+       → Automatically: currentIndex++
+       → Restart from Phase 1 with next UC
+       → No user prompt until all selected UCs complete
+
+   If all UCs complete:
+     → Show summary (see below)
+     → Suggest /dev-review {feature}
    ```
 
+**Summary Output (all UCs complete):**
+```markdown
+✅ All Use Cases Implemented
+
+**Completed:**
+- UC-AUTH-001: User Login ✓
+- UC-AUTH-003: Password Reset ✓
+- UC-AUTH-004: Email Verification ✓
+
+**Stats:**
+- Files changed: 12
+- Tests: All passing
+- Duration: ~45 minutes
+
+**Next Steps:**
+- Run `/dev-review auth` for code review
+- Create PR when ready
+```
+
 ## Communication Protocol
 
 ### When to Ask
@@ -439,8 +575,9 @@ When coding, use Context7 to look up library APIs:
 | `/utils/docs-graph` | Auto-updates on file changes |
 | `/dev-review` | Review after testing passes |
 
-## Example Flow
+## Example Flows
 
+### Example 1: Specific UC (Skip Selection)
 ```
 User: /dev-coding UC-AUTH-001
 
@@ -479,3 +616,146 @@ User: /dev-coding UC-AUTH-001
    → Suggest: "Run /dev-review before committing"
    → Note: "UC-AUTH-002 (Signup) is now unblocked"
 ```
+
+### Example 2: One by One Mode (Recommended)
+```
+User: /dev-coding auth
+
+📋 Available Use Cases for auth:
+  1. UC-AUTH-001: User Login
+  2. UC-AUTH-002: User Signup
+  3. UC-AUTH-003: Password Reset
+
+? Which use cases would you like to implement?
+  ◉ One by one (Recommended) ← User selects this
+  ○ Multiple (custom selection)
+  ○ All at once
+
+───────────────────────────────────────────────
+🔨 UC-AUTH-001: User Login
+───────────────────────────────────────────────
+
+Phase 1-6: Implement backend + frontend
+Phase 7: Auto-test
+  ✓ Navigate to /login
+  ✓ Fill form and submit
+  ✓ No console errors
+  ✓ API returns 200
+  ✓ Redirect to /dashboard works
+
+Phase 8: Complete
+  ✓ UC-AUTH-001 implemented and tested successfully!
+
+  Remaining: UC-AUTH-002, UC-AUTH-003
+
+  ? Continue with UC-AUTH-002? ← Prompt after testing passes
+    ◉ Yes (continue)
+    ○ No (stop here)
+    ○ Select different UCs
+
+User selects: Yes
+
+───────────────────────────────────────────────
+🔨 UC-AUTH-002: User Signup
+───────────────────────────────────────────────
+
+Phase 1-6: Implement backend + frontend
+Phase 7: Auto-test
+  ✓ Navigate to /signup
+  ✓ Fill registration form
+  ✓ Submit and verify
+  ✗ Console error: "Email validation failed"
+
+  ⚠️  Tests failed. Fixing...
+  → Updated validation logic
+  → Re-testing...
+  ✓ All tests pass
+
+Phase 8: Complete
+  ✓ UC-AUTH-002 implemented and tested successfully!
+
+  Remaining: UC-AUTH-003
+
+  ? Continue with UC-AUTH-003?
+    ◉ Yes
+    ○ No (stop here)
+    ○ Select different UCs
+
+User selects: No
+
+───────────────────────────────────────────────
+Summary
+───────────────────────────────────────────────
+✅ Completed:
+- UC-AUTH-001: User Login ✓
+- UC-AUTH-002: User Signup ✓
+
+⏸️  Pending:
+- UC-AUTH-003: Password Reset
+
+💡 Next steps:
+- Run /dev-review auth
+- Resume later with: /dev-coding UC-AUTH-003
+```
+
+**Key Points in "One by One" Mode:**
+1. Each UC is **fully implemented** (Phases 1-6)
+2. Each UC is **fully tested** (Phase 7) before prompting
+3. User gets a **checkpoint** to review/test manually if desired
+4. User **chooses** whether to continue or stop
+5. If tests fail, they're **fixed before** asking to continue
+6. Can **resume later** from any UC
+
+### Potential Issues with "One by One" Testing
+
+While "one by one" is the safest mode, be aware of these considerations:
+
+| Issue | Description | Mitigation |
+|-------|-------------|------------|
+| **Integration gaps** | UCs tested individually might miss cross-UC interactions | After all UCs complete, run full integration test |
+| **Shared state** | Later UCs might depend on state from earlier UCs | Use cumulative testing (don't reset DB between UCs) |
+| **Conflicting changes** | UC #3 might need different approach than UC #1 implemented | May need to refactor earlier UCs (acceptable tradeoff) |
+| **Performance at scale** | Individual UCs work, but all together cause issues | Final integration test should include load testing |
+| **Git commit strategy** | Should each UC be committed separately? | Depends on team workflow (see below) |
+
+**Best Practice - Cumulative Testing:**
+```
+UC #1: Test in isolation ✓
+UC #2: Test UC #2 + verify UC #1 still works ✓
+UC #3: Test UC #3 + verify UC #1, UC #2 still work ✓
+```
+
+This ensures each UC works both **independently** and **together**.
+
+**Implementation in Phase 7:**
+```javascript
+// For UC #2 onwards, add regression checks
+Phase 7: Auto-Test
+1. Test current UC (UC-AUTH-002: Signup) ✓
+2. Regression: Quick test of previous UCs
+   → UC-AUTH-001 (Login) still works? ✓
+3. All pass → Continue
+```
+
+**Git Strategy for "One by One":**
+
+| Strategy | When to Use | Commits |
+|----------|-------------|---------|
+| **Commit each UC** | When UCs are independent, team reviews incrementally | 1 commit per UC |
+| **Commit all together** | When UCs are tightly coupled, want atomic feature | 1 commit after all UCs |
+| **Hybrid** | Mix of both - commit stable UCs, batch dependent ones | Flexible |
+
+**Recommended Git Flow:**
+```
+One by One Mode:
+UC #1 complete → Commit → Continue?
+UC #2 complete → Commit → Continue?
+UC #3 complete → Commit → Done
+
+Multiple/All Mode:
+UC #1 complete → Auto-continue (no commit)
+UC #2 complete → Auto-continue (no commit)
+UC #3 complete → Single commit for all → Done
+```
+
+This gives "one by one" the advantage of **incremental commits** that are easier to review and revert.

package/skills/dev-scout/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-scout
 description: Explore and document existing codebases at various depths
-version: 2.8.0
+version: 2.9.0
 ---
 
 # /dev-scout - Codebase Explorer
@@ -153,6 +153,41 @@ Track coverage in output:
 
 ## Workflow
 
+### Step -1: Ensure Project Scout Exists (for Feature Scouts)
+
+**IMPORTANT**: If running a feature-level scout, check if project-level scout exists first:
+
+```
+If user requested: /dev-scout {feature} (feature-level)
+1. Check: plans/scout/stack.md exists?
+   → No: Run project-level scout FIRST
+      - Notify: "No project scout found. Analyzing entire project first, then {feature}..."
+      - Execute: Project-level scout (steps below)
+      - Output: plans/scout/README.md, structure.md, features.md, stack.md
+   → Yes: Continue to feature-level scout
+
+If user requested: /dev-scout (project-level)
+→ Skip this check, proceed directly to Step 0
+```
+
+**Why this matters:**
+- Feature scouts need project context (tech stack, patterns, structure)
+- `stack.md` is critical for understanding HOW the project works
+- Prevents isolated feature analysis without understanding the whole
+- Downstream skills (`/dev-specs`, `/dev-coding`) depend on `stack.md`
+
+**User Experience:**
+```
+User: /dev-scout auth
+Assistant: "No project scout found. I'll analyze the entire project first to understand the tech stack and structure, then focus on the auth feature specifically."
+
+[Runs project-level scout]
+✓ Project scout complete: plans/scout/
+
+[Then runs feature scout]
+✓ Feature scout complete: plans/features/auth/scout.md
+```
+
 ### Step 0: Check Documentation Graph
 
 Before exploring code, check existing documentation context:

package/skills/dev-specs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-specs
 description: Generate implementation specifications from BRD use cases
-version: 1.5.0
+version: 1.6.0
 ---
 
 # /dev-specs - Implementation Specifications
@@ -99,10 +99,28 @@ Before generating specs, verify prerequisites and gather context:
 **Auto-Scout Logic:**
 
 If scout.md doesn't exist:
-1. Notify user: "No scout found for {feature}, running analysis..."
-2. Execute scout workflow (medium mode) for the feature
-3. Save to `plans/features/{feature}/scout.md`
-4. Continue to Phase 1
+1. **First check if project-level scout exists:**
+   ```
+   Check: plans/scout/stack.md exists?
+   → No: Run project-level scout FIRST
+      - Notify: "No project scout found, analyzing entire codebase first..."
+      - Execute: /dev-scout (project-level, medium mode)
+      - Output: plans/scout/README.md, structure.md, features.md, stack.md
+      - This provides project-wide context and stack configuration
+   → Yes: Continue to feature scout
+   ```
+
+2. **Then run feature-level scout:**
+   - Notify user: "Running targeted analysis for {feature}..."
+   - Execute scout workflow (medium mode) for the feature
+   - Save to `plans/features/{feature}/scout.md`
+
+3. Continue to Phase 1
+
+**Why project scout first?**
+- `stack.md` tells us HOW to write specs (SDK, patterns, validation)
+- Prevents specs from suggesting wrong approaches (raw fetch vs. SDK)
+- Feature scout can reference project context for better targeting
 
 **Docs-Graph Integration:**
 
@@ -193,7 +211,8 @@ Read `plans/scout/stack.md` to understand HOW to implement:
 
 ```
 1. Check: plans/scout/stack.md exists?
-   → No: Warn "Run /dev-scout for better specs"
+   → No: This should not happen (Phase 0 auto-scout ensures it exists)
+   → Yes: Continue
 
 2. Extract key information:
    → API Layer: BaaS, REST, GraphQL, tRPC