feat: UX refactor — smart router, colon-namespaced skills, non-blocking hooks

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intent-layer",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Hierarchical AGENTS.md infrastructure for AI-navigable codebases. Create CLAUDE.md/AGENTS.md files that help AI agents navigate your codebase like senior engineers.",
   "author": {
     "name": "Intent Layer Contributors"

CLAUDE.md

@@ -40,13 +40,12 @@ intent-layer-plugin/
 ├── .claude-plugin/
 │   └── plugin.json          # Plugin manifest (name, version, author)
 ├── skills/                   # Slash-command skills (/intent-layer, etc.)
-│   ├── intent-layer/         # Main setup skill + sub-skills (git-history, pr-review, pr-review-mining)
-│   ├── intent-layer-maintenance/
-│   ├── intent-layer-onboarding/
-│   ├── intent-layer-query/
-│   ├── intent-layer-compound/ # End-of-session learning capture
-│   ├── intent-layer-health/   # Quick health check
-│   └── review-mistakes/       # Interactive mistake triage
+│   ├── intent-layer/         # Smart router + sub-skills (git-history, pr-review, pr-review-mining)
+│   │   └── workflows/        # Reference docs for setup, maintain, onboard flows
+│   ├── intent-layer-maintain/ # Ongoing maintenance (state = complete)
+│   ├── intent-layer-review/   # Batch triage of pending learnings
+│   ├── intent-layer-query/    # Query Intent Layer for answers
+│   └── intent-layer-health/   # Quick health check
 ├── agents/                   # Specialized subagents
 │   ├── explorer.md           # Analyzes directories, proposes nodes
 │   ├── validator.md          # Deep validation against codebase
@@ -67,7 +66,7 @@ intent-layer-plugin/
 
 | Component | Purpose | Invocation |
 |-----------|---------|------------|
-| **Skills** | Interactive workflows for setup/maintenance | `/intent-layer`, `/intent-layer-maintenance` |
+| **Skills** | Interactive workflows for setup/maintenance | `/intent-layer`, `/intent-layer:maintain`, `/intent-layer:review` |
 | **Agents** | Specialized analysis tasks | Auto-invoked by Claude when relevant |
 | **Hooks** | Learning loop: auto-capture, pitfall injection, staleness check | 5 hooks: SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, Stop |
 
@@ -97,7 +96,7 @@ intent-layer-plugin/
 | `capture_mistake.sh` | Record mistakes for learning loop (manual) |
 | `review_mistakes.sh` | Interactive triage of pending mistake reports |
 | `post-edit-check.sh` | Hook script for edit tracking |
-| `stop-learning-check.sh` | Stop hook: two-tier learning classifier (heuristic + Haiku) |
+| `stop-learning-check.sh` | Stop hook: three-tier learning classifier (heuristic + Haiku classify + Haiku extract) |
 | `inject-learnings.sh` | SessionStart hook: inject recent learnings |
 | `pre-edit-check.sh` | PreToolUse hook: inject covering AGENTS.md sections |
 | `capture-tool-failure.sh` | PostToolUseFailure hook: create skeleton reports |
@@ -127,14 +126,11 @@ Internal scripts used by hooks and other scripts:
 
 ### Skill Relationships
 
-- `intent-layer` → Initial setup (state = none/partial)
-- `intent-layer-maintenance` → Ongoing updates (state = complete)
-- `intent-layer-onboarding` → Orientation for new developers
-- `intent-layer-query` → Answer questions using Intent Layer
-- `intent-layer:clean` → Remove Intent Layer from a repo
-- `intent-layer-compound` → End-of-session learning capture and triage
-- `intent-layer-health` → Quick health check (validation + staleness + coverage)
-- `review-mistakes` → Interactive triage of pending mistake reports
+- `/intent-layer` → Smart router: detects state, counts pending, routes to appropriate action
+- `/intent-layer:maintain` → Ongoing updates (state = complete)
+- `/intent-layer:review` → Batch triage of pending learnings (auto-captured by stop hook)
+- `/intent-layer:query` → Answer questions using Intent Layer
+- `/intent-layer:health` → Quick health check (validation + staleness + coverage)
 
 All skills share scripts via `${CLAUDE_PLUGIN_ROOT}/scripts/`.
 

README.md

@@ -58,11 +58,11 @@ Interactive workflows invoked via slash commands:
 
 | Skill | Purpose | Command |
 |-------|---------|---------|
-| `intent-layer` | Set up new Intent Layer infrastructure | `/intent-layer` |
-| `intent-layer-maintenance` | Maintain existing Intent Layers | `/intent-layer-maintenance` |
-| `intent-layer-onboarding` | Orient new developers using Intent Layer | `/intent-layer-onboarding` |
-| `intent-layer-query` | Query Intent Layer for answers | `/intent-layer-query` |
-| `review-mistakes` | Interactive review of pending mistake reports | `/review-mistakes` |
+| `intent-layer` | Smart router: detects state, routes to setup/maintain/review | `/intent-layer` |
+| `intent-layer:maintain` | Maintain existing Intent Layers | `/intent-layer:maintain` |
+| `intent-layer:review` | Batch triage of pending learnings | `/intent-layer:review` |
+| `intent-layer:query` | Query Intent Layer for answers | `/intent-layer:query` |
+| `intent-layer:health` | Quick health check (validation + staleness + coverage) | `/intent-layer:health` |
 
 ### Agents
 
@@ -98,7 +98,7 @@ Agent makes mistake → PostToolUseFailure auto-creates skeleton
                       Stop hook evaluates: enrich or discard?
                               ↓
                       Next session: Agent offers interactive review
-                      or user runs /review-mistakes
+                      or user runs /intent-layer:review
                               ↓
                       User decides: Accept / Reject / Discard
                               ↓ (on accept)
@@ -110,7 +110,7 @@ Agent makes mistake → PostToolUseFailure auto-creates skeleton
                       PreToolUse injects relevant pitfalls before edits
 ```
 
-**Interactive review**: When pending reports exist, the agent offers to walk you through them conversationally. You can also explicitly run `/review-mistakes` to start a review session.
+**Interactive review**: When pending reports exist, the agent offers to walk you through them conversationally. You can also explicitly run `/intent-layer:review` to start a review session.
 
 **Supporting scripts:**
 
@@ -145,7 +145,7 @@ Agent makes mistake → PostToolUseFailure auto-creates skeleton
 ./scripts/capture_pain_points.sh pain_points.md
 
 # Run maintenance workflow
-# In Claude Code: /intent-layer-maintenance /path/to/project
+# In Claude Code: /intent-layer:maintain /path/to/project
 ```
 
 ### Onboarding
@@ -154,8 +154,8 @@ Agent makes mistake → PostToolUseFailure auto-creates skeleton
 # Generate orientation overview
 ./scripts/generate_orientation.sh /path/to/project
 
-# Or use the skill interactively
-# In Claude Code: /intent-layer-onboarding /path/to/project
+# Or use the router which includes onboarding as an option
+# In Claude Code: /intent-layer /path/to/project
 ```
 
 ## Plugin Structure
@@ -165,17 +165,21 @@ intent-layer-plugin/
 ├── .claude-plugin/
 │   └── plugin.json          # Plugin manifest
 ├── skills/                   # Slash-command skills
-│   ├── intent-layer/
-│   ├── intent-layer-maintenance/
-│   ├── intent-layer-onboarding/
-│   └── intent-layer-query/
+│   ├── intent-layer/         # Smart router + sub-skills
+│   │   └── workflows/        # Reference docs for flows
+│   ├── intent-layer-maintain/
+│   ├── intent-layer-review/
+│   ├── intent-layer-query/
+│   └── intent-layer-health/
 ├── agents/                   # Specialized subagents
 │   ├── explorer.md
 │   ├── validator.md
-│   └── auditor.md
+│   ├── auditor.md
+│   └── change-tracker.md
 ├── hooks/
-│   └── hooks.json            # PostToolUse hook config
+│   └── hooks.json            # 5 hook slots
 ├── scripts/                  # Shared bash scripts
+├── lib/                      # Internal library scripts
 └── references/               # Templates and guides
 ```
 
@@ -203,7 +207,7 @@ All scripts support:
 - Projects that change so rapidly the docs would be stale immediately
 - Codebases you won't use AI agents on
 
-### intent-layer-maintenance
+### intent-layer:maintain
 
 **Good for:**
 - Quarterly reviews of existing Intent Layers
@@ -212,7 +216,7 @@ All scripts support:
 - When agents consistently get confused about something
 
 **Not good for:**
-- Initial setup (use `intent-layer` first)
+- Initial setup (use `/intent-layer` first — it routes automatically)
 - Minor cosmetic changes that don't affect behavior
 
 ## CI Integration

docs/brainstorms/2026-02-15-ux-refactor-brainstorm.md

@@ -0,0 +1,113 @@
+# Intent Layer UX Refactor — Brainstorm
+
+Date: 2026-02-15
+
+## What we're building
+
+A full UX overhaul of the intent-layer plugin, restructuring from a flat list of 7 skills into a three-tier architecture (commands → skills → agents), redesigning the learning review pipeline for batch triage, and improving visual output quality across hooks and dashboards.
+
+## Why this approach
+
+The plugin grew organically and now has 7 slash commands with unclear boundaries. Users don't know which to run when. The learning capture pipeline requires 10+ interactions per session for a handful of learnings. Hook outputs dump full AGENTS.md sections before every edit with no deduplication. Dashboard scripts output plain ASCII with no visual hierarchy.
+
+The compound-engineering plugin demonstrates a working three-tier pattern: workflow commands chain skills and spawn agents. We're adopting this pattern while also fixing the review pipeline and output quality.
+
+## Key decisions
+
+### 1. Three-tier reorganization
+
+Restructure the plugin into three tiers:
+
+**Commands** (what users run):
+- `/intent-layer` — smart router that detects state and presents the right action
+- `/intent-layer:review` — batch learning triage (replaces `/intent-layer-compound` + `/review-mistakes`)
+- Workflow sub-commands: `/intent-layer:maintain`, `/intent-layer:health`, `/intent-layer:query`
+
+**Skills** (reusable knowledge, not interactive):
+- `node-authoring/` — how to write good AGENTS.md content
+- `hierarchy-design/` — T-shaped context, LCA placement, compression
+- `learning-loop/` — how the capture → triage → integrate cycle works
+
+**Agents** (already exist, unchanged):
+- `explorer.md`, `validator.md`, `auditor.md`, `change-tracker.md`
+
+Old standalone skills (`intent-layer-onboarding`, `intent-layer-health`, `intent-layer-query`) become sub-flows of the router or workflows. No migration aliases — clean break.
+
+### 2. Review pipeline redesign
+
+**Phase 1: Capture (automatic, non-blocking)**
+- Stop hook **never blocks session exit**
+- Auto-classifies confidence: high / medium / low
+- Appends confidence score and suggested section to each skeleton report
+- Captures go silently to `.intent-layer/mistakes/pending/`
+
+**Phase 2: Triage (batch, one interaction)**
+- `/intent-layer:review` shows ranked table of all pending learnings
+- User selects which to accept via `AskUserQuestion` with `multiSelect: true`
+- Remaining are discarded or deferred in one action
+- Accepted items integrate automatically — no further prompts
+
+**Phase 3: Auto-accept (optional fast path)**
+- `--auto-accept-high` flag integrates high-confidence items without prompting
+- Only medium/low items shown for review
+
+### 3. Smart router
+
+`/intent-layer` detects state and routes:
+
+| State | Condition | Action |
+|-------|-----------|--------|
+| none | No CLAUDE.md or AGENTS.md | Offer setup workflow |
+| partial | CLAUDE.md exists, no children | Continue setup |
+| complete + pending | Learnings waiting | Offer review first |
+| complete + stale | Nodes >30 days old | Suggest maintenance |
+| complete + healthy | Everything OK | Show menu: maintain, query, export |
+
+Priority order: pending learnings → stale nodes → healthy menu.
+
+### 4. Hook output deduplication
+
+PreToolUse changes:
+- Track injected nodes in session-scoped temp file
+- First edit to a file: full injection (Pitfalls, Checks, Patterns, Context)
+- Same node injected <5 min ago: one-liner summary instead of full content
+- High-risk areas (mistake history): always full injection with warning banner
+
+PostToolUse changes:
+- Only fire "review if behavior changed" when the edited file is actually referenced in the covering AGENTS.md (check Code Map, Entry Points sections)
+
+### 5. Colon-namespaced naming
+
+| Command | Purpose |
+|---------|---------|
+| `/intent-layer` | Smart router (main entry point) |
+| `/intent-layer:review` | Batch learning triage |
+| `/intent-layer:maintain` | Post-change maintenance pass |
+| `/intent-layer:health` | Quick validation (staleness + coverage) |
+| `/intent-layer:query` | Answer questions using Intent Layer |
+
+Five commands total, all under one namespace. Onboarding becomes a sub-flow of the router (not a standalone command).
+
+### 6. Dashboard color styling
+
+Add ANSI color support with `NO_COLOR` env var opt-out:
+- Green for healthy/passing/high rates
+- Yellow for warnings/stale/medium confidence
+- Red for failures/critical/low rates
+- Bold for headers and key metrics
+- Dim for secondary info
+
+Add `setup_colors()` helper to `lib/common.sh`. Apply to `show_status.sh`, `show_hierarchy.sh`, `show_telemetry.sh`, and `audit_intent_layer.sh`.
+
+## Open questions
+
+1. Should the smart router also auto-run on SessionStart (via hook) instead of requiring `/intent-layer`?
+2. Should `/intent-layer:review` be auto-suggested at session end (non-blocking hint) when there are pending learnings?
+3. What confidence threshold separates high from medium? Current stop hook uses a two-tier classifier (heuristic + Haiku) — should the confidence score come from the Haiku response directly?
+
+## Scope exclusions
+
+- MCP server changes (already built, works fine)
+- Template system changes (already built)
+- Agent restructuring (agents already follow the right pattern)
+- Backward-compatible aliases for old skill names (clean break)

lib/common.sh

@@ -79,6 +79,18 @@ file_newer_than() {
     [[ "$file_date" > "$cutoff_date" || "$file_date" == "$cutoff_date" ]]
 }
 
+# Set up ANSI color variables for CLI dashboard scripts.
+# Checks both TTY detection and NO_COLOR convention (https://no-color.org).
+# IMPORTANT: Hook scripts must NEVER call this — color codes corrupt JSON output.
+setup_colors() {
+    if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
+        RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'
+        BOLD=$'\033[1m'; DIM=$'\033[2m'; RESET=$'\033[0m'
+    else
+        RED=''; GREEN=''; YELLOW=''; BOLD=''; DIM=''; RESET=''
+    fi
+}
+
 # Output JSON for hook response (additionalContext pattern)
 output_context() {
     local hook_event="$1"

references/agent-feedback-protocol.md

@@ -130,7 +130,7 @@ Before marking task complete, check if you encountered Intent Layer gaps.
 Include Intent Layer feedback in PR description if findings emerged.
 
 ### Quarterly Maintenance
-Use accumulated feedback as input to `intent-layer-maintenance` skill.
+Use accumulated feedback as input to `intent-layer:maintain` skill.
 
 ## Example Workflow
 

references/parallel-orchestration.md

@@ -461,7 +461,7 @@ Formula: `batch_size = min(available_agents, resource_limit, task_count)`
 4. Present to user
 ```
 
-### /intent-layer-maintenance
+### /intent-layer:maintain
 
 ```
 1. detect_staleness.sh → List flagged nodes