@jabworks/condux 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/blueprint/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: blueprint
+description: "Produce dependency-free visual clarity artifacts at design time — grayscale HTML wireframes for UI screens and flows, and inline-SVG system diagrams (data models, flows, architecture, state machines) for backend work. During /discovery when the feature has a UI surface or a data model, from /draft-plan task cards, or standalone on \"mock this up\", \"wireframe this screen\", \"visualize the data model\", \"sketch the architecture\", \"diagram the flow\". Not for aesthetic or brand direction, editable design canvases or Figma, charts from real data, or generating code from a mockup."
+argument-hint: "[surface or model to visualize — optional; defaults to the current design context]"
+---
+
+# /blueprint
+
+Make the design visible before it's built. Wireframes tell a frontend dev what
+goes where and why; system diagrams tell a backend dev what talks to what.
+Structure, never style.
+
+## Usage
+
+```
+/blueprint checkout flow
+/blueprint orders data model
+/blueprint            # infers surfaces from the design being discussed
+```
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         BLUEPRINT                                │
+├──────────────────────────────────────────────────────────────────┤
+│  Step 1: ASSESS SURFACES                                         │
+│  What does the feature touch?                                    │
+│    - UI screens or flows        → wireframe family               │
+│    - Data models, services,     → diagram family                 │
+│      flows, state machines                                       │
+│    - Both                       → both families                  │
+│                                                                  │
+│  Step 2: PRODUCE                                                 │
+│  One self-contained HTML file per screen / flow state / diagram. │
+│  Wireframes follow references/wireframe-kit.md.                  │
+│  Diagrams follow references/diagram-kit.md.                      │
+│  No external assets, no CDN, no fonts beyond the system stack.   │
+│                                                                  │
+│  Step 3: DELIVER                                                 │
+│  Open in the browser (xdg-open / open). If neither works         │
+│  (headless, SSH), print the absolute paths and continue —        │
+│  never fail on delivery.                                         │
+│                                                                  │
+│  Step 4: LINK                                                    │
+│  Reference the files from the design doc or task card that       │
+│  motivated them, so the visual target travels with the design.   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## The Two Families
+
+**Wireframes (UI clarity).** Grayscale boxes with real content hierarchy and
+annotation callouts. A wireframe answers: what elements exist, how they group,
+what order they read in, what happens on each state (empty, loading, error,
+populated). Multiple states of one flow are separate files, named for the
+state. The full discipline — hard rules plus a copyable base-CSS block — is in
+`references/wireframe-kit.md`.
+
+**System diagrams (BE clarity).** Hand-authored inline SVG for four shapes:
+entity/data-model, request/data flow, architecture boxes-and-arrows, and state
+machines. A diagram answers: what entities or services exist, what relates to
+what, what direction data moves, what states are legal. Skeletons and
+label conventions are in `references/diagram-kit.md`.
+
+Pick per surface, not per request — a feature with a settings page and a new
+`preferences` table gets a wireframe *and* an entity diagram.
+
+## Where Files Go
+
+Write to `<git-root>/.condux/designs/<YYYY-MM-DD>-<feature>/mockups/<name>.html`,
+beside the feature's design doc. `.condux/` is gitignored working state,
+created on demand at the git root — before the first write, check it's
+ignored (`git check-ignore -q .condux/ || echo "not ignored"`) and offer to
+add it to `.gitignore` if it isn't. Not a git repo → fall back to CWD and say
+so once. Standalone invocations with no design doc use the same path with the
+request's kebab-case subject as `<feature>`.
+
+**Citation direction:** these files are ephemeral. A committed file — a spec,
+a changelog, a backlog item — may never cite a `.condux/` path; promote the
+mockup into the spec directory first and cite the committed copy.
+
+## Inside the Workflow
+
+- **/discovery** loads this skill at the propose step when the feature has a
+  UI surface or a data model — the mockups render the proposal, and the
+  signed-off design doc links the chosen ones. Side-by-side option *picking*
+  stays with discovery's own mockup-picker.
+- **/draft-plan** task cards may cite mockup paths so an implementer sees the
+  visual target for their task.
+- Standalone asks ("mock this up", "visualize the data model") run the same
+  three steps without the discovery context.
+
+## What Does NOT Happen
+
+```
+✗ Brand styling, palettes, typography choices, premium polish — structure only
+✗ Colors beyond grayscale (one muted annotation accent is the ceiling)
+✗ External dependencies — no Mermaid CDN, no image generation, no Figma
+✗ Code generation from the mockup (that's implementation's job, later)
+✗ Charts of real data (that's a dataviz concern, not a design mockup)
+✗ Editing the mockups after design sign-off without saying so
+```

