Tool profile: dev-loop config paths + active setup guidance

The capability-role tool profile (knowledge/verify/explore/tacit/design/intake)
carried over from loop-orchestrator but was under-surfaced and stale-named.

- Rename config paths to dev-loop: ~/.claude/dev-loop/tools.json (global) and
  <repo>/.dev-loop/tools.json (per-repo), plus DEV_LOOP_CONFIG_HOME/PROJECT env.
  The old loop-orchestrator paths + LOOP_ORCH_* env are still read as a fallback,
  so existing configs keep working (bats tests use the legacy env → still pass).
- Add /dev-loop:configure skill — maps your wiki (knowledge), test command
  (verify), code search (explore), etc. to real tools and writes tools.json.
- Add hooks/config-nudge.sh (SessionStart) — nudges toward /dev-loop:configure
  only when nothing is configured, at most weekly, then silent once set; kill
  switch DEV_LOOP_CONFIG_NUDGE=0.
- tool-profile.md + README document the paths, the configure skill, and the nudge.

Bump 0.3.0 -> 0.4.0.

Author: choiyounggi

.claude-plugin/marketplace.json

@@ -20,7 +20,7 @@
         "url": "https://github.com/choiyounggi/dev-loop.git"
       },
       "homepage": "https://github.com/choiyounggi/dev-loop",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "tags": [
         "orchestrator",
         "verification-loop",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-loop",
   "description": "loop-orchestrator's verification loop (TDD / PDCA / Reflexion) with the plan step FIXED to a wiki-grounded planning methodology (wiki-plan): every design decision is routed to a bundled semantic-layer wiki before code is written. Adds a knowledge-capture loop — sessions emit verified insights, and knowledge-flush researches, dedups, routes, and opens a wiki PR for owner review.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "choiyounggi",
     "url": "https://github.com/choiyounggi"

README.md

@@ -65,6 +65,31 @@ an ingest candidate. This is not a configurable role and cannot be turned off.
 The wiki lives at the plugin root (`wiki/`, `INDEX.md`, `AGENTS.md`,
 `templates/`); the wiki skills resolve their paths against `${CLAUDE_PLUGIN_ROOT}`.
 
+### Configuring your tools (optional)
+
+Like loop-orchestrator, dev-loop runs fully generic with **no** config, but you
+can map its **capability roles** to your real tools so the loop uses them:
+
+| Role | Map to |
+|------|--------|
+| `verify` | your project's **test / build / QA** command (the loop's run step) |
+| `knowledge` | your domain/team **wiki** or knowledge MCP (external facts) |
+| `explore` | code/symbol search (LSP, ripgrep, a source-search CLI) |
+| `tacit` | past incidents / danger-zone lore |
+| `design` | Figma / visual-spec MCP (UI work) |
+| `intake` | issue tracker (orchestrate's work-list) |
+
+(`plan` is **not** a role — the plan step is fixed to `wiki-plan`. And the bundled
+best-practice `wiki/` needs no config; `knowledge` is a *separate* external wiki.)
+
+Set it up with **`/dev-loop:configure`**, which writes `~/.claude/dev-loop/tools.json`
+(global) or `<repo>/.dev-loop/tools.json` (per-repo, team-shared). Precedence is
+git-config style: `defaults < ~/.claude/dev-loop/tools.json < <repo>/.dev-loop/tools.json`.
+A SessionStart hook nudges you (at most weekly, then never) if you haven't
+configured anything — silence it with `DEV_LOOP_CONFIG_NUDGE=0`. Legacy
+`loop-orchestrator` config paths are still read as a fallback. See
+`references/tool-profile.md` and `examples/tools.example.json`.
+
 ---
 
 ## The knowledge-capture loop
@@ -126,6 +151,7 @@ it never interferes with ordinary `gh pr create` in any repo.
 | `wiki-query` | Answer a question from the wiki with citations. |
 | `wiki-lint` | Health-check the wiki. |
 | `knowledge-flush` | Research + verify + route queued insights → one reviewed wiki PR. |
+| `configure` | Set up the capability-role tool profile (map your wiki, test command, etc.). |
 
 ## Structure
 
@@ -134,12 +160,13 @@ dev-loop/
 ├── .claude-plugin/{plugin,marketplace}.json
 ├── AGENTS.md INDEX.md templates/     # wiki schema + routing entry + page template
 ├── wiki/                             # 10-domain semantic-layer knowledge base
-├── skills/                           # the 7 skills above
+├── skills/                           # the 8 skills above
 ├── agents/test-quality-auditor.md    # bundled independent test auditor (loop step 6.5)
 ├── hooks/
 │   ├── hooks.json
 │   ├── preflight.sh                  # SessionStart: git/tmux/jq advisory
 │   ├── insight-instruction.sh        # SessionStart: inject ★ Insight capture instruction (global)
+│   ├── config-nudge.sh               # SessionStart: nudge to /dev-loop:configure if unconfigured (weekly)
 │   ├── loop-gate.sh                  # Stop: verification-loop integrity gate
 │   ├── harvest-insights.sh + harvest.js  # Stop: harvest insights → queue
 │   ├── auto-flush.sh                 # Stop: auto-run knowledge-flush (guarded) → PR

hooks/config-nudge.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# dev-loop — SessionStart: gently nudge the user to configure the tool profile
+# (knowledge=wiki, verify=test command, …) IF they haven't yet.
+#
+# Fires only when no tools.json is configured anywhere, and at most once a week
+# (a marker suppresses it) so it never nags. Once configured, it goes silent.
+# Disable entirely with DEV_LOOP_CONFIG_NUDGE=0.
+set +e
+
+[ "${DEV_LOOP_CONFIG_NUDGE:-1}" = "0" ] && exit 0
+
+# Don't nudge inside the flush working checkout.
+case "${CLAUDE_PROJECT_DIR:-$PWD}" in
+  "$HOME/.dev-loop/repo"*) exit 0 ;;
+esac
+
+PROJ="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+# Already configured? (dev-loop or legacy path, global or per-repo, or env.)
+configured=0
+for f in \
+  "$HOME/.claude/dev-loop/tools.json" \
+  "$HOME/.claude/loop-orchestrator/tools.json" \
+  "$PROJ/.dev-loop/tools.json" \
+  "$PROJ/.loop-orchestrator/tools.json" \
+  "${DEV_LOOP_CONFIG_HOME:-}" "${LOOP_ORCH_CONFIG_HOME:-}" \
+  "${DEV_LOOP_CONFIG_PROJECT:-}" "${LOOP_ORCH_CONFIG_PROJECT:-}"; do
+  [ -n "$f" ] && [ -f "$f" ] && { configured=1; break; }
+done
+[ "$configured" -eq 1 ] && exit 0
+
+# Rate-limit: skip if nudged within the last 7 days.
+MARK="$HOME/.dev-loop/.config-nudged"
+if [ -f "$MARK" ] && [ -n "$(find "$MARK" -mtime -7 2>/dev/null)" ]; then
+  exit 0
+fi
+mkdir -p "$HOME/.dev-loop" 2>/dev/null
+touch "$MARK" 2>/dev/null
+
+read -r -d '' MSG <<'EOF'
+# dev-loop — optional one-time setup
+
+dev-loop works with zero config, but you'll get more out of it by mapping its
+capability roles to your real tools. Notably:
+  • `verify`    → your project's actual test / build command (used in the loop's run step)
+  • `knowledge` → your domain/team wiki or knowledge MCP (external facts — the bundled best-practice wiki needs no setup)
+  • also: `explore` (code search), `tacit` (incidents), `design` (Figma)
+
+Run **/dev-loop:configure** to set these up (writes ~/.claude/dev-loop/tools.json,
+or <repo>/.dev-loop/tools.json for a team-shared, per-repo profile).
+
+(This reminder shows at most weekly until you configure, then stops. Silence it
+now with DEV_LOOP_CONFIG_NUDGE=0.)
+EOF
+
+printf '%s' "$MSG" | node -e '
+const fs=require("fs");let s="";try{s=fs.readFileSync(0,"utf8")}catch{}
+process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:s}}));
+' 2>/dev/null
+
+exit 0

