diff --git a/README.md b/README.md index 9a46759..6cec624 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ third-party orchestration service to use these files. [Skills](skills/README.md) · [Plugins](plugins/README.md) · [Validation and compatibility](docs/validation.md) -Version 0.2.0 is a community preview. Historical hook and selected-role tests are +Version 0.2.1 is a community preview. Historical hook and selected-role tests are recorded; the revised allocations and caps are not fully runtime-certified. ## Choose an arrangement diff --git a/arrangements/advanced-delivery/AGENTS.snippet.md b/arrangements/advanced-delivery/AGENTS.snippet.md index 2211d78..201cd12 100644 --- a/arrangements/advanced-delivery/AGENTS.snippet.md +++ b/arrangements/advanced-delivery/AGENTS.snippet.md @@ -1,34 +1,18 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -### Routing +### Role selection -Delegate only a bounded task with an independent result. -Inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Reserve Sol for backend implementation, unknown-cause diagnosis, ordinary review, and integration review; reserve Astra for advice, design direction, coupled implementation, and critical review. - -### Responsibilities - -Regular backend/frontend workers also handle fully specified small edits. The parent writes documentation; critical-reviewer handles scoped security review. Light variants and a separate security sweep are omitted. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence - -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -### Capacity +### Ownership and return -This fragment configures 5 total session threads, including the parent; use at most 4 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. diff --git a/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md b/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md index 30b152f..77b2c73 100644 --- a/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md @@ -1,41 +1,25 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -Optional skills can be installed independently. Use the fallback in the relevant section when one is absent; do not invent a callable Skill API on Codex CLI. +### Role selection -### Routing - -For dispatch, call the runtime's Skill tool with `codex-orchestration` when exposed; otherwise use its native skill-loading interface to read `SKILL.md`. In Codex prompts, use `$codex-orchestration`. -If it is absent, inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Reserve Sol for backend implementation, unknown-cause diagnosis, ordinary review, and integration review; reserve Astra for advice, design direction, coupled implementation, and critical review. - -### Responsibilities - -Regular backend/frontend workers also handle fully specified small edits. The parent writes documentation; critical-reviewer handles scoped security review. Light variants and a separate security sweep are omitted. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +### Ownership and return -### Optional engineering guidance +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. -For an ambiguous design or boundary, unexplained green result, duplicate knowledge, contract/input change, reversible-step or spike choice, or shared finite resource, call the Skill tool with `pragmatic-programmer` when exposed; otherwise load its `SKILL.md` natively. In Codex prompts, use `$pragmatic-programmer`. -If it is absent, explain the green signal, name one knowledge authority, validate the boundary and invariants, choose a reversible next step, identify resource ownership and release, and distinguish impossible states from operational errors. +## Engineering decisions -### Capacity +### Pragmatic Programmer -This fragment configures 5 total session threads, including the parent; use at most 4 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- For design tradeoffs, unclear boundaries, duplicate knowledge, an unexplained green result, or a reversible next step, invoke the Skill tool with `pragmatic-programmer` when installed. If no Skill tool exists, read its `SKILL.md` natively. +- If it is not installed, state the assumptions and invariants, keep one authority per fact, explain why the result works, and choose the smallest reversible step. Do not invent tools or install skills implicitly. diff --git a/arrangements/advanced-delivery/arrangement.toml b/arrangements/advanced-delivery/arrangement.toml index ed94e5b..092de06 100644 --- a/arrangements/advanced-delivery/arrangement.toml +++ b/arrangements/advanced-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "advanced-delivery" -version = "0.2.0" +version = "0.2.1" author = "Rafael Bittencourt" description = "Advanced Delivery: Complex product delivery with dedicated reasoning for decisions, diagnosis, ordinary review, critical review, and coupled implementation." license = "MIT" diff --git a/arrangements/balanced-delivery/AGENTS.snippet.md b/arrangements/balanced-delivery/AGENTS.snippet.md index b817fe4..201cd12 100644 --- a/arrangements/balanced-delivery/AGENTS.snippet.md +++ b/arrangements/balanced-delivery/AGENTS.snippet.md @@ -1,34 +1,18 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -### Routing +### Role selection -Delegate only a bounded task with an independent result. -Inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Reserve Astra for `advisor` and `hard-task-specialist`, and Sol for `backend-worker` and `integrator-reviewer`. Other roles use Luna, including critical review; if the evidence or available reviewer is insufficient for the risk, return to the parent for an independently qualified review. - -### Responsibilities - -Regular workers also handle small edits and create their regression tests. Advisor supplies design direction; hard-task-specialist handles unknown-cause diagnosis before a scoped repair. The parent writes documentation; critical-reviewer handles security review. Test-runner runs existing checks and never becomes a test author. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence - -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -### Capacity +### Ownership and return -This fragment configures 4 total session threads, including the parent; use at most 3 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. diff --git a/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md b/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md index 77454b6..77b2c73 100644 --- a/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md @@ -1,41 +1,25 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -Optional skills can be installed independently. Use the fallback in the relevant section when one is absent; do not invent a callable Skill API on Codex CLI. +### Role selection -### Routing - -For dispatch, call the runtime's Skill tool with `codex-orchestration` when exposed; otherwise use its native skill-loading interface to read `SKILL.md`. In Codex prompts, use `$codex-orchestration`. -If it is absent, inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Reserve Astra for `advisor` and `hard-task-specialist`, and Sol for `backend-worker` and `integrator-reviewer`. Other roles use Luna, including critical review; if the evidence or available reviewer is insufficient for the risk, return to the parent for an independently qualified review. - -### Responsibilities - -Regular workers also handle small edits and create their regression tests. Advisor supplies design direction; hard-task-specialist handles unknown-cause diagnosis before a scoped repair. The parent writes documentation; critical-reviewer handles security review. Test-runner runs existing checks and never becomes a test author. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +### Ownership and return -### Optional engineering guidance +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. -For an ambiguous design or boundary, unexplained green result, duplicate knowledge, contract/input change, reversible-step or spike choice, or shared finite resource, call the Skill tool with `pragmatic-programmer` when exposed; otherwise load its `SKILL.md` natively. In Codex prompts, use `$pragmatic-programmer`. -If it is absent, explain the green signal, name one knowledge authority, validate the boundary and invariants, choose a reversible next step, identify resource ownership and release, and distinguish impossible states from operational errors. +## Engineering decisions -### Capacity +### Pragmatic Programmer -This fragment configures 4 total session threads, including the parent; use at most 3 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- For design tradeoffs, unclear boundaries, duplicate knowledge, an unexplained green result, or a reversible next step, invoke the Skill tool with `pragmatic-programmer` when installed. If no Skill tool exists, read its `SKILL.md` natively. +- If it is not installed, state the assumptions and invariants, keep one authority per fact, explain why the result works, and choose the smallest reversible step. Do not invent tools or install skills implicitly. diff --git a/arrangements/balanced-delivery/arrangement.toml b/arrangements/balanced-delivery/arrangement.toml index e29b770..094e1b5 100644 --- a/arrangements/balanced-delivery/arrangement.toml +++ b/arrangements/balanced-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "balanced-delivery" -version = "0.2.0" +version = "0.2.1" author = "Rafael Bittencourt" description = "Balanced Delivery: Everyday product delivery with Luna implementing established patterns, Sol handling backend work and integration review, and Astra handling decisions and coupled implementation." license = "MIT" diff --git a/arrangements/lean-delivery/AGENTS.snippet.md b/arrangements/lean-delivery/AGENTS.snippet.md index 9b5f03f..201cd12 100644 --- a/arrangements/lean-delivery/AGENTS.snippet.md +++ b/arrangements/lean-delivery/AGENTS.snippet.md @@ -1,34 +1,18 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -### Routing +### Role selection -Delegate only a bounded task with an independent result. -Inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Use at most one active `advisor` and one active `integrator-reviewer`; other child roles use Luna. An advisor remains read-only and is not an implementation fallback. If coupling or risk exceeds the available implementing or reviewing role, return to the parent; do not weaken acceptance. - -### Responsibilities - -Backend/frontend workers handle small edits and write and run their own regression tests. Advisor supplies design direction but never implements. The parent owns documentation, standalone test execution, database and infrastructure work, and coupled or unknown-cause implementation; request separately qualified help when these exceed the parent's scope or capability. Critical-reviewer handles security review; never downgrade the required evidence. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence - -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -### Capacity +### Ownership and return -This fragment configures 3 total session threads, including the parent; use at most 2 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. diff --git a/arrangements/lean-delivery/AGENTS.with-skill.snippet.md b/arrangements/lean-delivery/AGENTS.with-skill.snippet.md index 207db48..77b2c73 100644 --- a/arrangements/lean-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/lean-delivery/AGENTS.with-skill.snippet.md @@ -1,41 +1,25 @@ -## Multi-Agent V2 orchestration +## Delegation and orchestration -Optional skills can be installed independently. Use the fallback in the relevant section when one is absent; do not invent a callable Skill API on Codex CLI. +### Role selection -### Routing - -For dispatch, call the runtime's Skill tool with `codex-orchestration` when exposed; otherwise use its native skill-loading interface to read `SKILL.md`. In Codex prompts, use `$codex-orchestration`. -If it is absent, inspect relevant live role descriptions and the current spawn schema; `list_agents` shows the running tree, not a role catalog. -Match an available role and its resolved allocation to read-only discovery, research, decision, or review; a bounded known artifact; unknown-cause diagnosis; coupled invariants; or integration review. -Use the least resource-intensive safe role; do not give edits to a read-only role. -Luna workers may implement established patterns; model allocation does not change a role's mandate. -Use at most one active `advisor` and one active `integrator-reviewer`; other child roles use Luna. An advisor remains read-only and is not an implementation fallback. If coupling or risk exceeds the available implementing or reviewing role, return to the parent; do not weaken acceptance. - -### Responsibilities - -Backend/frontend workers handle small edits and write and run their own regression tests. Advisor supplies design direction but never implements. The parent owns documentation, standalone test execution, database and infrastructure work, and coupled or unknown-cause implementation; request separately qualified help when these exceed the parent's scope or capability. Critical-reviewer handles security review; never downgrade the required evidence. +- Before delegating or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -The parent owns selection, integration, validation, and outcome; children never spawn children. -Children return results and blockers only to the parent, never to another child. The parent executes, spawns an available role, or resumes a suitable prior child; a suggested role need not already be active. -Every spawn explicitly sets `agent_type` and `fork_turns: "none"` and omits call-level model and reasoning-effort overrides. -The brief contains only relevant context, accepted decisions, and any relevant plan; outcome and acceptance criterion; in/out scope and ownership; interfaces and access constraints; expected artifact and checks; and stop conditions plus next consumer. -It needs neither a separate plan document nor a history dump. - -### Ownership and evidence +- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. -Keep writing ownership non-overlapping; serialize shared files, state, and interacting contracts. -`send_message` only queues a message; `followup_task` starts a completed child on a new turn with its history. -Stop or redirect a child that lacks evidence, exceeds its brief, repeats failure, or conflicts with owned work. -Only the parent integrates, inspects the diff, and verifies responsible checks; skipped, unavailable, or mocked required checks block acceptance. +### Ownership and return -### Optional engineering guidance +- Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. +- Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. +- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. -For an ambiguous design or boundary, unexplained green result, duplicate knowledge, contract/input change, reversible-step or spike choice, or shared finite resource, call the Skill tool with `pragmatic-programmer` when exposed; otherwise load its `SKILL.md` natively. In Codex prompts, use `$pragmatic-programmer`. -If it is absent, explain the green signal, name one knowledge authority, validate the boundary and invariants, choose a reversible next step, identify resource ownership and release, and distinguish impossible states from operational errors. +## Engineering decisions -### Capacity +### Pragmatic Programmer -This fragment configures 3 total session threads, including the parent; use at most 2 simultaneous children. Start with one useful child, not a full roster. -See [runtime validation](https://github.com/rafaelob/fleet-codex/blob/main/docs/validation.md) for environment-specific verification. A refused spawn does not justify idling while independent local work remains. +- For design tradeoffs, unclear boundaries, duplicate knowledge, an unexplained green result, or a reversible next step, invoke the Skill tool with `pragmatic-programmer` when installed. If no Skill tool exists, read its `SKILL.md` natively. +- If it is not installed, state the assumptions and invariants, keep one authority per fact, explain why the result works, and choose the smallest reversible step. Do not invent tools or install skills implicitly. diff --git a/arrangements/lean-delivery/arrangement.toml b/arrangements/lean-delivery/arrangement.toml index 9f8007f..c98e268 100644 --- a/arrangements/lean-delivery/arrangement.toml +++ b/arrangements/lean-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "lean-delivery" -version = "0.2.0" +version = "0.2.1" author = "Rafael Bittencourt" description = "Lean Delivery: Cost-conscious, well-bounded delivery with Luna implementing and reviewing, Sol reconciling deliveries, and one Astra advisor for decisions." license = "MIT" diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index cab2903..79a8a55 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.2.1 — 2026-09-13 + +- Keep insertable delegation rules concise: remove roster counts, concurrency + figures, model-allocation summaries, and runtime-evidence links from snippets. +- Invoke the optional orchestration skill with a native-reading fallback; keep + optional Pragmatic Programmer guidance in a separate engineering section. + ## 0.2.0 — 2026-09-13 - Add Balanced Delivery for everyday product work: two Astra roles, two Sol roles, diff --git a/docs/installation.md b/docs/installation.md index 6aa5a57..d13e9e0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -27,6 +27,12 @@ never restore a whole home over newer credentials or unrelated configuration. ## Choose a scope +Both snippet variants provide standalone delegation rules and invoke +`codex-orchestration` when installed. Choose `AGENTS.with-skill.snippet.md` only +when you also want the separate, optional Pragmatic Programmer engineering +section. Counts, model allocation and runtime evidence belong in the arrangement +README and configuration, not the inserted instruction section. + | Component | User scope | Project scope | | --- | --- | --- | | Configuration | `$CODEX_HOME/config.toml` (normally `~/.codex/config.toml`) | `/.codex/config.toml` |