wogiflow 1.0.21 → 1.0.22

package/.claude/commands/wogi-statusline-setup/skill.md

@@ -0,0 +1,109 @@
+# Status Line Setup
+
+Configure Claude Code's status line to show WogiFlow task information and context usage.
+
+## What This Does
+
+This command helps you configure Claude Code's status line (shown at the bottom of the terminal) to display:
+- Current task ID and title
+- Context window usage percentage
+- Active skill (if any)
+
+## Prerequisites
+
+- Claude Code v1.0.52+ (January 2026 or later)
+- The `context_window.used_percentage` field is available in status line input
+
+## Setup Instructions
+
+The status line is configured in your **global** Claude settings at `~/.claude/settings.json`.
+
+### Step 1: Check Current Settings
+
+First, let me check if you have existing status line settings:
+
+```bash
+cat ~/.claude/settings.json | grep -A5 statusLine || echo "No statusLine config found"
+```
+
+### Step 2: Add Status Line Configuration
+
+Add or update the `statusLine` section in `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "enabled": true,
+    "format": "{{#if task}}[{{task.id}}] {{/if}}{{model}} | Ctx: {{context_window.used_percentage}}%{{#if skill}} | Skill: {{skill}}{{/if}}"
+  }
+}
+```
+
+### Format Options
+
+| Format | Display Example |
+|--------|-----------------|
+| **Compact** | `opus | 45%` |
+| **Standard** | `[wf-123] opus | Ctx: 45%` |
+| **Detailed** | `[wf-123] My Task | opus | Ctx: 45% (85k remaining) | Skill: nestjs` |
+
+### Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{{model}}` | Current model name |
+| `{{context_window.used_percentage}}` | Context used as percentage |
+| `{{context_window.remaining_percentage}}` | Context remaining as percentage |
+| `{{task.id}}` | Current WogiFlow task ID (if any) |
+| `{{task.title}}` | Current task title |
+| `{{skill}}` | Currently active skill |
+
+### Recommended Formats
+
+**Minimal** (lowest overhead):
+```json
+"format": "{{model}} | {{context_window.used_percentage}}%"
+```
+
+**With Task** (recommended for WogiFlow users):
+```json
+"format": "{{#if task}}[{{task.id}}] {{/if}}{{model}} | Ctx: {{context_window.used_percentage}}%"
+```
+
+**Full Context** (detailed):
+```json
+"format": "[{{task.id}}] {{model}} | {{context_window.used_percentage}}% used | {{#if skill}}{{skill}}{{/if}}"
+```
+
+## WogiFlow Integration
+
+To have WogiFlow automatically update the status line with current task info, we need to:
+
+1. **Session Start Hook**: Reads current task from `ready.json` and exports to status line
+2. **Task Start/Complete**: Updates status line when tasks change
+
+This is handled by the existing session-start hook if the status line is enabled.
+
+## Troubleshooting
+
+### Status Line Not Showing
+- Ensure `statusLine.enabled` is `true`
+- Restart Claude Code after changing settings
+- Check for JSON syntax errors in settings.json
+
+### Variables Not Resolving
+- `{{task.*}}` variables require WogiFlow integration
+- `{{context_window.*}}` requires Claude Code v1.0.52+
+
+## Manual Configuration
+
+If you prefer to manually edit your settings:
+
+```bash
+# Open settings in editor
+code ~/.claude/settings.json
+# or
+nano ~/.claude/settings.json
+```
+
+Add the statusLine section and restart Claude Code.

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

