openplanr 3.0.1 → 3.1.1

package/lib/host-packages/openai/openplanr/skills/plan/scripts/planning-ids.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { mkdir, open, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { open, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 
 const KINDS = Object.freeze(['SPEC', 'US', 'T']);
 const EMPTY = Object.freeze({ SPEC: 1, US: 1, T: 1 });
@@ -71,9 +71,55 @@ function parseArgs(argv) {
   return options;
 }
 
+const shellQuote = (value) => (/^[\w./-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`);
+
+/** Returns the nearest `.planr/config.json` at or above `directory` and the specs folder it configures. */
+async function configuredRoot(directory) {
+  for (let current = directory; ; current = dirname(current)) {
+    const configPath = join(current, '.planr', 'config.json');
+    const raw = await readFile(configPath, 'utf8').catch((error) => {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+      throw error;
+    });
+    if (raw !== null) {
+      let agile;
+      try {
+        agile = JSON.parse(raw).outputPaths?.agile ?? '.planr';
+      } catch (error) {
+        throw new Error(`Project config ${configPath} is not valid JSON: ${error.message}`);
+      }
+      if (typeof agile !== 'string') throw new Error(`Project config ${configPath} has a non-string outputPaths.agile.`);
+      return { configPath, expected: resolve(current, agile, 'specs') };
+    }
+    if (dirname(current) === current) return null;
+  }
+}
+
+/** Accepts only an existing directory that the nearest project config names as its planning folder. */
+async function assertPlanningRoot(planningRoot) {
+  const project = await configuredRoot(planningRoot);
+  if (!project) {
+    throw new Error(`Planning root ${planningRoot} is not inside an OpenPlanr project: no .planr/config.json in it or any parent directory.`);
+  }
+  const { configPath, expected } = project;
+  if (planningRoot !== expected) {
+    throw new Error(`Planning root ${planningRoot} is not the planning folder configured by ${configPath}, which expects ${expected}.`);
+  }
+  const status = await stat(planningRoot).catch((error) => {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  });
+  if (!status) {
+    throw new Error(
+      `Planning root ${planningRoot} does not exist; ${configPath} expects it. Create it with \`mkdir -p ${shellQuote(planningRoot)}\`, or fix outputPaths.agile in ${configPath}.`,
+    );
+  }
+  if (!status.isDirectory()) throw new Error(`Planning root ${planningRoot} is not a directory; ${configPath} expects a directory there.`);
+}
+
 async function reserve({ root, preview, counts }) {
   const planningRoot = resolve(root);
-  if (!preview) await mkdir(planningRoot, { recursive: true });
+  await assertPlanningRoot(planningRoot);
   const run = async () => {
     const sequence = await currentSequence(planningRoot);
     const ids = Object.fromEntries(

package/lib/host-packages/openai/openplanr/skills/share/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: share
+description: Share a status report, sprint note or release notes with the team as a chat message draft that the user approves and sends. Use when the user asks to post a planning update to chat.
+argument-hint: "[status|sprint|release] [destination]"
+license: MIT
+---
+
+# OpenPlanr Share
+
+Turn the current planning state into a team update and hand it to ~~chat as a
+draft that the user reviews and sends. Perform the work in this session. Nothing
+leaves the session until the user approves the exact text and destination.
+
+## Choose the update
+
+The first argument picks the source; default to `status`.
+
+- `status`: the delivery report `planr-status` gives. Read the planning artifacts
+  directly, or use `openplanr status --json` when it is available.
+- `sprint`: the current sprint under `.planr/sprints/`: the one in progress, else
+  the most recent. Use its goal, selected items, progress and leftovers.
+- `release`: the newest release notes or changelog entry, or the version the
+  user names.
+
+When the working directory has no OpenPlanr planning files for the chosen source,
+say so and ask which project to use, or stop. Never build an update from guesses.
+
+The second argument is the destination: a channel or person. When it names a chat
+product from [connectors](references/connectors.md) instead, use that product's
+connection and still ask for the channel or person. When it is missing, ask for it.
+Never pick a destination yourself.
+
+## Write it
+
+Lead with the outcome in one line, then at most ten short lines: what finished,
+what is in progress, what is blocked and who can unblock it, and what comes next.
+Use counts and dates, link pull requests or issues when their URLs are known, and
+leave out local file paths, backlog IDs and internal detail the team cannot act
+on. Never include credentials or the contents of secret files.
+
+Format the text for where it goes, as listed under "Message format" in
+[connectors](references/connectors.md): when drafting through a connector, use the
+connector's input format, and follow the connector tool's own description when it
+states one; for text the user pastes, use the paste format. Use plain text when no
+format is listed.
+
+## Preview, then ask
+
+Show the complete text exactly as it will appear, the destination, and what will
+happen: "create a draft in <destination>; nothing is sent". Ask through the host's
+structured question surface, or one short chat question when there is none:
+create the draft, edit the text, or cancel. Create nothing without a clear yes.
+After an edit, preview again.
+
+## If ~~chat is connected
+
+A category is connected when the host exposes a tool for one of its products,
+loaded or deferred. On approval, use that connection to create a message draft
+in the destination, then report where the draft is and that the user sends it
+from the chat app.
+
+- Send directly only when the user explicitly asks to send and the connection
+  can send; confirm the destination once more first.
+- When the connection cannot create drafts, say so and offer to send on an
+  explicit request, or print the text instead.
+- When the connection fails, for example because a workspace admin has not
+  approved the app, report the error, print the text ready to paste, and stop.
+
+## With nothing connected
+
+Print the update ready to paste and the one connect step for the current host
+from [connectors](references/connectors.md), and suggest `/planr:connect`. Make no
+remote call and do not retry; the user runs this skill again once connected.
+
+## Rules
+
+- Never ask for, read, store or print a token, key or password, and never edit
+  host configuration.
+- One destination per run.
+- Never change planning files.
+
+## Return
+
+Lead with the result: draft created (where), sent (where, on explicit request),
+printed for pasting, or cancelled. Name the source used and any section that was
+empty or unavailable.

package/lib/host-packages/openai/openplanr/skills/share/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "OpenPlanr Share"
+  short_description: "Share a status report, sprint note or release notes with the…"
+  default_prompt: "Use $planr:share to share a status report, sprint note or release notes with the team as a chat message draft that the user approves and sends. Use when the user asks to post a planning update to chat."
+policy:
+  allow_implicit_invocation: false

package/lib/host-packages/openai/openplanr/skills/share/openplanr.skill.json

@@ -0,0 +1,37 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-share",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/connectors.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/share/references/connectors.md

@@ -0,0 +1,62 @@
+# Connectors
+
+OpenPlanr skills name a kind of service, such as `~~chat`, instead of a product. Connect
+the product your team uses through your host: the vendor publishes the connector, and
+you sign in through the host. OpenPlanr bundles no connectors; they and their credentials
+live in your host. Two optional features need a token: Linear sync (`openplanr linear`) and
+company sign-in (`openplanr company login`). Only when you use them does OpenPlanr store a
+token, in your OS keychain, or in an encrypted file at `~/.planr/credentials.enc` if you set
+`PLANR_CREDENTIAL_FILE_PASSPHRASE`. Tokens are sent only to Linear or to the company server
+you sign in to.
+`openplanr company logout` removes company tokens.
+Every skill also works with nothing connected and reports any remote step it skipped.
+
+| Category | Placeholder | Products |
+| --- | --- | --- |
+| Chat | `~~chat` | Slack, Microsoft Teams |
+| Project tracker | `~~project tracker` | Linear, GitHub Issues, Jira, Asana |
+| Source control | `~~source control` | GitHub, GitLab, Bitbucket |
+
+Never paste a token into a chat, file or command for OpenPlanr. After you connect a
+service, start a new request so the host loads its tools.
+
+## Chat (`~~chat`)
+
+Share a status report, sprint note or release notes as a message draft that you review and send yourself.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Slack | Message drafts | Run `/plugin install slack@claude-plugins-official`, then sign in to Slack from `/mcp`. A workspace admin may need to approve the app. | Install Slack from `/plugins` and sign in when asked. A workspace admin may need to approve the app. | Run `/add-plugin slack`, or install Slack from Customize, then sign in when asked. A workspace admin may need to approve the app. |
+
+Message format for Slack, drafting through the connector: standard Markdown, which the connector converts on send ([Slack's messaging guidance](https://github.com/slackapi/slack-mcp-plugin/blob/main/skills/slack-messaging/SKILL.md)): `**bold**`, `_italic_`, `[link text](https://example.com)`, `-` lists, `>` quotes. Do not use mrkdwn's `*bold*` or `<url|text>` here.
+
+Message format for Slack, text to paste: Slack mrkdwn ([formatting](https://docs.slack.dev/messaging/formatting-message-text)): `*bold*`, `_italic_`, `<https://example.com|link text>`, lines starting with `•` or `-` for lists, `>` for quotes; no headings or tables; escape `&`, `<` and `>` as `&amp;`, `&lt;` and `&gt;`.
+
+Also works with: [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Slack](https://docs.slack.dev/ai/slack-mcp-server) on 2026-10-09, [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) on 2026-10-09.
+
+## Project tracker (`~~project tracker`)
+
+Push planning status to linked issues after you approve each change, and read issue state back.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Linear | OpenPlanr syncs with it | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install Linear from `/plugins` and sign in when asked. | Run `/add-plugin linear`, or install Linear from Customize, then sign in when asked. |
+| GitHub Issues | OpenPlanr syncs with it | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context), [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Linear](https://linear.app/docs/mcp) on 2026-10-09, [GitHub Issues](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09, [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) on 2026-10-09.
+
+## Source control (`~~source control`)
+
+Read pull request and branch state for status reports and sprint reviews.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| GitHub | Read for context | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) (read for context), [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [GitHub](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) on 2026-10-09, [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09.

package/lib/host-packages/openai/openplanr/skills/ship/SKILL.md

@@ -62,13 +62,16 @@ Discover checks in this order:
 4. applicable CI and pre-commit configuration.
 
 The packaged read-only [verification discovery helper](scripts/discover-verification.mjs)
-may list candidates. Resolve it relative to this `SKILL.md`; pass the repository
-root and task path. It never executes checks or writes files. If it is unavailable,
+may list candidates. Resolve it relative to this `SKILL.md` and run
+`node <helper> --project <repository-root> --task <task-path>`; omit `--task` for a
+direct request. It never executes checks or writes files. If it is unavailable,
 inspect those four sources directly. Missing commands are diagnostics, not a
 reason to invent or skip all verification.
 
 Run the strongest applicable focused checks while working, then the relevant
-regression checks. Fix failures caused by the change and rerun affected checks.
+regression checks. Run each check on its own or under `set -o pipefail`, and judge
+it by its own exit code; to shorten output, write it to a log and read the tail.
+Fix failures caused by the change and rerun affected checks.
 Read [the result contract](references/result-contract.md) before reporting.
 
 Do not write progress into an approved design package. The studio derives

package/lib/host-packages/openai/openplanr/skills/ship/scripts/discover-verification.mjs

@@ -5,6 +5,7 @@ import { resolve } from 'node:path';
 
 const COMMAND = /^(?:npm|npx|pnpm|yarn|bun|node|deno|cargo|go|make|just|pytest|python(?:3)?\s+-m|dotnet|mvn|gradle|\.\/gradlew)\b/u;
 const PRIORITY = Object.freeze(['test', 'test:unit', 'test:integration', 'typecheck', 'check', 'lint', 'build']);
+const USAGE = 'Usage: node discover-verification.mjs --project <repository-root> [--task <task-path>]';
 const read = (path) => readFileSync(path, 'utf8').replace(/\r\n/gu, '\n');
 
 function commands(markdown) {
@@ -57,7 +58,7 @@ function parseArgs(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     if (argv[index] === '--project') options.project = argv[++index];
     else if (argv[index] === '--task') options.task = argv[++index];
-    else throw new Error(`Unknown argument: ${argv[index]}`);
+    else throw new Error(`Unknown argument: ${argv[index]}\n${USAGE}`);
   }
   return options;
 }

package/lib/host-packages/openai/openplanr/skills/sprint/SKILL.md

@@ -36,7 +36,7 @@ capability; it never blocks the run. Name every degraded input in `Issues`.
 | Capacity (engineers × working days) | Fit the list and name the overflow | Ask once; default 1 engineer × 10 days, stated in the return |
 | Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `openplanr sprint diff` is possible | First run, no diff |
 | Last Operate cycle | Rank its unfinished actions alongside | Skipped silently |
-| Linear or GitHub connection ([tracker connections](references/tracker-connections.md)) | Update linked issues on approval, read PR state | Local files only; report the external step as not run and name the connection to add |
+| ~~project tracker or ~~source control ([connectors](references/connectors.md)) | Update linked issues on approval, read PR state | Local files only; report the external step as not run and name the category to add |
 
 ## Step 0: Frame the run
 
@@ -135,11 +135,20 @@ openplanr sprint apply SPRINT-NNN --dry-run          # show the status and prior
 openplanr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
 ```
 
-Then update the issue linked to each changed item through the host's Linear or
-GitHub connection, with the status mapping in
-[tracker connections](references/tracker-connections.md), and report the items that
-were not updated. When the CLI is unavailable, apply the same status changes with
-the repository's own vocabulary and commit them with the same message.
+Then, if ~~project tracker is connected, update the issue linked to each changed
+item through the host's connection, with the status mapping in the
+[tracker sync reference](references/tracker-connections.md). Before any remote write,
+list every issue change: each issue to create, update, close or reopen, with its
+title and the status it moves to. Write only when the request explicitly asked for
+that push or the user approves the list. Afterwards, report each item that was not
+updated and why, and name the category and product used.
+
+With nothing connected, the local apply is the whole step: report the tracker
+update as not run and give the current host's step from
+[connectors](references/connectors.md).
+
+When the CLI is unavailable, apply the same status changes with the repository's
+own vocabulary and commit them with the same message.
 
 Close a finished sprint with `openplanr sprint close SPRINT-NNN`; it records the
 leftovers the next run carries.

package/lib/host-packages/openai/openplanr/skills/sprint/openplanr.skill.json

@@ -44,6 +44,17 @@
       ],
       "executable": false
     },
+    {
+      "path": "references/connectors.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
     {
       "path": "references/tracker-connections.md",
       "kind": "reference",

package/lib/host-packages/openai/openplanr/skills/sprint/references/connectors.md

@@ -0,0 +1,62 @@
+# Connectors
+
+OpenPlanr skills name a kind of service, such as `~~chat`, instead of a product. Connect
+the product your team uses through your host: the vendor publishes the connector, and
+you sign in through the host. OpenPlanr bundles no connectors; they and their credentials
+live in your host. Two optional features need a token: Linear sync (`openplanr linear`) and
+company sign-in (`openplanr company login`). Only when you use them does OpenPlanr store a
+token, in your OS keychain, or in an encrypted file at `~/.planr/credentials.enc` if you set
+`PLANR_CREDENTIAL_FILE_PASSPHRASE`. Tokens are sent only to Linear or to the company server
+you sign in to.
+`openplanr company logout` removes company tokens.
+Every skill also works with nothing connected and reports any remote step it skipped.
+
+| Category | Placeholder | Products |
+| --- | --- | --- |
+| Chat | `~~chat` | Slack, Microsoft Teams |
+| Project tracker | `~~project tracker` | Linear, GitHub Issues, Jira, Asana |
+| Source control | `~~source control` | GitHub, GitLab, Bitbucket |
+
+Never paste a token into a chat, file or command for OpenPlanr. After you connect a
+service, start a new request so the host loads its tools.
+
+## Chat (`~~chat`)
+
+Share a status report, sprint note or release notes as a message draft that you review and send yourself.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Slack | Message drafts | Run `/plugin install slack@claude-plugins-official`, then sign in to Slack from `/mcp`. A workspace admin may need to approve the app. | Install Slack from `/plugins` and sign in when asked. A workspace admin may need to approve the app. | Run `/add-plugin slack`, or install Slack from Customize, then sign in when asked. A workspace admin may need to approve the app. |
+
+Message format for Slack, drafting through the connector: standard Markdown, which the connector converts on send ([Slack's messaging guidance](https://github.com/slackapi/slack-mcp-plugin/blob/main/skills/slack-messaging/SKILL.md)): `**bold**`, `_italic_`, `[link text](https://example.com)`, `-` lists, `>` quotes. Do not use mrkdwn's `*bold*` or `<url|text>` here.
+
+Message format for Slack, text to paste: Slack mrkdwn ([formatting](https://docs.slack.dev/messaging/formatting-message-text)): `*bold*`, `_italic_`, `<https://example.com|link text>`, lines starting with `•` or `-` for lists, `>` for quotes; no headings or tables; escape `&`, `<` and `>` as `&amp;`, `&lt;` and `&gt;`.
+
+Also works with: [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Slack](https://docs.slack.dev/ai/slack-mcp-server) on 2026-10-09, [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) on 2026-10-09.
+
+## Project tracker (`~~project tracker`)
+
+Push planning status to linked issues after you approve each change, and read issue state back.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Linear | OpenPlanr syncs with it | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install Linear from `/plugins` and sign in when asked. | Run `/add-plugin linear`, or install Linear from Customize, then sign in when asked. |
+| GitHub Issues | OpenPlanr syncs with it | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context), [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Linear](https://linear.app/docs/mcp) on 2026-10-09, [GitHub Issues](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09, [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) on 2026-10-09.
+
+## Source control (`~~source control`)
+
+Read pull request and branch state for status reports and sprint reviews.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| GitHub | Read for context | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) (read for context), [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [GitHub](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) on 2026-10-09, [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09.

package/lib/host-packages/openai/openplanr/skills/sprint/references/tracker-connections.md

@@ -1,7 +1,9 @@
-# GitHub and Linear connections
+# Tracker sync reference
 
-These skills store and read no GitHub or Linear credentials. Remote steps run through a
-connection the host already has; the planning files stay the source of truth.
+These skills store and read no tracker or source control credentials. Remote steps
+run through a connection the host already has; the planning files stay the source of
+truth. OpenPlanr syncs with the trackers marked "OpenPlanr syncs with it" in
+[connectors](connectors.md), and reads other products for context only.
 
 ## Use the host's connection
 
@@ -14,16 +16,10 @@ command, URL or file.
 
 ## When a connection is missing
 
-Finish the local work first. Then report the remote step as not run and give the one
-line for the current host:
-
-| Host | Linear | GitHub |
-| --- | --- | --- |
-| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
-| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
-| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
-
-Ask the user to try again once connected; never retry the remote step on your own.
+Finish the local work first. Then report the remote step as not run, naming the
+category, and give the one connect step for the current host from
+[connectors](connectors.md). Ask the user to try again once connected; never retry the
+remote step on your own.
 
 ## Status mapping
 

package/lib/host-packages/openai/openplanr/skills/status/SKILL.md

@@ -11,9 +11,6 @@ planning artifacts, task statuses, dependency graph, current branch, and relevan
 runtime markers directly. Use the optional deterministic `openplanr status --json`
 utility when available, but do not require it or a semantic subprocess.
 
-Add GitHub or Linear lookups only when the user requests live remote state, through
-the host's connections as described in [tracker connections](references/tracker-connections.md).
-Keep local results useful when a connection is unavailable, and name the one to add.
 Report counts, ready and blocked work, dependency problems, and the most useful next
 action. Do not repair artifacts, start Plan or Ship, or change lifecycle state.
 
@@ -21,6 +18,20 @@ When the OpenPlanr dashboard is running (`planr-dashboard`), the same delivery
 state is browsable there: `#/overview` for the whole project, `#/detail/<id>`
 for one feature. This is navigation only.
 
+## With nothing connected
+
+The report comes entirely from local planning files and git. When the user asks
+for live remote state, report that step as not run, name the category it needs,
+and give the current host's step from [connectors](references/connectors.md).
+
+## If ~~project tracker or ~~source control is connected
+
+Add remote lookups only when the user requests live remote state: issue state
+from ~~project tracker, pull request and branch state from ~~source control,
+through the host's connections as described in the
+[tracker sync reference](references/tracker-connections.md). Name the category each
+remote fact came from. Status never writes to a remote service.
+
 ## Return
 
 Lead with the current delivery state, then summarize ready, blocked and pending

package/lib/host-packages/openai/openplanr/skills/status/openplanr.skill.json

@@ -22,6 +22,17 @@
       ],
       "executable": false
     },
+    {
+      "path": "references/connectors.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
     {
       "path": "references/tracker-connections.md",
       "kind": "reference",

package/lib/host-packages/openai/openplanr/skills/status/references/connectors.md

@@ -0,0 +1,62 @@
+# Connectors
+
+OpenPlanr skills name a kind of service, such as `~~chat`, instead of a product. Connect
+the product your team uses through your host: the vendor publishes the connector, and
+you sign in through the host. OpenPlanr bundles no connectors; they and their credentials
+live in your host. Two optional features need a token: Linear sync (`openplanr linear`) and
+company sign-in (`openplanr company login`). Only when you use them does OpenPlanr store a
+token, in your OS keychain, or in an encrypted file at `~/.planr/credentials.enc` if you set
+`PLANR_CREDENTIAL_FILE_PASSPHRASE`. Tokens are sent only to Linear or to the company server
+you sign in to.
+`openplanr company logout` removes company tokens.
+Every skill also works with nothing connected and reports any remote step it skipped.
+
+| Category | Placeholder | Products |
+| --- | --- | --- |
+| Chat | `~~chat` | Slack, Microsoft Teams |
+| Project tracker | `~~project tracker` | Linear, GitHub Issues, Jira, Asana |
+| Source control | `~~source control` | GitHub, GitLab, Bitbucket |
+
+Never paste a token into a chat, file or command for OpenPlanr. After you connect a
+service, start a new request so the host loads its tools.
+
+## Chat (`~~chat`)
+
+Share a status report, sprint note or release notes as a message draft that you review and send yourself.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Slack | Message drafts | Run `/plugin install slack@claude-plugins-official`, then sign in to Slack from `/mcp`. A workspace admin may need to approve the app. | Install Slack from `/plugins` and sign in when asked. A workspace admin may need to approve the app. | Run `/add-plugin slack`, or install Slack from Customize, then sign in when asked. A workspace admin may need to approve the app. |
+
+Message format for Slack, drafting through the connector: standard Markdown, which the connector converts on send ([Slack's messaging guidance](https://github.com/slackapi/slack-mcp-plugin/blob/main/skills/slack-messaging/SKILL.md)): `**bold**`, `_italic_`, `[link text](https://example.com)`, `-` lists, `>` quotes. Do not use mrkdwn's `*bold*` or `<url|text>` here.
+
+Message format for Slack, text to paste: Slack mrkdwn ([formatting](https://docs.slack.dev/messaging/formatting-message-text)): `*bold*`, `_italic_`, `<https://example.com|link text>`, lines starting with `•` or `-` for lists, `>` for quotes; no headings or tables; escape `&`, `<` and `>` as `&amp;`, `&lt;` and `&gt;`.
+
+Also works with: [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Slack](https://docs.slack.dev/ai/slack-mcp-server) on 2026-10-09, [Microsoft Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-teams-tools) on 2026-10-09.
+
+## Project tracker (`~~project tracker`)
+
+Push planning status to linked issues after you approve each change, and read issue state back.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| Linear | OpenPlanr syncs with it | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install Linear from `/plugins` and sign in when asked. | Run `/add-plugin linear`, or install Linear from Customize, then sign in when asked. |
+| GitHub Issues | OpenPlanr syncs with it | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context), [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [Linear](https://linear.app/docs/mcp) on 2026-10-09, [GitHub Issues](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [Jira](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09, [Asana](https://developers.asana.com/docs/using-asanas-mcp-server) on 2026-10-09.
+
+## Source control (`~~source control`)
+
+Read pull request and branch state for status reports and sprint reviews.
+
+| Product | Use | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- | --- |
+| GitHub | Read for context | Install the GitHub CLI from cli.github.com and run `gh auth login`. | Install GitHub from `/plugins` and sign in when asked, or install the GitHub CLI and run `gh auth login`. | Install the GitHub CLI from cli.github.com and run `gh auth login`. |
+
+Also works with: [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) (read for context), [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) (read for context). Add the vendor's connector in your host the same way.
+
+Verified: [GitHub](https://cli.github.com/manual/gh_auth_login) on 2026-10-09, [GitLab](https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/) on 2026-10-09, [Bitbucket](https://support.atlassian.com/atlassian-ai-gateway/docs/get-started-with-the-atlassian-remote-mcp-server/) on 2026-10-09.

package/lib/host-packages/openai/openplanr/skills/status/references/tracker-connections.md

@@ -1,7 +1,9 @@
-# GitHub and Linear connections
+# Tracker sync reference
 
-These skills store and read no GitHub or Linear credentials. Remote steps run through a
-connection the host already has; the planning files stay the source of truth.
+These skills store and read no tracker or source control credentials. Remote steps
+run through a connection the host already has; the planning files stay the source of
+truth. OpenPlanr syncs with the trackers marked "OpenPlanr syncs with it" in
+[connectors](connectors.md), and reads other products for context only.
 
 ## Use the host's connection
 
@@ -14,16 +16,10 @@ command, URL or file.
 
 ## When a connection is missing
 
-Finish the local work first. Then report the remote step as not run and give the one
-line for the current host:
-
-| Host | Linear | GitHub |
-| --- | --- | --- |
-| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
-| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
-| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
-
-Ask the user to try again once connected; never retry the remote step on your own.
+Finish the local work first. Then report the remote step as not run, naming the
+category, and give the one connect step for the current host from
+[connectors](connectors.md). Ask the user to try again once connected; never retry the
+remote step on your own.
 
 ## Status mapping