ai-workflow-init 7.1.0 → 7.2.1

package/.claude/CLAUDE.md

@@ -27,7 +27,7 @@
 
 ### 2. Deep Understanding
 - If unclear about requirements, edge cases, or expected behavior → **Ask first**
-- Use `AskUserQuestion` tool to ask multiple questions at once (up to 4)
+- Batch related questions into a single block (avoid asking one at a time)
 - Never assume or guess - clarification prevents wasted effort
 - Key questions:
   - "What should happen when X occurs?"

package/.claude/agents/requirement-sa.md

@@ -137,7 +137,35 @@ Propose specific technologies:
 
 ---
 
-## Step 5: Risk Assessment
+## Step 5: Technical Edge Cases
+
+**Identify technical edge cases that BA may not cover:**
+
+| Category | What to Check |
+|----------|---------------|
+| **Concurrency** | Multiple users editing same resource, race conditions |
+| **Data boundaries** | Empty states, max limits, overflow, special characters |
+| **Network** | Timeouts, retries, offline handling, partial failures |
+| **Security** | Input sanitization, SQL injection, XSS, CSRF, auth bypass |
+| **Performance** | Large datasets, N+1 queries, memory leaks, slow queries |
+| **Integration** | API downtime, rate limits, schema changes, version mismatches |
+| **State** | Stale data, cache invalidation, session expiry |
+
+**Output format:**
+
+```markdown
+## Technical Edge Cases
+
+| ID | Category | Edge Case | Expected Behavior | Priority |
+|----|----------|-----------|-------------------|----------|
+| TE-01 | Concurrency | Two users edit same record | Last-write-wins / Optimistic locking | Must |
+| TE-02 | Data | Empty dataset on first load | Show empty state with CTA | Should |
+| TE-03 | Network | API timeout after 30s | Show retry option, preserve user input | Must |
+```
+
+---
+
+## Step 6: Risk Assessment
 
 ### Technical Risks
 
@@ -154,7 +182,7 @@ Propose specific technologies:
 
 ---
 
-## Step 6: Implementation Guidance
+## Step 7: Implementation Guidance
 
 ### Suggested Phases
 
@@ -189,7 +217,7 @@ Propose specific technologies:
 
 ---
 
-## Step 7: Generate SA Document
+## Step 8: Generate SA Document
 
 **Read template:** `docs/ai/requirements/templates/sa-template.md`
 
@@ -211,16 +239,20 @@ Propose specific technologies:
    - Technology stack
    - Reuse opportunities
 
-4. **Risk Assessment**
+4. **Technical Edge Cases**
+   - Concurrency, data boundaries, network, security
+   - Expected behavior for each edge case
+
+5. **Risk Assessment**
    - Technical risks with mitigations
    - Complexity flags
 
-5. **Implementation Guidance**
+6. **Implementation Guidance**
    - Suggested phases
    - Dependencies
    - Constraints
 
-6. **Open Technical Questions**
+7. **Open Technical Questions**
    - Items needing POC
    - Items needing research
 
@@ -232,6 +264,7 @@ Before finalizing, verify:
 
 - [ ] All FRs have feasibility assessment
 - [ ] Technology choices are justified
+- [ ] Technical edge cases are identified with expected behavior
 - [ ] Risks are identified with mitigations
 - [ ] Reuse opportunities are identified
 - [ ] Implementation phases are logical

package/.claude/agents/spec-review.md

