@jabworks/condux 0.2.0 → 0.3.1

package/skills/finalize/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: finalize
+description: "End-of-task quality gate — typecheck → lint → format → tests. Runs in order, once. Stops on first failure and fixes before continuing. Run after all implementation is complete. Called automatically by /workflow, or standalone. Check AGENTS.md for the project's actual commands. Not for auditing whether requirements and plan steps are complete; use preflight first."
+argument-hint: "[package or path to scope — optional]"
+---
+
+# /finalize
+
+One quality gate at the end. Typecheck → lint → format → test. In that order. Once.
+
+## Usage
+
+```
+/finalize              # full repo
+/finalize apps/web     # scoped to package or path
+```
+
+## Before Running
+
+Check `AGENTS.md` for the project's finalize commands. If `AGENTS.md` defines a `finalize` script or step sequence, use that. Otherwise fall back to reading `package.json` scripts and infer the right commands. If no `.condux/plans/*<slug>*.md` exists for the inferred feature slug, note it in the output below — don't block. This is informational only, surfacing when a task ran without going through `/workflow` or `/draft-plan`, not a gate.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         FINALIZE                                │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: TYPECHECK                                              │
+│  Run: typecheck script from AGENTS.md or package.json          │
+│  → Failure: fix type errors, re-run typecheck only             │
+│  → Clean: proceed to Step 2                                     │
+│                                                                  │
+│  Step 2: LINT                                                   │
+│  Run: lint script from AGENTS.md or package.json               │
+│  → Errors: fix, re-run lint only to confirm                    │
+│  → Warnings: note them, do not block                           │
+│  → Clean: proceed to Step 3                                     │
+│                                                                  │
+│  Step 3: FORMAT                                                 │
+│  Run: format check, then auto-fix if dirty                     │
+│  → Report which files were changed                             │
+│  → Continue to Step 4 regardless (format is auto-fixed)        │
+│                                                                  │
+│  Step 4: TEST                                                   │
+│  Run: test script from AGENTS.md or package.json               │
+│  → Failure: diagnose, make one targeted fix, re-run            │
+│    failing tests only (not full suite)                         │
+│  → Still failing: stop, report, do not loop                    │
+│  → Clean: done                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Failure Handling
+
+```
+Typecheck fails
+  → Read the error carefully
+  → Fix the type issue
+  → Re-run typecheck only — do not proceed until clean
+
+Lint fails (errors, not warnings)
+  → Fix flagged issues (auto-fix with --fix if safe)
+  → Re-run lint only to confirm clean
+  → Do not proceed to tests until clean
+
+Format is dirty
+  → Run format --write
+  → Note changed files in output
+  → Continue — format never blocks
+
+Tests fail
+  → Read failure output carefully
+  → Make one targeted fix
+  → Re-run the failing test(s) only
+  → If still failing: STOP and report — do not loop
+```
+
+## Output Format
+
+The `Plan` line below only appears when no matching plan doc was found for the inferred feature slug — it's omitted entirely otherwise.
+
+```
+## Finalize: [task or feature name]
+
+Typecheck  ✓ clean
+Lint       ✓ clean  (2 warnings — not blocking)
+Format     ✓ 2 files auto-fixed (Button.tsx, invoice.router.ts)
+Tests      ✓ 18 passed, 0 failed
+Plan       (none found for this task — treating as standalone scope)
+
+Ready to commit.
+```
+
+On failure:
+
+```
+## Finalize: [task or feature name]
+
+Typecheck  ✗ FAILED
+  apps/web/src/components/InvoiceTable.tsx:42
+  Property 'onExport' does not exist on type 'InvoiceTableProps'
+  Fix: added onExport?: () => void to InvoiceTableProps
+  Re-run: ✓ clean
+
+Lint       ✓ clean
+Format     ✓ clean
+Tests      ✓ 18 passed
+```
+
+## What Does NOT Happen
+
+```
+✗ Running tests mid-implementation
+✗ Running lint/typecheck after individual file edits
+✗ Looping on test failures — one fix attempt, then stop and report
+✗ Blocking on lint warnings (errors only)
+✗ Running the full test suite multiple times
+✗ Skipping steps because "the change was small"
+```
+
+## See Also
+
+- `references/rationalization-table.md` — common rationalizations for skipping finalize and why they're wrong

