diff --git a/README.md b/README.md index cbcf4b40c..41222450d 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,8 @@ Repo-native agent orchestration, upstream Codex radar, and public publishing. - Publisher workflow for checked-in upstream reviews, impact classification, curated public signals, and automated low-frequency X publication records for `@decodexspace`. -- Installable Decodex plugin with reusable agent-facing skills for planning, - manual CLI, automation, commit, land, and labels. +- Installable Decodex plugin with reusable agent-facing skills for issue briefing, + planning, manual CLI, automation, commit, land, and labels. - Repository documentation split by question type into spec, runbook, reference, and decision lanes. diff --git a/apps/decodex/src/plugin_surface_tests.rs b/apps/decodex/src/plugin_surface_tests.rs index 01c70ccf9..6bc293d32 100644 --- a/apps/decodex/src/plugin_surface_tests.rs +++ b/apps/decodex/src/plugin_surface_tests.rs @@ -16,10 +16,30 @@ const AUTOMATION_SKILL: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/skills/automation/SKILL.md" )); +const AUTOMATION_AGENT_POLICY: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/skills/automation/agents/openai.yaml" +)); +const COMMIT_AGENT_POLICY: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/skills/commit/agents/openai.yaml" +)); const LABELS_SKILL: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/skills/labels/SKILL.md" )); +const LABELS_AGENT_POLICY: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/skills/labels/agents/openai.yaml" +)); +const LAND_AGENT_POLICY: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/skills/land/agents/openai.yaml" +)); +const MANUAL_CLI_AGENT_POLICY: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/skills/manual-cli/agents/openai.yaml" +)); const RESEARCH_SKILL: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/skills/research/SKILL.md" @@ -56,6 +76,10 @@ const ROUTING_REF: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/references/routing.md" )); +const ISSUE_BRIEFING_REF: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../plugins/decodex/references/issue-briefing.md" +)); const RESEARCH_METHOD_REF: &str = include_str!(concat!( env!("CARGO_MANIFEST_DIR"), "/../../plugins/decodex/references/research-method.md" @@ -92,8 +116,10 @@ fn packaged_plugin_manifest_routes_natural_language_research_to_decodex() { assert_contains(&manifest_surface, "\"推进\""); assert_contains(&manifest_surface, "ready mapped nodes directly"); assert_contains(&manifest_surface, "DAG"); + assert_contains(&manifest_surface, "issue briefing"); assert_contains(&default_prompts, "Research this with Decodex."); - assert_contains(&default_prompts, "Arrange accepted research."); + assert_contains(&default_prompts, "Arrange accepted Decodex work."); + assert_contains(&default_prompts, "Inspect this Decodex lane."); } #[test] @@ -101,6 +127,7 @@ fn packaged_skills_preserve_research_promotion_and_queue_boundaries() { let skill_surface = format!( "{DECODEX_SKILL}\n{PLANNING_SKILL}\n{AUTOMATION_SKILL}\n{LABELS_SKILL}\n{RESEARCH_SKILL}\n{ROUTING_REF}\n{RESEARCH_METHOD_REF}" ); + let planning_surface = format!("{PLANNING_SKILL}\n{ISSUE_BRIEFING_REF}\n{ROUTING_REF}"); assert_contains(&skill_surface, "## Natural-Language Research Routing"); assert_contains(&skill_surface, "`research X`"); @@ -121,6 +148,17 @@ fn packaged_skills_preserve_research_promotion_and_queue_boundaries() { assert_contains(&skill_surface, "ordinary non-Program issue intake"); assert_contains(&skill_surface, "not queue-label polling"); assert_contains(&skill_surface, "Require promoted research"); + assert_contains(&planning_surface, "Decodex-native issue briefs"); + assert_contains(&planning_surface, "generic dispatch briefing"); + assert_contains(&planning_surface, "one outcome"); + assert_contains(&planning_surface, "explicit non-goals"); + assert_contains(&planning_surface, "current-tree landing zone"); + assert_contains(&planning_surface, "validation expectations"); + assert_contains( + &planning_surface, + "Do not route Decodex issue briefing through an external delivery workflow", + ); + assert_not_contains(&planning_surface, "Pair with delivery"); } #[test] @@ -166,6 +204,19 @@ fn packaged_research_skills_encode_decodex_methodology() { assert_contains(&research_surface, "Program Intake"); } +#[test] +fn narrow_lifecycle_skills_are_explicit_only() { + for policy in [ + AUTOMATION_AGENT_POLICY, + COMMIT_AGENT_POLICY, + LABELS_AGENT_POLICY, + LAND_AGENT_POLICY, + MANUAL_CLI_AGENT_POLICY, + ] { + assert_contains(policy, "allow_implicit_invocation: false"); + } +} + fn assert_contains(haystack: &str, needle: &str) { assert!(haystack.contains(needle), "expected packaged plugin content to contain `{needle}`"); } @@ -176,3 +227,10 @@ fn assert_contains_normalized(haystack: &str, needle: &str) { assert_contains(&normalized_haystack, &normalized_needle); } + +fn assert_not_contains(haystack: &str, needle: &str) { + assert!( + !haystack.contains(needle), + "expected packaged plugin content not to contain `{needle}`" + ); +} diff --git a/docs/decisions/decodex-plugin-source.md b/docs/decisions/decodex-plugin-source.md index eab5480a8..9745dfc0e 100644 --- a/docs/decisions/decodex-plugin-source.md +++ b/docs/decisions/decodex-plugin-source.md @@ -33,8 +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, dispatch readiness, dependencies, - and concurrency +- `planning` for Decodex-native issue briefing, issue splitting, dispatch readiness, + dependencies, and concurrency - `manual-cli` for operator CLI use - `automation` for retained-lane control-plane use - `commit` for human-driven `decodex commit` @@ -50,6 +50,9 @@ copying their full contracts. - Decodex-specific skill updates can land with matching runtime, spec, and runbook updates. - Generic Playbook skills can shrink to generic repo discipline and explicit routing. +- Decodex issue briefing belongs to the Decodex plugin instead of a separate delivery + workflow. Generic progress, handoff, review, landing, and closeout state remains + runtime-owned rather than skill-owned. - `~/.codex/AGENTS.md` remains a portable bootstrap surface, not a Decodex runtime or operator contract. - Semantic drift audits for Decodex behavior changes should include `plugins/decodex/` diff --git a/docs/reference/workspace-layout.md b/docs/reference/workspace-layout.md index 5a1048cfc..39a65c7c1 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 publication records, blocked-cap records, and generated-media evidence. | | `dev/skills/` | Repository-development skills for Radar upstream triage, code analysis, release analysis, GitHub signal drafting, and X publishing. These are not part of installable plugin distribution. | -| `plugins/decodex/` | Canonical installable Decodex plugin source and reusable agent-facing skills, including planning, manual CLI, automation, commit, land, and labels. | +| `plugins/decodex/` | Canonical installable Decodex plugin source and reusable agent-facing skills, including issue briefing, 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. | diff --git a/docs/research/legacy-research-goal-audit.json b/docs/research/legacy-research-goal-audit.json index f2b32f639..3ba26ff73 100644 --- a/docs/research/legacy-research-goal-audit.json +++ b/docs/research/legacy-research-goal-audit.json @@ -61,13 +61,15 @@ }, { "legacy_target": "Delivery skill removal and drop-delivery designs", - "current_status": "Partially absorbed. Runtime-owned closeout, post-review lifecycle, and issue-scoped tracker tools exist, but the Decodex planning skill still references external delivery issue/split shaping.", + "current_status": "Implemented. Runtime-owned closeout, post-review lifecycle, and issue-scoped tracker tools exist, and Decodex planning now owns native issue briefing and issue splitting without an external delivery dependency.", "repo_evidence": [ "docs/spec/post-review-lifecycle.md", "docs/spec/tracker-tools.md", + "docs/spec/loop-runtime.md", + "plugins/decodex/references/issue-briefing.md", "plugins/decodex/skills/planning/SKILL.md" ], - "retained_value": "Future Decodex plugin self-containment should remove the residual external delivery dependency only after Decodex-native issue shaping exists." + "retained_value": "Keep Decodex-native issue briefing inside planning, and keep progress, review handoff, landing, closeout, and recovery as runtime-owned lifecycle surfaces." }, { "legacy_target": "Plan plugin to progress skill runs", @@ -211,11 +213,13 @@ }, { "id": "E9", - "kind": "gap", + "kind": "repo_source", "source": [ + "docs/spec/loop-runtime.md", + "plugins/decodex/references/issue-briefing.md", "plugins/decodex/skills/planning/SKILL.md" ], - "supports": "Decodex planning still points to external delivery issue/split shaping, so full delivery-skill removal is not complete." + "supports": "Decodex planning owns issue briefing and issue splitting directly, so Decodex no longer depends on an external delivery issue/split skill for Program Intake readiness." } ], "carry_forward_research_packet": { @@ -229,7 +233,6 @@ "New Decodex research continues to use runtime-local decodex.decision_contract/1 records for runtime authority and does not use the old research-run/2 event-log shape." ], "unresolved_execution_work": [ - "Decide later whether Decodex planning should become fully self-contained and remove its residual external delivery issue/split dependency.", "Reopen remote execution research only with live evidence for task status, diff, apply, issue/run/attempt provenance, repo gate, and PR handoff authority.", "Reopen landing receipt research only if the current decodex/commit/1 and GitHub merge/admin-merge records fail a concrete machine-readback requirement.", "Keep any future plan/progress adapter below lifecycle authority; progress memory cannot become terminal lane state." diff --git a/docs/spec/loop-runtime.md b/docs/spec/loop-runtime.md index bd11fd034..356b37d89 100644 --- a/docs/spec/loop-runtime.md +++ b/docs/spec/loop-runtime.md @@ -362,6 +362,15 @@ be represented internally as a DAG, but executable work still enters Decodex as ordinary Linear issue lanes with generic natural-language descriptions, tracker states, validation expectations, and Decodex lifecycle writeback. +Every mapped normal issue must carry a generic dispatch briefing that a cold-start +implementation lane can execute without replaying chat or reading private runtime +state. A complete Decodex-planned briefing names one outcome, required reading, +in-scope work, explicit non-goals, current-tree landing zone, ownership boundary, +acceptance criteria, validation expectations, and any real dependencies, blockers, or +conflict domains. At minimum, runtime eligibility rejects a machine-only fenced block +as the issue description; private pointers, progress checkpoints, review summaries, +PR bodies, or runtime events do not substitute for the issue briefing. + The operator CLI surface for promoted goals is `decodex intake goal --project --dry-run`, or the same command with `--config `. Dry-run reads the promoted Decision Contract diff --git a/plugins/decodex/.codex-plugin/plugin.json b/plugins/decodex/.codex-plugin/plugin.json index 373b1cf54..1b4834194 100644 --- a/plugins/decodex/.codex-plugin/plugin.json +++ b/plugins/decodex/.codex-plugin/plugin.json @@ -21,7 +21,7 @@ "interface": { "displayName": "Decodex", "shortDescription": "Research, plan, and operate Decodex.", - "longDescription": "Routes Decodex research, promotion, planning, CLI, labels, commit, landing, and automation.", + "longDescription": "Routes Decodex research, promotion, issue briefing and planning, CLI, labels, commit, landing, and automation.", "developerName": "hack-ink", "category": "Development", "capabilities": [ @@ -33,7 +33,7 @@ "termsOfServiceURL": "https://github.com/hack-ink/decodex", "defaultPrompt": [ "Research this with Decodex.", - "Arrange accepted research.", + "Arrange accepted Decodex work.", "Inspect this Decodex lane." ], "brandColor": "#0F766E" diff --git a/plugins/decodex/references/issue-briefing.md b/plugins/decodex/references/issue-briefing.md new file mode 100644 index 000000000..f18331c17 --- /dev/null +++ b/plugins/decodex/references/issue-briefing.md @@ -0,0 +1,71 @@ +# Decodex Issue Briefing Reference + +Use this reference when accepted Decodex work needs normal Linear issue briefs, +existing issue-batch intake, or Program Intake readiness. + +## Authority + +Issue briefing is part of Decodex planning. It starts only after one of these +authority sources exists: + +- an accepted and promoted Decision Contract +- an explicit execution instruction whose scope is already bounded +- a supplied batch of executable issue briefs for Program Intake + +The briefing is not a separate delivery workflow. Do not route Decodex issue +briefing through an external delivery plugin, delivery handoff, or progress skill. +Runtime progress, review handoff, landing, closeout, and recovery remain +Decodex runtime surfaces. + +## Generic Dispatch Briefing + +Every Decodex-planned issue must be understandable by a generic implementation lane +without replaying the originating chat or reading private runtime state. + +Include: + +1. one outcome +2. required reading +3. in-scope work +4. explicit non-goals +5. current-tree landing zone +6. ownership boundary +7. acceptance criteria +8. validation expectations +9. real dependencies, blockers, or conflict domains +10. dispatch notes needed for a cold-start agent + +Use concrete repository paths, commands, specs, runbooks, and project policy only +when they exist. Do not invent modules, validation flows, tracker state, or runtime +authority to make an issue sound complete. + +## Splitting Rules + +Split accepted work only when one issue would be too broad for one retained lane. +Split by real ownership boundary, validation surface, dependency, or conflict +domain. Keep the issue set small enough that each issue can be started, reviewed, +and validated independently. + +Each child issue must carry its own generic dispatch briefing. Name ordering only +when it is blocking. Do not expose internal graph ids, DAG edge editing, hidden goal +ids, or Program scheduler mechanics in the issue text. + +## Existing Issue Intake + +For `decodex intake issues`, treat the supplied issue descriptions as the public +briefing surface. If an issue is only a machine-readable block, private pointer, or +thin title, it is missing the generic dispatch briefing and should remain held until +the briefing is repaired. + +Do not use a progress checkpoint, review summary, PR body, or runtime event as a +substitute for the issue briefing. Those surfaces can support evidence, but the +normal issue remains the executable lane boundary. + +## Non-Goals + +- Do not create a roadmap, ADR, or broad project plan. +- Do not promote latent research. +- Do not mutate Linear, apply queue labels, or persist Program Intake rows from the + briefing step alone. +- Do not treat a briefing as proof that work is implemented, validated, reviewed, + ready to land, or closed out. diff --git a/plugins/decodex/references/routing.md b/plugins/decodex/references/routing.md index 188907baa..a65feb183 100644 --- a/plugins/decodex/references/routing.md +++ b/plugins/decodex/references/routing.md @@ -10,7 +10,7 @@ labels, retained automation, commit, or landing boundaries. - Promotion: use `research-promote` only after explicit acceptance such as "arrange this", "push this forward", "推进", or "做". - Planning: use `planning` after promotion or another explicit execution instruction - to create Decodex-friendly issue slices and Program readiness. + to create Decodex-native issue briefs and Program readiness. - Manual CLI: use `manual-cli` when a human is driving local commands, status, project registration, dry-run checks, recovery inspection, commit, or land. - Retained automation: use `automation` when Decodex owns issue intake, Program @@ -40,8 +40,9 @@ promotion. 2. A decision-ready result remains latent until promotion. 3. Promotion preserves the accepted objectives, non-goals, constraints, assumptions, objections, validation expectations, proposed issue summaries, and stop conditions. -4. Planning turns accepted work into user-readable Linear issue briefs and, when - appropriate, persisted Execution Program readiness. +4. Planning turns accepted work into user-readable Linear issue briefs with generic + dispatch briefing quality and, when appropriate, persisted Execution Program + readiness. 5. Program Intake dispatches ready mapped nodes directly. Queue labels are not the Program DAG scheduler. @@ -121,6 +122,8 @@ For human-driven PR landing: - Do not use global `AGENTS.md` as Decodex runtime, tracker, identity, landing, closeout, or cleanup authority. +- Do not route Decodex issue briefing through an external delivery workflow; planning + owns Decodex issue shaping after execution authority exists. - Do not hand-edit runtime DB rows, kill hidden `_attempt` children, or mutate Linear state to simulate lane controls. - Do not substitute raw GitHub merge, merge queue, `gh pr merge`, direct API mutation, diff --git a/plugins/decodex/skills/automation/agents/openai.yaml b/plugins/decodex/skills/automation/agents/openai.yaml new file mode 100644 index 000000000..5b1f887a9 --- /dev/null +++ b/plugins/decodex/skills/automation/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/plugins/decodex/skills/commit/agents/openai.yaml b/plugins/decodex/skills/commit/agents/openai.yaml new file mode 100644 index 000000000..5b1f887a9 --- /dev/null +++ b/plugins/decodex/skills/commit/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/plugins/decodex/skills/labels/agents/openai.yaml b/plugins/decodex/skills/labels/agents/openai.yaml new file mode 100644 index 000000000..5b1f887a9 --- /dev/null +++ b/plugins/decodex/skills/labels/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/plugins/decodex/skills/land/agents/openai.yaml b/plugins/decodex/skills/land/agents/openai.yaml new file mode 100644 index 000000000..5b1f887a9 --- /dev/null +++ b/plugins/decodex/skills/land/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/plugins/decodex/skills/manual-cli/agents/openai.yaml b/plugins/decodex/skills/manual-cli/agents/openai.yaml new file mode 100644 index 000000000..5b1f887a9 --- /dev/null +++ b/plugins/decodex/skills/manual-cli/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/plugins/decodex/skills/planning/SKILL.md b/plugins/decodex/skills/planning/SKILL.md index fa1644259..a4f8ac258 100644 --- a/plugins/decodex/skills/planning/SKILL.md +++ b/plugins/decodex/skills/planning/SKILL.md @@ -5,13 +5,21 @@ description: Use when accepted Decodex work needs slicing. # Planning -Shape accepted work into safe Decodex lanes. Read `../../references/routing.md` for -project policy and Program-vs-label dispatch rules. +Shape accepted work into Decodex-native issue briefs and Program Intake readiness. +Read `../../references/routing.md` for project policy and Program-vs-label dispatch +rules, and `../../references/issue-briefing.md` for generic dispatch briefing +quality. - Use this only after promotion or explicit execution instruction. -- Pair with delivery `issue` or `split` for durable issue text. +- Own issue shaping here; do not call external delivery `issue`, `split`, `brief`, + `handoff`, or `progress` skills for Decodex planning. - Give each issue one outcome, scope, landing zone, acceptance, validation, - dependencies, and dispatch-ready briefing. + dependencies, conflict-domain notes, and dispatch-ready briefing. - Preserve accepted Decision Contract constraints, objections, stop conditions, validation, and conflict-domain notes. +- Split work only by real ownership boundary, validation surface, dependency, or + conflict domain; each child issue must still be executable on its own. +- For existing issue-batch intake, hold issues that lack a generic dispatch briefing + instead of treating machine-only blocks, private pointers, progress checkpoints, or + review summaries as executable issue text. - Do not replace `WORKFLOW.md`, mutate active state, or queue latent research.