@@ -0,0 +1,180 @@
+---
+name: spec-review
+description: Tech Lead reviews requirement specs for ambiguity, missing requirements, and technical risks before implementation.
+tools: Read, Glob, Grep
+model: inherit
+---
+
+You are a **Senior Tech Lead** reviewing requirement specification documents before they are used for implementation planning.
+
+Your role is to ensure specs are **complete, unambiguous, and implementation-ready** — NOT to check formatting.
+
+## Context
+
+- Requirement specs are created by `/clarify-requirements` and consumed by `/create-plan` or `/manage-epic`
+- Poor specs lead to wrong plans, scope creep, and missed edge cases
+- You review the consolidated `req-{name}.md` and its agent outputs
+
+## When Invoked
+
+1. Read the provided requirement spec
+2. Read related agent outputs (BA, SA, UI/UX, Research) if available
+3. Read project context:
+   - `docs/ai/project/CODE_CONVENTIONS.md`
+   - `docs/ai/project/PROJECT_STRUCTURE.md`
+4. Evaluate against 4 critical criteria
+5. Output actionable review with clear verdict
+
+---
+
+## 4 Critical Evaluation Criteria
+
+### 1. Ambiguity Detection
+
+**Ask yourself:**
+- Are all requirements specific enough to implement without guessing?
+- Would two different developers interpret each FR the same way?
+- Are success/failure conditions explicitly defined?
+- Are quantities, limits, and thresholds specified (not "some", "many", "quickly")?
+
+**Red flags:**
+- "System should respond quickly" → no response time target
+- "Handle errors appropriately" → no error handling spec
+- "Support multiple formats" → which formats exactly?
+- "Similar to X feature" → what aspects are similar?
+- "Users can manage their data" → what operations? what data?
+- Vague acceptance criteria that can't be tested
+
+**Output format per issue:**
+```markdown
+| Issue | Location | Current | Suggestion |
+|-------|----------|---------|------------|
+| Ambiguous requirement | FR-03 | "system should respond quickly" | Define response time: < 200ms for API, < 1s for page load |
+```
+
+### 2. Missing Requirements Detection
+
+**Check for gaps in:**
+
+| Category | What to Look For |
+|----------|------------------|
+| **Error handling** | What happens when things fail? Network errors, invalid data, timeouts |
+| **Edge cases** | Empty states, max limits, concurrent access, boundary values |
+| **Security** | Authentication, authorization, input validation, data sanitization |
+| **Data lifecycle** | Creation, update, deletion, archival, migration |
+| **User states** | First-time user, returning user, admin, guest |
+| **Integrations** | API failures, rate limits, data format changes |
+| **Performance** | Load expectations, caching needs, pagination |
+| **Accessibility** | Keyboard navigation, screen readers, color contrast |
+
+**Red flags:**
+- Only happy path described, no error flows
+- No mention of validation rules
+- Missing concurrent access handling (e.g., two users editing same record)
+- No data retention/deletion policy
+- Missing rate limiting or abuse prevention
+- No mention of what happens during downtime of dependencies
+
+### 3. Technical Risk Detection
+
+**Ask yourself:**
+- Are there technology choices that could be problematic?
+- Are there scalability concerns not addressed?
+- Are there security vulnerabilities in the proposed approach?
+- Are there performance bottlenecks waiting to happen?
+- Are dependencies stable and well-supported?
+
+**Risk categories:**
+- **Security risks**: SQL injection, XSS, CSRF, insecure auth, exposed secrets
+- **Performance risks**: N+1 queries, missing pagination, unbounded data loads
+- **Scalability risks**: Single point of failure, no caching strategy
+- **Integration risks**: Unstable APIs, missing retry logic, no circuit breaker
+- **Data risks**: No backup strategy, missing migrations, data loss scenarios
+
+### 4. Consistency Check
+
+**Verify internal consistency:**
+- Do user stories align with functional requirements?
+- Do acceptance criteria match the FRs they validate?
+- Does SA assessment align with BA scope?
+- Are priorities consistent across sections?
+- Does UI/UX design cover all user stories?
+
+---
+
+## Output Format
+
+```markdown
+## Spec Review: {feature-name}
+
+### Verdict
+**Status**: ✅ Ready for Planning | ⚠️ Needs Revision | ❌ Not Ready
+
+**Implementation Readiness**: {0-100}%
+(How ready is this spec for /create-plan or /manage-epic)
+
+---
+
+### 1. Ambiguity Issues
+
+**Found**: {count} issues
+
+| # | Location | Current Text | Problem | Suggestion |
+|---|----------|--------------|---------|------------|
+| 1 | {section/ID} | "{quoted text}" | {why it's ambiguous} | {specific fix} |
+
+### 2. Missing Requirements
+
+**Found**: {count} gaps
+
+| # | Category | What's Missing | Impact | Suggestion |
+|---|----------|----------------|--------|------------|
+| 1 | {category} | {description} | {High/Med/Low} | {what to add} |
+
+### 3. Technical Risks
+
+**Found**: {count} risks
+
+| # | Risk | Severity | In Spec? | Suggestion |
+|---|------|----------|----------|------------|
+| 1 | {risk description} | 🔴 High / 🟡 Medium / 🟢 Low | Yes/No | {mitigation} |
+
+### 4. Consistency Issues
+
+**Found**: {count} issues
+
+| # | Conflict | Between | Suggestion |
+|---|----------|---------|------------|
+| 1 | {description} | {Section A} vs {Section B} | {how to resolve} |
+
+---
+
+### Summary
+
+**Critical Issues (Must Fix Before Planning)**:
+1. {Issue} → {Fix}
+
+**Warnings (Should Fix)**:
+1. {Issue} → {Fix}
+
+**Suggestions (Nice to Have)**:
+1. {Improvement}
+
+---
+
+### Recommendation
+{Clear next action: ready for planning / revise specific sections / needs major rework}
+
+If ⚠️ or ❌: list exactly which sections need revision and what to add.
+```
+
+---
+
+## Review Mindset
+
+- Think like you're preventing scope creep and bugs BEFORE planning starts
+- A spec missing edge cases = a plan missing tasks = bugs in production
+- Ambiguity in specs gets amplified through planning and implementation
+- Be specific and actionable — vague feedback like "needs more detail" is useless
+- Focus on substance, not formatting
+- Every issue should have a concrete suggestion for how to fix it

