feat: add self-learning system (workflow detection + auto-commands)

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Self-learning system: detects repeated workflows and creates slash commands/skills automatically
+
 ---
 
 ## [1.8.3] - 2026-03-22

CLAUDE.md

@@ -40,6 +40,8 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 **Working Memory**: Three shell-script hooks (`scripts/hooks/`) provide automatic session continuity. Toggleable via `devflow memory --enable/--disable/--status` or `devflow init --memory/--no-memory`. Stop hook → reads last turn from session transcript (`~/.claude/projects/{encoded-cwd}/{session_id}.jsonl`), spawns background `claude -p --model haiku` to update `.memory/WORKING-MEMORY.md` with structured sections (`## Now`, `## Progress`, `## Decisions`, `## Modified Files`, `## Context`, `## Session Log`; throttled: skips if triggered <2min ago; concurrent sessions serialize via mkdir-based lock). SessionStart hook → injects previous memory + git state as `additionalContext` on `/clear`, startup, or compact (warns if >1h stale; injects pre-compact memory snapshot when compaction happened mid-session). PreCompact hook → saves git state + WORKING-MEMORY.md snapshot + bootstraps minimal WORKING-MEMORY.md if none exists. Zero-ceremony context preservation.
 
+**Self-Learning**: A Stop hook (`stop-update-learning`) spawns a background `claude -p --model sonnet` to detect repeated workflows and procedural knowledge from session transcripts. Observations accumulate in `.memory/learning-log.jsonl` with confidence scores, temporal decay, and daily run caps. When confidence thresholds are met (3 observations for workflows with 24h+ temporal spread, 2 for procedural), artifacts are auto-created as slash commands (`.claude/commands/learned/`) or skills (`.claude/skills/learned-*/`). Toggleable via `devflow learn --enable/--disable/--status` or `devflow init --learn/--no-learn`. Configurable model/throttle/caps via `devflow learn --configure`.
+
 ## Project Structure
 
 ```
@@ -49,8 +51,8 @@ devflow/
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
 ├── scripts/                # Helper scripts (statusline, docs-helpers)
-│   └── hooks/              # Working Memory + ambient hooks (stop, session-start, pre-compact, ambient-prompt)
-├── src/cli/                # TypeScript CLI (init, list, uninstall, ambient)
+│   └── hooks/              # Working Memory + ambient + learning hooks (stop, session-start, pre-compact, ambient-prompt, stop-update-learning, background-learning)
+├── src/cli/                # TypeScript CLI (init, list, uninstall, ambient, learn)
 ├── .claude-plugin/         # Marketplace registry
 ├── .docs/                  # Project docs (reviews, design) — per-project
 └── .memory/                # Working memory files — per-project
@@ -94,6 +96,12 @@ Working memory files live in a dedicated `.memory/` directory:
 .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 (max runs, throttle, model)
+├── .learning-runs-today      # Daily run counter (date + count)
+├── .learning-update.log      # Background learning agent log
+├── .learning-last-trigger    # Throttle marker (epoch timestamp)
+├── .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)

README.md

@@ -189,6 +189,26 @@ Three shell hooks run behind the scenes:
 
 Working memory is **per-project** — scoped to each repo's `.memory/` directory. Multiple sessions across different repos don't interfere.
 
+## Self-Learning
+
+DevFlow detects repeated workflows and procedural knowledge across your sessions and automatically creates slash commands and skills.
+
+A background agent runs on session stop (same as Working Memory) and analyzes your session transcript for patterns. When a pattern is observed enough times (3 for workflows with 24h+ temporal spread, 2 for procedural knowledge), it creates an artifact:
+
+- **Workflow patterns** become slash commands at `.claude/commands/learned/`
+- **Procedural patterns** become skills at `.claude/skills/learned-*/`
+
+| Command | Description |
+|---------|-------------|
+| `devflow learn --enable` | Register the learning Stop hook |
+| `devflow learn --disable` | Remove the learning hook |
+| `devflow learn --status` | Show learning status and observation counts |
+| `devflow learn --list` | Show all observations sorted by confidence |
+| `devflow learn --configure` | Interactive configuration (model, throttle, daily cap) |
+| `devflow learn --clear` | Reset all observations |
+
+Observations accumulate in `.memory/learning-log.jsonl` with confidence scores and temporal decay. You can edit or delete any generated artifacts — they are never overwritten.
+
 ## Documentation Structure
 
 DevFlow creates project documentation in `.docs/` and working memory in `.memory/`:
@@ -201,6 +221,12 @@ DevFlow creates project documentation in `.docs/` and working memory in `.memory
 .memory/
 ├── WORKING-MEMORY.md         # Auto-maintained by Stop hook
 ├── backup.json               # Pre-compact git state snapshot
+├── learning-log.jsonl        # Learning observations (JSONL)
+├── learning.json             # Project-level learning config
+├── .learning-runs-today      # Daily run counter
+├── .learning-update.log      # Background learning agent log
+├── .learning-last-trigger    # Throttle marker
+├── .learning-notified-at     # New artifact notification marker
 └── knowledge/
     ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
     └── pitfalls.md            # Known pitfalls (area-specific gotchas)