package/skills/blueprint/evals/trigger_eval.json

@@ -0,0 +1,96 @@
+[
+  {
+    "query": "mock this up before we build it",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "wireframe the settings page so the frontend dev knows what to expect",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "can you mock up the checkout flow including the empty and error states",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "visualize the data model for orders and customers",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "sketch the architecture for the notification service",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "diagram the auth flow between the gateway and the identity service",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "draw the state machine for the subscription lifecycle",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "I want a visual of how the entities relate before we touch the schema",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "give me a quick layout mockup of the dashboard so we agree on structure",
+    "should_trigger": true,
+    "expected_skill": "blueprint"
+  },
+  {
+    "query": "show me a wireframe of both options for the onboarding screen",
+    "should_trigger": true,
+    "expected_skill": "blueprint",
+    "accept": ["discovery"]
+  },
+  {
+    "query": "before planning, can we visualize what this feature will look like",
+    "should_trigger": true,
+    "expected_skill": "blueprint",
+    "accept": ["discovery", "workflow"]
+  },
+  {
+    "query": "mock up the ER diagram for the new billing tables",
+    "should_trigger": true,
+    "expected_skill": "blueprint",
+    "kind": "in-context"
+  },
+  {
+    "query": "add a wireframe for the loading state too",
+    "should_trigger": true,
+    "expected_skill": "blueprint",
+    "kind": "in-context"
+  },
+  {
+    "query": "make this landing page look premium",
+    "should_trigger": false,
+    "expected_skill": null
+  },
+  {
+    "query": "plot signups per week as a bar chart",
+    "should_trigger": false,
+    "expected_skill": null
+  },
+  {
+    "query": "build the settings page from the approved design",
+    "should_trigger": false,
+    "expected_skill": null
+  },
+  {
+    "query": "implement this Figma design as a React component",
+    "should_trigger": false,
+    "expected_skill": null
+  },
+  {
+    "query": "pick a color palette and typography for the marketing site",
+    "should_trigger": false,
+    "expected_skill": null
+  }
+]

package/skills/blueprint/references/diagram-kit.md

@@ -0,0 +1,81 @@
+# Diagram Kit
+
+Reference for `/blueprint`. Hand-authored inline SVG — no Mermaid, no CDN, no
+renderer dependency. Every diagram is a self-contained HTML file that renders
+from `file://`.
+
+## Shared Conventions
+
+- Canvas: `<svg viewBox="0 0 W H" style="max-width:100%">` sized to content;
+  the page wraps it in the same `.frame` shell as the wireframe kit.
+- Palette mirrors the wireframe discipline: fills `#fff`/`#f0f0f0`, strokes
+  `#777`, text `#222`, the `#5b7c99` accent for the one thing the diagram is
+  about (the new entity, the changed edge) — never more than one accent use.
+- Text: `font-family: -apple-system, "Segoe UI", Roboto, sans-serif`, 13–14px
+  labels, 11px annotations. If a label doesn't fit its box, the box grows —
+  never shrink the font below 11px.
+- Arrowheads via one shared `<marker>`:
+
+```html
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+          markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M0,0 L10,5 L0,10 z" fill="#777"/>
+  </marker>
+</defs>
+<!-- usage: <line ... stroke="#777" marker-end="url(#arrow)"/> -->
+```
+
+- Every relationship line gets a label. An unlabeled arrow is a guess the
+  reader has to make.
+
+## 1. Entity / Data-Model
+
+One `<g>` per entity: title bar + field rows. Keys marked `PK` / `FK`; edge
+labels carry cardinality (`1..*`, `0..1`).
+
+```html
+<g transform="translate(40,40)">
+  <rect width="200" height="24" fill="#f0f0f0" stroke="#777"/>
+  <text x="100" y="17" text-anchor="middle" font-weight="600">orders</text>
+  <rect y="24" width="200" height="72" fill="#fff" stroke="#777"/>
+  <text x="8"  y="41">id  PK</text>
+  <text x="8"  y="61">user_id  FK</text>
+  <text x="8"  y="81">status</text>
+</g>
+<!-- edge: users 1..* orders -->
+<line x1="240" y1="80" x2="340" y2="80" stroke="#777" marker-end="url(#arrow)"/>
+<text x="290" y="72" text-anchor="middle" font-size="11">1..*</text>
+```
+
+## 2. Request / Data Flow
+
+Actors and stores as boxes on one horizontal band; numbered edges show
+sequence. Number every hop (`1. POST /orders`, `2. validate`, `3. INSERT`) —
+the numbers are what make it a flow rather than a topology.
+
+## 3. Architecture (boxes-and-arrows)
+
+Services as rounded rects (`rx="6"`), external systems as rects with a dashed
+stroke (`stroke-dasharray="4 3"`), boundaries (network, process, trust) as a
+large dashed `<rect>` behind its members with the boundary name in the top-left
+corner. Edges labeled with protocol or payload (`HTTP`, `queue: order.created`).
+
+## 4. State Machine
+
+States as rounded rects, transitions as labeled arrows, initial state marked
+with a filled dot and an arrow, terminal states with a double border (nested
+`<rect>` inset by 3px). Every transition label is the *event* that causes it,
+not a description of the target state.
+
+## Choosing the Shape
+
+| The question being asked | Shape |
+|---|---|
+| What entities exist and how do they relate? | Entity / data-model |
+| What happens, in what order, when X occurs? | Request / data flow |
+| What services exist and what talks to what? | Architecture |
+| What states are legal and what moves between them? | State machine |
+
+When a design raises two of these questions, draw two diagrams — a diagram
+answering two questions at once answers neither legibly.