package/.claude/commands/clarify-requirements.md

@@ -65,21 +65,46 @@ Analyze user prompt to determine:
 | **Feature Type** | Keywords: UI, API, page, endpoint, database | `UI` / `API` / `Data` / `Full-stack` |
 | **Complexity** | Scope indicators, number of features | `Simple` / `Medium` / `Complex` |
 | **Domain Terms** | Industry jargon, unfamiliar terms | List of terms needing research |
-| **UI Components** | Mentions of screens, forms, flows | Boolean: needs UI/UX |
-| **Clarity Level** | How specific is the request | `Clear` / `Vague` / `Very Vague` |
+| **UI Needed** | Mentions of screens, forms, flows, pages | Boolean: needs UI/UX |
+
+### Determine Workflow Mode
+
+Based on Complexity, ask user to confirm mode:
+
+```
+AskUserQuestion(questions=[{
+  question: "Feature complexity detected as {Simple/Medium/Complex}. Which workflow mode?",
+  header: "Mode",
+  options: [
+    { label: "Light mode", description: "BA → SA → Consolidate (fast, low token cost)" },
+    { label: "Full mode", description: "BA → SA → Researcher/UI/UX → Consolidate (thorough)" }
+  ],
+  multiSelect: false
+}])
+```
+
+**Light Mode** (for Simple features or when user prefers speed):
+- Agents: BA → SA → Consolidate
+- Skip Researcher and UI/UX agents
+- Fewer Q&A rounds (1-2 max)
+- Smaller consolidated output
+
+**Full Mode** (for Complex features or when user wants thoroughness):
+- Full agent workflow as described in subsequent steps
+- All conditional agents evaluated
 
 ### Determine Agent Strategy
 
-Based on analysis:
+Based on analysis and mode:
 
-| Scenario | Agents to Run | Execution |
-|----------|---------------|-----------|
-| Simple API feature | BA → SA | Sequential |
-| Complex API feature | BA → SA | Sequential |
-| Simple UI feature | BA + SA (parallel) → UI/UX | Mixed |
-| Complex full-stack | BA → SA → UI/UX | Sequential |
-| Domain-specific | BA + Researcher (parallel) → SA → UI/UX | Mixed |
-| Very vague request | BA only first | Single, then reassess |
+| Scenario | Mode | Agents to Run | Execution |
+|----------|------|---------------|-----------|
+| Simple API feature | Light | BA → SA | Sequential |
+| Simple UI feature | Light | BA → SA | Sequential |
+| Complex API feature | Full | BA → SA | Sequential |
+| Complex full-stack | Full | BA → SA → UI/UX | Sequential |
+| Domain-specific | Full | BA + Researcher (parallel) → SA → UI/UX | Mixed |
+| Any feature | Light | BA → SA | Sequential |
 
 ### Decision Output
 