@@ -239,6 +265,8 @@ Session context is saved and restored automatically via Working Memory hooks —
 | `npx devflow-kit list` | List available plugins |
 | `npx devflow-kit ambient --enable` | Enable always-on ambient mode |
 | `npx devflow-kit ambient --disable` | Disable ambient mode |
+| `npx devflow-kit learn --enable` | Enable self-learning |
+| `npx devflow-kit learn --disable` | Disable self-learning |
 | `npx devflow-kit uninstall` | Remove DevFlow |
 
 ### Init Options
@@ -250,6 +278,7 @@ Session context is saved and restored automatically via Working Memory hooks —
 | `--teams` / `--no-teams` | Enable/disable Agent Teams (experimental, 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 |

docs/reference/file-organization.md

@@ -42,17 +42,23 @@ devflow/
 │   ├── build-hud.js                  # Copies dist/hud/ → scripts/hud/
 │   ├── hud.sh                        # Thin wrapper: exec node hud/index.js
 │   ├── hud/                          # GENERATED — compiled HUD module (gitignored)
-│   └── hooks/                        # Working Memory + ambient hooks
+│   └── hooks/                        # Working Memory + ambient + learning hooks
 │       ├── stop-update-memory       # Stop hook: writes WORKING-MEMORY.md
 │       ├── session-start-memory     # SessionStart hook: injects memory + git state
 │       ├── pre-compact-memory       # PreCompact hook: saves git state backup
-│       └── ambient-prompt.sh        # UserPromptSubmit hook: ambient skill injection
+│       ├── ambient-prompt           # UserPromptSubmit hook: ambient skill injection
+│       ├── stop-update-learning     # Stop hook: triggers background learning
+│       ├── background-learning      # Background: pattern detection via Sonnet
+│       ├── json-helper.cjs           # Node.js jq-equivalent operations
+│       └── json-parse               # Shell wrapper: jq with node fallback
 └── src/
     └── cli/
         ├── commands/
         │   ├── init.ts
         │   ├── list.ts
         │   ├── memory.ts
+        │   ├── learn.ts
+        │   ├── ambient.ts
         │   ├── hud.ts
         │   └── uninstall.ts
         ├── hud/                          # HUD module (TypeScript source)
@@ -137,7 +143,7 @@ Skills and agents are **not duplicated** in git. Instead:
 
 Included settings:
 - `statusLine` - Configurable HUD with presets (replaces legacy statusline.sh)
-- `hooks` - Working Memory hooks (Stop, SessionStart, PreCompact)
+- `hooks` - Working Memory hooks (Stop, SessionStart, PreCompact) + Learning Stop hook
 - `env.ENABLE_TOOL_SEARCH` - Deferred MCP tool loading (~85% token savings)
 - `env.ENABLE_LSP_TOOL` - Language Server Protocol support
 - `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` - Agent Teams for peer-to-peer collaboration
@@ -146,7 +152,9 @@ Included settings:
 
 ## Working Memory Hooks
 
-Three hooks in `scripts/hooks/` provide automatic session continuity. Toggleable via `devflow memory --enable/--disable/--status` or `devflow init --memory/--no-memory`:
+Three hooks in `scripts/hooks/` provide automatic session continuity. Toggleable via `devflow memory --enable/--disable/--status` or `devflow init --memory/--no-memory`.
+
+A fourth hook (`stop-update-learning`) provides self-learning. Toggleable via `devflow learn --enable/--disable/--status` or `devflow init --learn/--no-learn`:
 
 | Hook | Event | File | Purpose |
 |------|-------|------|---------|

scripts/hooks/ambient-prompt

@@ -7,17 +7,19 @@
 
 set -e
 
-# jq is required to parse hook input JSON — silently no-op if missing
-if ! command -v jq &>/dev/null; then exit 0; fi
+# JSON parsing (jq with node fallback) — silently no-op if neither available
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/json-parse"
+if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
 
 INPUT=$(cat)
 
-CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+CWD=$(echo "$INPUT" | json_field "cwd" "")
 if [ -z "$CWD" ]; then
   exit 0
 fi
 
-PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null)
+PROMPT=$(echo "$INPUT" | json_field "prompt" "")
 
 # Skip slash commands — they have their own orchestration
 if [[ "$PROMPT" == /* ]]; then
@@ -42,9 +44,4 @@ fi
 # SYNC: must match tests/integration/helpers.ts AMBIENT_PREAMBLE
 PREAMBLE="AMBIENT MODE ACTIVE: Before responding, silently classify this prompt using the ambient-router skill already in your session context. If QUICK, respond normally without stating classification. If GUIDED or ORCHESTRATED, your FIRST tool calls MUST be Skill tool invocations for each selected skill — before writing ANY text about the task."
 
-jq -n --arg ctx "$PREAMBLE" '{
-  "hookSpecificOutput": {
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": $ctx
-  }
-}'
+json_prompt_output "$PREAMBLE"