Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The bundle codifies an **issue-driven development** workflow where the GitHub is
`issue-dispatch` is the upper-level implementation scheduler:

- `issue-dispatch` → N × `issue-implement` (one dedicated worker / worktree / branch / PR per issue; dependencies and high-conflict issues are serialized)
- `issue-implement` → `issue-dispatch` only for a single PR-shaped Ready issue invoked from Codex CLI on the default branch. The dispatcher launches `codex exec --worktree`; the native managed-worktree worker re-enters `issue-implement`, verifies isolation, establishes the expected issue branch, and continues without dispatching again.
- `issue-implement` → `issue-dispatch` only for a single PR-shaped Ready issue invoked from Codex CLI on the default branch. The dispatcher launches `codex exec --approve-for-me --worktree`; `--approve-for-me` runs the worker in `workspace-write` and routes sandbox-boundary approval requests to Auto-review. The native managed-worktree worker re-enters `issue-implement`, verifies isolation, establishes the expected issue branch, and continues without dispatching again.
- Direct multi-issue implementation requests enter `issue-dispatch`. `issue-pick` remains read-only and does not chain into it without a new explicit implementation request from the user.

`issue-discover` is the read-only entry point for finding new, untracked improvement themes from repository evidence:
Expand All @@ -40,7 +40,7 @@ The `issue-implement ↔ worktree-start` and `issue-implement ↔ issue-dispatch

- When `worktree-start` is the entry point and chains forward into `issue-implement`, the latter sees that it is already in a linked worktree and continues without re-invoking `worktree-start`.
- When `issue-implement` is the entry point and calls `worktree-start` from step 4, it must pass a pre-generated branch-name slug (`<title>-<issue番号>`), **not** the issue number. Passing the number would re-enter `worktree-start`'s Status-detection path and re-chain back into `issue-implement` unnecessarily. The recursion would still terminate via the no-op check, but the redundant invocation is avoided by routing through the task-description mode of `worktree-start`.
- When Codex CLI `issue-implement` on the default branch calls `issue-dispatch`, the dispatcher passes the issue number and expected branch to a new `codex exec --worktree` worker. That worker's isolation preflight recognizes its assignment, switches from detached HEAD or an unexpected branch before its first implementation write, and continues locally without calling `issue-dispatch` again.
- When Codex CLI `issue-implement` on the default branch calls `issue-dispatch`, the dispatcher passes the issue number and expected branch to a new `codex exec --approve-for-me --worktree` worker. That worker's isolation preflight recognizes its assignment, establishes the expected branch before its first implementation write, and continues locally without calling `issue-dispatch` again.

When editing one skill, check whether others reference it. Cross-references appear in two forms:

Expand Down Expand Up @@ -81,7 +81,7 @@ These strings are not localizable in the current implementation. Forking is requ
- A linked worktree dedicated to the current issue/task continues without double creation. A worktree assigned to another task, or with unverifiable assignment, stops. A non-default feature branch is preserved for a single implementation. A main working tree in detached HEAD stops as unclassifiable; a runtime-owned detached HEAD linked worktree (such as Codex App) is allowed when its current-task assignment is established.
- A write-capable parallel worker is evaluated first and requires **one worker = one worktree** even if it is already on a feature branch. Continue only when runtime/session context establishes that the linked worktree is dedicated to that worker; otherwise stop.
- Default-branch execution must move to a dedicated worktree or stop before implementation. There is no skip-and-continue path.
- Codex CLI on the default branch hands a single issue to `issue-dispatch`. The parent remains in its current cwd; the dispatcher launches one issue-specific worker with `codex exec --worktree`. Codex owns the managed worktree path and lifecycle. If dispatch preflight cannot guarantee native worktree support, sandbox, approval, authentication, or isolation, it stops before implementation without an IssueKit-managed fallback.
- Codex CLI on the default branch hands a single issue to `issue-dispatch`. The parent remains in its current cwd; the dispatcher launches one issue-specific worker with `codex exec --approve-for-me --worktree`. `--approve-for-me` runs the worker in `workspace-write` and routes sandbox-boundary approval requests to Auto-review; Codex owns the managed worktree path and lifecycle. If dispatch preflight cannot guarantee native worktree support, Auto-review, sandbox, authentication, or isolation, it stops before implementation without an IssueKit-managed fallback.
- Codex App managed worktrees and Handoff are App-owned. Skills may verify that the chat is isolated or tell the user to use the App UI, but must not claim to create or control App-managed worktrees.
- Claude Code interactive sessions may invoke `worktree-start`, which owns the in-session `EnterWorktree` call. `claude --worktree`, subagent `isolation: worktree`, Agent view background-session isolation, and Desktop automatic session worktrees remain runtime-owned paths.

Expand All @@ -97,7 +97,7 @@ Worktrees are fresh checkouts. Document dependency/environment initialization an
- `Depends on:` is a DAG. Open dependencies outside the candidate set block the issue. Dependencies inside the set create scheduling edges, but a downstream worker still waits for the dependency issue to close and land on the default branch; PR + CI success alone is not a merge substitute.
- High-overlap changes are serialized with the same merge barrier. If independence cannot be established, show the uncertain path estimate before implementation and ask the user whether to serialize or exclude.
- Multiple-issue concurrency defaults to 3 and is capped by the user's value, runtime limit, and currently independent Ready issue count. A failed worker blocks only its dependents; unrelated workers continue.
- Codex CLI write workers use `codex exec --worktree`. Their non-interactive sandbox writes the Codex-assigned managed worktree without granting broad repository access. IssueKit does not choose the worktree path or manage its Git metadata / cleanup. Fresh approvals cannot be requested mid-run, so native worktree support, approval, sandbox, `gh`, and Codex authentication are preflight requirements.
- Codex CLI write workers use `codex exec --approve-for-me --worktree`; `--approve-for-me` runs the worker in `workspace-write` and routes sandbox-boundary approval requests to Auto-review. Git metadata mutations such as `fetch`, `switch`, `add`, `commit`, and `push` are requested from their first attempt as narrowly scoped escalations for one exact command at a time. If Auto-review is unavailable, denied, or times out, the worker is blocked; it does not retry with broader permissions, writable-root additions, `--add-dir`, or manual worktree fallbacks. IssueKit does not choose the worktree path or manage its Git metadata / cleanup.
- Current Codex native subagents may be used for read-only analysis, but not parallel writes unless the runtime explicitly guarantees a dedicated cwd / worktree per worker. Claude Code write workers use `isolation: worktree`, Agent view isolation, or an equivalent official primitive; non-isolated Agent teams are not used.
- Codex App top-level Worktree chats and Handoff remain App-owned. When the surface cannot guarantee automated per-issue worktrees, return the plan and launch prompts; do not automate the UI.
- The parent waits for every worker to succeed, fail, block, or remain waiting, then aggregates issue number, state, branch, PR URL, CI, and blocker. It never auto-merges or auto-cleans worker state.
Expand All @@ -119,7 +119,7 @@ The runtime must be determined from the running agent's explicit environment, no

- `gh` CLI — all GitHub operations. Must be authenticated against the target repo.
- The CLI for the current agent runtime: Codex CLI (`brew install --cask codex`) when implementing from Codex, or Claude CLI (`npm install -g @anthropic-ai/claude-code`) when implementing from Claude Code. `cross-review` must fail loudly (not silently skip) when the corresponding CLI is unavailable or the current runtime has no documented reviewer-session launch step.
- Codex CLI dispatch additionally requires authenticated non-interactive `codex exec`, `codex exec --worktree` support, and sandbox write access to the runtime-assigned worker checkout.
- Codex CLI dispatch additionally requires authenticated non-interactive `codex exec`, `--approve-for-me` and `--worktree` support, and the `workspace-write` mode selected by `--approve-for-me`, with sandbox-boundary approval requests routed to Auto-review.
- Claude Code with `EnterWorktree` support — required by `worktree-start`. If unavailable, the skill instructs users to update/restart or start a new isolated session with `claude --worktree` rather than continuing on the default branch.

## Editing skills
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,11 +115,11 @@ issuekit ships ten skills under `skills/`:

Before `issue-implement` writes files or commits, it classifies the current location as a linked worktree, a non-default feature branch, or the repository's default branch. An existing linked worktree dedicated to the current issue/task is reused without creating another one; a linked worktree assigned to another task, or with unverifiable assignment, is not reused. A single implementation on an existing feature branch is also preserved. A write-capable parallel worker is evaluated first and is stricter: **one worker must have one dedicated worktree**. If exclusive assignment cannot be established from runtime/session context, the worker stops instead of assuming a linked worktree is safe.

[Codex subagent workflows](https://learn.chatgpt.com/docs/agent-configuration/subagents) are available in the CLI, IDE extension, and App, but the current documented subagent contract does not assign a dedicated cwd / worktree to each native subagent. Keep parallel exploration and review read-only where possible. `issue-dispatch` uses [`codex exec --worktree`](https://developers.openai.com/codex/cli/reference) for Codex CLI write workers and refuses same-checkout parallel writes when the runtime cannot guarantee isolation.
[Codex subagent workflows](https://learn.chatgpt.com/docs/agent-configuration/subagents) are available in the CLI, IDE extension, and App, but the current documented subagent contract does not assign a dedicated cwd / worktree to each native subagent. Keep parallel exploration and review read-only where possible. `issue-dispatch` uses [`codex exec --approve-for-me --worktree`](https://developers.openai.com/codex/cli/reference) for Codex CLI write workers and refuses same-checkout parallel writes when the runtime cannot guarantee isolation.

| Runtime | Isolation contract on the default branch |
| --- | --- |
| Codex CLI | A single `issue-implement` request on the default branch hands the issue to `issue-dispatch`. The parent starts one non-interactive worker with [`codex exec --worktree`](https://developers.openai.com/codex/cli/reference), without migrating its own cwd. Codex owns the managed worktree path and lifecycle; the worker verifies isolation and establishes its expected issue branch before editing. |
| Codex CLI | A single `issue-implement` request on the default branch hands the issue to `issue-dispatch`. The parent starts one non-interactive worker with [`codex exec --approve-for-me --worktree`](https://developers.openai.com/codex/cli/reference), without migrating its own cwd. `--approve-for-me` runs the worker in `workspace-write` and routes sandbox-boundary approval requests to Auto-review; Codex owns the managed worktree path and lifecycle; the worker verifies isolation and establishes its expected issue branch before editing. |
| Codex App | Start the chat in an App-managed **Worktree**, or use **Handoff** from Local to Worktree. These are App-owned features; issuekit does not create or control managed worktrees. See [Codex Worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees). |
| Claude Code CLI | Start isolated with `claude --worktree <name>`, or let `worktree-start` use `EnterWorktree` from an interactive session. See [Claude Code worktrees](https://code.claude.com/docs/en/worktrees). |
| Claude Code subagent | Set `isolation: worktree` in the agent frontmatter or spawn configuration. See [Claude Code subagents](https://code.claude.com/docs/en/sub-agents). |
Expand All @@ -138,7 +138,7 @@ Multiple-issue runs default to three concurrent workers. The effective limit is

Runtime behavior is deliberately asymmetric:

- **Codex CLI:** the parent launches one `codex exec --worktree` worker per issue with `workspace-write` and non-interactive approval behavior. Codex owns worktree creation and lifecycle. Each prompt carries the issue, dedicated-worker assignment, expected branch, and `issue-implement <N>` instruction; the worker verifies the linked worktree, switches from detached HEAD when necessary, and continues through PR and CI. A failed native worktree launch is reported without a `git worktree add` / `codex exec -C` fallback.
- **Codex CLI:** the parent launches one `codex exec --approve-for-me --worktree` worker per issue. `--approve-for-me` runs the worker in `workspace-write` and routes sandbox-boundary approval requests to Auto-review. Each Git metadata mutation is requested from its first attempt as a narrowly scoped escalation for one exact command. If Auto-review is unavailable, denied, or times out, the worker is blocked without broadening permissions or falling back to writable-root additions, `--add-dir`, or manual worktrees. Codex owns worktree creation and lifecycle. Each prompt carries the issue, dedicated-worker assignment, expected branch, and `issue-implement <N>` instruction; the worker verifies the linked worktree, establishes the branch before editing, and continues through PR and CI.
- **Claude Code:** use a subagent with `isolation: worktree`, Agent view's worktree-isolated background session, or an equivalent official isolation primitive. Do not use non-isolated Agent teams for write workers.
- **Codex App:** top-level Worktree chats and Handoff are App-owned. When the current surface cannot create one isolated chat per issue, the skill returns the worktree plan and per-issue launch prompts instead of automating the UI.

Expand Down
Loading
Loading