Update Decodex plugin skills

README.md

@@ -27,8 +27,8 @@ Repo-native agent orchestration and public Codex signal publishing.
   signal drafting, and X post drafting.
 - Publisher workflow for checked-in upstream impact classification and reviewable X
   drafts for `@decodexspace`.
-- Installable Decodex plugin with reusable agent-facing skills for manual CLI,
-  automation, commit, land, and labels.
+- Installable Decodex plugin with reusable agent-facing skills for planning,
+  manual CLI, automation, commit, land, and labels.
 - Repository documentation split by question type into spec, runbook, reference, and
   decision lanes.
 
@@ -96,13 +96,13 @@ without publishing every low-level or skipped item to the static site or Git his
 From the workspace root:
 
 ```sh
-cargo run -p decodex -- --help
-cargo run -p decodex -- probe stdio://
-cargo run -p decodex -- project list
-cargo run -p decodex -- status
-cargo run -p decodex -- diagnose --json
-cargo run -p decodex -- run --dry-run
-cargo run -p decodex -- serve --interval 60s --listen-address 127.0.0.1:8912
+cargo run -p decodex --bin decodex -- --help
+cargo run -p decodex --bin decodex -- probe stdio://
+cargo run -p decodex --bin decodex -- project list
+cargo run -p decodex --bin decodex -- status
+cargo run -p decodex --bin decodex -- diagnose --json
+cargo run -p decodex --bin decodex -- run --dry-run
+cargo run -p decodex --bin decodex -- serve --interval 60s --listen-address 127.0.0.1:8912
 ```
 
 ### Install from Source

docs/decisions/decodex-plugin-source.md

@@ -33,6 +33,8 @@ instructions.
 The plugin should own reusable agent-facing procedures and mode routing:
 
 - `decodex` for choosing manual CLI mode versus automation mode
+- `planning` for Decodex-friendly issue splitting, queue shaping, dependencies, and
+  concurrency
 - `manual-cli` for operator CLI use
 - `automation` for retained-lane control-plane use
 - `commit` for human-driven `decodex commit`

docs/index.md

@@ -16,7 +16,7 @@ The split below is by question type, not by human-versus-agent audience.
   `~/.codex/decodex/projects/<service-id>/` when the question is about validation,
   tracker routing, or execution policy.
 - Read `plugins/decodex/skills/decodex/SKILL.md` when the question is how an agent
-  should use Decodex in manual CLI mode or runtime-owned automation mode.
+  should plan for Decodex, use manual CLI mode, or use runtime-owned automation mode.
 - Then choose one primary lane:
   - `docs/spec/index.md` when the question is "what must be true?"
   - `docs/runbook/index.md` when the question is "which sequence should I execute?"

docs/reference/workspace-layout.md

@@ -25,7 +25,7 @@ should not be treated as repository source.
 | `artifacts/archive/` | Checked-in manifests for cold Radar archive batches stored as GitHub Release assets. |
 | `artifacts/social/` | Checked-in Publisher social post drafts and publication evidence. |
 | `dev/skills/` | Repository-development skills for Radar upstream triage, code analysis, release analysis, GitHub signal drafting, and X post drafting. These are not part of installable plugin distribution. |
-| `plugins/decodex/` | Canonical installable Decodex plugin source and reusable agent-facing skills, including manual CLI, automation, commit, land, and labels. |
+| `plugins/decodex/` | Canonical installable Decodex plugin source and reusable agent-facing skills, including planning, manual CLI, automation, commit, land, and labels. |
 | `docs/spec/` | Normative runtime, workflow, site, and content contracts. |
 | `docs/runbook/` | Operator procedures, validation sequences, deployment steps, and content workflows. |
 | `docs/reference/` | Current repository and artifact surface maps. |
@@ -46,7 +46,7 @@ The root `Cargo.toml` is a workspace manifest. It does not define a root package
 layout. Use package-qualified commands when invoking the runtime from the workspace root:
 
 ```sh
-cargo run -p decodex -- --help
+cargo run -p decodex --bin decodex -- --help
 cargo build -p decodex
 cargo install --path apps/decodex --force
 ```

docs/runbook/linear-archive-hygiene.md

@@ -35,7 +35,7 @@ Verification:
 Use the dry-run default before demos or large issue seeding:
 
 ```sh
-cargo run -p decodex -- archive-linear --repo-label repo:decodex --older-than-days 30
+cargo run -p decodex --bin decodex -- archive-linear --repo-label repo:decodex --older-than-days 30
 ```
 
 The command prints the terminal issues that would be archived, using `updatedAt`
