@jabworks/condux 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.9.0",
+  "version": "0.10.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/condux-doctor/doctor.mjs

@@ -15,7 +15,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const SKILL_BASE = path.dirname(fileURLToPath(import.meta.url));
-const PLUGIN_ROOT = path.resolve(SKILL_BASE, '..', '..', '..');
+const PLUGIN_ROOT = path.resolve(SKILL_BASE, '..', '..');
 const HOME = os.homedir();
 const EXEC_TIMEOUT = 5000;
 const PACKAGE = '@jabworks/condux';

package/skills/technical-spec/SKILL.md

@@ -23,7 +23,7 @@ to place the spec.
   {feature-slug}/           # cross-cutting, or scaffolded from the repo root
   apps/web/
     {feature-slug}/         # scaffolded while working in apps/web
-      index.md              # TOC, last updated, commit hash, changelog  ← scaffold creates this
+      index.md              # purpose, TOC, last updated, commit hash, changelog  ← scaffold creates this
       decisions.md          # Design decisions with context + rationale
       api.md                # Endpoints, types, external APIs consumed
       fields.md             # Field mappings: BE/3rd-party → UI, or forwarding chains
@@ -88,6 +88,18 @@ Read [references/templates.md](references/templates.md) for the structure of eac
 
 - Write only files that have real content
 - After writing, update the `## Contents` section in `index.md` with links to the files you created
+- Replace the HTML comment the scaffold left below the title with a one-line
+  `> …` note saying what the spec is for. That note is what `spec-browser`'s
+  catalog shows for the spec; leave it and the spec is listed with nothing to
+  identify it
+
+**Cite committed paths only.** The spec is durable; the design and plan it came
+from live in `.condux/`, which is gitignored — a citation into it is dead on
+every machine but this one. When the changelog or a content file needs to point
+at a design or a verification report, copy that file into the spec directory
+first (`design.md`, `verification.md`) and cite that path. If the artifact is
+already gone, say so and name what survives — a PR, a commit — instead of a
+path that resolves nowhere.
 
 ## Updating an Existing Spec
 

package/skills/technical-spec/references/scaffold.sh

@@ -82,9 +82,19 @@ fi
 
 mkdir -p "$SPEC_DIR"
 
+# The comment is the purpose slot. spec-browser's catalog (specs/index.md)
+# shows a spec's "> note" as its description and an honest "—" when there is
+# none, so a spec with no purpose line is listed with nothing to identify it.
+# A visible placeholder would be worse — it generates into the catalog looking
+# like content — so the prompt is an HTML comment, which the catalog skips and
+# no rendered view of the file displays.
 cat > "$SPEC_DIR/index.md" <<EOF
 # $INPUT — Tech Spec
 
+<!-- Replace this comment with a one-line "> …" note saying what this spec is
+     for. It is what specs/index.md shows for this spec; without it the catalog
+     lists this spec with no description. -->
+
 **Last updated:** $DATE
 **Commit:** $COMMIT
 **Status:** draft

package/skills/technical-spec/references/templates.md

@@ -9,6 +9,9 @@ Copy-paste templates for each spec file. Omit sections that don't apply — don'
 ```markdown
 # {Feature Name} — Tech Spec
 
+> One line: what this spec is for. This is what the catalog (`specs/index.md`)
+> shows for the spec — without it the spec is listed with no description.
+
 **Last updated:** {YYYY-MM-DD}
 **Commit:** {short-hash}
 **Status:** draft | review | stable
@@ -24,6 +27,13 @@ Copy-paste templates for each spec file. Omit sections that don't apply — don'
 - {YYYY-MM-DD} ({short-hash}): Initial spec
 ```
 
+**Cite committed paths only.** A spec is durable; the design and plan it came
+from are working state under `.condux/`, gitignored and gone on any other
+machine. If the changelog or body needs to point at a design or a verification
+report, copy that file into this spec's directory first (`design.md`,
+`verification.md`) and cite *that*. Six such citations were written before this
+rule existed and two were already dead when they were found.
+
 ---
 
 ## decisions.md

package/skills/workflow/SKILL.md

@@ -183,6 +183,16 @@ The spec is what you keep; the design and plan are scaffolding for building
 it. Don't promote working state into `docs/` or the repo root — a project's
 `docs/` belongs to the project, not to condux.
 
+**Citation direction: durable content may not depend on ephemeral content.**
+A committed file may not cite a path inside `.condux/` — that path is gone on
+any other machine and on any fresh clone, so the reference is dead for everyone
+but its author. When a spec, a changelog entry or a backlog item needs to point
+at a design or a verification report, **promote it first**: copy that file into
+the durable tree (the spec directory it belongs to) and cite the committed
+path. If the artifact no longer exists, say so and name what survives — a PR, a
+commit — rather than a path that resolves nowhere. The split above says where
+each artifact *lives*; this says which direction a reference may point.
+
 **Bootstrap.** `.condux/` is created on demand at the git root by the first
 skill that writes there. Before that first write, check it's ignored:
 

package/skills/workflow/hooks/codex-hooks.json

@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${PLUGIN_ROOT}/skills/condux/plan-review/references/annotate-server.js\" --codex-stop",
+            "command": "node \"${PLUGIN_ROOT}/skills/plan-review/references/annotate-server.js\" --codex-stop",
             "timeout": 345600
           }
         ]