dean0x · dean0x · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
@@ -50,7 +50,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 39 skills (single source of truth)
+├── shared/skills/          # 37 skills (single source of truth)
 ├── shared/agents/          # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation

@@ -24,7 +24,7 @@ After setup, DevFlow commands (`/code-review`, `/implement`, etc.) are available
 
 ```
 devflow/
-├── shared/skills/       # 35 skills (single source of truth)
+├── shared/skills/       # 37 skills (single source of truth)
 ├── shared/agents/       # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/   # 17 plugins (8 core + 9 optional)
 ├── scripts/hooks/       # Working Memory hooks

@@ -0,0 +1,116 @@
+# CLI Reference
+
+## Installation
+
+```bash
+npx devflow-kit init
+```
+
+The interactive wizard offers two modes:
+- **Recommended** (default) — Sensible defaults, quick setup
+- **Advanced** — Full interactive flow with all options
+
+Use `--recommended` or `--advanced` flags for non-interactive setup.
+
+### Init Options
+
+| Option | Description |
+|--------|-------------|
+| `--plugin <names>` | Comma-separated plugin names (e.g., `implement,code-review`) |
+| `--scope <user\|local>` | Installation scope (default: user) |
+| `--teams` / `--no-teams` | Enable/disable Agent Teams (default: off) |
+| `--ambient` / `--no-ambient` | Enable/disable ambient mode (default: on) |
+| `--memory` / `--no-memory` | Enable/disable working memory (default: on) |
+| `--learn` / `--no-learn` | Enable/disable self-learning (default: on) |
+| `--hud` / `--no-hud` | Enable/disable HUD status line (default: on) |
+| `--hud-only` | Install only the HUD (no plugins, hooks, or extras) |
+| `--verbose` | Show detailed output |
+
+### Scopes
+
+- `--scope user` (default) — Install for all projects (`~/.claude/`)
+- `--scope local` — Install for current project only (`.claude/`)
+
+## Plugin Management
+
+```bash
+npx devflow-kit list                          # List available plugins
+npx devflow-kit init --plugin=implement       # Install specific plugin
+npx devflow-kit init --plugin=implement,code-review  # Install multiple
+```
+
+### Available Plugins
+
+| Plugin | Type | Description |
+|--------|------|-------------|
+| `devflow-specify` | Core | Feature specification workflow |
+| `devflow-implement` | Core | Complete task implementation lifecycle |
+| `devflow-code-review` | Core | Comprehensive code review |
+| `devflow-resolve` | Core | Review issue resolution |
+| `devflow-debug` | Core | Competing hypothesis debugging |
+| `devflow-self-review` | Core | Simplifier + Scrutinizer |
+| `devflow-ambient` | Core | Ambient mode (always-on intent classification) |
+| `devflow-core-skills` | Core | Auto-activating quality skills |
+| `devflow-typescript` | Language | TypeScript patterns |
+| `devflow-react` | Language | React patterns |
+| `devflow-accessibility` | Language | Web accessibility patterns |
+| `devflow-frontend-design` | Language | Frontend design patterns |
+| `devflow-go` | Language | Go patterns |
+| `devflow-python` | Language | Python patterns |
+| `devflow-java` | Language | Java patterns |
+| `devflow-rust` | Language | Rust patterns |
+
+## Ambient Mode
+
+```bash
+npx devflow-kit ambient --enable     # Enable always-on ambient mode
+npx devflow-kit ambient --disable    # Disable ambient mode
+npx devflow-kit ambient --status     # Show current status
+```
+
+## Self-Learning
+
+```bash
+npx devflow-kit learn --enable       # Register the learning hook
+npx devflow-kit learn --disable      # Remove the learning hook
+npx devflow-kit learn --status       # Show status and observation counts
+npx devflow-kit learn --list         # Show all observations by confidence
+npx devflow-kit learn --configure    # Interactive config (model, throttle, caps)
+npx devflow-kit learn --clear        # Reset all observations
+npx devflow-kit learn --purge        # Remove invalid/corrupted entries
+```
+
+## HUD (Status Line)
+
+```bash
+npx devflow-kit hud --status         # Show current HUD config
+npx devflow-kit hud --enable         # Enable HUD
+npx devflow-kit hud --disable        # Disable HUD
+npx devflow-kit hud --detail         # Show tool/agent descriptions
+npx devflow-kit hud --no-detail      # Hide tool/agent descriptions
+```
+
+## Skill Shadowing
+
+Override any DevFlow skill with your own version. Shadowed skills survive `devflow init` — your version is installed instead of DevFlow's.
+
+```bash
+npx devflow-kit skills shadow software-design    # Create override (copies current as reference)
+vim ~/.devflow/skills/software-design/SKILL.md   # Edit your override
+npx devflow-kit skills list-shadowed             # List all overrides
+npx devflow-kit skills unshadow software-design  # Remove override
+```
+
+## Uninstall
+
+```bash
+npx devflow-kit uninstall
+```
+
+| Option | Description |
+|--------|-------------|
+| `--scope <user\|local>` | Uninstall scope (default: user) |
+| `--plugin <names>` | Selective uninstall by plugin name |
+| `--keep-docs` | Preserve `.docs/` directory |
+| `--dry-run` | Show what would be removed |
+| `--verbose` | Show detailed output |
@@ -0,0 +1,113 @@
+# Commands
+
+DevFlow provides six commands that orchestrate specialized agents. Commands spawn agents — they never do the work themselves.
+
+## /specify
+
+Interactive feature specification with three mandatory gates:
+
+1. **Understanding Gate** — Confirm the feature idea is understood
+2. **Scope Gate** — Validate priorities and boundaries
+3. **Acceptance Gate** — Confirm success criteria
+
+Creates a well-defined GitHub issue ready for `/implement`.
+
+```
+/specify              # Start interactive specification
+```
+
+## /implement
+
+Executes a single task through the complete development lifecycle:
+
+1. **Setup** — Auto-create feature branch (detects repo naming conventions)
+2. **Exploration** — Analyze codebase for relevant patterns and dependencies
+3. **Planning** — Design the implementation approach
+4. **Implementation** — Write code on the feature branch
+5. **Validation** — Build, typecheck, lint, and test
+6. **Refinement** — Simplifier (code clarity) + Scrutinizer (9-pillar quality)
+7. **Alignment** — Shepherd verifies implementation matches the original request
+
+Creates a PR when complete.
+
+```
+/implement add JWT auth      # From description
+/implement #42               # From GitHub issue
+/implement                   # From conversation context
+```
+
+## /code-review
+
+Multi-perspective code review with up to 18 specialized reviewers running in parallel:
+
+**Always active:** Security, Architecture, Performance, Complexity, Consistency, Regression, Testing
+
+**Conditionally active** (when relevant files detected): TypeScript, React, Accessibility, Go, Python, Java, Rust, Database, Dependencies, Documentation
+
+Each reviewer produces findings with:
+- **Category**: Blocking (must-fix), Should-Fix, Pre-existing (informational)
+- **Severity**: CRITICAL, HIGH, MEDIUM, LOW
+- **Location**: Exact file:line reference
+- **Fix**: Specific code solution
+
+Supports multi-worktree auto-discovery — one command reviews all active branches.
+
+```
+/code-review                 # Review current branch (or all worktrees)
+/code-review #42             # Review specific PR
+```
+
+## /resolve
+
+Processes all issues from `/code-review` reports:
+
+1. **Parse** — Extract all issues from the latest unresolved review
+2. **Batch** — Group by file/function for efficient resolution
+3. **Resolve** — Parallel resolver agents validate each issue, then:
+   - **Fix** standard issues directly
+   - **Fix carefully** (public API, shared state, core logic) with systematic test-first refactoring
+   - **Won't Fix** impractical issues (e.g., micro-optimizing startup code)
+   - **Defer** only genuine architectural overhauls to tech debt
+4. **Simplify** — Clean up all modified files
+5. **Report** — Write resolution summary with full decision audit trail
+
+```
+/resolve                     # Resolve latest review (or all worktrees)
+/resolve #42                 # Resolve specific PR's review
+/resolve --review 2026-03-28_0900  # Resolve specific review run
+```
+
+## /debug
+
+Investigates bugs using competing hypotheses:
+
+1. **Hypothesis Generation** — Identify 3-5 plausible explanations
+2. **Parallel Investigation** — Each hypothesis investigated independently by separate agents
+3. **Evidence Evaluation** — Hypotheses ranked by supporting evidence
+4. **Root Cause** — Best-supported explanation with fix recommendation
+
+```
+/debug "login fails after session timeout"
+/debug #42                   # Investigate from GitHub issue
+```
+
+## /self-review
+
+Self-review workflow that runs two sequential quality passes:
+
+1. **Simplifier** — Code clarity, reuse opportunities, efficiency
+2. **Scrutinizer** — 9-pillar quality evaluation (correctness, security, performance, etc.)
+
+```
+/self-review                 # Review recent changes
+```
+
+## Ambient Mode
+
+Not a command — an always-on hook that classifies every prompt and loads proportional skill sets:
+
+| Depth | When | What happens |
+|-------|------|-------------|
+| **QUICK** | Chat, git ops, trivial edits | Zero overhead — respond normally |
+| **GUIDED** | Small implementations, focused debugging | Skills loaded, main session implements |
+| **ORCHESTRATED** | Complex tasks, multi-file changes | Full agent pipeline (same as slash commands) |
@@ -0,0 +1,56 @@
+# Self-Learning
+
+DevFlow detects repeated workflows and procedural knowledge across sessions and automatically creates slash commands and skills.
+
+## How it works
+
+A background agent runs on session end, batching every 3 sessions (5 at 15+ observations) to analyze transcripts for patterns. When a pattern is observed enough times (3 observations with 24h+ temporal spread), it creates an artifact:
+
+- **Workflow patterns** become slash commands at `.claude/commands/self-learning/`
+- **Procedural patterns** become skills at `.claude/skills/{slug}/`
+
+Observations accumulate in `.memory/learning-log.jsonl` with confidence scores and temporal decay. Generated artifacts are never overwritten — you can edit or delete them freely.
+
+## CLI Commands
+
+```bash
+npx devflow-kit learn --enable       # Register the learning SessionEnd hook
+npx devflow-kit learn --disable      # Remove the learning hook
+npx devflow-kit learn --status       # Show status and observation counts
+npx devflow-kit learn --list         # Show all observations sorted by confidence
+npx devflow-kit learn --configure    # Interactive config (model, throttle, daily cap, debug)
+npx devflow-kit learn --clear        # Reset all observations
+npx devflow-kit learn --purge        # Remove invalid/corrupted entries
+```
+
+## Configuration
+
+Use `devflow learn --configure` for interactive setup, or edit `.memory/learning.json` directly:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Model | `haiku` | Model for background analysis |
+| Batch size | 3 sessions (5 at 15+ obs) | Sessions accumulated before analysis |
+| Daily cap | 5 runs | Maximum learning runs per day |
+| Debug | `false` | Enable verbose logging |
+
+## Observation Lifecycle
+
+1. **Accumulate** — Each session end appends the session ID to `.memory/.learning-session-count`
+2. **Batch** — When count reaches threshold, session IDs are moved to `.learning-batch-ids`
+3. **Analyze** — Background agent reads batch transcripts, extracts patterns
+4. **Score** — Observations get confidence scores based on frequency and temporal spread
+5. **Create** — When confidence threshold met (3 observations, 24h+ spread), artifact is generated
+6. **Reinforce** — Existing observations are reinforced locally (no LLM) on each session end
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `.memory/learning-log.jsonl` | All observations (one JSON per line) |
+| `.memory/learning.json` | Project-level configuration |
+| `.memory/.learning-runs-today` | Daily run counter (date + count) |
+| `.memory/.learning-session-count` | Session IDs pending batch |
+| `.memory/.learning-batch-ids` | Session IDs for current batch |
+| `.memory/.learning-notified-at` | Artifact notification marker |
+| `~/.devflow/logs/{project-slug}/.learning-update.log` | Background agent log |
@@ -0,0 +1,81 @@
+# Working Memory
+
+DevFlow automatically preserves session context across restarts, `/clear`, and context compaction — zero ceremony required.
+
+## How it works
+
+Three shell hooks run behind the scenes:
+
+| Hook | When | What |
+|------|------|------|
+| **Stop** | After each response | Updates `.memory/WORKING-MEMORY.md` with current focus, decisions, and progress. Throttled — skips if updated <2 min ago. |
+| **SessionStart** | On startup, `/clear`, resume, compaction | Injects previous working memory + fresh git state as system context. Warns if memory is >1h stale. |
+| **PreCompact** | Before context compaction | Backs up git state to JSON. Bootstraps a minimal working memory from git if none exists yet. |
+
+Working memory is **per-project** — scoped to each repo's `.memory/` directory. Multiple sessions across different repos don't interfere.
+
+## Enable / Disable
+
+```bash
+npx devflow-kit init --memory          # Enable during install
+npx devflow-kit init --no-memory       # Disable during install
+devflow memory --enable                # Toggle on
+devflow memory --disable               # Toggle off
+devflow memory --status                # Check current state
+```
+
+## File Structure
+
+```
+.memory/
+├── WORKING-MEMORY.md         # Auto-maintained by Stop hook (overwritten each session)
+├── backup.json               # Pre-compact git state snapshot
+├── learning-log.jsonl        # Learning observations (JSONL, one entry per line)
+├── learning.json             # Project-level learning config
+├── .learning-runs-today      # Daily run counter (date + count)
+├── .learning-session-count   # Session IDs pending batch (one per line)
+├── .learning-batch-ids       # Session IDs for current batch run
+├── .learning-notified-at     # New artifact notification marker (epoch timestamp)
+└── knowledge/
+    ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
+    └── pitfalls.md            # Known pitfalls (PF-NNN, area-specific gotchas)
+```
+
+Debug logs are stored at `~/.devflow/logs/{project-slug}/`.
+
+## Working Memory Sections
+
+The Stop hook maintains these sections in `WORKING-MEMORY.md`:
+
+| Section | Purpose |
+|---------|---------|
+| `## Now` | Current focus and immediate next steps |
+| `## Progress` | What's done, what remains, blockers |
+| `## Decisions` | Architectural and design decisions made this session |
+| `## Modified Files` | Files changed with status |
+| `## Context` | Repository state, build status, test results |
+| `## Session Log` | Timestamped log of significant actions |
+
+## Long-term Knowledge
+
+Beyond session memory, DevFlow persists architectural decisions and known pitfalls:
+
+- **`decisions.md`** — ADR-numbered entries (append-only). Reviewers check if changes violate prior decisions.
+- **`pitfalls.md`** — PF-numbered entries scoped by area. Reviewers check if changes reintroduce known pitfalls.
+
+These files are read by reviewers automatically during `/code-review`.
+
+## Documentation Structure
+
+DevFlow creates project documentation in `.docs/`:
+
+```
+.docs/
+├── reviews/{branch-slug}/              # Review reports per branch
+│   ├── .last-review-head              # HEAD SHA for incremental reviews
+│   └── {timestamp}/                   # Timestamped review directory
+│       ├── {focus}.md                 # Reviewer reports
+│       ├── review-summary.md          # Synthesizer output
+│       └── resolution-summary.md      # Written by /resolve
+└── design/                            # Implementation plans
+```