@widnyana/design-thinking 0.0.20 → 0.1.0

package/GUIDE.md

@@ -0,0 +1,233 @@
+# design-thinking: guide, tips, and tricks
+
+This guide covers the Claude Code plugin and the pi / omp package. They share the
+same methods, references, and commands. Where the two harnesses behave differently,
+the section says so.
+
+## The idea in one paragraph
+
+Draw the graph before you write the code. Nodes are functions (or screens, or
+agent tasks), edges are what flows between them, and every failure path gets a
+name. Then the code must match the graph. If it does not, one of the two is
+wrong, and a review can show which one.
+
+The method comes from r17x's gist:
+https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a
+
+## Pick the right method
+
+| You are working on | Method | Shape | Where it shows up |
+|---|---|---|---|
+| Code: a feature, a fix, a refactor | Design Thinking | `X → Graph → Effect<A, E, R>` | `/cg`, `/cg-plan`, `/cg-review`, `/cg-map`, `/dt` |
+| An interface: screens, flows, components | Design Graph | `Job → Flow → Surface<C, V, N>` | `/cg-plan` and `/cg-review` switch to it for interface tasks |
+| Work split across subagents or workers | Graph Protocol | `X → Graph → Delegation<A, E, R>` | `/cg-plan` adds it when a task needs more than one worker |
+| A research topic | Meta Research Prompt Generator | waves of research, review, index, synthesis agents | `/research-prompt` |
+
+The letters mean the same thing in every method:
+
+- **A (or C)**: what flows on the happy path.
+- **E (or V)**: every way it breaks (or every way the content can be missing).
+- **R (or N)**: what each node needs before it can run (or before a screen can show).
+
+## Commands at a glance
+
+| Command | Use it when |
+|---|---|
+| `/dt` | You want every plan and review in this session drawn as a graph first. Bare `/dt` toggles. `/dt on`, `/dt off`, `/dt status` set or show it. |
+| `/dt <prompt>` | You want to start a task with the mode on. It turns the mode on (never off) and runs the prompt. |
+| `/cg <module or task>` | You want to see how existing code flows, or sketch the flow of a new task. |
+| `/cg-plan <task>` | You are about to build something and want the design agreed first. |
+| `/cg-review [target]` | You finished a change and want to check the code against its graph. No target means the current `git diff`. |
+| `/cg-map <language or framework>` | The stack is new to you, or to the agent, and you want the markers mapped to its idioms first. |
+| `/research-prompt <topic>` | You want a multi-agent research run on a topic. |
+
+Claude Code: if another plugin has a command with the same name, use the full name,
+for example `/design-thinking:cg-plan`.
+
+## A normal working loop
+
+1. `/dt on` at the start of a session where real design decisions happen.
+2. `/cg-map <stack>` once per stack, only if the stack vocabulary is unclear.
+3. `/cg-plan <task>`. Read the graph. Push back on the graph, not on the code.
+4. Approve (see "How approval works" below). The agent implements to match the graph.
+5. `/cg-review` on the diff. It rebuilds the graph the code really implements and
+   compares it with the plan.
+6. `/dt off` when you are done.
+
+## How approval works
+
+**pi and omp** have a mechanical gate. While `/dt` is on and nothing is approved,
+file edits, shell commands, and code execution are blocked. Read-only tools still
+work. When a run ends with a graph, a dialog opens:
+
+- **Approve**: the gate opens and implementation starts at once.
+- **Refine**: you type feedback, the agent updates the graph, and the dialog opens again.
+- **Deny**: everything stays blocked until a new graph is shown.
+
+The approval covers one instruction from you. When you send a new message, the gate
+closes again and the agent folds your message into the existing graph. Sessions
+with no UI use `/dt approve` and `/dt deny` instead.
+
+**Claude Code** has no mechanical gate. The mode is a rule the agent follows: graph
+and questions first, no edits until you say go. Say "approved" or "go ahead" in
+plain words.
+
+## Reading a graph quickly
+
+Read these sections first. They catch most problems:
+
+1. **PROBLEM**: one line. If it is vague, stop and fix it before anything else.
+2. **GRAPH**: follow the arrows. Every arrow should carry something you can name.
+3. **VERDICT**: does it say what the code must satisfy, or name the mismatches?
+
+The markers:
+
+| Marker | Meaning |
+|---|---|
+| `⟳retry[×n]` | transient failure, try again |
+| `↯escape(alt)` | recoverable, return an alternative |
+| `☠die` | a bug or broken invariant, not a domain error |
+| `🔒 x → y` | untrusted data becomes trusted here, and only here |
+| `(1)` `(N)` `(T)` | runs once, many values over time, valid for a time window |
+| `⛈ name` | a layer that wraps the node (logging, retry policy) without changing it |
+| `@scope` | where a resource is acquired and released |
+
+Red flags worth a comment before you approve:
+
+- A failure with no marker. Someone will swallow it later.
+- `☠die` on something a user can cause. That is a domain error, not a bug.
+- Validation in the middle of the graph instead of at a `🔒` edge.
+- TEST LAYERS that needs a mock of half the world. The node does too much.
+- A `(N)` node drawn as `(1)`, for example a paginated API treated as one call.
+
+## Tips for `/cg`
+
+- Name a real entry point: `/cg src/http/router.ts` or `/cg "what happens on POST /orders"`.
+  A vague target gives a vague graph.
+- Every node in a trace comes with `path:line` under `src:`. If a line is missing or
+  wrong, ask the agent to verify it. The format forbids guessed paths.
+- The **Tests** section appears only when the test wiring differs from production.
+  That difference is exactly what the tests swap out, so read it.
+- A plain fact question ("what port does X use") gets a plain answer, no graph.
+
+## Tips for `/cg-plan`
+
+- Give the task with its constraints: `/cg-plan add per-user rate limit, Redis is already a dependency, 429 with Retry-After`.
+- Interface tasks get the Design Graph skeleton (JOB, SURFACES, FLOW, VOID, NEEDS,
+  ATTENTION, PROOF). Check the VOID section: empty, loading, partial, error, and
+  denied each need a design, not a default.
+- A small task stops after the graph. A task with two or more independent parts
+  gets a delegation plan: a DELEGATED GRAPH with waves and one AGENT SUBGRAPH per
+  node. Each worker then returns a RETURN block, and the agent ends with an
+  IMPLEMENTED GRAPH that lists OFF-SCRIPT work and GAPS.
+- Nodes that touch the same files never run in the same wave. If you see that, the
+  plan is wrong.
+- Keep the plan graph in the session. `/cg-review` compares against it.
+
+## Tips for `/cg-review`
+
+- Run it with no argument right after implementation: it reviews `git diff`.
+- Point it at one module when the diff is large: `/cg-review src/billing/`.
+- Findings are grouped by § number (1 to 10). §2 (tangled happy path) and §4
+  (unhandled breaks) are usually the ones that cause incidents.
+- For delegated work, give it the delegated graph and the workers' RETURN blocks.
+  It compares each subgraph with what was really built.
+
+## Tips for `/cg-map`
+
+- Run it once per stack and keep the answer in the session. Later plans and reviews
+  reuse the vocabulary.
+- Good inputs are specific: `/cg-map rust tokio axum`, `/cg-map python fastapi sqlalchemy`.
+
+## `/research-prompt`: research runs
+
+It is a two-step tool, as r17x designed it. Step one writes a prompt file and prints
+one command. Step two is you running that command. The generator never starts the
+research itself, so you can read the prompt before many agents spend tokens on it.
+
+```
+/research-prompt nix store
+REFS: ./docs/prior-research.md, https://nixos.org/manual
+Focus on garbage collection internals and binary cache trust model.
+```
+
+Input fields, in any order after the first line:
+
+- `NAME: <kebab-case>`: the project name. Without it, the first plain line becomes the name.
+- `REFS: a, b`: files or URLs the researchers read first. Bare `./`, `/`, `~/`, or `http` tokens count too.
+- `DEPENDS_ON: name1, name2`: earlier research projects to build on.
+- Any other text: context that focuses the topics.
+
+Everything lives under `./research/` in the directory where you run it:
+
+```
+./research/
+  projects/<NAME>/.<NAME>.research.prompt   the coordinator prompt
+  projects/<NAME>/RESEARCH.md               the final document
+  scratch/                                   per-node working files
+  ref/INDEX.md, ref/<repo>/, ref/<file>     cloned repos and downloaded specs
+```
+
+Tips:
+
+- Run the printed command from the same directory. All paths in the prompt are relative.
+- Claude Code prints a `claude -p ... --allowedTools ...` line. pi prints `pi --mode json -p ...`,
+  omp prints `omp --mode json -p ...`. pi needs a subagent tool installed for the parallel waves.
+- The run streams JSON events so you can see it working. Without the streaming flag
+  (`--output-format stream-json` on Claude Code, `--mode json` on pi/omp), print mode
+  stays silent until the very end. A quieter way to watch progress from a second
+  terminal: `ls -lt research/scratch research/ref`. Scratch files appear when each
+  node finishes, so an empty `scratch/` early in wave 1 is normal.
+- Run it in a scratch or research directory, not inside a code repo you care about:
+  `research/ref/` gets full `git clone` copies, and code indexers will pick them up.
+- No model is pinned. Add `--model <name>` to the printed line if you want a specific one.
+- Interrupted run: run `/research-prompt` again with the same NAME. It lists which
+  nodes are COMPLETE or MISSING and prints a resume command. Finished nodes are
+  skipped.
+- Finished project: the same NAME is refused. Build on it with
+  `DEPENDS_ON: <NAME>` under a new name.
+- Add `research/scratch/` and `research/ref/` to `.gitignore` unless you want cloned
+  repos in your history. `research/projects/*/RESEARCH.md` is the part worth keeping.
+- pi with `/dt` on: the prompt file write goes through the approval gate. Approve it,
+  or `/dt off` first.
+
+## Harness differences
+
+| | Claude Code | pi / omp |
+|---|---|---|
+| Install | `/plugin install design-thinking@eyay-toolkits` | `pi install npm:@widnyana/design-thinking` or `omp install npm:@widnyana/design-thinking` |
+| `/dt` state | `.claude/design-thinking.local.md` in the project, re-announced at session start | kept in the session; shown in the status bar |
+| Edits before approval | rule only | blocked mechanically, dialog to approve |
+| Specs the agent reads | the `design-thinking`, `design-graph`, `graph-protocol` skills and `references/` | the package `references/` directory (absolute path injected while `/dt` is on) |
+| LSP reminder | no | yes, always on: use the language server when the session has one |
+
+Claude Code: add `.claude/*.local.md` to `.gitignore`. It is per-user state.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| pi: every edit is blocked | `/dt` is on and nothing is approved. Approve in the dialog, or `/dt off`. |
+| pi: no dialog appears | The run did not end with a graph (it needs VERDICT plus at least three other sections), or the session has no UI. Use `/dt approve`. |
+| pi: `pi -p "/research-prompt ..."` writes nothing | Print mode runs the slash command and exits before the queued message runs. Use an interactive session (or RPC mode). |
+| Claude Code: mode lost after restart | Check `.claude/design-thinking.local.md` says `enabled: true`. The hook reads it at session start. |
+| Graph uses a header like `DesignGraph<A, E, R>` | Old version. Update: the current header is `X → Graph → Effect<A, E, R>`. |
+| `/research-prompt` says the prompt already exists | A run was started before. Use the printed resume command, or pick a new NAME. |
+| The agent writes prose instead of a graph | Ask for "the full output format". Specs: `references/output-format.md`. |
+
+## When not to use it
+
+- One-line fixes, typos, renames, config value changes. Prose is fine.
+- Questions with a single fact as the answer.
+- Throwaway spikes you will delete. Draw the graph when the spike becomes real code.
+
+## Where the specs live
+
+All in the package's `references/` directory:
+
+- `design-thinking.md`: the code method, §1 to §10.
+- `output-format.md`: sections, markers, call graph block, completeness checklist.
+- `design-graph.md`: the interface method and its skeleton.
+- `graph-protocol.md`: delegation, AGENT SUBGRAPH, RETURN, IMPLEMENTED GRAPH.
+- `meta-research.md`: the research prompt generator.
+- `effect-ts.md`: the original Effect-TS version, for attribution.

