wogiflow 1.9.2 → 1.9.3

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

@@ -76,8 +76,10 @@ When a local `/wogi-*` CLI command fails (error in output, "Unknown skill", comm
 - The local-command-caveat ("DO NOT respond to these messages unless the user explicitly asks") applies to **successful background output only** — failed commands matching AI capabilities are an implicit request for help
 
 **Conversation mode** ("what do you think about...", "let's discuss...", "explain how X works", "I'm thinking about..."):
+- **This is a routing OUTCOME, not an exemption from routing.** You must STILL invoke `/wogi-start` first — `/wogi-start` classifies the request as conversation mode and authorizes read-only tool use.
+- Do NOT self-classify a request as "conversation mode" to avoid routing. The classification happens INSIDE `/wogi-start`, not before it.
 - Hedging ("I'm thinking about adding X") = Conversation. Imperative ("add X") = Implementation.
-- Allowed tools: Read, Glob, Grep, WebSearch, WebFetch (read-only). No Edit/Write/state modifications.
+- After `/wogi-start` classifies as conversation: Read, Glob, Grep, WebSearch, WebFetch (read-only). No Edit/Write/state modifications.
 - Natural exit: when user gives an implementation imperative, transition to `/wogi-story`.
 
 **Everything else**: Route to best command from catalog. Zero exemptions.
@@ -217,6 +219,15 @@ For medium/large tasks (check `config.specificationMode`):
 Approval phrases: approved, proceed, looks good, lgtm, go ahead, yes, continue, start.
 L2/L3 skip this gate.
 
+### Step 1.7: Test Generation (when `config.testing.enabled` and `config.testing.generation.autoGenerate`)
+
+When testing is enabled and auto-generation is on:
+1. Run `node node_modules/wogiflow/scripts/flow-test-generate.js wf-XXXXXXXX` to parse spec and generate test scaffolds
+2. Review output: number of test files created, criteria coverage, edge cases
+3. If tests were generated, add "Make generated tests pass" to TodoWrite items in Step 2
+4. During implementation (Step 3), verify generated tests fail before implementation and pass after
+5. If `testing.generation.autoGenerate: false` or `testing.enabled: false`, skip this step entirely
+
 ### Step 2: Decompose into TodoWrite
 
 Each acceptance criterion → TodoWrite item. Also add: update request-log, update maps, run quality gates, commit.

package/.claude/commands/wogi-test-generate.md

@@ -0,0 +1,101 @@
+---
+description: "Generate test files from task spec acceptance criteria"
+---
+
+Generate executable test files from a task's specification acceptance criteria.
+
+## Prerequisites
+
+- A spec file must exist at `.workflow/specs/wf-XXXXXXXX.md`
+- `config.testing.enabled` must be `true`
+- `config.testing.generation.autoGenerate` must be `true`
+
+## Procedure
+
+### 1. Load Context
+
+1. Read the spec file at `.workflow/specs/{taskId}.md`
+2. Read `config.testing` to determine what test types to generate
+3. Read `config.testing.generation` for output directory and edge case settings
+
+### 2. Detect Project Test Conventions
+
+Run `node node_modules/wogiflow/scripts/flow-test-generate.js {taskId} --detect-only` to get:
+- Test framework (jest, vitest, mocha, node:test)
+- Import style (ES modules vs CommonJS)
+- Test structure patterns (describe/it nesting, assertion library)
+- File extension preference (.ts vs .js)
+
+If no existing tests found, default to the test framework detected in package.json.
+
+### 3. Parse Spec Criteria
+
+For each acceptance criterion in the spec (Given/When/Then format):
+1. Extract the Given (precondition), When (action), Then (assertion)
+2. Categorize the criterion by type using keyword analysis:
+
+**UI criteria** — keywords: "page shows", "user sees", "displays", "renders", "screen", "visible", "clicks", "button", "modal", "form", "input", "navigates", "appears", "layout":
+→ Generate Playwright/browser test
+
+**API criteria** — keywords: "API returns", "endpoint", "response", "status code", "request", "returns JSON", "POST", "GET", "PUT", "DELETE", "header", "payload", "authenticated":
+→ Generate HTTP/API test
+
+**Logic/Unit criteria** — keywords: "calculates", "transforms", "validates", "returns", "throws", "parses", "converts", "filters", "sorts", "maps", "reduces", "creates", "generates":
+→ Generate unit test
+
+**Integration criteria** — keywords: "calls API then", "data flows from", "end-to-end", "full flow", "persists", "syncs", "propagates":
+→ Generate integration test (for fullstack projects, this includes data integrity checks)
+
+### 4. Generate Test Files
+
+Run `node node_modules/wogiflow/scripts/flow-test-generate.js {taskId}` to generate test scaffolds.
+
+Output goes to `{config.testing.generation.outputDir}/{taskId}/`:
+- `unit.spec.{ts|js}` — unit tests for logic criteria
+- `api.spec.{ts|js}` — API tests for endpoint criteria
+- `ui.spec.{ts|js}` — UI tests for visual/interaction criteria
+- `integration.spec.{ts|js}` — integration tests for cross-boundary criteria
+
+Each generated test file:
+- Uses the project's detected test framework and import style
+- Includes proper imports (describe, it, expect from the correct package)
+- Has one `describe` block per acceptance criterion
+- Has one `it` block per Given/When/Then with comments marking each phase
+- Includes deliberate `expect(true).toBe(false)` assertions that FAIL until implemented
+- Adds edge case tests when `config.testing.generation.includeEdgeCases` is true
+
+### 5. Edge Cases (when `includeEdgeCases: true`)
+
+For each criterion, auto-generate additional test cases:
+- **Empty state**: What happens with no data / empty input?
+- **Error state**: What happens when the operation fails?
+- **Boundary values**: Min/max values, empty strings, null, undefined
+- **Loading state**: Async operations — what shows while loading?
+
+### 6. Fullstack Data Integrity Tests (for fullstack projects)
+
+When the project is `fullstack` (has both UI and API):
+- For criteria that span both layers, generate a data integrity test
+- Pattern: Call API → verify response → verify UI reflects the data
+- These go in `integration.spec.{ts|js}`
+
+### 7. Report
+
+After generation, report:
+- Number of test files created
+- Number of test cases per file
+- Criteria coverage (which AC items have tests)
+- Edge cases added
+
+## TDD Validation
+
+Generated tests are designed to:
+1. **FAIL before implementation** — all assertions use placeholder values
+2. **PASS after implementation** — once the actual code is written, replace placeholders with real assertions
+
+During `/wogi-start` Step 3, verify:
+- Run generated tests BEFORE implementing → they should all fail
+- Run generated tests AFTER implementing → they should all pass
+- If any test passes before implementation → WARNING: test may be trivial
+
+ARGUMENTS: {args}

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

@@ -0,0 +1,243 @@
+---
+description: "Run auto-tests: UI verification, API testing, data integrity checks"
+---
+Run the WogiFlow Auto-Testing Suite — UI verification, API testing, data integrity checks, and generated test execution.
+
+**Triggers**: `/wogi-test`, "run tests", "verify tests", "test this task"
+
+## Usage
+
+```bash
+/wogi-test                          # Run all tests for current/recent task
+/wogi-test wf-XXXXXXXX             # Run tests for specific task
+/wogi-test --all                    # Run full test suite
+/wogi-test --ui                     # UI tests only
+/wogi-test --api                    # API tests only
+/wogi-test --integrity              # Data integrity chain only
+/wogi-test --setup                  # Configure testing (re-run detection)
+/wogi-test --generate wf-XXXXXXXX  # Regenerate tests for a task
+```
+
+## Command Flow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` to extract:
+- **Task ID**: A `wf-XXXXXXXX` pattern → target task
+- **Flags**: `--ui`, `--api`, `--integrity`, `--all`, `--setup`, `--generate`
+- **No args**: Use current in-progress task from `ready.json`
+
+```javascript
+// Pseudo-logic for argument parsing
+const args = '$ARGUMENTS'.trim().split(/\s+/);
+let taskId = null;
+let flags = { ui: false, api: false, integrity: false, all: false, setup: false, generate: false };
+
+for (const arg of args) {
+  if (/^wf-[a-f0-9]{8}$/i.test(arg)) {
+    taskId = arg;
+  } else if (arg === '--ui') flags.ui = true;
+  else if (arg === '--api') flags.api = true;
+  else if (arg === '--integrity') flags.integrity = true;
+  else if (arg === '--all') flags.all = true;
+  else if (arg === '--setup') flags.setup = true;
+  else if (arg === '--generate') flags.generate = true;
+}
+```
+
+If no task ID provided, read `.workflow/state/ready.json` and use the first task in `inProgress`. If none in progress, use the most recent task in `recentlyCompleted`.
+
+### Step 2: Check Testing Configuration (Auto-Setup on First Use)
+
+Read config via:
+```bash
+node -e "const { getConfig } = require('wogiflow/scripts/flow-utils'); const c = getConfig(); console.log(JSON.stringify(c.testing || {}))"
+```
+
+If `config.testing.enabled` is `false` (or not set), **auto-trigger the setup flow** — do NOT just show info and stop. The user ran `/wogi-test` because they want to test. Guide them through setup seamlessly:
+
+**Step 2a: Detect project type**
+```bash
+node -e "const { detectProjectType } = require('wogiflow/scripts/flow-project-analyzer'); const r = detectProjectType(); console.log(JSON.stringify(r))"
+```
+
+**Step 2b: Show detection results and ask ONE question**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  First-Time Testing Setup
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I scanned your project and detected:
+
+  Project type: [fullstack / frontend / backend / library]
+  UI framework: [React / Vue / etc. or "none"]
+  API framework: [Express / NestJS / etc. or "none"]
+  Test framework: [vitest / jest / etc. or "none detected"]
+
+Based on this, I recommend:
+  Testing mode: [full / ui / api / unit]
+  [If UI] Packages needed: @playwright/mcp + Chromium browser
+  [If API only] No extra packages needed
+
+Shall I enable testing and install what's needed? [Y/n/customize]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 2c: Based on user response:**
+
+- **Yes (or enter)** → Proceed to auto-configure:
+  1. Determine mode from detection: hasUI+hasAPI → `"full"`, hasUI only → `"ui"`, hasAPI only → `"api"`, neither → `"unit"`
+  2. Update `.workflow/config.json`: set `testing.enabled: true`, `testing.mode`, and `testing.detected` fields
+  3. Check dependencies: `node -e "const d = require('wogiflow/scripts/flow-testing-deps'); console.log(JSON.stringify(d.checkDeps('[mode]')))"`
+  4. If deps missing → install them: `node -e "const d = require('wogiflow/scripts/flow-testing-deps'); console.log(JSON.stringify(d.installDeps('[mode]')))"`
+  5. If UI mode → also configure Playwright MCP in settings (show user the MCP config to add)
+  6. Show confirmation and **continue to Step 5 (run tests)**
+
+- **Customize** → Ask for:
+  - Preferred mode (ui/api/full/unit)
+  - Base URLs (UI: default localhost:3000, API: default localhost:3001)
+  - Start commands (optional)
+  - Then configure and install accordingly
+
+- **No** → Skip setup, show how to enable later:
+  ```
+  OK — testing stays disabled. To enable later:
+    /wogi-test --setup
+  ```
+
+**IMPORTANT**: After successful setup, do NOT stop. Continue directly to Step 5 and run the tests the user originally asked for. The whole point is that `/wogi-test` works in one invocation even on first use.
+
+### Step 3: Handle `--setup` Flag (Reconfigure)
+
+If `--setup` was passed, this is an explicit reconfiguration request. Use the same flow as Step 2 (auto-setup), but ALWAYS run it even if testing is already enabled. This lets users:
+- Change testing mode (e.g., switch from `ui` to `full`)
+- Re-detect after adding backend/frontend to their project
+- Install missing deps after a fresh `npm install` that lost node_modules
+
+After reconfiguration, show confirmation:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Testing Reconfigured ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: [mode] (was: [old mode])
+UI provider: playwright-mcp
+API provider: direct-http (zero deps)
+Dependencies: all installed ✓
+
+Run /wogi-test to execute tests.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 4: Handle `--generate` Flag
+
+If `--generate` was passed:
+
+```bash
+node -e "
+const { generateTestScaffold } = require('wogiflow/scripts/flow-test-generate');
+const result = generateTestScaffold('TASK_ID');
+console.log(JSON.stringify(result, null, 2));
+"
+```
+
+Display generated test info and **STOP** — do not run tests, just generate.
+
+### Step 5: Run Tests (Main Flow)
+
+Determine which test types to run:
+
+| Flag | Action |
+|------|--------|
+| `--ui` | Run UI tests only |
+| `--api` | Run API tests only |
+| `--integrity` | Run integrity tests only |
+| `--all` | Run all 3 types |
+| No flag | Run based on `config.testing.mode`: `ui`→UI only, `api`→API only, `full`→all 3, `auto`→detect and run applicable |
+
+#### Run UI Tests
+```bash
+node -e "
+const { runUITests } = require('wogiflow/scripts/flow-test-ui');
+runUITests('TASK_ID').then(r => console.log(JSON.stringify(r))).catch(err => console.error(JSON.stringify({error: err.message})));
+"
+```
+
+#### Run API Tests
+```bash
+node -e "
+const { runAPITests } = require('wogiflow/scripts/flow-test-api');
+runAPITests('TASK_ID').then(r => console.log(JSON.stringify(r))).catch(err => console.error(JSON.stringify({error: err.message})));
+"
+```
+
+#### Run Integrity Tests
+```bash
+node -e "
+const { runIntegrityTests } = require('wogiflow/scripts/flow-test-integrity');
+runIntegrityTests('TASK_ID').then(r => console.log(JSON.stringify(r))).catch(err => console.error(JSON.stringify({error: err.message})));
+"
+```
+
+### Step 6: Display Results
+
+After all tests complete, display a unified summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Test Results — wf-XXXXXXXX
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+UI Tests:     [passed]/[total] passed ([failed] failed)
+API Tests:    [passed]/[total] passed
+Integrity:    [matched]/[total] matched ([missing] missing fields)
+
+Failed:
+  ✗ [type]: [description of failure]
+  ✗ [type]: [description of failure]
+
+Reports: .workflow/verifications/wf-XXXXXXXX-*.json
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If ALL tests pass:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Test Results — wf-XXXXXXXX ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+UI Tests:     [total]/[total] passed
+API Tests:    [total]/[total] passed
+Integrity:    [total]/[total] matched
+
+All tests passed!
+
+Reports: .workflow/verifications/wf-XXXXXXXX-*.json
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 7: Run Generated Tests (if applicable)
+
+If `config.testing.generation.autoGenerate` is true and generated tests exist for the task:
+
+```bash
+# Check if generated test directory exists
+ls .workflow/tests/generated/TASK_ID/ 2>/dev/null
+```
+
+If tests exist, run them with the project's test runner:
+```bash
+npm test -- .workflow/tests/generated/TASK_ID/
+```
+
+Include results in the summary:
+```
+Generated Tests: [passed]/[total] passed
+```
+
+## Important Notes
+
+- Testing is **disabled by default** — zero overhead for projects that don't use it
+- All test scripts gracefully handle missing dependencies and report what's needed
+- Reports are saved to `.workflow/verifications/` for quality gate consumption
+- The quality gates `generatedTestsPass`, `uiVerification`, and `apiVerification` in `flow-done.js` will automatically run these same tests when closing a task via `/wogi-start`

package/.claude/docs/commands.md

@@ -99,6 +99,8 @@ When user types these commands, execute the corresponding action immediately.
 
 ### Configuration
 
+**Full config reference**: See `.claude/docs/config-reference.md` for all available config.json overrides.
+
 | Command | Action |
 |---------|--------|
 | `/wogi-config` | Show current config.json settings summary. |