WogiFlow

A self-improving AI development workflow that learns from your feedback and works across multiple AI coding CLIs.

Quick Start

``bash


Install

npm install wogiflow

Analyze your project

npx flow onboard

Sync to your CLI

npx flow bridge sync
`

Supported CLIs

WogiFlow works with 6 AI coding CLIs. Use whichever you prefer - the workflow state is shared.

| CLI | Enforcement | Rules File | Min Version | Guide |
|-----|-------------|------------|-------------|-------|
| Claude Code | Hard (hooks) | CLAUDE.md | 2.1.23+ | Guide |
| Gemini CLI | Hard (hooks) | GEMINI.md | - | Guide |
| Cursor | Mixed | .cursor/rules/wogiflow.mdc | - | Guide |
| OpenCode | Hard (plugins) | AGENTS.md | - | Guide |
| Codex | Soft (rules) | AGENTS.md | - | Guide |
| Kimi | Soft (rules) | AGENTS.md | - | Guide |

> Claude Code 2.1.23+ Recommended: Includes critical fixes for per-user temp directory isolation (shared systems), async hook cancellation, and ripgrep timeout reporting. Earlier versions may experience silent search failures.

Enforcement levels:
- Hard: Blocks operations before execution (best protection)
- Mixed: Hard at prompt level, soft after
- Soft: Advisory only (rules in context, no blocking)

$3

Workflow state is stored in .workflow/state/ - CLI-agnostic. You can:
1. Start a task in Claude Code
2. Continue it in Cursor
3. Finish it in Gemini CLI

Run npx flow bridge sync after switching to regenerate CLI-specific files.

---

Core Features

| Feature | Description |
|---------|-------------|
| Task Gating | Blocks implementation without an active task |
| Self-Completing Tasks | /wogi-start runs until all criteria pass |
| Component Registry | Prevents duplicate components via app-map |
| Post-Edit Validation | Auto-runs lint/typecheck after every edit |
| Request Logging | All changes logged with tags for searchability |
| Hybrid Mode | Claude plans, local LLM executes (20-60% token savings) |
| Peer Review | Multi-model code review for diverse perspectives |
| Skills System | Modular add-ons that learn from your sessions |
| Research Protocol | Enforces verification before capability claims |

---

Developer Workflow

$3

`bash


Session start

/wogi-morning # Morning briefing with task recommendations
/wogi-ready # Show available tasks
/wogi-status # Project overview

Task execution

/wogi-start TASK-012 # Start task (self-completing loop)
/wogi-start "add feature" # Or describe what you want

Creation

/wogi-story "Add login" # Create story with acceptance criteria
/wogi-bug "Login fails" # Report a bug

Session end

/wogi-review # Code review with 3 parallel agents
/wogi-session-end # Save progress, commit, push
`

$3

`
/wogi-start "add logout button"
│
├── [AUTO] Classify request → Implementation
├── [AUTO] Check app-map for existing components
├── [AUTO] Generate acceptance criteria
│
│ FOR EACH edit:
│ ├── [AUTO] Validate file is in scope
│ ├── [AUTO] Run lint/typecheck
│
├── [AUTO] Verify ALL criteria met
├── [AUTO] Update app-map, request-log
└── [AUTO] Commit changes
`

$3

| Category | Commands |
|----------|----------|
| Tasks | /wogi-ready, /wogi-start, /wogi-status, /wogi-deps |
| Create | /wogi-story, /wogi-bug, /wogi-feature |
| Review | /wogi-review, /wogi-peer-review |
| Components | /wogi-map, /wogi-map-add, /wogi-map-scan |
| Session | /wogi-morning, /wogi-session-end, /wogi-health |
| Hybrid | /wogi-hybrid, /wogi-hybrid-setup, /wogi-hybrid-off |
| Utilities | /wogi-search, /wogi-trace, /wogi-config |

---

CLI Commands

`bash


Setup

flow onboard # Analyze project, populate state files
flow bridge sync # Sync to current CLI

Tasks

flow ready # Show task queue
flow start # Start task
flow status # Project overview

Components

flow map-index scan # Rescan codebase
flow map-sync # Compare index with app-map

Hybrid Mode

flow hybrid enable # Enable with setup wizard
flow hybrid status # Show configuration

Skills

flow skill-learn # Extract learnings from session
flow skill detect # Detect frameworks

Health

flow health # Check workflow integrity
flow verify all # Run all quality gates
`

---

File Structure

`
.workflow/
├── config.json # Workflow configuration
├── bridges/ # CLI bridge implementations
├── templates/ # Templates for CLI files
├── docs/cli-guides/ # Per-CLI documentation
└── state/
├── ready.json # Task queue
├── request-log.md # Change history
├── app-map.md # Component registry
├── decisions.md # Project rules
└── progress.md # Session handoff notes

.claude/ # Claude Code specific
├── skills/ # Skill modules
├── docs/ # Documentation
└── rules/ # Project rules

CLAUDE.md # Claude Code instructions (generated)
GEMINI.md # Gemini CLI instructions (generated)
AGENTS.md # Codex/Kimi/OpenCode instructions (generated)
`

---

Configuration

Main configuration in .workflow/config.json:

`json
{
"enforcement": {
"strictMode": true
},
"hooks": {
"rules": {
"taskGating": { "enabled": true },
"validation": { "enabled": true },
"componentReuse": { "enabled": true }
}
},
"qualityGates": {
"feature": { "require": ["tests", "appMapUpdate", "requestLogEntry"] }
},
"hybrid": {
"enabled": false,
"provider": "ollama"
}
}
``

---

Documentation

Detailed documentation is in the Knowledge Base:

| Category | Topics |
|----------|--------|
| Setup & Onboarding | Installation, onboarding, component indexing |
| Task Execution | Workflow steps, verification, completion |
| Self-Improvement | Skills, learning, model adapters |
| Memory & Context | Context management, session persistence |
| Development Tools | Figma analyzer, code traces, MCP |
| Safety & Guardrails | Damage control, checkpoints, security |
| Configuration | All configuration options |

$3

Each supported CLI has its own guide explaining setup, enforcement, and usage:

- Claude Code Guide
- Gemini CLI Guide
- Cursor Guide
- OpenCode Guide
- Codex Guide
- Kimi Guide

---

Self-Improving Workflow

WogiFlow learns from your corrections:

1. Correction → You correct the AI's work
2. Fix → AI fixes immediately
3. Learn → AI asks to persist the rule
4. Update → Updates decisions.md / skills / config
5. Track → Logs to feedback-patterns.md

After 3+ similar corrections → promotes to permanent instruction.

---

License

AGPL-3.0