package/skills/finalize/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "run the quality gate", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "typecheck lint format test", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "finalize the task", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "all done implementing, run the checks", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "is the build green", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "run tests and lint before I commit", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "finalize just apps/web", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "prettier rewrote 3 files during the check, is that ok", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "should I run lint after every file edit", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "whats the projects test command, AGENTS.md has it maybe", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "tests failing, keep looping until green", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "run the full suite twice just to be sure", "should_trigger": true, "expected_skill": "finalize", "kind": "in-context" },
+  { "query": "am I actually done though", "should_trigger": true, "expected_skill": "preflight" },
+  { "query": "commit this with a proper message", "should_trigger": true, "expected_skill": "git-commit" },
+  { "query": "fix this type error in the component", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "why is this one test failing", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "review the diff before merge", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "format this sql query nicely for the doc", "should_trigger": false, "expected_skill": null },
+  { "query": "what does the no-unused-vars eslint rule mean", "should_trigger": false, "expected_skill": null },
+  { "query": "release the package to npm", "should_trigger": true, "expected_skill": "release" }
+]

package/skills/finalize/references/rationalization-table.md

@@ -0,0 +1,15 @@
+# Finalize Rationalization Table
+
+Common rationalizations agents use to skip or shortcut the finalize gate — and why they're wrong.
+
+| Rationalization                                     | Reality                                                                                  | Counter                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| "The change was too small to break types"           | Type errors compound. A small change that breaks an import breaks everything downstream. | Run typecheck. It takes seconds.                                           |
+| "I already ran lint during implementation"          | Lint state during implementation is stale. You may have added new violations since.      | Run lint once at the end, clean.                                           |
+| "Tests were passing before my change"               | Your change may have introduced a regression that existing tests catch.                  | Run tests. That's their purpose.                                           |
+| "I'll skip format — it's just whitespace"           | Noisy diffs make code review harder and hide real changes.                               | Format is auto-fixed and non-blocking. There's no reason to skip it.       |
+| "The tests take too long to run"                    | Check AGENTS.md for a fast/watch mode. Scope the run to the affected package.            | Run scoped tests. Don't run the full suite if there's a faster option.     |
+| "I fixed the failing test so I can skip re-running" | The fix might have introduced a new failure.                                             | Re-run the affected test(s). One command.                                  |
+| "Typecheck is already run by the build"             | The build runs in CI, not locally. You want to catch errors before push, not after.      | Run typecheck locally before committing.                                   |
+| "I'll fix the lint errors in a follow-up"           | Follow-ups don't happen. The lint errors accumulate and become background noise.         | Fix now. It's part of the task.                                            |
+| "There are too many test failures to fix right now" | Stop and report. Don't merge broken tests.                                               | If tests are failing and you can't fix them, surface that — don't hide it. |