hooks/hooks.json

@@ -12,6 +12,10 @@
           {
             "type": "command",
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/insight-instruction.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/config-nudge.sh"
           }
         ]
       }

references/tool-profile.md

@@ -88,12 +88,17 @@ and tends to drag in an environment-specific tool's own assumptions.
 Layered like `git config`, lowest to highest:
 
 ```
-built-in defaults  <  ~/.claude/loop-orchestrator/tools.json  <  <repo>/.loop-orchestrator/tools.json
+built-in defaults  <  ~/.claude/dev-loop/tools.json  <  <repo>/.dev-loop/tools.json
 ```
 
-- **per-user** (`~/.claude/loop-orchestrator/tools.json`) — your machine's tools,
-  applied across every project you run the orchestrator in.
-- **per-repo** (`<repo>/.loop-orchestrator/tools.json`) — commit it to share a
+Run **`/dev-loop:configure`** to set these up interactively (it maps your wiki,
+test command, etc. and writes the file). The legacy `loop-orchestrator` paths
+(`~/.claude/loop-orchestrator/tools.json`, `<repo>/.loop-orchestrator/tools.json`)
+are still read as a fallback.
+
+- **per-user** (`~/.claude/dev-loop/tools.json`) — your machine's tools,
+  applied across every project.
+- **per-repo** (`<repo>/.dev-loop/tools.json`) — commit it to share a
   team-standard mapping; overrides your per-user file.
 - Merge is **per role and per field**: a per-repo file can override one role — or
   one field of a role — and inherit the rest. To drop an inherited value, set that