package/skills/blueprint/references/wireframe-kit.md

@@ -0,0 +1,88 @@
+# Wireframe Kit
+
+Reference for `/blueprint`. The discipline is what keeps a wireframe
+unambiguous: the moment brand styling creeps in, reviewers debate taste
+instead of structure.
+
+## Hard Rules
+
+1. **Grayscale only.** Backgrounds `#fff`–`#f5f5f5`, borders `#ccc`,
+   text `#222`/`#777`. One muted accent (`#5b7c99`) is allowed for
+   annotation callouts only — never for UI elements.
+2. **System font stack.** `-apple-system, "Segoe UI", Roboto, sans-serif`.
+   No webfonts, no font files.
+3. **No imagery.** Photos and illustrations render as a crossed box with a
+   label (`.img-box`). Icons render as their name in brackets, e.g. `[gear]`.
+4. **Real hierarchy, placeholder content.** Headings, labels, and CTAs carry
+   their actual intended text; body copy may be greeked with `▓▓▓` bars.
+5. **Annotate decisions, not furniture.** A callout explains *why this is
+   here* or *what happens on interaction* — not "this is a button".
+6. **One file per screen or flow state.** Empty, loading, error, and populated
+   are different files named for the state:
+   `settings-page.html`, `settings-page-empty.html`, `settings-page-error.html`.
+7. **Self-contained.** All CSS inline in a `<style>` block. No external
+   requests of any kind. The file must render identically from `file://`.
+
+## Base CSS
+
+Copy this block into every wireframe's `<style>` and build on it.
+
+```css
+* { margin: 0; box-sizing: border-box; }
+body {
+  font-family: -apple-system, "Segoe UI", Roboto, sans-serif;
+  background: #f5f5f5; color: #222; padding: 24px;
+}
+.frame {            /* the device/viewport boundary */
+  background: #fff; border: 2px solid #ccc; border-radius: 6px;
+  max-width: 1100px; margin: 0 auto; padding: 24px;
+}
+.box {              /* generic grouping region */
+  border: 1px dashed #bbb; border-radius: 4px;
+  padding: 16px; margin-bottom: 16px;
+}
+.row { display: flex; gap: 16px; }
+.row > * { flex: 1; }
+.img-box {          /* rule 3: imagery placeholder */
+  border: 1px solid #ccc; background:
+    linear-gradient(45deg, transparent 49.5%, #ccc 49.5%, #ccc 50.5%, transparent 50.5%),
+    linear-gradient(-45deg, transparent 49.5%, #ccc 49.5%, #ccc 50.5%, transparent 50.5%);
+  display: flex; align-items: center; justify-content: center;
+  color: #777; min-height: 120px;
+}
+.btn {              /* any actionable element */
+  display: inline-block; border: 1px solid #777; border-radius: 4px;
+  padding: 8px 20px; background: #eee; color: #222;
+}
+.greek {            /* rule 4: body-copy placeholder */
+  color: #ccc; letter-spacing: 2px; overflow: hidden; white-space: nowrap;
+}
+.note {             /* rule 5: annotation callout — the only accent use */
+  border-left: 3px solid #5b7c99; background: #eef2f6; color: #33475b;
+  padding: 8px 12px; font-size: 13px; margin: 8px 0;
+}
+```
+
+Greeked copy: `<div class="greek">▓▓▓▓▓▓▓▓ ▓▓▓▓ ▓▓▓▓▓▓</div>` at whatever
+width the real copy would occupy.
+
+## Page Skeleton
+
+```html
+<title>settings-page — wireframe</title>
+<style>/* base CSS above */</style>
+<div class="frame">
+  <div class="box"><strong>Header</strong> · [logo] · nav: Account / Billing / Team</div>
+  <div class="row">
+    <div class="box"><!-- sidebar --></div>
+    <div class="box" style="flex:3"><!-- main content --></div>
+  </div>
+  <div class="note">Sidebar collapses below 768px — Billing moves into the header nav.</div>
+</div>
+```
+
+## Review Posture
+
+Present a wireframe as a question, not an answer: "this is the structure I
+understood — what's wrong with it?" When two structures genuinely compete,
+produce both files and let discovery's mockup-picker run the choice.