package/README.md

@@ -5,7 +5,7 @@ AI coding agents ship code before asking what breaks. This extension flips the
 order: with `/dt` active, [pi](https://pi.dev) draws the call graph first —
 nodes are functions, edges are data flow, every failure path is named — then
 writes code that *is* the graph. Plans, reviews, and refactors render in a
-fixed, mechanically checkable notation (Graph Protocol) that looks the same in
+fixed, mechanically checkable notation that looks the same in
 Go, Rust, Python, or TypeScript.
 
 Method by [r17x](https://github.com/r17x) ([Design Thinking
@@ -23,7 +23,7 @@ the error, retry silently, drop the request) nobody agreed to, or the
 reviewer approves a plan that was never specific enough to catch the
 mismatch once the code lands.
 
-Design Graph replaces the prose plan with something that can be diffed.
+The graph replaces the prose plan with something that can be diffed.
 Nodes are functions, edges are data and error/escape paths, boundaries are
 named — fixed before code exists. `/cg-review` then reconstructs the graph
 the code actually implements and diffs it against the one that was planned,
@@ -33,6 +33,35 @@ Go, Rust, Python, or TypeScript, so the check doesn't depend on the stack.
 Skip it for a one-line fix — prose is fine there. Reach for `/dt` when the
 change has a failure path worth agreeing on before it's written.
 
+Guides, tips, and troubleshooting: [GUIDE.md](GUIDE.md).
+
+## Three methods, one shape
+
+From r17x's gist: the same three-channel discipline, applied to three materials.
+
+| Method | Shape | Nodes / edges | Use for |
+|---|---|---|---|
+| Design Thinking | `X → Graph → Effect<A, E, R>` | functions / data flow | code: plans, reviews, refactors |
+| Design Graph | `Job → Flow → Surface<C, V, N>` | surfaces / the moves between them | interfaces: screens, flows, components |
+| Graph Protocol | `X → Graph → Delegation<A, E, R>` | tasks / data dependencies | splitting work across subagents: AGENT SUBGRAPH in, IMPLEMENTED GRAPH out |
+
+Plus r17x's **Meta Research Prompt Generator** (from the gist comments) as
+`/research-prompt`: one topic line in, one research coordination prompt file
+and the command to run it out. Its waves of research, review, index, and
+synthesis agents each get an AGENT SUBGRAPH. All its files live under
+`./research/` in the directory where you run it:
+
+```
+./research/
+  projects/<NAME>/.<NAME>.research.prompt   the coordinator prompt
+  projects/<NAME>/RESEARCH.md               the final document
+  scratch/n1_<slug>.md, r1_review_<slug>.md per-node working files
+  ref/INDEX.md, ref/<repo>/, ref/<file>     cloned repos and downloaded specs
+```
+
+Add `research/scratch/` and `research/ref/` to `.gitignore` if you do not want
+them committed.
+
 ## Install
 
 ```bash
@@ -43,7 +72,7 @@ pi install npm:@widnyana/design-thinking
 omp install npm:@widnyana/design-thinking
 
 # pinned version
-pi install npm:@widnyana/design-thinking@0.0.19
+pi install npm:@widnyana/design-thinking@0.1.0
 
 # from a local checkout of this repo
 pi install /absolute/path/to/pi-packages/design-thinking
@@ -63,15 +92,18 @@ pi -e ./pi-packages/design-thinking
 
 | Command | What it does |
 |---|---|
-| `/dt` | Toggle Design Thinking mode. While on, plans and reviews render as Design Graphs. Persists across restarts. |
+| `/dt` | Toggle Design Thinking mode. While on, plans and reviews render as annotated call graphs. Persists across restarts. |
 | `/dt on\|off\|status` | Set or query the mode explicitly. |
 | Review dialog | When a run ends with a presented Design Graph — or the agent asks for approval in prose — a dialog opens automatically (arrow keys + Enter or mouse), **never mid-run**: **Approve** arms the gate (file edits, shells, code execution) **and** sends the go-ahead so implementation starts immediately, **Refine** asks for feedback and sends it back to the agent (the dialog re-opens after the updated graph), **Deny** keeps everything blocked until a new Design Graph is presented (a Deny latches — it won't re-prompt on every run end). Headless/no-UI sessions fall back to manual `/dt approve\|deny`. While unapproved, `write`, `edit`, `bash`, and code-execution tools are blocked outright — read-only exploration keeps `read`/`grep`/`glob`, plus read-only MCP lookups (qmd, codegraph explore). |
 | LSP reminder | Always-on, independent of `/dt`: while the harness has an `lsp` tool (omp with LSP enabled — default), every run gets a short `LSP FIRST` block — use the language server for definitions/references/renames/diagnostics, never hand-grep or hand-edit renames; if the project has no configured server, the agent tells you once per session how to enable one. Without an `lsp` tool, you get one notification per session **with a UI** (omp: enable it or add a server; pi: pi has no LSP integration) — headless/no-UI sessions get none. |
 | `/dt <prompt>` | Turn the mode **on** (never off), then run `<prompt>` under it — graph and clarifying questions first, implementation after your go-ahead. |
 | `/cg <module \| task>` | Generate a call graph: extract the graph existing code implements, or sketch one for a task. |
-| `/cg-plan <task>` | Design before code — full Design Graph, then implement to match it. |
+| `/cg-plan <task>` | Design before code: full graph, then (when the task needs several workers) a Graph Protocol delegation plan with one AGENT SUBGRAPH per node, then implement and compare. |
 | `/cg-review [file\|module\|diff]` | Reconstruct the implemented graph, diff it against the method's checklist, end with a VERDICT. |
-| `/cg-map <language\|framework>` | Map the Protocol vocabulary onto a stack's idioms (Result vs exceptions, RAII vs defer). |
+| `/cg-map <language\|framework>` | Map the Design Thinking vocabulary onto a stack's idioms (Result vs exceptions, RAII vs defer). |
+| `/research-prompt <topic>` | Meta Research Prompt Generator: writes `./research/projects/<NAME>/.<NAME>.research.prompt` and prints the `claude -p` / `pi --mode json -p` / `omp --mode json -p` command that runs it. Fields: `NAME:`, `REFS:`, `DEPENDS_ON:`, free-text context. |
+
+With `/dt` on, the file `/research-prompt` writes goes through the approval gate like any other edit: approve it in the review dialog, or run `/dt off` first.
 
 ## A real-world walkthrough
 
@@ -81,7 +113,7 @@ Task: *add rate limiting to an Express API.* One design pass, end to end:
 > /dt                                        # mode on — graph-first rules injected
 
 > /cg-plan add per-user rate limiting to the API
-    → agent sketches a DesignGraph first (SHAPES, GRAPH, E, boundaries),
+    → agent sketches the graph first (SHAPES, GRAPH, E, boundaries),
       then implements code that matches it
 
 > /cg-map nodejs                             # optional: before planning, when the
@@ -107,6 +139,6 @@ flowchart LR
     P --> C[implement] --> R["/cg-review <file>"] --> O["/dt off"]
 ```
 
-Skills (`graph-protocol`, `design-method`, `design-graph`) are loaded by the
+Skills (`design-thinking`, `design-graph`, `graph-protocol`) are loaded by the
 agent on demand mid-turn — you never invoke them directly; the `/cg*` prompts
 and `/dt` mode tell the model when to reach for them.

package/extensions/design-thinking.ts

@@ -1,24 +1,25 @@
 /**
  * Design Thinking — pi extension
  *
- * Adopts the three pillars:
- *   - Design Thinking : the mindset (§1–§10 pipeline, problem-first)
- *   - Design Graph    : the artifact (annotated call graph of a concrete problem)
- *   - Graph Protocol  : the notation spec (fixed sections, fixed markers)
+ * Adopts r17x's three methods (one shape, three materials):
+ *   - Design Thinking : code, X → Graph → Effect<A, E, R> (§1-§10 pipeline)
+ *   - Design Graph    : interface, Job → Flow → Surface<C, V, N>
+ *   - Graph Protocol  : delegation, AGENT SUBGRAPH in, IMPLEMENTED GRAPH out
  *
  * When /dt mode is active, every turn appends a compact distilled block to the
- * system prompt so design/plan/review answers render as Design Graphs in
- * Graph Protocol form. Full specs live in the package's references/ directory,
+ * system prompt so design/plan/review answers render as an annotated call
+ * graph in the Design Thinking output format. Full specs live in the package's references/ directory,
  * loaded on demand — not inlined here, to keep the injected prompt small.
  * Separately, an ALWAYS-ON LSP reminder composes into every run's system
  * prompt while the harness exposes an `lsp` tool (mode-independent); without
  * one, the user is told once per session how to enable it.
  *
  * Commands:
+ *   /research-prompt <msg>  Meta Research Prompt Generator (references/meta-research.md)
  *   /dt            toggle Design Thinking mode
  *   /dt on|off     set explicitly
  *   /dt approve|deny  manual arm/revoke fallback (headless / no-UI sessions)
- *   After a gated run presents a Design Graph, a review dialog opens
+ *   After a gated run presents a design graph, a review dialog opens
  *   automatically: Approve (arm + implement), Refine (send feedback), or
  *   Deny (keep file edits blocked). /dt <prompt> turns the mode ON (never
  *   off) and runs the prompt — graph + clarifying questions before code.
@@ -36,7 +37,7 @@
  *     decision is applied only if its epoch is still current AND the gate is
  *     still on AND still unapproved. Stale decisions are discarded, not
  *     applied.
- *   - The dialog opens at run end when the agent presented a Design Graph
+ *   - The dialog opens at run end when the agent presented a design graph
  *     (VERDICT + section headers) OR ended the turn asking for approval in
  *     prose — the human always gets a button, never a prose-only ask.
  *   - Dialogs are opened with an extension-owned AbortSignal: omp binds
@@ -52,6 +53,7 @@
  * to whatever stack the project uses; never the discipline.
  */
 
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -77,7 +79,7 @@ const DISTILLED = `
 DESIGN THINKING MODE — active.
 Read the problem. Draw the data flow as a call graph. Write code that IS the graph.
 
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ R: what each node needs      (§5)
 │              │   │  └──── E: where the graph breaks    (§4)
@@ -93,7 +95,7 @@ Pipeline: shapes → graph(A) → cardinality → E(⟳retry ↯escape ☠die)
 Rules:
 - ANY turn that will end in code or file changes (feature, change, fix,
   refactor — the model does NOT get to reclassify the request): render the
-  Design Graph in Graph Protocol form and any clarifying questions FIRST;
+  graph in the Design Thinking output format and any clarifying questions FIRST;
   ZERO mutations until the user approves the design — no file edits, no
   shell commands, no code execution. Reading/exploring code first is fine,
   via read-only tools only (read/grep/glob; read-only MCP devices such as
@@ -105,25 +107,29 @@ Rules:
   when the run ends — never mid-run: approve (implement the presented design
   without re-presenting the graph), refine (present an updated graph), or
   deny (stay blocked).
-- Design, plan, and review answers must render a Design Graph — fixed
+- Design, plan, and review answers must render the graph, fixed
   sections: PROBLEM, SHAPES, GRAPH, CARDINALITY, BOUNDARIES, BEHAVIOR, SCOPE,
   TEST LAYERS, VERDICT.
 - The happy path (A) stays readable; failure handling lives at defined join points.
 - Each layer scopes its own E; inner errors never leak through.
 - If the code doesn't match the call graph, the implementation is wrong.
 - Adapt vocabulary to the current language/stack; never the discipline.
+- Interface work uses the Design Graph (Surface<C, V, N>) skeleton.
+- Delegating to subagents or workers follows Graph Protocol: AGENT SUBGRAPH
+  in, IMPLEMENTED GRAPH out, compared before the work counts as done.
 
 Full specs — read these when a section needs detail:
-- ${REF_DIR}/protocol.md      (Graph Protocol: notation spec + worked example)
-- ${REF_DIR}/method.md        (the §1–§10 method, generalized)
-- ${REF_DIR}/design-graph.md  (the artifact spec + completeness checklist)
+- ${REF_DIR}/design-thinking.md  (the code method, §1-§10)
+- ${REF_DIR}/output-format.md    (sections, markers, call graph block, checklist)
+- ${REF_DIR}/design-graph.md     (the interface method + skeleton)
+- ${REF_DIR}/graph-protocol.md   (delegation: execution graph, AGENT SUBGRAPH, RETURN)
   The extension blocks file edits, shells (bash/powershell), and code
   execution (eval) mechanically until the user approves — a review dialog
   opens when a graph-presenting run ends. Approval covers
   ONE human turn: it stays armed across the many runs it takes to implement
   the approved design, and drops the moment the user sends a new instruction.
   Treat that next instruction as a refinement of the current design: UPDATE
-  the existing Design Graph to fold it in and re-present it (do not start a
+  the existing design graph to fold it in and re-present it (do not start a
   blank graph unless the goal itself changed), then end the turn and wait for
   the dialog. /dt deny or mode off also re-lock.
   NEVER ask the user to run /dt approve, /dt deny, or any approval command:
@@ -177,7 +183,7 @@ interface DtState {
 
 
 const GATE_REASON =
-	"Design Thinking mode is ON: file edits, shell commands, and code execution are blocked until the user approves the presented design. Do NOT attempt this change through any other channel — no bash or shell commands, no eval/scripts, no subagent delegation. Explore with read-only tools (read/grep/glob), present (or update and re-present) the Design Graph (Graph Protocol), then END YOUR TURN with NO prose approval request — an approval dialog opens for the user automatically when the run ends. NEVER ask the user to run /dt approve, /dt deny, or any command; NEVER re-attempt the blocked action this turn.";
+	"Design Thinking mode is ON: file edits, shell commands, and code execution are blocked until the user approves the presented design. Do NOT attempt this change through any other channel — no bash or shell commands, no eval/scripts, no subagent delegation. Explore with read-only tools (read/grep/glob), present (or update and re-present) the design graph, then END YOUR TURN with NO prose approval request — an approval dialog opens for the user automatically when the run ends. NEVER ask the user to run /dt approve, /dt deny, or any command; NEVER re-attempt the blocked action this turn.";
 
 const REVIEW_OPTIONS = [
 	"Approve — implement now",
@@ -210,12 +216,12 @@ const LSP_SUGGESTION_OMP =
 const LSP_SUGGESTION_PI =
 	"LSP Reminder: pi has no LSP integration — code intelligence falls back to text search. omp provides a built-in `lsp` tool.";
 
-// Graph Protocol section headers. A real Design Graph renders the fixed set;
+// Output-format section headers (code and interface skeletons). A real graph renders the fixed set;
 // VERDICT is mandatory. Requiring VERDICT + ≥3 others avoids tripping on a bare
 // mention of the word "verdict" in prose, and still fires on a graph rendered
 // without that exact literal elsewhere.
 const SECTION_HEADER =
-	/^[ \t]*#{0,4}[ \t>*-]*(PROBLEM|SHAPES|GRAPH|CARDINALITY|BOUNDARIES|BEHAVIOR|SCOPE|TEST LAYERS|VERDICT)\b/gm;
+	/^[ \t]*#{0,4}[ \t>*-]*(PROBLEM|SHAPES|GRAPH|CARDINALITY|BOUNDARIES|BEHAVIOR|SCOPE|TEST LAYERS|JOB|SURFACES|FLOW|VOID|NEEDS|BOUNDARY|ATTENTION|PROOF|VERDICT)\b/gm;
 
 /** The agent is asking the human for a go-ahead in prose — narrow on purpose so
  *  an ordinary closing sentence does not trip it. */
@@ -235,7 +241,7 @@ function messageText(content: unknown): string {
 		.join("\n");
 }
 
-/** Does an assistant message render a Design Graph (Graph Protocol)? */
+/** Does an assistant message render a design graph (code or interface skeleton)? */
 function presentsGraph(message: { role: string; content?: unknown }): boolean {
 	if (message.role !== "assistant") return false;
 	const seen = new Set<string>();
@@ -260,10 +266,10 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 	// "armed" lets mutating tools through. Approval is NOT consumed by runs:
 	// implementing an approved design spans many runs, and re-arming per run
 	// only produced approval loops. It is re-locked by relock() when a new user
-	// instruction arrives, when a NEW Design Graph is presented, by /dt deny, or
+	// instruction arrives, when a NEW design graph is presented, by /dt deny, or
 	// when the mode turns off.
 	let approval: "none" | "armed" = "none";
-	// A Design Graph was presented in the CURRENT design cycle. Reset by
+	// A design graph was presented in the CURRENT design cycle. Reset by
 	// relock() — i.e. when a new user instruction arrives. Approval is scoped to
 	// one human turn: it survives the many runs of implementing an approved
 	// design, and drops the moment the user speaks again (a new goal, or a
@@ -447,7 +453,7 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 			applyStatus(ctx);
 			ctx.ui.notify(
 				on
-					? "Design Thinking ON — plans and reviews will render as Design Graphs (Graph Protocol)"
+					? "Design Thinking ON — plans and reviews will render as annotated call graphs"
 					: "Design Thinking OFF",
 				"info",
 			);
@@ -458,13 +464,35 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 				relock();
 				// deliverAs "steer": sends immediately when idle, queues mid-stream.
 				await pi.sendUserMessage(
-					`${prompt}\n\n(Design Thinking is ON: before implementing, present the Design Graph (Graph Protocol) and any clarifying questions, then wait for my go-ahead.)`,
+					`${prompt}\n\n(Design Thinking is ON: before implementing, present the design graph and any clarifying questions, then wait for my go-ahead.)`,
 					{ deliverAs: "steer" },
 				);
 			}
 		},
 	});
 
+	// ── /research-prompt command ────────────────────────────────────────────
+	// r17x's Meta Research Prompt Generator. The template ships in references/;
+	// pi prompts cannot read package files, so the command reads it and sends
+	// it with the user's message (§6 boundary: file → text, read once here).
+	pi.registerCommand("research-prompt", {
+		description: "Meta Research Prompt Generator: writes ./research/projects/<NAME>/.<NAME>.research.prompt and prints the run command",
+		handler: async (args, ctx) => {
+			let generator: string;
+			try {
+				generator = fs.readFileSync(path.join(REF_DIR, "meta-research.md"), "utf8");
+			} catch (err) {
+				ctx.ui.notify(`research-prompt: cannot read ${REF_DIR}/meta-research.md (${(err as Error).message})`, "error");
+				return;
+			}
+			const harness = isOmp() ? "omp" : "pi";
+			await pi.sendUserMessage(
+				`${generator}\n\n---\n\nYou run inside ${harness}: in step 8 print only the ${harness} command.\n\nUser message:\n${(args ?? "").trim()}`,
+				{ deliverAs: "steer" },
+			);
+		},
+	});
+
 	// ── Run hooks ───────────────────────────────────────────────────────────
 	// A genuine user instruction re-locks the gate: the previous approval covered
 	// the previous turn's work only. Our own go-ahead / refine messages arrive as
@@ -606,7 +634,7 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 			}
 			retractOffer();
 			await pi.sendUserMessage(
-				`Refine the presented design (do not implement yet): ${feedback.trim()}\n\n(Design Thinking: update the Design Graph (Graph Protocol) per this feedback and present it again. Mutations stay blocked.)`,
+				`Refine the presented design (do not implement yet): ${feedback.trim()}\n\n(Design Thinking: update the design graph per this feedback and present it again. Mutations stay blocked.)`,
 				{ deliverAs: "steer" },
 			);
 		})().catch((err: unknown) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@widnyana/design-thinking",
-  "version": "0.0.20",
+  "version": "0.1.0",
   "type": "module",
   "description": "Design Thinking · Design Graph · Graph Protocol — a stack-agnostic design methodology for pi. Turns every plan, review, and refactor into an annotated call graph. Method originally by r17x; generalized to a pi package by widnyana.",
   "author": {
@@ -21,6 +21,7 @@
     "skills",
     "references",
     "README.md",
+    "GUIDE.md",
     "LICENSE"
   ],
   "repository": {

package/prompts/cg-map.md

@@ -1,16 +1,16 @@
 ---
-description: Map the Graph Protocol vocabulary onto a language/framework's concrete idioms
+description: Map the Design Thinking vocabulary onto a language/framework's concrete idioms
 argument-hint: "<language | framework>"
 ---
-Map the Design Graph method onto: $@
+Map the Design Thinking method onto: $@
 
 Produce a vocabulary mapping so the method's three channels (A, E, R) and its
 markers have concrete, idiomatic counterparts in the target stack. Output a
-mapping table followed by a small worked mini-graph in Graph Protocol format.
+mapping table followed by a small worked mini-graph in the Design Thinking output format.
 
 ## Mapping table (required rows)
 
-| Protocol concept | Question to answer for the target stack |
+| Concept | Question to answer for the target stack |
 |---|---|
 | **A** — happy path | Where does the straight-line happy path live? (main fn, do-block, generator pipeline, SQL CTE chain…) |
 | **E** — failure carrying | How are failures values vs control flow? (Result/Either, checked exceptions, error returns, panics+recover, throw at layer joins…) |
@@ -30,11 +30,12 @@ mapping table followed by a small worked mini-graph in Graph Protocol format.
 - Be concrete: name actual libraries, patterns, and syntax idioms of the stack.
 - If the stack lacks a native counterpart for a concept, say so and name the
   closest convention (and its cost).
-- After the table, render a mini Design Graph (PROBLEM → header tree → GRAPH →
+- After the table, render a mini graph (PROBLEM → header tree → GRAPH →
   VERDICT only) for a small example task in this stack, using the mapped
   vocabulary — proving the mapping works end to end.
 - This mapping is a companion artifact: once produced, refer to it in later
   `/cg-plan` and `/cg-review` runs in the same stack.
 
-Full specs live in this package's `references/` directory: `protocol.md`
-(notation), `method.md` (the method), `design-graph.md` (artifact).
+Full specs live in this package's `references/` directory: `design-thinking.md`
+(the code method), `output-format.md` (format + checklist), `design-graph.md`
+(the interface method), `graph-protocol.md` (delegation to agents).