@@ -44,7 +44,7 @@ as the age cutoff. It does not mutate Linear unless `--execute` is present.
 For another Decodex-managed repo, run from that registered checkout or pass its centralized config:
 
 ```sh
-cargo run -p decodex -- archive-linear --config ~/.codex/decodex/projects/ashen-vale --repo-label repo:ashen-vale --older-than-days 30
+cargo run -p decodex --bin decodex -- archive-linear --config ~/.codex/decodex/projects/ashen-vale --repo-label repo:ashen-vale --older-than-days 30
 ```
 
 ## Execute
@@ -53,7 +53,7 @@ After the dry run shows only issues that should leave the active tracker view,
 repeat the command with `--execute`:
 
 ```sh
-cargo run -p decodex -- archive-linear --repo-label repo:decodex --older-than-days 30 --execute
+cargo run -p decodex --bin decodex -- archive-linear --repo-label repo:decodex --older-than-days 30 --execute
 ```
 
 This archives issues through Linear `issueArchive` with `trash = false`. It does

docs/runbook/self-dogfood-pilot.md

@@ -4,7 +4,7 @@ Goal: Run the `decodex` MVP against one target repository and a bounded set of q
 Read this when: You are preparing a dry run or live self-dogfood pilot and need the bounded operator procedure for config, target-repo requirements, and expected run behavior.
 Preconditions: `codex app-server` is available locally; `gh` is available locally for live PR-backed handoff validation, merge inspection, and retained branch cleanup; the target repository exists on disk; the project contract exists under `~/.codex/decodex/projects/<service-id>/`; referenced `WORKFLOW.md [context.read_first]` files exist in `[paths].repo_root`; the Linear team exposes the required workflow states; and the tracker and GitHub token env-var names are configured through `tracker.api_key_env_var` and `github.token_env_var` in the centralized project config.
 Depends on: `docs/spec/runtime.md`, `docs/spec/workflow-file.md`, `docs/spec/app-server.md`, the registered project `WORKFLOW.md`, and `Makefile.toml` for repo-native verification tasks.
-Verification: `cargo run -p decodex -- probe`; `cargo run -p decodex -- project add ~/.codex/decodex/projects/decodex`; `cargo run -p decodex -- project list`; `cargo run -p decodex -- run --dry-run`; and, when the environment is ready, `cargo run -p decodex -- run`.
+Verification: `cargo run -p decodex --bin decodex -- probe`; `cargo run -p decodex --bin decodex -- project add ~/.codex/decodex/projects/decodex`; `cargo run -p decodex --bin decodex -- project list`; `cargo run -p decodex --bin decodex -- run --dry-run`; and, when the environment is ready, `cargo run -p decodex --bin decodex -- run`.
 
 ## Alignment note
 
@@ -27,7 +27,7 @@ Verification: `cargo run -p decodex -- probe`; `cargo run -p decodex -- project
 Recommended first-run check:
 
 ```sh
-cargo run -p decodex -- probe
+cargo run -p decodex --bin decodex -- probe
 ```
 
 If `decodex probe` does not return `PROBE_OK`, stop there. The orchestrator loop depends on the same direct `app-server` contract.
@@ -170,9 +170,9 @@ Use `decodex` itself as the first target repo and keep intake bounded by applyin
 Use dry run first to validate config loading, issue discovery, and worktree planning without mutating Linear or creating worktree directories.
 
 ```sh
-cargo run -p decodex -- project add ~/.codex/decodex/projects/decodex
-cargo run -p decodex -- project list
-cargo run -p decodex -- run --dry-run
+cargo run -p decodex --bin decodex -- project add ~/.codex/decodex/projects/decodex
+cargo run -p decodex --bin decodex -- project list
+cargo run -p decodex --bin decodex -- run --dry-run
 ```
 
 Expected behavior:
@@ -191,7 +191,7 @@ dry run: no Decodex project config supplied or registered; nothing to execute.
 ### Live run
 
 ```sh
-cargo run -p decodex -- run
+cargo run -p decodex --bin decodex -- run
 ```
 
 On a normal successful run, `decodex` will:
@@ -276,7 +276,7 @@ is still unmerged, use the normal reviewed lane checkout instead.
 After `probe`, `project add`, `run --dry-run`, and `run` all behave as expected, use `serve` for the long-running pilot loop:
 
 ```sh
-cargo run -p decodex -- serve --interval 60s
+cargo run -p decodex --bin decodex -- serve --interval 60s
 ```
 
 ### Installed-binary observer loop
@@ -570,7 +570,7 @@ Decodex is intentionally Unix-only, and the control plane relies on Unix file-de
 decodex serve --interval 60s --listen-address 127.0.0.1:8912
 ```
 