package/skills/discovery/SKILL.md

@@ -49,6 +49,9 @@ as any other soft gate in this skill.
 │  Present 2-3 approaches with tradeoffs.                        │
 │  Show design in sections — get acknowledgment per section      │
 │  before moving on.                                              │
+│  UI surface or data model involved? Load `blueprint` to        │
+│  render the proposal visually — wireframes and diagrams        │
+│  become part of what gets signed off.                           │
 │                                                                  │
 │  Step 4: DETAIL ROUND — feed the spec                           │
 │  With the approach chosen, ask ONE more batch, grouped by      │
@@ -168,7 +171,10 @@ design that lives only in conversation doesn't count as signed off.
 ignored — see the bootstrap step there. Honour an `AGENTS.md` path override
 if the project defines one.
 
-For side-by-side layout comparisons or architecture diagrams during the design phase, see `references/mockup-picker.md`.
+For full design mockups — grayscale UI wireframes, data-model / flow /
+architecture diagrams — load the `blueprint` skill; the design doc links the
+files it produces. For *picking between* side-by-side options in the browser,
+see `references/mockup-picker.md` (it can point at blueprint's files).
 
 ## Design Review Loop
 

package/skills/draft-plan/SKILL.md

@@ -110,6 +110,10 @@ implementer (especially a subagent) sees only their own card, so `Consumes`
 is what prevents drift like `clearLayers()` in Task 3 vs `clearFullLayers()`
 in Task 7.
 
+When `blueprint` mockups exist for the feature, a card may cite the relevant
+file under `.condux/designs/<feature>/mockups/` so the implementer sees the
+visual target for their task (ephemeral→ephemeral citation — allowed).
+
 ## Code Sketches
 
 Plans are reviewed by annotation before any code is written, so the cheapest

package/skills/workflow/SKILL.md

@@ -150,6 +150,7 @@ Load each only when its step is reached.
 | Skill | When | Gate discipline |
 |---|---|---|
 | `discovery` | LARGE, before planning, or scope unclear | soft gate — ask before skipping |
+| `blueprint` | discovery's propose step, or a standalone mockup/visualization ask | load only when a UI surface or data model is in play; structure, never styling |
 | `draft-plan` | LARGE, after discovery sign-off | needs a signed-off design; no design → apply the discovery soft gate first |
 | `test-first-development` | user asks, or picks it at CP-1 | one upfront consent; always ask before editing an existing test spec |
 | `subagent-execution` | LARGE plan where specialization/parallelism pays off | default is implement yourself |

package/skills/workflow/hooks/routing.md

@@ -8,7 +8,7 @@ it with the user, then executes the matching flow, loading downstream skills onl
 when a step needs them.
 
 **These skills execute _within_ workflow, never instead of it:** `discovery`,
-`draft-plan`, `test-first-development`, `subagent-execution`,
+`draft-plan`, `blueprint`, `test-first-development`, `subagent-execution`,
 `subagent-deployment`, `preflight`, `finalize`, `code-review`,
 `root-cause-analysis`, `live-verification`, `plan-review`, `technical-spec`.