diff --git a/README.md b/README.md index a0f5c855..3bbf0c94 100644 --- a/README.md +++ b/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 diff --git a/docs/decisions/decodex-plugin-source.md b/docs/decisions/decodex-plugin-source.md index a92f389c..1fc0b208 100644 --- a/docs/decisions/decodex-plugin-source.md +++ b/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` diff --git a/docs/index.md b/docs/index.md index a36b9d25..719cff19 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ The split below is by question type, not by human-versus-agent audience. `~/.codex/decodex/projects//` 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?" diff --git a/docs/reference/workspace-layout.md b/docs/reference/workspace-layout.md index ef9fce0a..52c6f3ce 100644 --- a/docs/reference/workspace-layout.md +++ b/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 ``` diff --git a/docs/runbook/linear-archive-hygiene.md b/docs/runbook/linear-archive-hygiene.md index 6ffe0782..fc0b3416 100644 --- a/docs/runbook/linear-archive-hygiene.md +++ b/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 diff --git a/docs/runbook/self-dogfood-pilot.md b/docs/runbook/self-dogfood-pilot.md index ce5385fb..38ba7804 100644 --- a/docs/runbook/self-dogfood-pilot.md +++ b/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//`; 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 diff --git a/plugins/decodex/.codex-plugin/plugin.json b/plugins/decodex/.codex-plugin/plugin.json index d03070f5..d195c91e 100644 --- a/plugins/decodex/.codex-plugin/plugin.json +++ b/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." ], diff --git a/plugins/decodex/skills/automation/SKILL.md b/plugins/decodex/skills/automation/SKILL.md index b448d20e..2f06601d 100644 --- a/plugins/decodex/skills/automation/SKILL.md +++ b/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/" -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/" +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 ` or `cargo run -p decodex -- serve --config -` when the operator wants to register that project and start the scheduler -in one command. -Use `decodex run ` or `cargo run -p decodex -- run ` only for a deliberate one-issue -automation pass; it still uses the same retained-lane eligibility and lifecycle rules. +Use `decodex serve --config ` or +`cargo run -p decodex --bin decodex -- serve --config ` when the operator +wants to register that project and start the scheduler in one command. +Use `decodex run ` or `cargo run -p decodex --bin decodex -- run ` only +for a deliberate one-issue automation pass; it still uses the same retained-lane +eligibility and lifecycle rules. ## Intake and Ownership diff --git a/plugins/decodex/skills/decodex/SKILL.md b/plugins/decodex/skills/decodex/SKILL.md index b11cd0b7..fb9981de 100644 --- a/plugins/decodex/skills/decodex/SKILL.md +++ b/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`. diff --git a/plugins/decodex/skills/manual-cli/SKILL.md b/plugins/decodex/skills/manual-cli/SKILL.md index 31fb7a56..ec95c0dd 100644 --- a/plugins/decodex/skills/manual-cli/SKILL.md +++ b/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: --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/" -cargo run -p decodex -- status -cargo run -p decodex -- run --dry-run -cargo run -p decodex -- archive-linear --repo-label repo: --older-than-days 30 +cargo run -p decodex --bin decodex -- probe stdio:// +cargo run -p decodex --bin decodex -- project add "$HOME/.codex/decodex/projects/" +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: --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 -cargo run -p decodex -- run -cargo run -p decodex -- run +cargo run -p decodex --bin decodex -- run +cargo run -p decodex --bin decodex -- run ``` Before starting a live run, read the `automation` skill and the registered project's diff --git a/plugins/decodex/skills/planning/SKILL.md b/plugins/decodex/skills/planning/SKILL.md new file mode 100644 index 00000000..2939546a --- /dev/null +++ b/plugins/decodex/skills/planning/SKILL.md @@ -0,0 +1,91 @@ +--- +name: planning +description: Use when shaping Decodex-friendly issue sets, queue strategy, project capacity, dependencies, or concurrency. Helps agents split work so retained lanes can run independently without overlapping ownership or bypassing registered project policy. +--- + +# Planning + +## Goal + +Shape work so Decodex can run the right lanes in parallel while each issue remains +independently executable, reviewable, and recoverable. + +Use this before queueing a broad feature, migration, or cleanup effort into Decodex. +For durable issue text, pair this skill with the delivery plugin's `split` or `issue` +skill, then use the `labels` skill when applying Decodex intake labels. + +## Read First + +- The registered project `project.toml` for `service_id`, repo path, worktree root, + and credential environment-variable names. +- The registered project `WORKFLOW.md` for startable states, terminal states, + dependency policy, validation commands, gate profiles, and context files. +- `docs/spec/runtime.md` for eligibility, one-lane-per-issue ownership, and dispatch + slots. +- `docs/spec/workflow-file.md` for `max_concurrent_agents`, gate profile semantics, + and workspace hooks. +- `docs/spec/owned-lane-policy.md` and `docs/spec/post-review-lifecycle.md` for + retained review, landing, closeout, cleanup, and manual-intervention boundaries. +- `docs/reference/operator-control-plane.md` when using `status` or the dashboard to + understand current queue, active lanes, review waits, and cleanup debt. + +## Good Decodex Issues + +Each issue should have: + +- one concrete outcome that can land as one PR-backed lane +- required reading and current authority files +- explicit scope and non-goals +- a narrow landing zone, preferably one module, service, docs lane, or workflow seam +- acceptance criteria that can be checked without asking product intent again +- validation commands or the applicable `WORKFLOW.md` gate profile +- explicit blockers or dependency issues when the issue cannot start yet +- enough natural-language briefing in the Linear description for generic dispatch + +Do not make the description only a machine-readable fenced block. Generic normal +dispatch requires a usable briefing surface. + +## Parallelism Rules + +- Split by ownership boundary, validation surface, or deployable behavior, not by + arbitrary chronology. +- Prefer several independent queued issues over one broad issue when their file sets, + contracts, and verification can be isolated. +- Put shared contracts, schema changes, and cross-cutting migrations in a foundation + issue first; queue downstream slices only after the blocking contract lands or mark + the dependency explicitly in the tracker. +- Avoid queueing issues that are likely to edit the same hot files, branch lineage, + config authority, or generated artifacts unless the ordering is explicit. +- Keep one issue responsible for any user-facing wording or spec contract that several + implementation slices depend on, then link the other issues to that authority. +- Use `decodex:queued:` only for issues that are startable under the + registered `WORKFLOW.md`; the label does not bypass state, blocker, terminal-state, + active-lease, or capacity checks. +- Set `[execution] max_concurrent_agents = 0` only when the project is intentionally + uncapped. Use a positive value when the repo, accounts, CI budget, or review surface + needs bounded parallelism. + +## Queue Shaping + +1. Use `decodex status` or the dashboard to read active lanes, queued candidates, + retry waits, review waits, landing state, recovery worktrees, cleanup debt, and + available capacity. +2. Use `decodex run --dry-run` to confirm project loading, issue discovery, + eligibility, dependency blockers, and worktree planning before live automation. +3. Queue only the next independent slice set. Leave future or blocked slices unqueued + until the dependency is terminal or the `WORKFLOW.md` policy makes them startable. +4. If capacity is finite, keep the highest-value independent slices queued first + instead of flooding the queue with dependent work. +5. When a lane stops with `decodex:needs-attention`, resolve the recorded blocker + before clearing the label or re-queueing. + +## Boundaries + +- This skill does not replace project-local `WORKFLOW.md` policy or runtime + eligibility. +- Do not use planning guidance to manually mutate active labels, runtime DB rows, or + retained worktrees. +- Do not convert a human-driven manual task into retained-lane automation unless the + user asks for automation or the registered workflow requires it. +- Do not use parallelism as a reason to split one atomic behavior across dependent + issues that cannot be validated or reviewed independently.