Skip to content

Generalize plan-issue runtime adapters and add installer flow #233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
graysurf merged 2 commits into from
Mar 16, 2026
Merged

Generalize plan-issue runtime adapters and add installer flow #233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8f67d3
feat(plan-issue-delivery): add runtime adapter installer
graysurf Mar 16, 2026
2af7872
fix(plan-issue-delivery): track codex adapter config template
graysurf Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 28 additions & 2 deletions prompts/plan-issue-delivery-main-agent-init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,15 @@ Execution context (fill before run)
`$AGENT_HOME/out/plan-issue-delivery/{repo-slug}/issue-<ISSUE_NUMBER>/plan/plan-integration-pr.md`
- Plan integration mention URL path:
`$AGENT_HOME/out/plan-issue-delivery/{repo-slug}/issue-<ISSUE_NUMBER>/plan/plan-integration-mention.url`
- Role mapping reference:
`$AGENT_HOME/skills/automation/plan-issue-delivery/references/AGENT_ROLE_MAPPING.md`
- Canonical workflow roles:
- `implementation`
- `review`
- `monitor`
- Runtime adapter metadata:
- record `runtime_name` / `runtime_role` only when the active runtime
supports named child-agent roles

PR grouping policy (scene-based; both are valid)

Expand All @@ -59,8 +68,12 @@ Required workflow
`MAIN_AGENT_INIT_SNAPSHOT_PATH` + `TASK_PROMPT_PATH` +
`PLAN_SNAPSHOT_PATH` + `SUBAGENT_INIT_SNAPSHOT_PATH` +
`DISPATCH_RECORD_PATH` + decision-scoped `REVIEW_EVIDENCE_PATH` artifacts under
`$AGENT_HOME/out/plan-issue-delivery/...` -> delegate to subagents with
required `PLAN_BRANCH` base-branch context -> if blocked, clarify and
`$AGENT_HOME/out/plan-issue-delivery/...` -> select the correct
`workflow_role` for each spawned task and persist it in sprint
manifests/dispatch records -> when the active runtime supports named
child-agent roles, also persist `runtime_name` / `runtime_role` ->
delegate to subagents with required `PLAN_BRANCH` base-branch context ->
if blocked, clarify and
continue on the same task lane -> `ready-sprint` (pre-merge checkpoint) ->
review each PR using the shared review rubric -> generate
`REVIEW_EVIDENCE_PATH` from `REVIEW_EVIDENCE_TEMPLATE_PATH` -> execute
Expand Down Expand Up @@ -89,6 +102,15 @@ Required workflow
Mandatory subagent launch rule

- For each task, use the rendered `TASK_PROMPT_PATH` from dispatch hints as the primary init prompt when spawning subagents.
- Use `workflow_role=implementation` for implementation-owned sprint lanes.
- Use `workflow_role=review` only for read-only audit/evidence helpers.
- Use `workflow_role=monitor` only for long-running CI/status watch helpers.
- Always record the chosen `workflow_role` in `DISPATCH_RECORD_PATH`.
- If the active runtime supports named child-agent roles, also record
`runtime_name` / `runtime_role`.
- If a named-role runtime falls back to a generic child agent, record
`runtime_role=generic` plus `runtime_role_fallback_reason` before spawning
the child agent.
- Always copy `$AGENT_HOME/prompts/plan-issue-delivery-subagent-init.md` to sprint runtime and attach `SUBAGENT_INIT_SNAPSHOT_PATH`.
- Always attach `PLAN_SNAPSHOT_PATH` from issue runtime workspace as fallback plan context.
- Always attach `DISPATCH_RECORD_PATH` from sprint manifests for execution-fact traceability.
Expand Down Expand Up @@ -128,6 +150,9 @@ Mandatory subagent launch rule
- `SUBAGENT_INIT_SNAPSHOT_PATH`
- `PLAN_SNAPSHOT_PATH`
- `DISPATCH_RECORD_PATH`
- `workflow_role`
- optional `runtime_name` / `runtime_role` (or `runtime_role_fallback_reason`
when a named-role runtime falls back to generic)
- `PLAN_BRANCH`
- plan task section snippet/link/path (`<plan-file>#<sprint/task section>` or equivalent)
- Do not start subagents with ad-hoc prompts that bypass the required dispatch bundle.
Expand All @@ -137,6 +162,7 @@ Reporting contract (every update)
- Phase:
- Commands run:
- Gate status:
- Workflow roles / runtime adapters:
- Subagent assignments / PR references:
- Blockers / risks:
- Next required action:
Expand Down
32 changes: 23 additions & 9 deletions prompts/plan-issue-delivery-subagent-init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,21 @@ Execution context (fill before run)
- Subagent init snapshot path: `<SUBAGENT_INIT_SNAPSHOT_PATH>`
- Plan snapshot path: `<PLAN_SNAPSHOT_PATH>`
- Dispatch record path: `<DISPATCH_RECORD_PATH>`
- Workflow role: `<implementation>`
- Runtime role: `<runtime-specific role or N/A>`