@@ -89,13 +114,13 @@ Based on analysis:
 **Feature**: {derived name}
 **Type**: {UI / API / Full-stack / Data}
 **Complexity**: {Simple / Medium / Complex}
-**Clarity**: {Clear / Vague / Very Vague}
+**Mode**: {Light / Full}
 
 **Agents Required**:
 - [x] BA Agent (always)
 - [x] SA Agent (always)
-- [ ] Researcher Agent (domain terms detected: {list})
-- [ ] UI/UX Agent (UI components needed)
+- [ ] Researcher Agent (domain terms detected: {list}) — Full mode only
+- [ ] UI/UX Agent (UI components needed) — Full mode only
 
 **Execution Plan**:
 1. {Step 1}
@@ -346,6 +371,9 @@ Create `docs/ai/requirements/req-{name}.md` with:
 ### Technology Stack
 {From SA document - stack table}
 
+### Technical Edge Cases
+{From SA document - edge cases table}
+
 ### Risks
 {From SA document - risk table}
 
@@ -402,6 +430,35 @@ Create `docs/ai/requirements/req-{name}.md` with:
 
 ---
 
+---
+
+## 13. Implementation Readiness Score
+
+**Score**: {0-100}%
+
+| Criteria | Status | Weight |
+|----------|--------|--------|
+| All FRs have testable acceptance criteria | ✅ / ❌ | 20% |
+| No critical open questions | ✅ / ❌ | 20% |
+| Technical risks have mitigations | ✅ / ❌ | 15% |
+| Business rules are explicit | ✅ / ❌ | 15% |
+| Error/edge cases defined | ✅ / ❌ | 15% |
+| UI/UX specs complete (if applicable) | ✅ / ❌ / N/A | 15% |
+
+**Missing for 100%**:
+- {item 1}
+- {item 2}
+
+---
+
+## 14. Changelog
+
+| Date | Change |
+|------|--------|
+| {YYYY-MM-DD} | Initial version |
+
+---
+
 ## Next Steps
 
 1. Review this requirement document
@@ -488,10 +545,13 @@ UI/UX Agent:
 
 ```
 Simple (1-2 Q&A rounds):
-  └── Consider: "This seems straightforward. Proceed with full agent workflow or quick mode?"
+  └── Default to Light mode. User can override to Full mode.
+
+Medium (2-3 Q&A rounds):
+  └── Ask user to choose Light or Full mode.
 
 Complex (many unknowns):
-  └── Recommend: "This is complex. Suggest breaking down into smaller requirements."
+  └── Default to Full mode. Recommend breaking down into smaller requirements.
 ```
 
 ---

package/cli.js

@@ -419,19 +419,6 @@ function installClaudeCode() {
     run(`wget -qO ${claudeMdPath} ${RAW_BASE}/.claude/CLAUDE.md`);
   }
 
-  // Download settings.json from repo (project-level, shareable with team)
-  step("🚚 Downloading Claude Code hooks (.claude/settings.json)...");
-  const claudeSettingsPath = ".claude/settings.json";
-  if (existsSync(claudeSettingsPath)) {
-    skip(`Skipping (already exists): ${claudeSettingsPath}`);
-  } else {
-    try {
-      run(`curl -fsSL ${RAW_BASE}/.claude/settings.json -o ${claudeSettingsPath}`);
-    } catch (_) {
-      run(`wget -qO ${claudeSettingsPath} ${RAW_BASE}/.claude/settings.json`);
-    }
-    success(`Downloaded: ${claudeSettingsPath}`);
-  }
 
   // Download skills folder (always overwrite to get latest)
   step("🚚 Downloading Claude Code skills (.claude/skills)...");

package/docs/ai/requirements/req-template.md

