Skip to content

Add managed parallel delivery - #7

Merged
samtay32 merged 2 commits into
mainfrom
codex/parallel-delivery-adapter
Jul 26, 2026
Merged

Add managed parallel delivery#7
samtay32 merged 2 commits into
mainfrom
codex/parallel-delivery-adapter

Conversation

@samtay32

@samtay32 samtay32 commented Jul 26, 2026

Copy link
Copy Markdown
Owner

Outcome

Adds adaptive, primary-agent-managed parallel delivery while preserving a safe serial fallback. The user continues working through one conversation; the primary agent decides when native subagents help and owns assignment, monitoring, recovery, integration, verification, and cleanup.

What changed

  • adds the coordinate-parallel-delivery skill and durable delegation record
  • adds fail-closed config guardrails: three-worker default, four-worker hard cap, no nested delegation, no authority expansion, isolated parallel writes, and mandatory serial fallback
  • ships conservative read-only worker profiles for Codex, Gemini CLI, and OpenCode, plus Claude Code with --claude
  • routes the end-to-end delivery skill through the adaptive coordination decision
  • updates the README, architecture, operating manual, source tradeoffs, plugin metadata, changelog, and version to 0.3.0
  • adds lifecycle, migration, tamper-resistance, adapter-permission, tarball, and packed-install coverage

Decisions and non-goals

  • This is a portable policy coordinator over native harness capabilities, not a bundled agent framework or mandatory swarm.
  • Parallel writes require a verified separate worktree/workspace; a branch alone is not isolation.
  • Firstmate Kimi/tmux runtime changes remain deferred because they add a supervisor/session dependency rather than improving the portable contract.
  • This PR prepares 0.3.0 but does not publish npm.

