wogiflow 1.0.21 → 1.0.22

package/.claude/commands/wogi-skills.md

@@ -0,0 +1,87 @@
+Manage skill packages for specialized development workflows.
+
+Usage:
+- `/wogi-skills` - List installed and available skills
+- `/wogi-skills add [name]` - Install a skill
+- `/wogi-skills remove [name]` - Remove a skill
+- `/wogi-skills info [name]` - Show skill details
+
+## What Are Skills?
+
+Skills are modular add-ons that provide:
+- Specialized slash commands
+- Code templates
+- Coding rules/conventions
+- Best practices for specific tech stacks
+
+## Available Skills
+
+| Skill | Description | Commands Added |
+|-------|-------------|----------------|
+| `nestjs` | NestJS module builder | `/nestjs-scaffold`, `/nestjs-entity`, `/nestjs-db` |
+| `react` | React component patterns | `/react-component`, `/react-hook` |
+| `python` | Python/FastAPI patterns | `/python-endpoint`, `/python-test` |
+
+## Output - List
+
+```
+🧰 Wogi Flow Skills
+
+Installed:
+  ✓ nestjs - NestJS module builder
+    Commands: /nestjs-scaffold, /nestjs-entity, /nestjs-db
+
+Available:
+  ○ react - React component patterns
+  ○ python - Python/FastAPI patterns
+
+Use: /wogi-skills add [name] to install
+     /wogi-skills info [name] for details
+```
+
+## Output - Info
+
+```
+📦 Skill: nestjs
+
+NestJS module builder with production-ready patterns.
+
+Commands:
+  /nestjs-scaffold [name]  Create complete module
+  /nestjs-entity [name]    Create TypeORM entity
+  /nestjs-dto [name]       Create DTOs with validation
+  /nestjs-migration [name] Generate migration
+  /nestjs-db migrate       Run migrations
+  /nestjs-db seed          Run seed data
+
+Rules included:
+  • conventions.md - Architecture patterns
+  • database.md - TypeORM patterns
+
+Templates included:
+  • entity.template.ts
+  • dto.template.ts
+  • service.template.ts
+  • controller.template.ts
+  • module.template.ts
+```
+
+## Installation
+
+When adding a skill:
+1. Copy skill folder to `.claude/skills/[name]/`
+2. Update `config.json` with skill in `skills.installed`
+3. Skill commands become available immediately
+
+## Creating Custom Skills
+
+See: `.claude/skills/README.md` for skill creation guide
+
+Structure:
+```
+.claude/skills/[name]/
+  skill.md           # Description and usage
+  rules/             # Coding conventions
+  commands/          # Slash commands
+  templates/         # Code templates
+```

package/.claude/commands/wogi-standup.md

@@ -0,0 +1,28 @@
+Generate a daily standup summary.
+
+Gather from:
+1. `.workflow/state/request-log.md` - Recent entries (last 24h or specify days)
+2. `.workflow/state/ready.json` - In progress and ready tasks
+3. `.workflow/state/progress.md` - Any noted blockers
+
+Output format:
+```
+📅 Standup Summary
+
+Yesterday:
+  • Completed TASK-011: Login form validation
+  • Fixed bug BUG-003: Password reset email
+  • Added Button variants to app-map
+
+Today:
+  • Continue TASK-012: Forgot password link
+  • Start TASK-015: User profile page
+
+Blockers:
+  • Waiting on API endpoint for user preferences
+
+Notes:
+  • Decided to use React Query for data fetching (see decisions.md)
+```
+
+Optional: Pass number of days to look back `/wogi-standup 3`

package/.claude/commands/wogi-start.md