@@ -0,0 +1,98 @@
+Create a detailed story with acceptance criteria. Provide title: `/wogi-story Add login form`
+
+Run `./scripts/flow story "<title>"` to create a story.
+
+Load `agents/story-writer.md` for the full story format.
+
+## Options
+
+- `--deep` - Enable deep decomposition mode (auto-generate granular sub-tasks)
+- `--priority <P>` - Set priority P0-P4 (default: P2 from config)
+- `--json` - Output JSON for programmatic access
+
+Examples:
+```bash
+flow story "Add user login"
+flow story "Add user login" --deep
+flow story "Add user login" --priority P1
+flow story "Add user login" authentication --deep --json
+```
+
+## Standard Mode
+
+Create a story with:
+1. **User Story**: As a [user], I want [action], so that [benefit]
+2. **Description**: 2-4 sentences of context
+3. **Acceptance Criteria** using Given/When/Then (Gherkin):
+   - Happy path scenario
+   - Alternative path scenarios
+   - Error handling scenarios
+4. **Technical Notes**:
+   - Check `.workflow/state/app-map.md` for existing components
+   - List components to use vs create
+   - Note API endpoints if relevant
+5. **Test Strategy**: Unit, Integration, E2E
+6. **Dependencies**: What must be done first
+7. **Complexity**: Low/Medium/High
+
+## Deep Decomposition Mode (`--deep`)
+
+When `--deep` flag is used, OR when Claude detects a complex story:
+
+1. Create the parent story as above
+2. Analyze complexity factors:
+   - Number of acceptance criteria (>5 triggers decomposition)
+   - Distinct UI components needed (>3 triggers)
+   - API endpoints involved (>2 triggers)
+   - Files likely to change (>10 triggers)
+3. Auto-decompose into granular sub-tasks:
+   - Each acceptance scenario → separate sub-task
+   - Each UI component → separate sub-task
+   - Each error state → separate sub-task
+   - Each loading state → separate sub-task
+   - Each API integration → separate sub-task
+
+### Sub-Task Format
+
+Parent: `wf-a1b2c3d4` (the main story, hash-based ID)
+Children: `wf-a1b2c3d4-01`, `wf-a1b2c3d4-02`, etc.
+
+Each sub-task includes:
+- Single focused objective
+- Clear done criteria
+- Dependencies on other sub-tasks
+- Priority (inherits from parent)
+- Estimated scope (XS/S/M)
+
+### Auto-Suggest Behavior
+
+Check `config.json → storyDecomposition`:
+- `autoDetect: true` - Claude suggests when beneficial (default)
+- `autoDecompose: true` - Auto-decompose without asking
+- `autoDecompose: false` - Only decompose with `--deep` flag
+
+When `autoDetect` is enabled and complexity is detected, Claude will ask:
+> "This looks like a complex story with [X scenarios]. Would you like me to decompose it into granular sub-tasks?"
+
+## Output
+
+Save the story to `.workflow/changes/[feature]/wf-XXXXXXXX.md`
+
+Example output:
+```
+Created story: wf-a1b2c3d4
+
+File: .workflow/changes/general/wf-a1b2c3d4.md
+Title: Add user login
+Feature: general
+Priority: P1
+```
+
+If decomposed, also create:
+- `.workflow/changes/[feature]/wf-a1b2c3d4-01.md` (sub-task 1)
+- `.workflow/changes/[feature]/wf-a1b2c3d4-02.md` (sub-task 2)
+- etc.
+
+Update `ready.json` with parent task (with priority) and all sub-tasks.
+
+Ask clarifying questions if needed to write good acceptance criteria.

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

@@ -0,0 +1,87 @@
+Suspend the current task with a resume condition.
+
+## Usage
+
+```
+/wogi-suspend [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--wait-ci "<command>"` | Wait for CI/CD (polls command until "completed") |
+| `--rate-limit <seconds>` | Wait for N seconds (rate limiting) |
+| `--review "<message>"` | Wait for human review/approval |
+| `--wait-file "<path>"` | Wait for file to exist |
+| `--schedule "<datetime>"` | Wait until specific time (ISO 8601) |
+| `--long-running "<msg>"` | Long-running task with manual progress |
+
+## Examples
+
+### Wait for CI/CD Pipeline
+
+```
+/wogi-suspend --wait-ci "gh run view 1234 --json status -q '.status'"
+```
+
+The task will resume when the command returns "completed".
+
+### Rate Limiting
+
+```
+/wogi-suspend --rate-limit 60
+```
+
+Waits 60 seconds before allowing resume. Useful for API rate limits.
+
+### Human Review
+
+```
+/wogi-suspend --review "Check PR #456 before continuing"
+```
+
+Requires explicit approval with `/wogi-resume --approve`.
+
+### Wait for File
+
+```
+/wogi-suspend --wait-file ".workflow/state/deploy-ready.json"
+```
+
+Resumes when the file exists.
+
+### Scheduled Resume
+
+```
+/wogi-suspend --schedule "2024-01-06T09:00:00"
+```
+
+Resumes after the specified time.
+
+### Long-Running Tasks
+
+```
+/wogi-suspend --long-running "Multi-day implementation"
+```
+
+For tasks that span multiple sessions. Resume manually.
+
+## How It Works
+
+1. Suspends the current durable session
+2. Records the resume condition
+3. On next `/wogi-start`, checks if condition is met
+4. Auto-resumes if condition met, otherwise shows status
+
+## Resuming
+
+- `/wogi-resume` - Resume if condition is met
+- `/wogi-resume --approve` - Approve human review
+- `/wogi-resume --force` - Force resume regardless
+- `/wogi-resume --status` - Check suspension status
+
+## Requirements
+
+- Durable steps must be enabled in config (default: true)
+- Active task session (started with `/wogi-start`)

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