Verification

  • npm run release:check — 38 tests passed; syntax, tarball inspection, and clean packed-install smoke passed
  • all 9 skills passed quick_validate.py
  • plugin passed validate_plugin.py
  • npx --yes markdownlint-cli2@0.20.0 **/*.md #CHANGELOG\ 2.md — 0 errors (the untracked owner file CHANGELOG 2.md remains untouched and outside this PR)
  • git diff --check — clean

Upgrade, rollback, and monitoring

Existing project customizations are preserved as versioned reconciliation proposals. Legacy isolated_independent_only config migrates to the new safe adaptive policy. Roll back by reverting this PR; no database or production migration is involved. Monitor CI, the current-head CodeRabbit review, unresolved threads, and the protected review-receipt check before merge.

Known risk

Native harness schemas can evolve. The adapters are read-only and version-documented, while unsupported or uncertain capabilities fail back to serial execution.

Summary by CodeRabbit

  • New Features

    • Added adaptive parallel delivery with bounded native subagents and automatic serial fallback.
    • Added read-only research workers for supported agent environments.
    • Added delegation tracking and clearer delivery coordination guidance.
    • Added safeguards for worker limits, isolated writes, verification, and non-recursive delegation.
  • Upgrade Impact

    • Version 0.3.0 includes migration support that preserves existing project files and adds safe parallel-delivery defaults.
  • Documentation

    • Updated guides, architecture diagrams, changelog, and templates to explain coordination, worker boundaries, and verification practices.

@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown

Review Change Stack

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3ccfa6d4-5af8-4a04-b6f1-f7b535a4adb7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The release adds coordinator-managed adaptive delivery, bounded native worker adapters, durable delegation records, protected parallel-delivery configuration, installation wiring, documentation, and tests for migration, guardrails, artifacts, and packed installs.

Changes

Adaptive delivery coordination

Layer / File(s) Summary
Coordination contract and policy
skills/coordinate-parallel-delivery/*, skills/run-autonomous-delivery/SKILL.md, assets/project-template/.agent-stack/*, assets/project-template/AGENTS.md, assets/project-template/GEMINI.md, docs/ARCHITECTURE.md
Adds serial-versus-bounded-parallel coordination rules, worker authority limits, isolated-write requirements, delegation records, recovery behavior, and primary-agent integration ownership.
Runtime policy and installation wiring
bin/ultimate-agent-stack.mjs, assets/project-template/.claude/agents/*, assets/project-template/.codex/agents/*, assets/project-template/.gemini/agents/*, assets/project-template/.opencode/agents/*, package.json, .codex-plugin/plugin.json, .github/workflows/publish.yml
Adds adaptive parallel-delivery defaults, migration and validation, coordinator prompts and doctor reporting, native read-only worker templates, harness installation changes, and 0.3.0 metadata.
Documentation and release surface
README.md, CHANGELOG.md, docs/OPERATING_MANUAL.md, docs/SKILL_STACK.md, docs/SOURCES_AND_TRADEOFFS.md
Documents the one-coordinator model, capability levels, native subagent behavior, fallback rules, package contents, and upgrade impact.
Installation and policy validation
test/agent-stack.test.mjs, scripts/packed-smoke.mjs, .markdownlint-cli2.jsonc
Tests lifecycle installation, Claude-mode artifacts, legacy migration, adapter restrictions, immutable guardrails, packed artifacts, and markdown lint configuration.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PrimaryAgent
  participant CoordinateParallelDelivery
  participant NativeWorker
  participant ProjectPolicy
  participant Verification
  PrimaryAgent->>CoordinateParallelDelivery: select execution strategy
  CoordinateParallelDelivery->>ProjectPolicy: read worker and isolation limits
  CoordinateParallelDelivery->>NativeWorker: dispatch bounded read-only or isolated assignment
  NativeWorker-->>PrimaryAgent: return findings and evidence
  PrimaryAgent->>Verification: inspect, integrate, and verify output
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately summarizes the main change: adding managed parallel delivery.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/parallel-delivery-adapter

Comment @coderabbitai help to get the list of available commands.

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bin/ultimate-agent-stack.mjs`:
- Around line 1378-1397: Update the `parallel-delivery` report’s error matching
to also recognize the whole-object validation error `"parallel_delivery must be
an object"` (or otherwise use the appropriate `validateConfig()` error scope),
ensuring `ok` is false whenever `config.parallel_delivery` is missing or
non-object while preserving existing field-error handling. Add a regression test
that deletes or replaces `parallel_delivery` with a non-object and asserts the
report named `parallel-delivery` has `ok === false`.

In `@docs/ARCHITECTURE.md`:
- Line 115: Update the DELEGATION.md entry in the durable-state table in
ARCHITECTURE.md to document the actual path
assets/project-template/.agent-stack/artifacts/DELEGATION.md, matching the
coordination skill’s .agent-stack/artifacts/DELEGATION.md reference.
- Around line 81-83: Update the architecture diagram’s coordination edge so
coordination originates from LOCK rather than RD, preserving the execution order
where shaping and locking occur before strategy selection. Keep the existing
PD-to-BV and bounded-delegation relationships unchanged, and ensure the diagram
matches the contract in SKILL.md.

In `@skills/coordinate-parallel-delivery/SKILL.md`:
- Line 59: Revise the serial fallback instruction near “Otherwise, continue
serially” so “without asking the user” applies only to selecting the delivery
strategy. Explicitly preserve required human-authority checkpoints for
credentials, destructive production actions, releases, legal/compliance risks,
and other irreversible decisions.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ce96d86d-0072-4490-8e4f-d5588ca43bb1

📥 Commits

Reviewing files that changed from the base of the PR and between fcec734 and bd5f7dc.

⛔ Files ignored due to path filters (2)
  • docs/assets/synthesis-map.svg is excluded by !**/*.svg
  • package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (27)
  • .codex-plugin/plugin.json
  • .github/workflows/publish.yml
  • .markdownlint-cli2.jsonc
  • CHANGELOG.md
  • README.md
  • STARTER_PROMPT.md
  • assets/project-template/.agent-stack/HANDOFF.md
  • assets/project-template/.agent-stack/artifacts/DELEGATION.md
  • assets/project-template/.agent-stack/core-policy.json
  • assets/project-template/.claude/agents/uas-researcher.md
  • assets/project-template/.codex/agents/uas_researcher.toml
  • assets/project-template/.gemini/agents/uas-researcher.md
  • assets/project-template/.opencode/agents/uas-researcher.md
  • assets/project-template/AGENTS.md
  • assets/project-template/GEMINI.md
  • bin/ultimate-agent-stack.mjs
  • docs/ARCHITECTURE.md
  • docs/OPERATING_MANUAL.md
  • docs/SKILL_STACK.md
  • docs/SOURCES_AND_TRADEOFFS.md
  • package.json
  • scripts/packed-smoke.mjs
  • skills/coordinate-parallel-delivery/SKILL.md
  • skills/coordinate-parallel-delivery/agents/openai.yaml
  • skills/coordinate-parallel-delivery/references/delegation-contract.md
  • skills/run-autonomous-delivery/SKILL.md
  • test/agent-stack.test.mjs

Comment thread bin/ultimate-agent-stack.mjs
Comment thread docs/ARCHITECTURE.md Outdated
Comment thread docs/ARCHITECTURE.md Outdated
Comment thread skills/coordinate-parallel-delivery/SKILL.md Outdated

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@samtay32
samtay32 marked this pull request as ready for review July 26, 2026 17:33
@samtay32
samtay32 merged commit 5a63dbc into main Jul 26, 2026
32 checks passed
@samtay32
samtay32 deleted the codex/parallel-delivery-adapter branch July 28, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant