@widnyana/design-thinking 0.0.6 → 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,11 +72,15 @@ pi install npm:@widnyana/design-thinking
 omp install npm:@widnyana/design-thinking
 
 # pinned version
-pi install npm:@widnyana/design-thinking@0.0.1
+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
 
+# via the omp marketplace
+omp plugin marketplace add widnyana/eyay-toolkits
+omp plugin install design-thinking@eyay-toolkits
+
 # try without installing
 pi -e npm:@widnyana/design-thinking
 pi -e ./pi-packages/design-thinking
@@ -59,14 +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. |
-| `/dt approve\|deny` | Arm/revoke file edits for the next agent run — run `approve` after a presented graph to let the implementation run edit, `deny` to re-lock. |
+| 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
 
@@ -76,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
@@ -102,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.