-The listener serves the operator console from the canonical `GET /` and `GET /dashboard` routes, the same JSON operator snapshot used by `cargo run -p decodex -- status --json` through the `/dashboard/control` WebSocket, and the minimal `GET /livez` liveness probe on the same listener. The single console keeps `Projects`, `Running Lanes`, `Intake Queue`, `Review & Landing`, `Recovery Worktrees`, and `Run Ledger` visible together. Intake candidates that are already claimed by a running lane are shown as active queue echoes, capacity-bound candidates are shown as waiting rather than blocked, running lane worktrees stay with their owning lane, and retained/recovery worktrees remain folded until diagnostics are needed:
+The listener serves the operator console from the canonical `GET /` and `GET /dashboard` routes, the same JSON operator snapshot used by `cargo run -p decodex --bin decodex -- status --json` through the `/dashboard/control` WebSocket, and the minimal `GET /livez` liveness probe on the same listener. The single console keeps `Projects`, `Running Lanes`, `Intake Queue`, `Review & Landing`, `Recovery Worktrees`, and `Run Ledger` visible together. Intake candidates that are already claimed by a running lane are shown as active queue echoes, capacity-bound candidates are shown as waiting rather than blocked, running lane worktrees stay with their owning lane, and retained/recovery worktrees remain folded until diagnostics are needed:
 
 - `GET /` or `GET /dashboard`: the same single-page operator console
 - `GET /dashboard/control`: WebSocket transport for snapshots, live run activity, and local dashboard control acknowledgements
@@ -648,8 +648,8 @@ git -C /absolute/path/to/hack-ink/decodex/.worktrees/XY-123 log --oneline --deco
 Before dropping to local storage internals, inspect the supported runtime surface:
 
 ```sh
-cargo run -p decodex -- status
-cargo run -p decodex -- status --json
+cargo run -p decodex --bin decodex -- status
+cargo run -p decodex --bin decodex -- status --json
 ```
 
 Use the human-readable view when you need the current leased run, lane worktree ownership, and session-history summary at a glance. Use `--json` when you want a machine-readable snapshot with stable identifiers such as `run_id`, `issue_id`, `thread_id`, `branch`, and repository-relative `worktree_path`.
@@ -712,9 +712,9 @@ Use the operator dashboard or `status` for run ids, attempts, and failure class;
 When changing `decodex` itself, keep the pilot path healthy with:
 
 ```sh
-cargo run -p decodex -- probe
-cargo run -p decodex -- project add ~/.codex/decodex/projects/decodex
-cargo run -p decodex -- run --dry-run
+cargo run -p decodex --bin decodex -- probe
+cargo run -p decodex --bin decodex -- project add ~/.codex/decodex/projects/decodex
+cargo run -p decodex --bin decodex -- run --dry-run
 cargo make fmt
 cargo make lint
 cargo make check

plugins/decodex/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "decodex",
   "version": "0.1.0",
-  "description": "Agent-facing workflows for using Decodex in manual CLI and runtime-owned automation modes.",
+  "description": "Agent-facing workflows for planning, using, and operating Decodex in manual CLI and runtime-owned automation modes.",
   "author": {
     "name": "hack-ink",
     "email": "hi@hack.ink",
@@ -21,7 +21,7 @@
   "interface": {
     "displayName": "Decodex",
     "shortDescription": "Use Decodex manually or as an automated retained-lane control plane.",
-    "longDescription": "Routes Codex agents through Decodex's two supported use modes: manual CLI development workflows such as commit, land, status, project registration, and dry runs; and runtime-owned automation workflows such as serve, registered project contracts, Linear labels, tracker tools, review handoff, landing, closeout, and operator status. The plugin keeps Decodex-specific instructions with the Decodex runtime instead of duplicating them in generic playbooks.",
+    "longDescription": "Routes Codex agents through Decodex's planning and usage surfaces: Decodex-friendly issue splitting, queue shaping, and concurrency; manual CLI development workflows such as commit, land, status, project registration, account selection, and dry runs; and runtime-owned automation workflows such as serve, registered project contracts, Linear labels, tracker tools, review handoff, landing, closeout, and operator status. The plugin keeps Decodex-specific instructions with the Decodex runtime instead of duplicating them in generic playbooks.",
     "developerName": "hack-ink",
     "category": "Development",
     "capabilities": [
@@ -33,6 +33,7 @@
     "termsOfServiceURL": "https://github.com/hack-ink/decodex",
     "defaultPrompt": [
       "Use Decodex to inspect this lane.",
+      "Split this feature into Decodex-friendly independent issues.",
       "Run the Decodex automation preflight.",
       "Land this PR through Decodex."
     ],

plugins/decodex/skills/automation/SKILL.md

@@ -38,19 +38,20 @@ decodex serve --interval 60s
 From the Decodex repo while developing the runtime:
 
 ```sh
