@detergent-software/conductor 2.2.0-dev.2 → 3.0.0-dev.1

package/plugin/skills/work-item/trackers/ado-boards.md

@@ -0,0 +1,23 @@
+# ADO Boards
+
+For a profile with `"tracker": { "kind": "ado-boards", "key": "<KEY>", "query": "…" }`. Items are Azure DevOps work items, keyed `<KEY>-<work item id>` (`CAD-1234` is work item 1234), because ADO's ids are numbers alone. In `Approved via:`, this tracker's name is `Azure DevOps Boards`.
+
+Every read and write goes through `conduct` (SKILL.md), as the identity the conductor uses for Boards (the project's ADO token, else the `az login`): never `az boards` or a helper. This file is the vocabulary.
+
+**States** go by the state's type. These are the built-in names for the Scrum, Agile, Basic and CMMI processes. The profile's `tracker.states` adds names or overrides them (`{ "Blocked": "started" }`), and the conductor reads them the same way. A state neither knows is neither open nor closed: ask Jason before moving an item out of it. `conduct brief` gives the state and its type.
+
+| Phase table says | Type | Built-in states (Scrum process first) |
+|---|---|---|
+| not started | `backlog`, `unstarted` | New, Approved, To Do, Proposed (`backlog` only through `tracker.states`) |
+| in progress | `started` | Committed, Active, In Progress, Doing, Resolved |
+| in review | `started` | none of its own: the item stays in progress (Committed on Scrum), and the linked PR shows the review. A profile that adds a review state in `tracker.states` names it there. |
+| done | `completed` | Done, Closed |
+| canceled | `canceled` | Removed |
+
+The Started, PR opened and Landed notes move the item: Started to Committed and assigned, PR opened links the PR (an `ArtifactLink` for an ADO PR, a `Hyperlink` for a GitHub one), Landed to Done, by the profile's `tracker.transitions` over those defaults. A move ADO refuses (one its process doesn't allow) is a warning on `conduct note`'s stderr; the note stands.
+
+**Areas** are Area Paths below the profile's `tracker.areaRoot`, written with `/` (`Web`, `Api/Auth`). `conduct brief` gives the item's, and `conduct file` refuses any other and lists them.
+
+**Links.** A Predecessor is a blocker, a Successor an item it blocks, and Related is related; `conduct brief` lists each with its state.
+
+**Approvals.** The conductor reads an `approve` (or `approved`) or `revise: …` discussion comment by an approver (the conductor's identity, or one the profile's `approvers` names, by unique name) after the newest `<skill> · Plan` note, under the skill's name or an alias. A comment that is itself a `<skill> · ` note doesn't count, and one typed in the web UI counts as its text. `conduct brief KEY-n --fresh` gives the answer's words and `createdAt` (`approval`); quote it: `Approved via: Azure DevOps Boards (Jason's comment "<text>", <createdAt>)`.

package/plugin/skills/work-item/trackers/github-issues.md

@@ -0,0 +1,23 @@
+# GitHub Issues
+
+For a profile with `"tracker": { "kind": "github-issues", "key": "<KEY>" }`. Items are the issues of the code host's repo (or `tracker.owner` / `tracker.repo`), keyed `<KEY>-<issue number>` (`PAR-12` is issue #12). In `Approved via:`, this tracker's name is `GitHub Issues`.
+
+Every read and write goes through `conduct` (SKILL.md), as the project's gh account: never `gh issue` or the GitHub MCP tools. This file is the vocabulary.
+
+**States.** An issue is open or closed; the open phases are labels. `conduct brief` gives the state the conductor reads:
+
+| Phase table says | Issue |
+|---|---|
+| not started | open, with the queue label (`tracker.queueLabel`) and no phase label |
+| in progress | open, labelled `in-progress` |
+| in review | open, labelled `in-review` |
+| done | closed as completed |
+| canceled | closed as not planned, or as a duplicate |
+
+The Started, PR opened and Landed notes move the issue: Started labels it `in-progress` and assigns the gh account, PR opened swaps that for `in-review` and links the PR (a GitHub PR by the `Refs <owner>/<repo>#<n>` that `conduct pr create` adds to its body, any other by a comment with its URL), Landed closes it as completed and takes the phase label off. The profile's `tracker.transitions` names other labels.
+
+**Areas** are the labels that start with the profile's `tracker.areaPrefix` (such as `area:api`): the Area is the rest (`api`). `conduct brief` gives the issue's, and `conduct file` refuses any other.
+
+**Links.** Blockers are GitHub's issue dependencies ("blocked by"); one in another repo is `<owner>/<repo>#<n>`. GitHub has no related relation, so `conduct file` writes `Related: #n` in the new issue's body.
+
+**Approvals.** The conductor reads an `approve` or `revise: …` comment by an approver (the project's gh account, or a login the profile's `approvers` names) after the newest `<skill> · Plan` note, under the skill's name or an alias. `conduct brief KEY-n --fresh` gives the answer's words and `createdAt` (`approval`); quote it: `Approved via: GitHub Issues (Jason's comment "<text>", <createdAt>)`.