scripts/resolve-tools.sh

@@ -1,8 +1,12 @@
 #!/bin/sh
-# resolve-tools.sh — resolve the loop-orchestrator tool profile by layering
+# resolve-tools.sh — resolve the dev-loop tool profile by layering
 # config files over built-in defaults (git-config style precedence):
 #
-#   built-in defaults  <  ~/.claude/loop-orchestrator/tools.json  <  <repo>/.loop-orchestrator/tools.json
+#   built-in defaults  <  ~/.claude/dev-loop/tools.json  <  <repo>/.dev-loop/tools.json
+#
+# (The old loop-orchestrator paths — ~/.claude/loop-orchestrator/tools.json and
+#  <repo>/.loop-orchestrator/tools.json — are still read as a fallback so existing
+#  configs keep working after the rename.)
 #
 # Each capability role (intake / knowledge / tacit / verify / explore /
 # design, plus any custom role) is merged independently and field-wise, so a project file can
@@ -19,10 +23,11 @@
 #   resolve-tools.sh --role verify # print just the resolved object for one role
 #
 # env overrides (mainly for tests / non-standard layouts):
-#   LOOP_ORCH_CONFIG_HOME     per-user config path
-#                             (default: ~/.claude/loop-orchestrator/tools.json)
-#   LOOP_ORCH_CONFIG_PROJECT  per-repo config path
-#                             (default: <git-root-or-PWD>/.loop-orchestrator/tools.json)
+#   DEV_LOOP_CONFIG_HOME      per-user config path
+#                             (default: ~/.claude/dev-loop/tools.json)
+#   DEV_LOOP_CONFIG_PROJECT   per-repo config path
+#                             (default: <git-root-or-PWD>/.dev-loop/tools.json)
+#   LOOP_ORCH_CONFIG_HOME / LOOP_ORCH_CONFIG_PROJECT — legacy fallbacks (still honored)
 set -eu
 
 JQ=$(command -v jq) || { echo "resolve-tools: jq not found" >&2; exit 127; }
@@ -38,12 +43,34 @@ DEFAULTS='{
   "design":    {"kind":"default","when":"visual/UI spec for FE/UI tasks, e.g. a Figma link in the issue — read the referenced design before implementing (orchestrate Phase 0/2; loop-implement step 1)"}
 }'
 
-home_cfg="${LOOP_ORCH_CONFIG_HOME:-$HOME/.claude/loop-orchestrator/tools.json}"
-if [ -n "${LOOP_ORCH_CONFIG_PROJECT:-}" ]; then
+# Per-user config: explicit env wins; else the dev-loop path; else the legacy
+# loop-orchestrator path if it exists; else the canonical dev-loop path.
+if [ -n "${DEV_LOOP_CONFIG_HOME:-}" ]; then
+  home_cfg="$DEV_LOOP_CONFIG_HOME"
+elif [ -n "${LOOP_ORCH_CONFIG_HOME:-}" ]; then
+  home_cfg="$LOOP_ORCH_CONFIG_HOME"
+elif [ -f "$HOME/.claude/dev-loop/tools.json" ]; then
+  home_cfg="$HOME/.claude/dev-loop/tools.json"
+elif [ -f "$HOME/.claude/loop-orchestrator/tools.json" ]; then
+  home_cfg="$HOME/.claude/loop-orchestrator/tools.json"
+else
+  home_cfg="$HOME/.claude/dev-loop/tools.json"
+fi
+
+# Per-repo config: same precedence, resolved against the repo root.
+if [ -n "${DEV_LOOP_CONFIG_PROJECT:-}" ]; then
+  proj_cfg="$DEV_LOOP_CONFIG_PROJECT"
+elif [ -n "${LOOP_ORCH_CONFIG_PROJECT:-}" ]; then
   proj_cfg="$LOOP_ORCH_CONFIG_PROJECT"
 else
   root=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