-cargo run -p decodex -- probe stdio://
-cargo run -p decodex -- project add "$HOME/.codex/decodex/projects/<service-id>"
-cargo run -p decodex -- status
-cargo run -p decodex -- run --dry-run
-cargo run -p decodex -- run
-cargo run -p decodex -- serve --interval 60s
+cargo run -p decodex --bin decodex -- probe stdio://
+cargo run -p decodex --bin decodex -- project add "$HOME/.codex/decodex/projects/<service-id>"
+cargo run -p decodex --bin decodex -- status
+cargo run -p decodex --bin decodex -- run --dry-run
+cargo run -p decodex --bin decodex -- run
+cargo run -p decodex --bin decodex -- serve --interval 60s
 ```
 
-Use `decodex serve --config <project-dir>` or `cargo run -p decodex -- serve --config
-<project-dir>` when the operator wants to register that project and start the scheduler
-in one command.
-Use `decodex run <ISSUE>` or `cargo run -p decodex -- run <ISSUE>` only for a deliberate one-issue
-automation pass; it still uses the same retained-lane eligibility and lifecycle rules.
+Use `decodex serve --config <project-dir>` or
+`cargo run -p decodex --bin decodex -- serve --config <project-dir>` when the operator
+wants to register that project and start the scheduler in one command.
+Use `decodex run <ISSUE>` or `cargo run -p decodex --bin decodex -- run <ISSUE>` only
+for a deliberate one-issue automation pass; it still uses the same retained-lane
+eligibility and lifecycle rules.
 
 ## Intake and Ownership
 

plugins/decodex/skills/decodex/SKILL.md

@@ -11,10 +11,13 @@ Route agent work through the right Decodex surface without duplicating the runti
 specs. Decodex has two supported use modes:
 
 - Manual CLI mode: a human is driving local development, commits, PR preparation,
-  landing, status inspection, project registration, or dry-run checks.
+  landing, status inspection, project registration, account selection, or dry-run
+  checks.
 - Automation mode: Decodex owns retained-lane execution through registered project
   contracts, `serve`, `run`, tracker labels, issue-scoped tools, review handoff,
   landing, closeout, and operator status.
+- Planning support: agents shape Decodex-friendly issue sets, queue strategy,
+  dependency boundaries, and concurrency before retained-lane automation starts.
 
 ## First Steps
 
@@ -26,6 +29,7 @@ specs. Decodex has two supported use modes:
    directory supplied with `--config`.
 5. Use the narrow skill for the current action:
    - `manual-cli` for normal operator CLI use.
+   - `planning` for Decodex-friendly issue splitting, queue shaping, and concurrency.
    - `automation` for retained-lane control-plane use.
    - `commit` for `decodex commit`.
    - `land` for `decodex land`.

plugins/decodex/skills/manual-cli/SKILL.md

@@ -22,7 +22,8 @@ runtime-owned retained-lane lifecycle.
 ## Command Surface
 
 Use the installed `decodex` binary when the operator is working from an installed
-runtime. Use `cargo run -p decodex -- ...` when developing this repository itself.
+runtime. Use `cargo run -p decodex --bin decodex -- ...` when developing this
+repository itself.
 
 Common manual checks and dry-run probes:
 
@@ -38,11 +39,11 @@ decodex archive-linear --repo-label repo:<name> --older-than-days 30
 Development equivalents from the Decodex repo root:
 
 ```sh
-cargo run -p decodex -- probe stdio://
-cargo run -p decodex -- project add "$HOME/.codex/decodex/projects/<service-id>"
-cargo run -p decodex -- status
-cargo run -p decodex -- run --dry-run
-cargo run -p decodex -- archive-linear --repo-label repo:<name> --older-than-days 30
+cargo run -p decodex --bin decodex -- probe stdio://
+cargo run -p decodex --bin decodex -- project add "$HOME/.codex/decodex/projects/<service-id>"
+cargo run -p decodex --bin decodex -- status
+cargo run -p decodex --bin decodex -- run --dry-run
+cargo run -p decodex --bin decodex -- archive-linear --repo-label repo:<name> --older-than-days 30
 ```
 
 Live `run` commands enter the runtime-owned automation path, even when an operator
@@ -51,8 +52,8 @@ starts one pass manually:
 ```sh
 decodex run
 decodex run <ISSUE>
-cargo run -p decodex -- run
-cargo run -p decodex -- run <ISSUE>
+cargo run -p decodex --bin decodex -- run
+cargo run -p decodex --bin decodex -- run <ISSUE>
 ```
 
 Before starting a live run, read the `automation` skill and the registered project's