package/plugin/skills/work-item/trackers/linear.md

@@ -0,0 +1,21 @@
+# Linear
+
+For a profile with `"tracker": { "kind": "linear", "team": "<KEY>" }`. Items are Linear issues (`KEY-n`) of that team. In `Approved via:`, this tracker's name is `Linear`.
+
+Every read and write goes through `conduct` (SKILL.md), as the Linear key the conductor uses: never the Linear MCP tools. This file is the vocabulary.
+
+**Statuses** go by Linear's status type, which every team has, whatever it names its statuses. `conduct brief` gives both (`status.name`, `status.type`):
+
+| Phase table says | Status type | Usual name |
+|---|---|---|
+| not started | `backlog`, `unstarted`, `triage` | Backlog, Todo, Triage |
+| in progress | `started` | In Progress |
+| in review | `started` | In Review (the team's second started status) |
+| done | `completed` | Done |
+| canceled | `canceled`, `duplicate` | Canceled, Duplicate |
+
+The Started, PR opened and Landed notes move the item to in progress (and assign it to the key's owner), to in review (with the PR attached), and to done, by the profile's `tracker.transitions` over those defaults. A move Linear refuses is a warning on `conduct note`'s stderr; the note stands.
+
+**Areas** are labels of the profile's `tracker.areaLabelGroup` group (ATK's is `Area`, with labels such as `apps/conductor` or `skills/verify-atk`). An issue takes one; the group is single-select, so a change to several sub-Areas takes their parent (`skills`, not `skills/a` and `skills/b`). `conduct brief` gives the item's, and `conduct file` refuses any other and lists them.
+
+**Approvals.** The conductor reads an `approve` or `revise: …` comment by an approver (the account behind the conductor's Linear key, or one the profile's `approvers` names) after the newest `<skill> · Plan` note, under the skill's name or an alias. When Claude writes with Jason's key, his comments and Claude's notes carry the same author, so the `<skill> · ` heading is what tells them apart: a note is never an answer. `conduct brief KEY-n --fresh` gives the answer's words and `createdAt` (`approval`). An auto-approve rule's comment comes the same way, also as the key's owner, with words that start `approve: auto-approved by the conductor:`; record it as `Approved via: auto (…)`, not as Jason's comment. A read can lag a minute behind a write.

package/protocol/PROTOCOL.md

@@ -18,7 +18,7 @@ A note is a tracker comment whose first non-blank line is its heading:
 ## <skill> · <Phase>[ · <kind>: <one line>]
 ```
 
-- `<skill>` is the profile's `skills.work`, or one of its `skills.aliases`.
+- `<skill>` is the profile's `skills.work`, or one of its `skills.aliases`, without a `conductor:` prefix: the conductor plugin's `conductor:work-item` heads its notes `work-item · `.
 - `<Phase>` is one of the phases below.
 - A Handoff must carry a kind and a one-line text. A few other phases may carry one of their own kinds. All other phases carry none.
 - The heading is what tells a worker's note from a person's comment, since both can carry the same author.

package/build/mod.js

@@ -1,53 +0,0 @@
-import { existsSync } from 'node:fs';
-import { join, sep } from 'node:path';
-import { ConductorError } from "./errors.js";
-import { outputOf } from "./run.js";
-// The plugin's name and its marketplace's, both from mod/.claude-plugin.
-export const MOD_NAME = 'conductor';
-const MARKETPLACE = 'conductor';
-// `conduct install-mod`: installs the conductor mod (a Claude Code plugin) for every session of this
-// user, from the mod folder of this package as a folder marketplace. Claude Code reads a folder
-// marketplace's plugin from the folder itself, so `conduct upgrade` replaces the mod with the daemon,
-// and open sessions pick it up with /reload-plugins.
-export async function installMod(dir, deps) {
-    if (!existsSync(join(dir, '.claude-plugin', 'marketplace.json'))) {
-        throw new ConductorError(`${dir} holds no conductor mod`, [
-            'reinstall the package: npm i -g @detergent-software/conductor',
-        ]);
-    }
-    // Every session would read the mod from a folder that goes away with its worktree.
-    if (dir.includes(`${sep}.claude${sep}worktrees${sep}`)) {
-        throw new ConductorError(`${dir} is in a worktree, which goes away`, [
-            'run install-mod from the main checkout or the npm package',
-            'to try a worktree build: claude --plugin-dir apps/conductor/mod',
-        ]);
-    }
-    // A marketplace of that name added from another folder (a linked build, an older install) would
-    // keep its path, since install adds a marketplace only when none of the name is there. None is fine.
-    await deps.claude(['plugin', 'marketplace', 'remove', MARKETPLACE]);
-    const result = await deps.claude(['plugin', 'install', MOD_NAME, '--marketplace', dir, '--scope', 'user']);
-    if (result.code !== 0)
-        throw new ConductorError('could not install the conductor mod', [outputOf(result, 1000)]);
-    deps.out(`installed the conductor mod from ${dir}`);
-    deps.out('open sessions load it with /reload-plugins; the console session is the one started with CONDUCTOR_CONSOLE=1');
-}
-// `conduct install-mod --remove`: uninstalls the mod and forgets its marketplace, saying what each
-// step did.
-export async function removeMod(deps) {
-    const uninstalled = await deps.claude(['plugin', 'uninstall', `${MOD_NAME}@${MARKETPLACE}`, '--scope', 'user']);
-    const forgot = await deps.claude(['plugin', 'marketplace', 'remove', MARKETPLACE]);
-    if (uninstalled.code !== 0 && forgot.code !== 0) {
-        throw new ConductorError('could not remove the conductor mod', [outputOf(uninstalled, 500), outputOf(forgot, 500)]);
-    }
-    if (uninstalled.code !== 0) {
-        deps.out(`removed the conductor marketplace; the plugin uninstall said: ${outputOf(uninstalled, 500)}`);
-    }
-    else if (forgot.code !== 0) {
-        deps.out(`uninstalled the conductor mod; removing its marketplace said: ${outputOf(forgot, 500)}`);
-    }
-    else {
-        deps.out('removed the conductor mod');
-    }
-    deps.out('open sessions drop it with /reload-plugins');
-}
-//# sourceMappingURL=mod.js.map

package/build/mod.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"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"}

package/mod/.claude-plugin/marketplace.json

@@ -1,6 +0,0 @@
-{
-  "name": "conductor",
-  "description": "The conductor mod, shipped inside @detergent-software/conductor and installed by `conduct install-mod`.",
-  "owner": { "name": "Emergent Software" },
-  "plugins": [{ "name": "conductor", "source": "./" }]
-}

package/mod/.claude-plugin/plugin.json

@@ -1,7 +0,0 @@
-{
-  "name": "conductor",
-  "version": "1.0.0",
-  "description": "The conductor console's plumbing: the inbox band, the fleet pane, zero-token commands, Remote Control pushes and escalation wake-ups.",
-  "author": { "name": "Emergent Software" },
-  "types": "./types/index.d.ts"
-}

package/mod/README.md

@@ -1,19 +0,0 @@
-# Conductor mod
-
-A Claude Code plugin (a hooks module) that does the conductor console's plumbing in code, so it costs no tokens. Only the console (`CONDUCTOR_CONSOLE=1`) gets anything from it: the inbox band, the fleet pane, `/conductor` `/inbox` `/approve` `/revise` `/attach` `/notify` `/pause` `/unpause` `/focus-project`, toasts, Remote Control pushes (and the one warning when Remote Control is off), the one model wake-up for an escalation, a nudge to load `/conductor-console` in a console started without it, and a warm prompt cache while the console idles (a ping every 55 minutes, or a `/clear` past 150k or a night of pings). What it shows and does is in the conductor README's *Mod* section (`apps/conductor/README.md`).
-
-Install it with the daemon's CLI, which ships this folder:
-
-```text
-conduct install-mod
-```
-
-| File | Holds |
-|---|---|
-| `hooks/register.tsx` | the hooks: session start, commands, the band, the pane, the event stream; only its top-level functions take `$` |
-| `hooks/model.ts` | the logic without the engine: parsing the daemon's answers, what the band and pane show, what each event asks for |
-| `types/index.d.ts` | the `$.state` contract (`conductor.snapshot`, `confirming`, `expanded`) |
-| `tests/conductor.test.tsx` | `claude plugin test`: the hooks against the engine, the daemon faked beneath them |
-| `tests/model.spec.ts` | vitest (`pnpm -C apps/conductor test`, in CI): `model.ts` |
-
-`pnpm -C apps/conductor typecheck` type-checks this folder in CI against Claude Code's plugin API, kept in `apps/conductor/mod-types/` (the conductor README's *Mod* section says how to refresh it).