@@ -0,0 +1,465 @@
+Start working on a task. Provide the task ID as argument: `/wogi-start wf-XXXXXXXX`
+
+## Structured Execution (v2.1)
+
+This command implements a **structured execution loop**:
+- **Model-invoked skills**: Auto-loads relevant skills based on task context
+- **Specification mode**: Generates spec before coding (for medium/large tasks)
+- **Four-phase loop**: Spec → Test → Implement → Verify
+- **File-based validation**: Every phase produces artifacts
+- **Self-reflection**: Checkpoints to pause and verify approach
+
+### Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  /wogi-start wf-XXXXXXXX                                │
+├─────────────────────────────────────────────────────────┤
+│  0.5 PARALLEL CHECK: Are other tasks parallelizable?    │
+│     → If yes: Show parallel option before proceeding    │
+│  1. Load context + Match skills (auto-invoke)           │
+│  2. Generate specification (if medium/large task)       │
+│  3. SPEC PHASE: Plan implementation steps               │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  🪞 Reflection: Does spec fully address needs?    │  │
+│  └───────────────────────────────────────────────────┘  │
+│  4. TEST PHASE: Write/update tests first                │
+│  5. IMPLEMENT PHASE: Code each acceptance criteria      │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  FOR EACH scenario:                               │  │
+│  │    → Mark in_progress                             │  │
+│  │    → Implement                                    │  │
+│  │    → Verify (run tests, typecheck)                │  │
+│  │    → Save verification artifact                   │  │
+│  │    → If failing: fix and retry                    │  │
+│  │    → Mark completed                               │  │
+│  └───────────────────────────────────────────────────┘  │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  🪞 Reflection: Any bugs or regressions?          │  │
+│  └───────────────────────────────────────────────────┘  │
+│  5.5 CRITERIA CHECK: Re-read spec, verify EACH done     │
+│     → If ANY not done: implement it, loop back          │
+│  6. VERIFY PHASE: Spec verification + quality gates     │
+│     → MANDATORY: Verify all spec deliverables exist     │
+│  7. Save final verification artifact                    │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  🪞 Reflection: Does this match user request?     │  │
+│  └───────────────────────────────────────────────────┘  │
+│  8. Update request-log, app-map, ready.json             │
+│  9. Commit changes                                      │
+│  10. ✓ Task complete                                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Step 0.5: Parallel Execution Check (Automatic)
+
+**Before starting, automatically check if parallel execution is available:**
+
+1. Read `.workflow/state/ready.json`
+2. Check if there are 2+ tasks in the `ready` array
+3. If yes, run parallel detection:
+   ```bash
+   node scripts/flow-parallel.js check
+   ```
+   Or programmatically check `findParallelizable(readyTasks)`
+
+4. **If parallelizable tasks exist**, display:
+   ```
+   ⚡ PARALLEL EXECUTION AVAILABLE
+   Note: X other tasks could run in parallel with this one.
+   Tasks: wf-002, wf-003 (no dependencies with wf-001)
+
+   Options:
+   - Continue with wf-001 (sequential execution)
+   - Run wf-001, wf-002, wf-003 in parallel (faster, isolated worktrees)
+   ```
+
+5. **Decision criteria** (agent should consider):
+   - **Use parallel** when: Tasks are independent, user wants speed, tasks don't share files
+   - **Use sequential** when: Tasks share files, need to review each result, prefer careful approach
+
+6. If parallel is chosen: Use `flow parallel` with worktree isolation
+7. If sequential: Continue with this task normally
+
+**This check happens automatically at the start of every `/wogi-start`**
+
+---
+
+### Step 1: Load Context + Match Skills
+
+1. Read `.workflow/state/ready.json`
+2. Find the task in the ready array
+3. Move it to inProgress array, save ready.json
+4. Load task context:
+   - Find story file in `.workflow/changes/*/wf-XXXXXXXX.md` or tasks.json
+   - Extract user story, acceptance criteria, technical notes
+5. Check `.workflow/state/app-map.md` for components mentioned
+6. Check `.workflow/state/decisions.md` for relevant patterns
+7. **Auto-invoke skills** based on task context:
+   - Run skill matcher against task description
+   - Load matched skills (patterns.md, anti-patterns.md, learnings.md)
+   - Display matched skills with scores
+
+**Skill Matching Output:**
+```
+🔧 Matched Skills:
+   nestjs [●●●●○]
+   keyword: "service", "entity", task type: "feature"
+   react [●●○○○]
+   keyword: "component"
+```
+
+### Step 1.5: Generate Specification (Medium/Large Tasks)
+
+For medium/large tasks (check `config.json → specificationMode`):
+
+1. Generate specification to `.workflow/specs/wf-XXXXXXXX.md`:
+   - Acceptance criteria (structured Given/When/Then)
+   - Implementation steps
+   - Files to change (auto-detected)
+   - Test strategy
+   - Verification commands
+2. Display spec summary
+3. **Reflection checkpoint**: "Does this spec fully address the requirements?"
+4. Wait for implicit approval (continue = approved)
+
+**Spec Output:**
+```
+📋 Generated Specification:
+
+Acceptance Criteria: 4 scenarios
+Implementation Steps: 6 steps
+Files to Change: 3 files (medium confidence)
+Verification Commands: 4 commands
+
+🪞 Reflection: Does this spec fully address the requirements?
+   - Are there any edge cases not covered?
+   - Is the scope clear and achievable?
+```
+
+### Step 2: Decompose into TodoWrite Checklist
+
+Extract each acceptance criteria scenario as a TodoWrite item:
+
+```
+Given [context] When [action] Then [outcome]
+→ Todo: "Implement: [short description of scenario]"
+```
+
+Also add:
+- "Update request-log.md with task entry"
+- "Update app-map.md if new components created"
+- "Run quality gates"
+- "Commit changes"
+
+### Step 3: Execute Each Scenario (Loop)
+
+For each acceptance criteria:
+
+1. **Mark in_progress** in TodoWrite
+2. **Implement** the scenario following matched skill patterns
+3. **Run verification** (saves artifact to `.workflow/verifications/`):
+   - Run lint: `npm run lint`
+   - Run typecheck: `npm run typecheck` or `npx tsc --noEmit`
+   - Run related tests if they exist
+4. **Save verification artifact** (JSON file with exit codes, output)
+5. **If not working**: Debug, fix, retry verification (max 5 attempts)
+6. **Mark completed** only when verification passes
+
+**Verification Artifact:**
+```json
+{
+  "taskId": "wf-abc123",
+  "phase": "implementation",
+  "timestamp": "2026-01-10T...",
+  "results": [
+    {"command": "npm run lint", "exitCode": 0, "passed": true},
+    {"command": "npm run typecheck", "exitCode": 0, "passed": true}
+  ],
+  "allPassed": true
+}
+```
+
+### Step 3.5: Criteria Completion Verification (MANDATORY)
+
+**This is the enforcement loop that ensures everything was actually done.**
+
+After implementing all scenarios, BEFORE running quality gates:
+
+1. **Re-read the original acceptance criteria** from the spec file
+2. **For EACH criterion**, verify it was actually implemented:
+   ```
+   ┌─────────────────────────────────────────────────────────┐
+   │  CRITERIA COMPLETION CHECK                              │
+   ├─────────────────────────────────────────────────────────┤
+   │  Re-reading acceptance criteria from spec...            │
+   │                                                         │
+   │  □ Criterion 1: Given X, When Y, Then Z                │
+   │    → Check: Does the code actually do Z when Y?         │
+   │    → Status: ✓ IMPLEMENTED / ✗ NOT DONE                │
+   │                                                         │
+   │  □ Criterion 2: Given A, When B, Then C                │
+   │    → Check: Does the code actually do C when B?         │
+   │    → Status: ✓ IMPLEMENTED / ✗ NOT DONE                │
+   │                                                         │
+   │  ... for ALL criteria                                   │
+   └─────────────────────────────────────────────────────────┘
+   ```
+
+3. **If ANY criterion is NOT implemented**:
+   - Add it back to TodoWrite as in_progress
+   - Implement it
+   - Verify it works
+   - Return to step 3.5 and re-check ALL criteria again
+
+4. **Only proceed when ALL criteria show ✓ IMPLEMENTED**
+
+**This is NOT optional. This is what prevents "claiming done when not done."**
+
+The key question for each criterion:
+> "If I run the code right now, does it actually do what this criterion describes?"
+
+Not "did I write code for this" but "does the code WORK as specified?"
+
+---
+
+### Step 4: Run Quality Gates + Final Verification
+
+**MANDATORY FIRST CHECK - Spec Verification Gate:**
+
+Before running any other quality gates, verify all deliverables from the spec exist:
+
+```bash
+node scripts/flow-spec-verifier.js verify wf-XXXXXXXX
+```
+
+This checks:
+1. Parse the task's spec file (`.workflow/changes/wf-XXXXXXXX.md`)
+2. Extract all promised files from Technical Notes / Components sections
+3. Verify each file exists
+4. Verify JS/JSON files have valid syntax
+
+**Output:**
+```
+═══════════════════════════════════════════════════
+  Spec Verification
+═══════════════════════════════════════════════════
+Spec: .workflow/changes/wf-abc123.md
+
+✓ Spec verification passed (5/5 deliverables)
+```
+
+**If spec verification fails:**
+```
+✗ Spec verification FAILED (3/5 deliverables)
+
+Missing files:
+  ✗ scripts/flow-missing-feature.js
+    (listed in: Technical Notes → Components)
+```
+→ **STOP. Create the missing files before proceeding.**
+→ Do NOT skip this check. This prevents implementation gaps.
+
+**After spec verification passes**, read `config.json` → `qualityGates` for task type and verify:
+
+- `tests`: Run test command if configured, ensure passing
+- `requestLogEntry`: Verify entry exists in request-log.md
+- `appMapUpdate`: Verify new components are in app-map.md
+- `noNewFeatures`: (for refactors) Verify no new features added
+
+**Save final verification artifact** to `.workflow/verifications/wf-XXXXXXXX-final.json`
+
+**Reflection checkpoint:**
+```
+🪞 Reflection: Have I introduced any bugs or regressions?
+   - Does the code follow project patterns from decisions.md?
+   - Is there any code that could be simplified?
+```
+
+**If any gate fails**: Fix the issue and re-verify. Do not proceed until all required gates pass.
+
+### Step 5: Final Reflection + Finalize
+
+1. **Pre-completion reflection:**
+   ```
+   🪞 Reflection: Does this match what the user asked for?
+      - Have all acceptance criteria been met?
+      - Are there any loose ends to address?
+   ```
+2. Update ready.json: Move task to recentlyCompleted
+3. Git add and commit with message: `feat: Complete wf-XXXXXXXX - [title]`
+4. Show completion summary with verification results
+
+### Output
+
+**Start:**
+```
+✓ Started: wf-XXXXXXXX - [Title]
+
+🔧 Matched Skills:
+   nestjs [●●●●○] - keyword: "service", task type: "feature"
+
+📋 Specification generated: .workflow/specs/wf-XXXXXXXX.md
+   Acceptance Criteria: 4 scenarios
+   Implementation Steps: 6 steps
+   Files to Change: 3 (medium confidence)
+
+User Story:
+As a [user], I want [action], so that [benefit]
+
+Acceptance Criteria (4 scenarios):
+□ 1. Given... When... Then...
+□ 2. Given... When... Then...
+□ 3. Given... When... Then...
+□ 4. Given... When... Then...
+
+🪞 Reflection: Does spec fully address requirements? ✓
+
+Beginning structured execution loop...
+```
+
+**During (for each scenario):**
+```
+[IMPLEMENT] Working on scenario 1/4: [description]
+→ Implementing...
+→ Running verification...
+   ✓ lint passed
+   ✓ typecheck passed
+→ Artifact saved: .workflow/verifications/wf-XXXXXXXX-scenario-1.json
+→ ✓ Scenario complete
+
+[IMPLEMENT] Working on scenario 2/4: [description]
+→ Implementing...
+→ Running verification...
+   ✗ typecheck failed: Property 'x' does not exist
+→ Fixing...
+→ Running verification... ✓
+→ Artifact saved: .workflow/verifications/wf-XXXXXXXX-scenario-2.json
+→ ✓ Scenario complete
+```
+
+**Reflection checkpoint (post-implementation):**
+```
+🪞 Reflection: Have I introduced any bugs or regressions?
+   - Code follows patterns from decisions.md ✓
+   - No unnecessary complexity detected ✓
+```
+
+**End:**
+```
+[CRITERIA CHECK] Re-reading acceptance criteria from spec...
+  ✓ Criterion 1: "Given X, When Y, Then Z" - IMPLEMENTED
+  ✓ Criterion 2: "Given A, When B, Then C" - IMPLEMENTED
+  ✓ Criterion 3: "Error handling for invalid input" - IMPLEMENTED
+  ✓ Criterion 4: "Config option to disable feature" - IMPLEMENTED
+  → All 4/4 criteria verified as implemented
+
+[VERIFY] Running spec verification...
+  ✓ Spec verification passed (5/5 deliverables)
+
+[VERIFY] Running quality gates...
+  ✓ tests passed (12/12)
+  ✓ lint passed
+  ✓ typecheck passed
+  ✓ requestLogEntry found
+  ✓ appMapUpdate verified
+
+Final verification artifact: .workflow/verifications/wf-XXXXXXXX-final.json
+
+🪞 Reflection: Does this match user request? ✓
+
+✓ Completed: wf-XXXXXXXX - [Title]
+  4/4 scenarios implemented
+  Verification artifacts: 5 files
+  Changes committed: "feat: Complete wf-XXXXXXXX - [title]"
+```
+
+## Options
+
+### `--no-loop`
+Disable the self-completing loop. Just load context and stop (old behavior):
+```
+/wogi-start wf-XXXXXXXX --no-loop
+```
+
+### `--no-spec`
+Skip specification generation (for small tasks or quick fixes):
+```
+/wogi-start wf-XXXXXXXX --no-spec
+```
+
+### `--no-skills`
+Skip automatic skill loading:
+```
+/wogi-start wf-XXXXXXXX --no-skills
+```
+
+### `--no-reflection`
+Skip reflection checkpoints (faster but less thorough):
+```
+/wogi-start wf-XXXXXXXX --no-reflection
+```
+
+### `--max-retries N`
+Limit retry attempts per scenario (default: 5):
+```
+/wogi-start wf-XXXXXXXX --max-retries 3
+```
+
+### `--pause-between`
+Ask for confirmation between scenarios:
+```
+/wogi-start wf-XXXXXXXX --pause-between
+```
+
+### `--verify-only`
+Only run verification without implementation (for debugging):
+```
+/wogi-start wf-XXXXXXXX --verify-only
+```
+
+### `--phased`
+Enable phased execution mode (Contract → Skeleton → Core → Edge Cases → Polish):
+```
+/wogi-start wf-XXXXXXXX --phased
+```
+
+This breaks implementation into focused phases with context isolation:
+1. **Contract**: Define interfaces, types, API contracts (NO implementation)
+2. **Skeleton**: Create file structure, stub implementations (NO logic)
+3. **Core Logic**: Implement happy path only (assume valid inputs)
+4. **Edge Cases**: Handle errors and validation (NO core logic changes)
+5. **Polish**: Optimization, cleanup, documentation
+
+Each phase has constraints to prevent scope creep. Use for complex tasks.
+
+Phase commands:
+- `flow phase complete <taskId>` - Complete current phase
+- `flow phase skip <taskId>` - Skip current phase
+- `flow phase status <taskId>` - Show phase status
+
+## When Things Go Wrong
+
+### Scenario keeps failing after max retries
+- Stop and report: "Scenario X failed after N attempts. Issue: [description]"
+- Leave task in inProgress
+- User can investigate and re-run `/wogi-start TASK-XXX` to continue
+
+### Quality gate keeps failing
+- Report which gate is failing and why
+- Attempt to fix automatically
+- If can't fix after 3 attempts, stop and report
+
+### Context getting too large
+- After 3+ scenarios, check context size
+- If getting large, commit current progress and suggest `/wogi-compact`
+- Progress is preserved in files and ready.json
+
+## Important
+
+- **TodoWrite is mandatory**: Use it to track progress through scenarios
+- **Self-verification is mandatory**: Don't mark scenarios done without checking they work
+- **Criteria completion check is mandatory**: After implementing, re-read ALL criteria and verify EACH one actually works. If any is not done, implement it and check again. This is the loop that prevents "claiming done when not done."
+- **Spec verification is mandatory**: All files promised in spec must exist before completion
+- **Quality gates are mandatory**: Task isn't done until gates pass
+- **Commits preserve progress**: Even if you stop mid-task, work is saved

package/.claude/commands/wogi-status.md

@@ -0,0 +1,41 @@
+Show full project overview.
+
+Run `./scripts/flow status` to see the overview.
+
+Options:
+- `--json` - Output JSON for programmatic access
+
+Related: `/wogi-morning` for session-focused briefing with suggested next action.
+
+Gather information from:
+1. `.workflow/state/ready.json` - Task counts by status
+2. `.workflow/changes/` - Active features
+3. `.workflow/bugs/` - Open bugs
+4. `.workflow/state/app-map.md` - Component count
+5. `git status` - Branch and uncommitted changes
+6. `.workflow/state/request-log.md` - Recent activity (last 5 entries)
+
+Output format:
+```
+📊 Project Status
+
+Tasks:
+  Ready: 5 | In Progress: 2 | Blocked: 1 | Completed: 12
+
+Features:
+  • auth (3 tasks remaining)
+  • user-profile (1 task remaining)
+
+Bugs: 2 open
+
+Components: 24 mapped
+
+Git:
+  Branch: feature/auth
+  Uncommitted: 3 files
+
+Recent Activity:
+  • R-045: Added login form validation
+  • R-044: Fixed password reset flow
+  • R-043: Created Button component
+```