Required inputs from main-agent (must be attached)

- Rendered task prompt artifact (`TASK_PROMPT_PATH`) from `start-sprint`.
- Sprint-scoped subagent companion prompt snapshot (`SUBAGENT_INIT_SNAPSHOT_PATH`).
- Issue-scoped plan snapshot fallback (`PLAN_SNAPSHOT_PATH`) copied from source plan.
- Task-scoped dispatch record (`DISPATCH_RECORD_PATH`) with execution facts (worktree/branch/mode/group).
- `DISPATCH_RECORD_PATH` role facts:
- `workflow_role` should be `implementation` for implementation lanes
- if runtime adapter metadata is present, `runtime_role` should match the
assigned runtime role for this lane
- if a named-role runtime fell back to generic, `runtime_role_fallback_reason`
must explain why the preferred runtime role was unavailable
- Required base branch context (`PLAN_BRANCH`) for PR targeting.
- Plan task context for assigned IDs:
- exact task section snippet and/or
Expand All @@ -63,21 +71,25 @@ Delivery requirements
created yet.
3. Resolve plan context in this order: assigned task snippet/link/path -> `PLAN_SNAPSHOT_PATH` -> source plan link/path (last fallback).
4. If plan references conflict, follow issue runtime-truth assignment (`Task Decomposition` row) and escalate ambiguities.
5. Validate `DISPATCH_RECORD_PATH` matches assigned task IDs, worktree, branch, execution mode, and `PLAN_BRANCH` before editing.
6. Keep changes within assigned task scope; escalate before widening scope.
7. If required context is missing/conflicting or another blocker stops progress, return a blocker packet with exact lane facts, the missing
5. Validate `DISPATCH_RECORD_PATH` matches assigned task IDs, worktree, branch,
execution mode, `PLAN_BRANCH`, and `workflow_role` before editing.
6. If `DISPATCH_RECORD_PATH` declares a non-implementation `workflow_role`,
stop and request corrected dispatch before editing.
7. Keep changes within assigned task scope; escalate before widening scope.
8. If required context is missing/conflicting or another blocker stops progress, return a blocker packet with exact lane facts, the missing
input, current status, and the next unblock action needed from main-agent.
8. Run relevant tests for impacted areas and capture results.
9. Keep commits and PR description traceable to task IDs.
10. Surface risks early with concrete mitigation options.
11. Keep sprint PRs open for `ready-sprint` pre-merge review; do not self-merge.
12. Wait for required PR CI checks to finish before marking work ready for review/merge.
13. If PR CI fails, diagnose and fix the failures, push updates, and repeat until required checks pass (or escalate external blockers with
9. Run relevant tests for impacted areas and capture results.
10. Keep commits and PR description traceable to task IDs.
11. Surface risks early with concrete mitigation options.
12. Keep sprint PRs open for `ready-sprint` pre-merge review; do not self-merge.
13. Wait for required PR CI checks to finish before marking work ready for review/merge.
14. If PR CI fails, diagnose and fix the failures, push updates, and repeat until required checks pass (or escalate external blockers with
evidence).

Update format (every checkpoint)

- Task IDs completed/in progress:
- Workflow role / runtime role:
- Task lane facts (`Owner / Branch / Worktree / PR`):
- Files/components changed:
- Tests run + key results:
Expand All @@ -91,4 +103,6 @@ Done criteria
- PR content is reviewable, with clear task mapping and no hidden scope changes.
- Required PR CI checks are passing, or external blockers are escalated with concrete evidence and mitigation options.
- Sprint PR targets assigned `PLAN_BRANCH` and stays unmerged until main-agent review decision.
- If the active runtime fell back to a generic child agent, the fallback
rationale remains recorded in `DISPATCH_RECORD_PATH`.
- If blocked, do not claim done; return the blocker packet and wait for main-agent clarification/unblock.
4 changes: 4 additions & 0 deletions scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ scripts/
│ │ └── shell.sh
│ └── zsh-common.zsh
├── lint.sh
├── plan-issue-adapter
├── project-resolve
├── semgrep-scan.sh
└── test.sh
Expand Down Expand Up @@ -103,6 +104,9 @@ scripts/

- `scripts/check_plan_issue_worktree_cleanup.sh`
- Checks leftover `plan-issue-delivery` worktree directories.
- `scripts/plan-issue-adapter`
- Explicit installer/sync/status entrypoint for optional `plan-issue-delivery`
runtime adapters (`codex|claude|opencode`).
- `scripts/chrome-devtools-mcp.sh`
- Launcher for chrome-devtools MCP server with repo env handling.
- `scripts/project-resolve`
Expand Down
Loading
Loading