@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/session/refine.md

@@ -0,0 +1,188 @@
+# /session:refine
+
+Refine requirements or plan before continuing execution.
+
+---
+
+## Syntax
+
+```
+/session:refine [requirements|plan]
+```
+
+---
+
+## Behavior
+
+Opens refinement mode to adjust requirements or technical plan without creating a new iteration.
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Minor clarification needed | `/session:refine requirements` |
+| Technical approach adjustment | `/session:refine plan` |
+| Add missing AC | `/session:refine requirements` |
+| Change implementation detail | `/session:refine plan` |
+
+**Note:** For major scope changes, use `/session:scope-change` instead.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:refine                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load current session                                        │
+│     ↓                                                           │
+│  2. Show current state                                          │
+│     - requirements.md or plan.md                                │
+│     ↓                                                           │
+│  3. Ask for refinements                                         │
+│     - What needs to change?                                     │
+│     - Why?                                                      │
+│     ↓                                                           │
+│  4. Apply changes                                               │
+│     - Update file                                               │
+│     - Log change in progress.md                                 │
+│     ↓                                                           │
+│  5. Show diff and confirm                                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example: Refine Requirements
+
+```
+/session:refine requirements
+```
+
+Output:
+
+```
+📝 REFINE REQUIREMENTS
+
+Session: stories/2026-01-11-new-products-entity
+
+─────────────────────────────────────────
+
+📋 CURRENT ACCEPTANCE CRITERIA
+
+AC1: Admin can create a new product ✓
+AC2: Admin can upload product images ✓
+AC3: Admin can assign products to categories
+AC4: Products are listed with pagination
+AC5: Team members can view products
+
+─────────────────────────────────────────
+
+What would you like to refine?
+> Add AC for product search functionality
+
+─────────────────────────────────────────
+
+📝 PROPOSED CHANGES
+
++ AC6: Products can be searched by name and SKU
+
+Why this change?
+> Client requested search feature during review
+
+─────────────────────────────────────────
+
+Apply these changes? [Yes/Edit/Cancel]
+
+> Yes
+
+✓ requirements.md updated
+✓ Change logged in progress.md
+```
+
+---
+
+## Example: Refine Plan
+
+```
+/session:refine plan
+```
+
+Output:
+
+```
+📐 REFINE PLAN
+
+Session: stories/2026-01-11-new-products-entity
+
+─────────────────────────────────────────
+
+📋 CURRENT PLAN
+
+## Phase 2: Backend
+- [ ] Configure entity in entities.config.ts
+- [ ] Add translations
+
+─────────────────────────────────────────
+
+What would you like to refine?
+> Need custom service for price calculation
+
+─────────────────────────────────────────
+
+📝 PROPOSED CHANGES
+
+## Phase 2: Backend
+- [ ] Configure entity in entities.config.ts
++ - [ ] Create ProductsService with price calculation
+- [ ] Add translations
+
+Estimated impact: +2 files
+
+─────────────────────────────────────────
+
+Apply these changes? [Yes/Edit/Cancel]
+
+> Yes
+
+✓ plan.md updated
+✓ scope.json updated (2 new files)
+✓ Change logged in progress.md
+```
+
+---
+
+## Refinement vs Scope Change
+
+| Refinement | Scope Change |
+|------------|--------------|
+| Minor clarifications | Major new requirements |
+| Implementation details | New ACs that change scope |
+| Same T-Shirt size | T-Shirt size increases |
+| No new iteration | Creates new iteration |
+| `/session:refine` | `/session:scope-change` |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `requirements` | Refine requirements.md |
+| `plan` | Refine plan.md |
+| `--interactive` | Guided refinement mode |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:scope-change` | For major scope changes |
+| `/session:execute` | Continue after refinement |
+| `/session:status` | View current state |

package/claude/commands/session/resume.md

@@ -0,0 +1,192 @@
+# /session:resume
+
+Resume an existing session by recovering all context.
+
+---
+
+## Syntax
+
+```
+/session:resume [session-path]
+```
+
+---
+
+## Behavior
+
+### Without path (wizard)
+
+```
+/session:resume
+```
+
+Shows list of active sessions to select from.
+
+### With path
+
+```
+/session:resume stories/2026-01-11-new-entity
+/session:resume 2026-01-11-new-entity
+```
+
+Resumes the specified session directly.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:resume                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. SESSION SELECTION                                           │
+│     │                                                           │
+│     ├─► With path: Use that session                             │
+│     │                                                           │
+│     └─► Without path: Show wizard                               │
+│         ┌─────────────────────────────────────┐                 │
+│         │ Active sessions:                    │                 │
+│         │                                     │                 │
+│         │ STORIES:                            │                 │
+│         │ [1] 2026-01-11-new-entity (iter-02) │                 │
+│         │ [2] 2026-01-08-refactor-auth        │                 │
+│         │                                     │                 │
+│         │ TASKS:                              │                 │
+│         │ [3] 2026-01-10-improve-search       │                 │
+│         │                                     │                 │
+│         │ Which one to resume? [1-3]          │                 │
+│         └─────────────────────────────────────┘                 │
+│     ↓                                                           │
+│  2. CONTEXT LOADING                                             │
+│     │                                                           │
+│     │  For Stories:                                             │
+│     │  [✓] context.md                                           │
+│     │  [✓] requirements.md                                      │
+│     │  [✓] plan.md                                              │
+│     │  [✓] scope.json                                           │
+│     │  [✓] pendings.md                                          │
+│     │  [✓] iterations/*/closed.json                             │
+│     │  [✓] current/progress.md                                  │
+│     │                                                           │
+│     │  For Tasks:                                               │
+│     │  [✓] requirements.md                                      │
+│     │  [✓] progress.md                                          │
+│     ↓                                                           │
+│  3. CONTEXT SUMMARY                                             │
+│     ↓                                                           │
+│  4. ASK NEXT STEPS                                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+📋 SESSION LOADED
+
+Project: New Entity - Products
+Type: Story (STORY workflow)
+T-Shirt: L
+Iteration: 02-scope-change
+
+─────────────────────────────────────────
+
+📝 Objective:
+Implement Products entity with complete CRUD...
+
+📊 Current state:
+- Phase: EXECUTE (backend-developer completed)
+- Progress: 60%
+- Next: frontend-developer
+
+🔄 Scope change (iteration-02):
+- Added "variants" field to entity
+- Requires updating migrations and API
+
+📌 Global pending items:
+- [ ] Add performance tests
+- [ ] Document API endpoints
+- [ ] Review DB indexes
+
+─────────────────────────────────────────
+
+What would you like to do?
+[1] Continue from where you left off
+[2] View more details
+[3] Create new iteration
+[4] Change phase
+```
+
+---
+
+## File Reading Order
+
+### For Stories
+
+1. `context.md` → Understand the project
+2. `requirements.md` → What needs to be achieved
+3. `plan.md` → How to achieve it
+4. `scope.json` → What files are in scope
+5. `pendings.md` → What was left pending
+6. `iterations/*/closed.json` → Why each iteration was closed
+7. `current/progress.md` → Current phase state
+8. `current/changes.md` → What files were modified
+
+### For Tasks
+
+1. `requirements.md` → What needs to be achieved
+2. `progress.md` → Current state
+
+---
+
+## Iteration Evaluation
+
+For each closed iteration:
+
+```json
+{
+  "iteration": "01-initial",
+  "status": "completed",
+  "closedAt": "2026-01-05T10:30:00Z",
+  "summary": "Initial implementation, pending scope change",
+  "nextIteration": "02-scope-change"
+}
+```
+
+Claude must:
+1. **Read** closing reason
+2. **Extract** learnings (what worked, what didn't)
+3. **Not repeat** mistakes from previous iterations
+4. **Respect** previous decisions
+
+---
+
+## Special Considerations
+
+| Situation | Action |
+|-----------|--------|
+| High business risk | Remind when resuming |
+| Critical pending items | Show highlighted |
+| Previous iteration failed | Explain what went wrong |
+| Long time since last activity | Suggest reviewing code changes |
+
+---
+
+## Example with Alert
+
+```
+⚠️ RISK REMINDER
+
+This session works with: Checkout Flow (critical)
+
+Last activity: 5 days ago
+There have been 12 commits in the repo since then.
+
+Recommendation: Verify there are no conflicts with
+recent changes before continuing.
+
+Continue? [Yes/Review changes first]
+```

package/claude/commands/session/review.md

@@ -0,0 +1,192 @@
+# /session:review
+
+Request or perform code review for the session.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Reference these skills during review:
+- `.claude/skills/service-layer/SKILL.md` - Validate service patterns
+- `.claude/skills/react-patterns/SKILL.md` - Validate component patterns
+- `.claude/skills/zod-validation/SKILL.md` - Validate schema usage
+- `.claude/skills/tanstack-query/SKILL.md` - Validate data fetching patterns
+
+For security review:
+- `.claude/skills/api-bypass-layers/SKILL.md` - Multi-layer security validation
+- `.claude/skills/better-auth/SKILL.md` - Authentication patterns
+- `.claude/skills/permissions-system/SKILL.md` - Authorization validation
+
+---
+
+## Syntax
+
+```
+/session:review [--self]
+```
+
+---
+
+## Behavior
+
+Initiates code review process for the current session changes.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:review                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Collect changes                                             │
+│     - Read scope.json                                           │
+│     - Get modified files                                        │
+│     ↓                                                           │
+│  2. Analyze changes                                             │
+│     - Code quality                                              │
+│     - Security patterns                                         │
+│     - Performance implications                                  │
+│     - Best practices                                            │
+│     ↓                                                           │
+│  3. Generate review report                                      │
+│     - Issues found                                              │
+│     - Suggestions                                               │
+│     - Approval status                                           │
+│     ↓                                                           │
+│  4. Update session status                                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🔍 CODE REVIEW
+
+Session: stories/2026-01-11-new-products-entity
+Files changed: 12
+Lines added: 450
+Lines removed: 23
+
+─────────────────────────────────────────
+
+📋 REVIEW CATEGORIES
+
+## Security ✓
+No security issues found.
+
+## Performance ⚠
+- ProductsService.ts:45 - Consider caching for
+  frequently accessed products
+- Suggestion: Add index on `categoryId`
+
+## Code Quality ✓
+- Follows existing patterns
+- Proper TypeScript types
+- Good error handling
+
+## Best Practices ⚠
+- products.cy.ts:12 - Missing negative test case
+- ProductForm.tsx:89 - Consider extracting validation
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Critical Issues:  0
+Warnings:         2
+Suggestions:      2
+
+─────────────────────────────────────────
+
+Review Status: APPROVED WITH SUGGESTIONS
+
+Proceed to close session? [Yes/Address suggestions first]
+```
+
+---
+
+## With Critical Issues
+
+```
+❌ CODE REVIEW - CHANGES REQUIRED
+
+─────────────────────────────────────────
+
+## Security ❌
+
+CRITICAL: SQL injection vulnerability
+Location: ProductsService.ts:67
+
+```typescript
+// BAD - Direct string interpolation
+const query = `SELECT * FROM products WHERE name = '${name}'`;
+
+// GOOD - Use parameterized queries
+const query = `SELECT * FROM products WHERE name = $1`;
+```
+
+## Performance ❌
+
+CRITICAL: N+1 query detected
+Location: ProductsList.tsx:34
+- Each product triggers separate category fetch
+- Solution: Use eager loading or batch fetch
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Critical Issues:  2
+Warnings:         1
+Suggestions:      3
+
+─────────────────────────────────────────
+
+Review Status: CHANGES REQUIRED
+
+You must fix critical issues before proceeding.
+Run /session:execute to address the issues.
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--self` | Self-review mode (Claude reviews) |
+| `--detailed` | Show line-by-line analysis |
+| `--security-only` | Focus on security review |
+
+---
+
+## Task Manager Integration
+
+If `taskManager.enabled`:
+
+```
+📋 POSTING REVIEW
+
+ClickUp: #abc123
+
+Posting review comment...
+✓ Review posted
+
+Updating status to "In Review"...
+✓ Status updated
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:validate` | Validate before review |
+| `/session:execute` | Fix review issues |
+| `/session:close` | Close after approval |