@jkwd/inbase 0.1.9 → 0.1.11

package/skill/inbase/SKILL.md

@@ -2,9 +2,12 @@
 name: inbase
 description: >-
   Grounds source-file changes in the Inbase visual map. Use when creating,
-  editing, or deleting application source files in this repository. Lists every
-  feature step, then works only via patch files. Do not use for git, docs-only,
-  lockfiles, or questions.
+  editing, or deleting application source files in this repository, including
+  when the user chats a change request without /inbase. Direct chat is blocked
+  unless they invoked /inbase or /skipinbase. Lists every feature step, then
+  edits live files after invocation and records each step with inbase
+  propose-patch (no patch file). Do not use for git, docs-only, lockfiles, or
+  questions.
 ---
 
 # Inbase visual edits
@@ -13,41 +16,91 @@ Apply this skill **whenever the work is file changes in this repository**.
 Skip it for git, lockfiles, `.inbase`, `.cursor`, or questions with no code
 changes.
 
-The LLM uses a plan-first loop. It reports the complete plan before writing a
-patch. When **Step by step** is on, it waits for the user to invoke the
-highlighted step, publishes only that step's diff, then waits for **Run step**
-on the following step or an alternative instruction. When **Step by step** is
-off, `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE` for every
-remaining step without the user clicking Run step; after the last patch, wait
-for the user to **Complete**. They can still walk Previous/Next over the diffs.
-Always work via patch files. Do not Write, StrReplace, or Delete project files.
+Sessions start only from the visualizer (**Setup LLM session**). This chat
+cannot open a session.
 
-Every Cursor chat has an explicit session ID. Pass that same ID to every
-command. The visualizer stores immutable diffs under `.inbase/diff-sessions/<session-id>/diffs/`.
+- **`/skipinbase`**: do the user's request without Inbase. Do not attach, wait,
+  or record patches.
+- **`/inbase`**, or this conversation already has a `VISUAL_CODER_SESSION` from
+  `/inbase`: connect if needed, then follow Required sequence. Do not refuse.
+- **Any other file-change request**: do not edit files and do not run Inbase
+  commands. Reply with exactly this line, then **stop**:
 
-Inbase must already be running (`inbase run` or `npx inbase run`). Prefer
-`npx inbase` so the local package is used.
-
-## Required sequence
+```
+direct chat interaction not allowed use /skipinbase [request] to bypass inbase.
+```
 
-1. As soon as this skill applies, start the visual session so the explorer can
-   offer a blueprint handshake. Do this before reading context or listing steps:
+The LLM uses a plan-first loop. It reports the complete plan before editing
+files. When **Step by step** is on, it waits for the user to click **Create
+proposal** on the first step, edits live files for that step, records them with `inbase propose-patch`,
+then waits for **Accept proposal** or an alternative instruction. When **Step
+by step** is off, `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE` for
+every remaining step without the user clicking; after the last recorded step,
+wait for the user to **Accept proposal**. They can still walk Previous/Next
+over the recorded diffs.
+
+**Recorded patches are the session record.** After `VISUAL_CODER_EXECUTE`, edit
+live project files with Write, StrReplace, and Delete for that step only. Then
+run `inbase propose-patch` with no patch file. Inbase diffs the working tree
+against the snapshot taken at invoke and stores that patch. A later instruction
+replaces the withdrawn step; edit from the accepted live files, not from the
+withdrawn proposal. Do not write a unified diff yourself.
+
+The visualizer stores immutable diffs under
+`.inbase/diff-sessions/<session-id>/diffs/`. Inbase must already be running
+(`inbase run` or `npx inbase run`). Prefer `npx inbase` so the local package
+is used.
+
+If this chat is not yet attached, run:
 
 ```bash
-npx inbase start-session --session "<current-cursor-chat-id>"
+npx inbase attach
 ```
 
-2. **Stop and wait for the blueprint handshake**. Do not report a plan and do
-   not write a patch until this prints `VISUAL_CODER_BLUEPRINT_READY`:
+That attaches this chat to the session currently focused in the map. No id is
+passed in; read `VISUAL_CODER_SESSION` from the output and use that
+`--session` value for every later command. Then continue from
+`wait-for-blueprint` below. Do **not** run `start-session`. Do **not** wait
+for a blueprint handshake.
+
+## Direct response
+
+Visualizer signals arrive as `VISUAL_CODER_ACK` from `attach`,
+`wait-for-blueprint`, and `wait-for-approval`. While a wait command is running
+you cannot chat; that process is the listen loop.
+
+The moment a command prints `VISUAL_CODER_ACK`, **reply in this chat first**
+with one short sentence that acknowledges the signal. Echo the ack, for
+example: `Got it — running step 2: Show ColorGenerator on Home.` Then continue
+the required tools in the same turn. Do not wait for the user after the ack.
+Do not start with a long analysis. Do not call tools before that sentence.
+
+After `propose-patch` on a non-final step, the **next tool call must be**
+`wait-for-approval`. Do not explore, search, or re-plan in between. **Accept
+proposal** invokes the next step; when that wait returns `EXECUTE`, implement
+that step immediately. Do not run `wait-for-blueprint` again. Do not report a
+new plan.
+
+## Required sequence
+
+1. **Read the current layout**. `/inbase` already started the session. Run
+   this once to load the optional blueprint and instruction — it returns
+   immediately. Do not wait for the user to send a blueprint. Then report a
+   plan.
 
 ```bash
-npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
+npx inbase wait-for-blueprint --session "<session-id>"
 ```
 
