Implementation workflow appends branch suffix on approved spec PR branch

[captainsafia]

Summary

When an implementation is started on top of an approved spec PR, the implementation agent can push to a suffixed branch such as oz-agent/spec-issue-447-auto-implement-routing even though the spec PR was created on oz-agent/spec-issue-447.

This leaves the outer workflow looking at the approved spec PR branch while the agent has pushed implementation changes somewhere else.

Observed behavior

For issue 447:

• spec creation uses oz-agent/spec-issue-447
• implementation runs with the approved spec PR branch as the target branch
• the agent writes/pushes pr-metadata.json.branch_name as oz-agent/spec-issue-447-auto-implement-routing

Why this happens

The branch contracts are inconsistent:

• core/workflows/create_spec_from_issue.py hard-codes spec branches as oz-agent/spec-issue-{issue_number} and asks the spec agent to use that branch exactly.
• core/workflows/create_implementation_from_issue.py sets target_branch to the approved spec PR head branch when a plan-approved PR is selected, so the target branch is also oz-agent/spec-issue-447.
• The implementation prompt still says pr-metadata.json.branch_name may append a descriptive slug as long as it starts with {target_branch}.
• .agents/skills/implement-issue/SKILL.md strengthens that by saying the branch name must contain a short auto-generated suffix.
• apply_create_implementation_result only accepts branch-name overrides when there is no selected approved spec PR. In the approved-spec case, it ignores the suffixed metadata branch and checks the original spec branch for updates.

The result is that the agent can follow its prompt/skill instructions and still produce a branch the outer workflow does not use for the approved-spec implementation path.

Recommended fix

Make the implementation branch contract conditional:

1. When selected_spec_pr_number is present, instruct the agent to use {target_branch} exactly.
   • pr-metadata.json.branch_name must equal {target_branch}.
   • Do not append a descriptive suffix.
   • Commit and push implementation changes directly to the approved spec PR branch.
2. When there is no approved spec PR selected and the workflow is creating or updating a standalone implementation PR, continue allowing {target_branch}-<descriptive-slug>.
3. Update .agents/skills/implement-issue/SKILL.md so the suffix requirement only applies to standalone implementation branches, not approved spec PR branches.
4. Add or update tests covering both paths:
   • approved spec PR path rejects or does not request suffixes
   • standalone implementation path still allows suffixes such as oz-agent/implement-issue-447-add-routing

Expected behavior

For plan-approved implementations, the implementation agent should push to the approved spec PR branch exactly, so spec and implementation changes remain in one PR as intended.

[oz-for-oss]

@captainsafia

Here's what I found while triaging this issue:

The reported branch mismatch is reproducible from the current workflow contract. No additional reporter input is needed for initial triage.

Maintainer details

I concluded that implementation-on-approved-spec runs can be instructed to push a suffixed branch even though the apply path only checks the approved spec PR branch..

Triage summary

This looks like a workflow bug in the branch handoff contract for plan-approved implementations. The report's root-cause analysis is supported by the current code: spec PRs use oz-agent/spec-issue-{issue_number}, implementation runs on the approved spec PR head branch when one is selected, but the implementation prompt and wrapper skill still permit or require a suffixed metadata branch. The apply step only honors pr-metadata.json.branch_name overrides for standalone implementation PRs, not for selected approved spec PRs.

Evidence

• core/workflows/create_spec_from_issue.py builds spec branches as oz-agent/spec-issue-{issue_number} and tells the spec agent to use that branch exactly.
• core/workflows/create_implementation_from_issue.py sets target_branch from the selected approved spec PR head ref, then renders prompt text allowing branch_name to append a short descriptive slug as long as it starts with target_branch.
• .agents/skills/implement-issue/SKILL.md currently says branch_name must start with the supplied prefix and contain a short auto-generated suffix.
• apply_create_implementation_result only switches to the metadata branch when selected_spec_pr_number is false, so a suffixed branch from the approved-spec path is ignored during the branch-update check.

Suggested fix direction

Make the prompt and wrapper skill conditional: when an approved spec PR is selected, require pr-metadata.json.branch_name to equal the approved spec PR branch exactly and push implementation changes to that branch. Keep suffixes allowed for standalone implementation PRs, and add tests for both paths.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Powered by Oz

[oz-for-oss]

This issue has been labeled ready-to-implement and is open for contributions involving code changes. If you'd like to tackle it, feel free to open a pull request against this issue. You can also comment @oz-agent on this issue to have the bot draft an implementation PR automatically.

[oz-for-oss]

@captainsafia

I'm implementing this issue with no spec context.

You can view the conversation on Warp.

I created a new draft implementation PR for this issue.

Next steps:

• Review the implementation changes in the PR.
• Complete any manual verification needed for this issue before merging.

Powered by Oz