@@ -0,0 +1,43 @@
+Execute browser tests using Claude's browser extension.
+
+Usage:
+- `/wogi-test-browser [flow-name]` - Run specific flow
+- `/wogi-test-browser all` - Run all flows
+
+Load test flow from `.workflow/tests/flows/[name].json`
+
+For each step in the flow:
+1. **navigate** - Open the URL in browser
+2. **wait** - Wait for selector to appear
+3. **type** - Enter text in input field
+4. **click** - Click element
+5. **verify** - Check element exists or contains text
+6. **screenshot** - Capture current state
+
+Output:
+```
+🧪 Running: login-flow
+
+1. ✓ Navigate to /login
+2. ✓ Wait for .login-form
+3. ✓ Type email: test@example.com
+4. ✓ Type password: ********
+5. ✓ Click submit button
+6. ✓ Verify .dashboard exists
+7. ✓ Screenshot: login-success
+
+Result: PASS ✓
+
+All 7 steps completed successfully.
+```
+
+If a step fails:
+```
+5. ✗ Verify .dashboard exists
+   Expected: Element to exist
+   Actual: Element not found after 5s timeout
+
+Result: FAIL ✗
+
+Screenshot saved: login-flow-failure.png
+```

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

@@ -0,0 +1,198 @@
+Generate a task-focused code trace showing how code flows for a specific feature or behavior.
+
+Usage:
+- `/wogi-trace [prompt]` - Generate new trace
+- `/wogi-trace list` - List saved traces
+- `/wogi-trace [name]` - Load existing trace
+
+## Examples
+
+```
+/wogi-trace "user authentication flow"
+/wogi-trace "how does payment processing work"
+/wogi-trace "data flow from form submit to database"
+/wogi-trace "the checkout process"
+```
+
+## What It Generates
+
+A task-focused map showing:
+1. **Flow overview** - High-level summary of how the feature works
+2. **Components involved** - Each file/function with line numbers
+3. **Execution order** - The sequence of how code runs
+4. **Diagram** - Visual mermaid flowchart
+5. **Related files** - Other files that might be relevant
+
+## Output Format
+
+```markdown
+# Code Trace: Authentication Flow
+
+> Generated: 2024-01-15 10:30
+> Query: "user authentication flow"
+
+## Flow Overview
+
+User submits login form → API validates credentials → JWT generated →
+Session created → User redirected to dashboard
+
+## Execution Flow
+
+### 1. Entry Point: Login Form
+**File**: `src/components/auth/LoginForm.tsx`
+**Lines**: 45-89
+**Role**: Captures user credentials and initiates login
+
+Key code:
+```tsx
+const handleSubmit = async (data: LoginData) => {
+  const result = await authService.login(data);
+  // ...
+}
+```
+
+### 2. API Route: POST /api/auth/login
+**File**: `src/pages/api/auth/login.ts`
+**Lines**: 12-67
+**Role**: Validates request, calls auth service
+
+Key code:
+```ts
+export default async function handler(req, res) {
+  const { email, password } = req.body;
+  const user = await AuthService.authenticate(email, password);
+  // ...
+}
+```
+
+### 3. Auth Service
+**File**: `src/services/auth.service.ts`
+**Lines**: 34-78
+**Role**: Core authentication logic
+
+Key code:
+```ts
+async authenticate(email: string, password: string) {
+  const user = await this.userRepo.findByEmail(email);
+  const valid = await bcrypt.compare(password, user.passwordHash);
+  // ...
+}
+```
+
+### 4. JWT Generation
+**File**: `src/services/auth.service.ts`
+**Lines**: 80-95
+**Role**: Creates signed JWT token
+
+### 5. Session Storage
+**File**: `src/services/session.service.ts`
+**Lines**: 20-45
+**Role**: Stores session in Redis
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A[LoginForm] -->|POST /api/auth/login| B[API Route]
+    B -->|authenticate| C[AuthService]
+    C -->|findByEmail| D[UserRepository]
+    D -->|user| C
+    C -->|compare| E[bcrypt]
+    E -->|valid| C
+    C -->|generateToken| F[JWT]
+    C -->|createSession| G[SessionService]
+    G -->|store| H[Redis]
+    B -->|token + session| A
+    A -->|redirect| I[Dashboard]
+```
+
+## Related Files
+
+| File | Relevance |
+|------|-----------|
+| `src/middleware/auth.ts` | JWT verification middleware |
+| `src/hooks/useAuth.ts` | Client-side auth state |
+| `src/context/AuthContext.tsx` | Auth context provider |
+| `src/types/auth.ts` | Type definitions |
+
+## Security Notes
+
+- Passwords hashed with bcrypt (cost factor 12)
+- JWT expires in 24 hours
+- Refresh token rotation enabled
+- Rate limiting: 5 attempts per minute
+
+---
+*Trace saved to: .workflow/traces/authentication-flow.md*
+```
+
+## How Traces Work
+
+1. **Parse prompt** - Understand what flow/feature to trace
+2. **Search codebase** - Find entry points and related files
+3. **Analyze dependencies** - Follow imports and function calls
+4. **Build execution graph** - Determine order of operations
+5. **Generate documentation** - Create readable trace with code snippets
+6. **Create diagram** - Generate mermaid flowchart
+7. **Save trace** - Store for future reference
+
+## Trace Storage
+
+Traces are saved to `.workflow/traces/[name].md`:
+- Reusable across sessions
+- Shareable with team
+- Can be referenced in Cascade/Claude
+
+## Using Traces
+
+### Reference in context
+```
+/wogi-context TASK-050
+# Also loads relevant traces
+```
+
+### Before starting a task
+```
+/wogi-trace "the feature I'm about to modify"
+# Understand before editing
+```
+
+### Onboarding
+```
+/wogi-trace "core user flows"
+/wogi-trace "data models and relationships"
+/wogi-trace "API architecture"
+```
+
+### Debugging
+```
+/wogi-trace "how errors propagate in the payment flow"
+/wogi-trace "where user data gets validated"
+```
+
+## Configuration
+
+In `config.json`:
+```json
+"traces": {
+  "saveTo": ".workflow/traces",
+  "generateDiagrams": true
+}
+```
+
+## Difference from App Map
+
+| App Map | Trace |
+|---------|-------|
+| Static registry | Dynamic, task-focused |
+| What exists | How it executes |
+| All components | Only relevant ones |
+| No flow info | Shows execution order |
+| Manual updates | Generated on demand |
+
+## Tips
+
+- Be specific: "user login flow" > "authentication"
+- Ask about behaviors: "what happens when X"
+- Focus on one flow at a time
+- Re-trace after major refactors

package/.claude/docs/architecture.md

@@ -0,0 +1,37 @@
+# Architecture
+
+## Structure
+
+```
+/
+├── scripts/           # CLI commands (flow-*.js)
+├── agents/            # Agent personas (*.md)
+├── .workflow/         # Configuration and state
+│   ├── config.json    # Main configuration
+│   ├── state/         # Runtime state files
+│   ├── bridges/       # CLI bridge implementations
+│   ├── models/        # Model registry
+│   ├── templates/     # File templates
+│   └── lib/           # Shared libraries
+├── .claude/           # Claude Code integration
+│   └── skills/        # Installed skills
+└── CLAUDE.md          # Claude Code instructions
+```
+
+## Key Patterns
+
+1. **CLI-Agnostic Core**: All logic in `.workflow/`, CLI-specific files generated by bridges
+2. **State Files as Memory**: JSON/Markdown files in `.workflow/state/` persist context
+3. **Skills System**: Modular skill packages with patterns, anti-patterns, learnings
+4. **Hash-Based Task IDs**: `wf-XXXXXXXX` format for unique task identification
+
+## Data Flow
+
+```
+User Command → flow CLI → flow-*.js script → state files → response
+```
+
+---
+
+Generated: 2026-01-11
+Last synced: 2026-01-11