-   The explorer asks **Setup blueprint: Yes vs No**.
-   - **No**: skip placement; continue without user-placed files or islands.
-   - **Yes**: the user places files (`Space`) and islands (`B`), then clicks
-     **Send blueprint**.
+   The user may have placed files (`Space`) and islands (`B`), or left the
+   blueprint empty. That choice is already on the session. They can keep
+   placing on later steps. This chat's blueprint is stored only for this
+   session.
+   If `wait-for-blueprint` prints `VISUAL_CODER_INSTRUCTION_START` /
+   `VISUAL_CODER_INSTRUCTION_END`, that text is the user's request for this
+   session. Plan from that instruction and the blueprint together. The
+   instruction does not override an enabled blueprint; if they conflict,
+   ask the user.
 3. Read the handshake output between `VISUAL_CODER_BLUEPRINT_START` and
    `VISUAL_CODER_BLUEPRINT_END`, or read
    `.inbase/diff-sessions/<session-id>/blueprint.json`.
@@ -73,13 +126,13 @@ npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
    and choose files from the request itself. Viewpoint never overrides the
    blueprint: still follow this session's blueprint when `enabled` is true.
 6. List **all** steps needed to finish the feature. Keep steps small enough that
-   one patch is one landscape change (usually one new file, or a few related
-   edits).
-7. Report the plan before making a diff:
+   one recorded step is one landscape change (usually one new file, or a few
+   related edits).
+7. Report the plan before editing files:
 
 ```bash
 npx inbase report-plan \
-  --session "<current-cursor-chat-id>" \
+  --session "<session-id>" \
   --feature "short feature name" \
   --steps "Add Clock component" \
   --steps "Show Clock on Home"
@@ -88,92 +141,92 @@ npx inbase report-plan \
 8. **Stop and wait for invocation**:
 
 ```bash
-npx inbase wait-for-approval --session "<current-cursor-chat-id>"
-```
-
-   Do not write a patch until this prints `VISUAL_CODER_EXECUTE`. If Step by
-   step is off, this returns immediately for each remaining step.
-9. Implement only the invoked step as a unified diff. Paths are relative to the
-   project root (same ids as `codebase.json`):
-
-```diff
---- /dev/null
-+++ b/src/components/Clock.tsx
-@@ -0,0 +1,5 @@
-+export function Clock() {
-+  return <time>00:00</time>
-+}
-```
-
-```diff
---- a/src/pages/Home.tsx
-+++ b/src/pages/Home.tsx
-@@ -1,3 +1,4 @@
-+import { Clock } from '../components/Clock'
- import { Counter } from '../components/Counter'
+npx inbase wait-for-approval --session "<session-id>"
 ```
 
-   Write that diff to a new `.patch` file, then publish it:
+   Do not edit project files until this prints `VISUAL_CODER_ACK execute` /
+   `VISUAL_CODER_EXECUTE`. If Step by step is off, this returns immediately for
+   each remaining step. First reply in chat acknowledging the ack, then re-read
+   this session's `blueprint.json`; the user can place files and islands on any
+   step.
+9. Implement only the invoked step by editing the live project files (Write,
+   StrReplace, Delete). Paths are the same ids as `codebase.json`. Then record
+   the step — Inbase diffs the working tree against the snapshot taken at
+   invoke:
 
 ```bash
-npx inbase propose-patch \
-  --session "<current-cursor-chat-id>" \
-  /tmp/step.patch
+npx inbase propose-patch --session "<session-id>"
 ```
 
-   The patch path or stdin is required. Never write or replace a patch already
-   stored in the session folder.
+   Do not write a unified diff. Do not pass a `.patch` file. Never write or
+   replace a patch already stored in the session folder.
 
-10. **Stop.** Do not apply the patch and do not edit project files directly.
-11. Wait until the user clicks **Run step** on the next step (or, when Step by
+10. **Stop editing** until the next `VISUAL_CODER_EXECUTE`. The stored patch is
+    the session record; disk already has your edits. Your next tool call is
+    `wait-for-approval` — nothing else.
+11. Wait until the user clicks **Accept proposal** on the current step (or, when Step by
    step is off, until the next step is auto-invoked), sends an alternative
-   instruction, clicks **Complete** on the last step, or stops the workflow:
+   instruction, or stops the workflow:
 
 ```bash