-  proj_cfg="$root/.loop-orchestrator/tools.json"
+  if [ -f "$root/.dev-loop/tools.json" ]; then
+    proj_cfg="$root/.dev-loop/tools.json"
+  elif [ -f "$root/.loop-orchestrator/tools.json" ]; then
+    proj_cfg="$root/.loop-orchestrator/tools.json"
+  else
+    proj_cfg="$root/.dev-loop/tools.json"
+  fi
 fi
 
 # Load a layer as compact JSON; warn + skip if missing/invalid (fail-open to {}).

skills/configure/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: configure
+description: Set up dev-loop's capability-role tool profile — map `knowledge` (your domain wiki / MCP), `verify` (your project's test/build/QA command), `explore` (code search), `tacit` (past incidents), and `design` (Figma/visual spec) to the actual tools this environment has, then write ~/.claude/dev-loop/tools.json (global) or <repo>/.dev-loop/tools.json (per-repo). Use when asked to "configure dev-loop", "set up tools", "map my wiki/test command", or "/dev-loop:configure".
+---
+
+# configure — set up the dev-loop tool profile
+
+dev-loop runs fully generic with **no** config (every role falls back to the
+model's own behavior). Configuring the roles makes the loop use *your* real tools:
+your domain wiki for facts, your actual test command for verification, etc. The
+bundled best-practice `wiki/` (used by `wiki-plan`) needs no config — the
+`knowledge` role is for a separate *external/domain* wiki.
+
+> Note: the plan step is fixed to `wiki-plan` and is NOT configurable. There is no
+> `plan` role.
+
+## Steps
+
+1. **Show the current profile.** Run and report what is already set vs. default:
+   ```sh
+   sh ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-tools.sh --summary
+   ```
+
+2. **Decide scope.**
+   - **Global** (all your projects): `~/.claude/dev-loop/tools.json`
+   - **Per-repo** (committed, team-shared; overrides global per role/field):
+     `<repo>/.dev-loop/tools.json`
+   Ask the user which, if unclear. (Legacy `~/.claude/loop-orchestrator/tools.json`
+   and `<repo>/.loop-orchestrator/tools.json` are still read as a fallback.)
+
+3. **Map each role to a real tool.** Read `${CLAUDE_PLUGIN_ROOT}/examples/tools.example.json`
+   as the shape and `references/tool-profile.md` for the schema. For THIS
+   environment, detect and propose concrete mappings, then confirm with the user:
+
+   | Role | Map to | How to find it |
+   |------|--------|----------------|
+   | `knowledge` | your domain/policy **wiki** or knowledge MCP | check available MCP servers (e.g. a `wiki_search`/`search_wiki` tool) |
+   | `verify` | your project's **test / build / QA** command | read `package.json` scripts / Makefile / `pom.xml` / CI config for the real command |
+   | `explore` | code/symbol search (LSP, `rtb-sourcecode`, ripgrep) | what this repo/language supports |
+   | `tacit` | past incidents / danger-zone lore (MCP) | check for a lore/incidents MCP |
+   | `design` | Figma / visual-spec MCP | only if UI work; check for a Figma MCP |
+   | `intake` | issue tracker (orchestrate work-list) | Jira/GitHub issues MCP, if used |
+
+   Leave any role the user has no tool for as `default` (omit it).
+   `kind` is one of `mcp | skill | agent | cli | default`; add `ref`, and
+   optionally `how` (invocation hint) and `when` (a one-line trigger).
+
+4. **Write the file** for the chosen scope, e.g. global:
+   ```jsonc
+   // ~/.claude/dev-loop/tools.json
+   {
+     "knowledge": { "kind": "mcp", "ref": "<your-wiki-mcp>", "how": "search -> read", "when": "domain facts, policy, code values" },
+     "verify":    { "kind": "cli", "ref": "<your test/build command>", "how": "run only; report failures verbatim", "when": "step 5 — running tests" }
+   }
+   ```
+   Include only the roles being set; unset roles inherit `default`. For `verify`,
+   map the **exact** command (e.g. `pnpm -w test`, `./gradlew test`) — verified by
+   reading the project's build config, not guessed.
+
+5. **Validate.** Re-run `resolve-tools.sh --summary` and confirm each role now
+   resolves as intended (not `default` where you set it). Report the final profile.
+
+## Guardrails
+- Never map `verify` (or any role) to a tool that runs its own implement/fix/retry
+  loop — a role is injected into ONE loop step, never a nested loop (see
+  `references/tool-profile.md`). `verify` must run tests and report only.
+- Do not invent MCP/tool names — only map tools you confirmed exist in this
+  environment. If unsure, leave the role `default` and say so.
+- Never write secrets/tokens into tools.json; reference tools by name only.