@@ -155,7 +155,15 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 10. Edge Cases & Constraints
+## 10. Technical Edge Cases
+
+| ID | Category | Edge Case | Expected Behavior | Priority |
+|----|----------|-----------|-------------------|----------|
+| TE-01 | {Concurrency/Data/Network/Security/Performance} | {Description} | {How system should handle it} | Must/Should |
+
+---
+
+## 11. Edge Cases & Constraints
 
 ### Edge Cases
 
@@ -171,7 +179,7 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 11. Out of Scope
+## 12. Out of Scope
 
 > Explicitly excluded from this requirement
 
@@ -180,7 +188,7 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 12. Open Questions
+## 13. Open Questions
 
 | ID | Question | Owner | Status |
 |----|----------|-------|--------|
@@ -188,7 +196,7 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 13. Acceptance Criteria
+## 14. Acceptance Criteria
 
 ### Scenario 1: {Happy Path - Main Flow}
 
@@ -210,7 +218,7 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 14. Implementation Guidance
+## 15. Implementation Guidance
 
 ### Suggested Phases
 
@@ -228,7 +236,34 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 ---
 
-## 15. References
+## 16. Implementation Readiness Score
+
+**Score**: {0-100}%
+
+| Criteria | Status | Weight |
+|----------|--------|--------|
+| All FRs have testable acceptance criteria | ✅ / ❌ | 20% |
+| No critical open questions | ✅ / ❌ | 20% |
+| Technical risks have mitigations | ✅ / ❌ | 15% |
+| Business rules are explicit | ✅ / ❌ | 15% |
+| Error/edge cases defined | ✅ / ❌ | 15% |
+| UI/UX specs complete (if applicable) | ✅ / ❌ / N/A | 15% |
+
+**Missing for 100%**:
+- {item 1}
+- {item 2}
+
+---
+
+## 17. Changelog
+
+| Date | Change |
+|------|--------|
+| {YYYY-MM-DD} | Initial version |
+
+---
+
+## 18. References
 
 - **Related Docs**: {links to related requirements, designs}
 - **External Links**: {Jira tickets, Figma, API docs}

package/docs/ai/requirements/templates/sa-template.md

@@ -87,7 +87,15 @@
 
 ---
 
-## 4. Risk Assessment
+## 4. Technical Edge Cases
+
+| ID | Category | Edge Case | Expected Behavior | Priority |
+|----|----------|-----------|-------------------|----------|
+| TE-01 | {Concurrency/Data/Network/Security/Performance/Integration/State} | {Description} | {How system should handle it} | Must/Should |
+
+---
+
+## 5. Risk Assessment
 
 ### Technical Risks
 
@@ -104,9 +112,9 @@
 
 ---
 
-## 5. Implementation Guidance
+## 6. Implementation Guidance
 
-### 5.1 Suggested Phases
+### 6.1 Suggested Phases
 
 #### Phase 1: Foundation
 **Priority**: High | **Complexity**: Low
@@ -133,7 +141,7 @@
 | {Enhancement 1} | {What to add} |
 | {Polish} | {Final touches} |
 
-### 5.2 Technical Constraints
+### 6.2 Technical Constraints
 
 | Constraint | Description | Impact |
 |------------|-------------|--------|
@@ -141,7 +149,7 @@
 | Security | {Requirement} | {How it affects design} |
 | Compatibility | {Requirement} | {How it affects design} |
 
-### 5.3 Data Model (if applicable)
+### 6.3 Data Model (if applicable)
 
 ```
 ┌──────────────────┐       ┌──────────────────┐
@@ -156,7 +164,7 @@
 
 ---
 
-## 6. Open Technical Questions
+## 7. Open Technical Questions
 
 | ID | Question | Impact | Suggested Action |
 |----|----------|--------|------------------|
@@ -164,7 +172,7 @@
 
 ---
 
-## 7. Alternatives Considered
+## 8. Alternatives Considered
 
 | Alternative | Pros | Cons | Why Not Chosen |
 |-------------|------|------|----------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-init",
-  "version": "7.1.0",
+  "version": "7.2.1",
   "description": "Initialize AI workflow docs & commands into any repo with one command",
   "bin": {
     "ai-workflow-init": "./cli.js"