-npx inbase wait-for-approval --session "<current-cursor-chat-id>"
+npx inbase wait-for-approval --session "<session-id>"
 ```
 
-12. Read the wait command output:
+12. Read the wait command output. Reply in chat with the `VISUAL_CODER_ACK`
+    line first, then:
 
-   - Exit `0` (`VISUAL_CODER_EXECUTE`): the highlighted step was invoked. Build
-     only that step, publish its incremental diff with `inbase propose-patch`,
+   - Exit `0` (`VISUAL_CODER_ACK execute` / `VISUAL_CODER_EXECUTE`): the
+     highlighted step was invoked. If this is a later step, implement it now —
+     do not explore, re-plan, or run `wait-for-blueprint`. Re-read this
+     session's `blueprint.json` only if you need placed files. Edit live files
+     for that step only, record with `inbase propose-patch` (no patch file),
      then wait again.
-   - Exit `5` (`VISUAL_CODER_FINISHED`): that was the last step. The visualizer
-     already applied the final patch and removed stored session diffs and
-     blueprint drafts. Optionally run `--clear` if anything remains, tell the
-     user the feature is done, and **stop**. Do not propose another patch.
-   - Exit `4` (`VISUAL_CODER_REPLAN`): do **not** apply files and do not rewrite
-     an earlier diff. Follow the text between
-     `VISUAL_CODER_INSTRUCTION_START` and `VISUAL_CODER_INSTRUCTION_END`, read
-     this session's `blueprint.json` when it is enabled (files, islands,
-     `addedFunctions`, `addedVariables`, `addedImports`). The blueprint stays
-     leading. If the new instruction would differ from it, ask the user before
-     replacing the plan. Read `user-context.json` (follow the viewpoint only if
-     `followLook` is true), replace the plan from the current step onward using
-     `inbase report-plan`, then wait for the user to invoke the first revised
-     step.
-   - Exit `2` (`VISUAL_CODER_STOPPED`) or `3` (timeout): make no further
-     project changes.
+   - Exit `5` (`VISUAL_CODER_ACK finished` / `VISUAL_CODER_FINISHED`): that was
+     the last step. The visualizer already applied the final patch and removed
+     stored session diffs and blueprint drafts. Optionally run `--clear` if
+     anything remains, tell the user the feature is done, and **stop**. Do not
+     propose another patch.
+   - Exit `4` (`VISUAL_CODER_ACK replan` / `VISUAL_CODER_REPLAN`): do **not**
+     edit project files and do not rewrite an earlier accepted patch. The
+     withdrawn proposal is no longer live; disk is baseline + accepted patch
+     files. Follow the text between `VISUAL_CODER_INSTRUCTION_START` and
+     `VISUAL_CODER_INSTRUCTION_END`, read this session's `blueprint.json` when
+     it is enabled (files, islands, `addedFunctions`, `addedVariables`,
+     `addedImports`). The blueprint stays leading. If the new instruction would
+     differ from it, ask the user before replacing the plan. Read
+     `user-context.json` (follow the viewpoint only if `followLook` is true),
+     replace the plan from the current step onward using `inbase report-plan`,
+     then wait for the next `VISUAL_CODER_EXECUTE` before editing again. The
+     replacement edits must sit on the accepted live files, not the withdrawn
+     proposal.
+   - Exit `2` (`VISUAL_CODER_ACK stopped` / `VISUAL_CODER_STOPPED`) or `3`
+     (`VISUAL_CODER_ACK timeout`): make no further project changes.
 
 13. After a finished handshake, the explorer already removed stored session
     diffs and blueprint drafts. Optionally run:
 
 ```bash
-npx inbase propose-patch --session "<current-cursor-chat-id>" --clear
+npx inbase propose-patch --session "<session-id>" --clear
 ```
 
 ## Do not
 
-- Skip `inbase start-session` once this skill applies
-- Skip `inbase wait-for-blueprint` or report a plan before `VISUAL_CODER_BLUEPRINT_READY`
+- Start a visual session from chat with `start-session`; sessions start only
+  from **Setup LLM session** in the map
+- Edit files on a direct chat request; reply with the `/skipinbase` line and stop
+- Invent a session id for `/inbase`; run `npx inbase attach` with no `--session`
+- Skip `inbase wait-for-blueprint`; it returns immediately and provides the optional blueprint and instruction
 - Treat the chat request, viewpoint, or your own plan as overriding an enabled blueprint
 - Skip, rename, relocate, or replace this session's `blueprint.json` files, islands, functions, variables, or imports when `enabled` is true
 - Silently differ from the blueprint; ask the user first
 - Read global `user-context.json` for placed files; those live on the session blueprint
 - Follow the user's look when `followLook` is false
-- Write, edit, create, or delete project files directly
-- Announce file lists instead of a patch
-- Write a patch before its plan step is invoked
+- Edit project files before `VISUAL_CODER_EXECUTE`
+- Keep editing after `inbase propose-patch` until the next `VISUAL_CODER_EXECUTE`
+- Write a unified diff yourself; `inbase propose-patch` with no file records the git diff
+- Pass a `.patch` file to `propose-patch` unless you are debugging the CLI
+- Explore, search, or re-plan after `propose-patch` before `wait-for-approval`
+- Stay silent or call tools before acknowledging a `VISUAL_CODER_ACK` in chat
 - Propose the next step before `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE`
 - Propose another patch after `VISUAL_CODER_FINISHED`
 - Reuse, overwrite, or expand an existing session diff