package/skills/plan-review/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: plan-review
+description: "Render a plan in a local browser for inline annotation, then return an approve / request-revisions / deny decision to the agent. Auto-captures the plan via a Claude Code ExitPlanMode hook or a Codex Stop hook, or runs manually on any markdown file or spec directory. Self-contained — no network egress, no third-party runtime deps. When the agent finishes planning (Claude Code ExitPlanMode, or a Codex planning turn) and you want to review/annotate before it implements, or when you invoke /plan-review on a markdown plan or spec directory. Also owns its own machinery — steer-mode review loops, the live spec preview, and installing or troubleshooting the ExitPlanMode / Codex Stop hooks. Not for cataloging a whole specs tree; use spec-browser."
+---
+
+# /plan-review
+
+Interactive plan review. The agent's plan opens in a local browser; you select
+any text to attach an inline comment, chat with the agent, then submit a decision.
+The decision flows back to the agent — **Approve** lets it proceed, **Request
+Revisions** sends your notes back so it revises and re-presents, and **Reject**
+tells it not to implement — reconsider whether the feature should be built.
+
+Inspired by [Plannotator](https://github.com/backnotprop/plannotator), rebuilt
+in-house so it carries **no third-party runtime dependency** and makes **no
+network calls** — safe for strict environments.
+
+## Ways in
+
+### Auto — ExitPlanMode hook (the real workflow)
+
+When installed as part of the **condux plugin**, this hook ships in the plugin
+(`hooks/hooks.json`) and is auto-registered — no setup. Every time the agent
+exits plan mode, the plan is captured and the review UI opens automatically. The
+hook blocks until you decide. The plugin entry is:
+
+```json
+// dist/plugins/condux/hooks/hooks.json (shipped — for reference)
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review/references/annotate-server.js\" --hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Standalone (no plugin)?** Wire the same hook by hand in your
+`settings.json` (project `.claude/settings.json` or `~/.claude/settings.json`),
+swapping `${CLAUDE_PLUGIN_ROOT}/skills/condux/plan-review` for the absolute path:
+
+```bash
+find ~/.claude ~/.codex ~/.agents -name annotate-server.js -path '*plan-review*' 2>/dev/null | head -1
+```
+
+What the hook returns to the agent:
+
+| Your decision | Hook output | Agent behavior |
+|---|---|---|
+| **Approve** | `permissionDecision: "allow"` (+ notes as `additionalContext` if any) | proceeds to implement |
+| **Request Revisions** | `permissionDecision: "deny"`, reason = *revise this plan* + feedback | revises the plan, re-enters plan mode (re-triggers the hook) |
+| **Reject** | `permissionDecision: "deny"`, reason = *do not implement, reconsider* + feedback | stops; reconsiders whether the feature should be built, or proposes a different approach |
+
+### Auto — Codex Stop hook
+
+Codex has **no `ExitPlanMode`** interception point, so plan review runs off
+Codex's experimental **`Stop` hook**. When a planning turn ends
+(`permission_mode === "plan"`), `annotate-server.js --codex-stop` reads the plan
+from the Stop payload (`last_assistant_message`, falling back to
+`transcript_path`) and opens the same review UI. On any other turn it emits `{}`
+and exits, leaving the turn untouched.
+
+**Installed via the condux plugin?** The `Stop` hook ships with it. The Codex
+manifest (`.codex-plugin/plugin.json`) sets `"hooks": "./hooks/codex-hooks.json"`,
+which Codex loads **instead of** the default `hooks/hooks.json` (that one is
+Claude's `ExitPlanMode` hook, inert on Codex). Just enable `[features] hooks =
+true` in `$CODEX_HOME/config.toml`, then **restart Codex** and **trust the hook**
+when prompted — no installer needed.
+
+**Standalone (no plugin)?** Run the installer once — it writes `~/.codex/hooks.json`
++ sets the feature flag, then restart Codex and trust the hook:
+
+```bash
+bash /PATH/TO/plan-review/references/install-codex-hook.sh
+# or, after a plugin install:
+find ~/.codex ~/.claude -name install-codex-hook.sh -path '*plan-review*' 2>/dev/null | head -1 | xargs bash
+```
+
+| Your decision | Hook output | Codex behavior |
+|---|---|---|
+| **Approve** (no notes) | `{}` (turn completes) | plan accepted, turn ends |
+| **Approve** (with notes) | `{"decision":"block","reason":<approved + notes>}` | continues the turn; agent implements while addressing the notes |
+| **Request Revisions** | `{"decision":"block","reason":<revise + feedback>}` | revises the plan in the same turn (re-triggers on next stop) |
+| **Reject** | `{"decision":"block","reason":<do not implement, reconsider + feedback>}` | stops; reconsiders whether the feature should be built, or proposes a different approach |
+
+Caveats: Codex hooks are **experimental and disabled on Windows**; the review is
+**post-render** (after Codex prints the plan), not a pre-interception like Claude
+Code. The plugin hook invokes bare `node` (resolved via `${PLUGIN_ROOT}`, the
+variable Codex substitutes in plugin hook commands — it does **not** set Claude's
+`${CLAUDE_PLUGIN_ROOT}`, so never use that in `codex-hooks.json`) — if Codex
+Desktop can't find `node` on `PATH`, fall back to the installer, which bakes in
+an **absolute** node path.
+
+### Manual — on any file or spec directory
+
+```bash
+node /PATH/TO/plan-review/references/annotate-server.js <plan-or-spec.md>
+node /PATH/TO/plan-review/references/annotate-server.js <spec-dir>
+```
+
+Serves the file, writes your decision to `<file>.feedback.md`, and stays running
+(Ctrl+C to stop). Pass `--no-open` to skip the automatic browser launch (used by
+the test suite; also right for headless/CI runs). Use this for ad-hoc review of a spec or a written plan when you
+are not in plan mode. After submitting, read `<file>.feedback.md` to action it.
+
+**Directory mode** reviews a whole spec folder (e.g. `specs/wan-config/` from
+the `technical-spec` skill): every top-level `*.md` is listed in the sidebar,
+notes are tagged with their source file, edits to any file live-reload (with a
+per-file revision diff), and the decision lands in `<dir>/review.feedback.md`
+grouped by file. Works in manual and `--steer` modes; this is also the live
+preview surface for `technical-spec` (its old preview server is retired).
+
+### Steer — agent-invoked loop (any agent, no hook needed)
+
+When you want the review to actually **drive an agent** outside Claude's
+`ExitPlanMode` / Codex `Stop` hooks — e.g. an agent that wrote a plan to a file
+and wants you to gate it — run the server in `--steer` mode. The server is
+**long-lived**: launch it once, and one browser tab stays open for the whole
+review while the agent loops.
+
+```bash
+# 1. Launch once, in the background (default port 7777; override with --port).
+node /PATH/TO/plan-review/references/annotate-server.js <plan.md> --steer &
+
+# 2. Each round: block until you submit a decision (long-poll).
+curl -s http://127.0.0.1:7777/api/decision
+#   → {"decision":"Request Revisions","feedback":"<markdown>","feedbackFile":"<abs>.feedback.md"}
+```
+
+The agent runs the **iterative loop** off that decision:
+
+1. Launch the server (step 1) — the review tab opens and stays open.
+2. `GET /api/decision` — blocks until you decide; returns the decision JSON.
+3. Branch on `decision`:
+   - **Approve** → stop looping, implement the plan (use `feedback` as notes). The server exits.
+   - **Request Revisions** → edit `<plan.md>` **in place**; the open tab live-reloads the new plan over SSE (orphaned notes auto-clear). **Go to 2.**
+   - **Reject** → stop; do not implement — reconsider whether to build this, or surface the blocker. The server exits.
+
+Same steering the hooks give you, available to any agent that can run a command
+and read a file — at the cost of the agent orchestrating the loop itself rather
+than a hook blocking inline. Because the server is long-lived, **the same tab
+reflects every revision** — no new tab per round. The decision is also written to
+`<plan.md>.feedback.md` as a record each round.
+
+## The review surface
+
+A three-pane layout over a **decision bar**: a left sidebar with two tabs —
+**Contents** (heading outline with per-section note counts; in directory mode,
+each document is a top-level node with its headings nested, click to switch
+docs) and **Files** (paths the plan touches, parsed from inline code and
+fences, badged **exists**/**new** against the repo; click jumps to the first
+mention, repeat clicks cycle) — the centered rendered plan (middle), and a
+**Review** rail (right) holding your notes and messages. The decisions live in
+a fixed bar along the bottom — `[Reject] ——— [Request revisions] [Approve]` —
+with a live summary of what rides along ("3 notes · 1 message will be sent").
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Step 1  RENDER     Plan renders centered in the browser, w/ TOC. │
+│  Step 2  ANNOTATE   Select text → a toolbar opens above it. Pick  │
+│                     a category (Comment / Issue / Question /       │
+│                     Suggestion / Nitpick) → the note input opens.  │
+│                     Or message the agent in the Review rail.       │
+│  Step 3  DECIDE     Bottom bar: Approve / Request Revisions /     │
+│                     Reject — with a note/message count summary.    │
+│  Step 4  RETURN     Decision + notes (each tagged with its        │
+│                     category and quoting its anchor) go back.     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Selecting text opens a floating **annotation toolbar** anchored above the
+selection (it flips below when there's no room). It starts as a category
+**menubar**; choosing a category expands it to reveal the note input and
+Save/Cancel. Saving highlights the text and anchors the note; clicking a
+highlight or a note cross-links the two. The page live-reloads when the plan
+file changes on disk (SSE + `fs.watch`).
+
+When the agent **revises** the plan, the tab doesn't silently swap the text: a
+banner reports the change (`+adds / -dels lines`) with a **View changes** toggle
+that shows a unified line diff (old vs. new, folding long unchanged runs), and
+the now-orphaned notes clear so the next round starts clean. Submitting a
+decision **clears your notes immediately** and replaces the decision bar's
+content with a confirmation that states what the agent does next
+(implement / revise / rework).
+
+## Guarantees (why it passes review)
+
+- **No egress.** Server binds `127.0.0.1` only; the HTML template embeds its own
+  markdown renderer and uses a system monospace font — no CDN, no web fonts, no
+  paste/share service. Audit: `grep -rE 'https?://' references/*.html` returns nothing.
+- **No dependencies.** `annotate-server.js` is Node stdlib only.
+- **Auditable.** One stdlib server + one self-contained HTML file. The UI is
+  styled after the **Terminus UI** design system (Button, Badge, Card, Textarea,
+  Popover) — adapted as vanilla CSS tokens + classes, no React, no bundle.
+
+## Files
+
+| File | Role |
+|---|---|
+| `references/annotate-server.js` | Local server. `--hook` (Claude ExitPlanMode), `--codex-stop` (Codex Stop), `<file> --steer` (agent-invoked blocking loop), or `<file|dir>` alone for manual mode. A directory argument reviews every top-level `*.md` in it. |
+| `references/install-codex-hook.sh` | Registers the Codex `Stop` hook in `~/.codex` and enables the hooks feature flag. |
+| `references/plan-review-template.html` | Self-contained review UI (renderer + annotation surface). |
+
+## Related skills
+
+- `draft-plan` — produces the plan this skill reviews.
+- `technical-spec` — persists decisions/API/quirks; this server (directory mode) is its live preview + review surface.

package/skills/plan-review/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "review the plan in the browser", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "open the annotation ui for this plan", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "let me annotate before you implement", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "plan review on .condux/plans/2026-07-04-git-skills.md", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "run the steer mode review loop", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "review the spec directory with per-file notes", "should_trigger": true, "expected_skill": "plan-review", "accept": ["spec-browser"] },
+  { "query": "open live preview of specs/wan-config", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "approve / request revisions flow for this plan", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "the exitplanmode hook isnt opening the browser", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "install the codex stop hook for plan review", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "reject this plan, dont build it", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "send my notes on section 3 back to the agent", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "why didnt the review tab reload after the revision", "should_trigger": true, "expected_skill": "plan-review", "kind": "in-context" },
+  { "query": "something like plannotator?", "should_trigger": true, "expected_skill": "plan-review" },
+  { "query": "review this code diff", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "review pr #42 on github", "should_trigger": true, "expected_skill": "code-review" },
+  { "query": "write the plan first", "should_trigger": true, "expected_skill": "draft-plan", "accept": ["workflow"] },
+  { "query": "browse all our specs as one doc site", "should_trigger": true, "expected_skill": "spec-browser" },
+  { "query": "build the spec index catalog", "should_trigger": true, "expected_skill": "spec-browser" },
+  { "query": "review this google doc proposal", "should_trigger": false, "expected_skill": null }
+]