spec: support configurable template formats for Oz responses by oz-for-oss[bot] · Pull Request #361 · warpdotdev/oz-for-oss

oz-for-oss · 2026-04-26T18:43:39Z

Summary

add a product spec for configurable Oz workflow comment templates in .github/oz/config.yml
add a tech spec for a workflow_comments section, a centralized template registry, and helper/script refactors
scope the first release to workflow-owned deterministic response text while leaving model-authored prose out of config

Validation

reviewed specs/GH347/product.md and specs/GH347/tech.md for config shape, scope boundaries, and implementation alignment
confirmed the specs build directly on the shared workflow config path introduced by issue Remove Warp-specific hardcoded values from self-improvement scripts for OSS compatibility #338

Notes

no open product questions remain for the first release; model-authored prose stays out of scope

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

oz-for-oss · 2026-04-26T18:44:20Z

@oz-for-oss[bot]

I'm starting a first review of this spec-only pull request.

You can view the conversation on Warp.

I completed the review and posted feedback on this pull request.

Powered by Oz

oz-for-oss

Overview

This PR adds product and tech specs for configurable workflow_comments in .github/oz/config.yml, centered on a shared template registry, strict validation, and preserving current behavior when no overrides are configured.

Concerns

The tech spec's migration target list still omits several deterministic workflow-owned comment surfaces that remain hardcoded outside helpers, so the scoped implementation would not yet satisfy the product claim that current hardcoded workflow comment copy becomes configurable.
The Next steps design only templates the section heading while leaving the actual step text hardcoded in workflow entrypoints, which keeps some of the most repository-specific workflow guidance out of config.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Powered by Oz

captainsafia

@oz-agent Let's make the following tweaks to the spec.

oz-for-oss · 2026-04-26T19:15:36Z

@captainsafia

I'm working on changes requested in this PR (responding to a PR review body). Spec context was found and will be used to ground the change.

You can view the conversation on Warp.

I pushed changes to this PR based on the comment.

Replied to and attempted to resolve 5 review comments that this run addressed.

Next steps:

Review the changes pushed to this PR.
Follow up with another comment if further adjustments are needed.

Powered by Oz

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

captainsafia · 2026-04-26T21:33:00Z

/oz-review

oz-for-oss · 2026-04-26T21:33:36Z

@captainsafia

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and posted feedback on this pull request.

Powered by Oz

oz-for-oss

Overview

This PR adds a centralized workflow comment template registry, extends .github/oz/config.yml loading to support workflow_comments, routes several existing helper/entrypoint strings through the new renderer, and adds specs, docs, and targeted tests for the new configuration surface.

Concerns

The first-release template surface is still incomplete. Several deterministic workflow-owned completion/no-op messages remain hardcoded outside workflow_comments, so repositories still cannot fully customize the core progress-comment copy promised by the product/tech specs. Examples include create_spec_from_issue.py:201, create_implementation_from_issue.py:245, respond_to_pr_comment.py:309, and the review completion/no-op paths in review_pr.py:432-446 and review_pr.py:738.
The render-time Missing placeholder values... error omits the resolved config path, which makes broken overrides harder to trace than the README/spec contract suggests.

Verdict

Found: 0 critical, 1 important, 1 suggestions

Request changes

Powered by Oz

oz-for-oss · 2026-04-26T21:40:24Z

+
+#### 2a. Enumerate the first-release template registry
+
+The first release should explicitly register every deterministic user-visible string that is currently hardcoded in helpers or workflow entrypoints, rather than leaving implementers to rediscover them during coding. The initial namespace/key set should be documented in the new module and reflected in README examples.


⚠️ [IMPORTANT] This first-release registry still falls short of the product goal to make core workflow completion copy configurable. The implementation in this PR leaves several deterministic completion/no-op messages hardcoded outside workflow_comments — for example create_spec_from_issue.py:201, create_implementation_from_issue.py:245, respond_to_pr_comment.py:309, and review_pr.py:432-446 / review_pr.py:738. Repositories would still need to fork Python to change those responses, so the surface list here should either add those keys or narrow the promised coverage.

oz-for-oss · 2026-04-26T21:40:24Z

+        name: str(value)
+        for name, value in (context or {}).items()
+    }
+    missing = sorted(name for name in placeholders if name not in normalized_context)


💡 [SUGGESTION] The other validation failures include the resolved .github/oz/config.yml path, but this render-time error does not. If a repo override uses an allowed placeholder that the caller forgot to supply, the maintainer only sees namespace.key, which is harder to trace than the README/spec contract implies. Consider including the resolved config path in this exception when the selected template came from workflow_comments.

… registry Add missing completion/no-op template keys to the registry and route all previously hardcoded entrypoint strings through render_comment_template: - create-spec-from-issue.complete_no_diff - create-implementation-from-issue.complete_no_diff - respond-to-pr-comment.complete_no_diff - review-pull-request.complete_no_feedback / complete_approved_with_reviewers / complete_approved_no_reviewers / complete_changes_requested / complete_commented Also include the resolved config path in the render-time missing-placeholder error when the template came from a workflow_comments override, and update the tech spec to enumerate all first-release keys including the completion paths. Co-Authored-By: Oz <oz-agent@warp.dev>

captainsafia · 2026-04-26T23:21:16Z

Addressed the review feedback:

Hardcoded workflow comments moved to template registry:

create-spec-from-issue.complete_no_diff — "I analyzed this issue but did not produce a spec diff." (was hardcoded at create_spec_from_issue.py:201)
create-implementation-from-issue.complete_no_diff — "I analyzed this issue but did not produce an implementation diff." (was hardcoded at create_implementation_from_issue.py:245)
respond-to-pr-comment.complete_no_diff — "I analyzed the request but did not produce any changes." (was hardcoded at respond_to_pr_comment.py:309)
review-pull-request.complete_no_feedback — no-feedback no-op path (was hardcoded at review_pr.py:738)
review-pull-request.complete_approved_with_reviewers — uses ${reviewer_mentions} placeholder
review-pull-request.complete_approved_no_reviewers
review-pull-request.complete_changes_requested
review-pull-request.complete_commented

The _format_review_completion_message() helper in review_pr.py now delegates to render_comment_template() for all four review completion variants.

Config path in render-time errors: When a template was configured via workflow_comments and a caller fails to supply a placeholder value, the error now includes the resolved .github/oz/config.yml path (matching the format used by all other config validation errors). Default-template missing-placeholder errors are unchanged.

Spec updated: specs/GH347/tech.md section 2a now enumerates all first-release keys including the completion/no-op paths and ${reviewer_mentions} in the placeholder list.

captainsafia · 2026-04-27T00:07:38Z

@oz-agent Resolve the merge conflicts in this PR.

oz-for-oss · 2026-04-27T00:08:10Z

@captainsafia

I'm working on changes requested in this PR (responding to a PR conversation comment). Spec context was found and will be used to ground the change.

You can view the conversation on Warp.

I pushed changes to this PR based on the comment.

Next steps:

Review the changes pushed to this PR.
Follow up with another comment if further adjustments are needed.

Powered by Oz

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

captainsafia · 2026-04-27T00:37:13Z

/oz-review

oz-for-oss · 2026-04-27T00:37:55Z

@captainsafia

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and posted feedback on this pull request.

Powered by Oz

oz-for-oss

Overview

This PR introduces the new workflow_comments config surface, adds a centralized template registry and render path across the workflow scripts, expands unit coverage, and documents/specifies the new override model.

Concerns

The new product spec/example and placeholder guidance imply that create-spec-from-issue.complete_created can interpolate ${spec_preview_markdown} and ${next_steps_markdown}, but the shipped implementation currently validates that template against allowed_placeholders=("pr_url",) only. A maintainer who copies the documented example will get a config-validation failure instead of the advertised behavior.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Powered by Oz

oz-for-oss · 2026-04-27T00:44:08Z

+        "complete_created",
+        "I created a new [spec PR](${pr_url}) for this issue.",
+        allowed_placeholders=("pr_url",),


⚠️ [IMPORTANT] The new product spec/example now shows create-spec-from-issue.complete_created embedding ${spec_preview_markdown} and ${next_steps_markdown}, but this allowlist only permits pr_url. Copying that documented config currently fails validation instead of working. Either expose those placeholders here (and pass them from the caller) or update the spec/docs to describe the shipped surface as separate shared.spec_preview / shared.next_steps_section overrides.

spec: add configurable response template specs

f84a8c2

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

oz-for-oss Bot mentioned this pull request Apr 26, 2026

Support configurable template formats for Oz responses #347

Open

oz-for-oss Bot commented Apr 26, 2026

View reviewed changes

Comment thread specs/GH347/tech.md Outdated

Comment thread specs/GH347/tech.md

captainsafia reviewed Apr 26, 2026

View reviewed changes

Comment thread specs/GH347/product.md Outdated

Comment thread specs/GH347/product.md

Comment thread specs/GH347/tech.md Outdated

Comment thread specs/GH347/tech.md Outdated

Comment thread specs/GH347/tech.md

captainsafia mentioned this pull request Apr 26, 2026

fix(workflows): move per-PR concurrency from workflow level to the trusted respond job #364

Closed

spec: refine configurable comment template specs

0940583

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

captainsafia added the plan-approved Indicates that the plan associated with this PR has been approved. label Apr 26, 2026

feat: add configurable workflow comment templates

0ef5f57

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

oz-for-oss Bot commented Apr 26, 2026

View reviewed changes

merge: sync oz-agent/spec-issue-347 with main

39a4dcc

Co-Authored-By: Safia Abdalla <captainsafia@users.noreply.github.com>

oz-for-oss Bot commented Apr 27, 2026

View reviewed changes


		#### 2a. Enumerate the first-release template registry

		The first release should explicitly register every deterministic user-visible string that is currently hardcoded in helpers or workflow entrypoints, rather than leaving implementers to rediscover them during coding. The initial namespace/key set should be documented in the new module and reflected in README examples.

Conversation

oz-for-oss Bot commented Apr 26, 2026

Summary

Validation

Notes

Uh oh!

oz-for-oss Bot commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

Uh oh!

captainsafia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oz-for-oss Bot commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

captainsafia commented Apr 26, 2026

Uh oh!

oz-for-oss Bot commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

oz-for-oss Bot Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

captainsafia commented Apr 26, 2026

Uh oh!

captainsafia commented Apr 27, 2026

Uh oh!

oz-for-oss Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

captainsafia commented Apr 27, 2026

Uh oh!

oz-for-oss Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

oz-for-oss Bot commented Apr 26, 2026 •

edited

Loading

oz-for-oss Bot commented Apr 26, 2026 •

edited

Loading

oz-for-oss Bot commented Apr 26, 2026 •

edited

Loading

oz-for-oss Bot commented Apr 27, 2026 •

edited

Loading

oz-for-oss Bot commented Apr 27, 2026 •

edited

Loading