Harden agent relay workflow authoring guidance

[khaliqgant]

Summary

• add a non-negotiable workflow checklist and review artifact schema
• require sequential Claude-then-Codex review/fix loops with test hardening
• clean up workflow examples around preflight, top-level await, and pipeline review requirements
• bump package metadata for the updated skills and command

Verification

• node -e "JSON.parse(require('fs').readFileSync('prpm.json','utf8')); console.log('prpm.json OK')"
• git diff --check
• checked TypeScript example block balance and parsed the main full examples after stripping imports

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR standardizes mandatory sequential Claude→Codex fresh-eyes review/fix loops across workflow skills. Version numbers are bumped across README, prpm.json, and skill documentation to reflect substantive updates to the create-workflow command, relay-80-100-workflow, and writing-agent-relay-workflows guidance. The changes strengthen verification gates, evidence-based repair cycles, deterministic acceptance ordering, and commit/PR boundary gating.

Changes

Fresh-Eyes Review/Fix Loop Pattern Implementation

Layer / File(s)	Summary
Version and metadata alignment README.md, prpm.json	Package version increments from 1.0.6 to 1.0.9 and nested skill/command versions are aligned, signaling updates to the fresh-eyes review/fix specifications in create-workflow, relay-80-100-workflow, and writing-agent-relay-workflows.
Create-workflow command specification commands/create-workflow.md	Slash command documentation formally specifies the mandatory sequential Claude→Codex review/fix loop: review findings, fixer repairs and validates, Claude reviews again, Codex repeats from scratch until resolved or blocked. Output contract requires one-paragraph summary and max-5 bullet checklist. Constraints strengthen evidence-based gates and require post-Codex-fix review path for commit/PR gating.
Relay skill documentation updates skills/relay-80-100-workflow/SKILL.md	Squad review process is updated to mandate sequential Claude-then-Codex fresh-eyes loops with evidence-based fix validation, replacing independent reviewer model. Final acceptance and commit/PR creation depend on post-Codex-fix green state.
Writing-agent-relay-workflows comprehensive authoring guide skills/writing-agent-relay-workflows/SKILL.md	Substantially expanded documentation consolidates mandatory fresh-eyes patterns with new "Non-Negotiable Workflow Checklist" and "Mandatory Fresh-Eyes Review Loops" sections. Updated Quick Reference examples (Pipeline and Conversation shapes) incorporate explicit Claude/Codex reviewer/fixer agents, deterministic preflight/verification gates, and bounded iteration rules. Added "Mandatory Claude-Then-Codex Review/Fix Loops" common pattern with full code snippet, updated PR shipping recipe with async runWorkflow() wrapper and integrated review/fix/acceptance gating, added YAML template alternative with loop chain and acceptance-after-review gate, and expanded "Common Mistakes" with rules on git diff --quiet, dual-loop skipping, and interactive-team preset guidance.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• AgentWorkforce/skills#41: Modifies skills/relay-80-100-workflow/SKILL.md to introduce squad review with post-review fix and BLOCKED_NO_COMMIT handling, directly connected to this PR's relay skill updates.
• AgentWorkforce/skills#29: Modifies skills/writing-agent-relay-workflows/SKILL.md and version metadata in prpm.json; this PR extends that original dual Claude→Codex fresh-eyes review/fix loop guidance with comprehensive examples and patterns.
• AgentWorkforce/skills#26: Modifies the same writing-agent-relay-workflows skill around PR shipping and end-to-end workflow steps; this PR extends the PR recipe with integrated mandatory fresh-eyes review/fix/acceptance gating.

Poem

🐰 A Hop Through Fresh Eyes

Double-check, then check again,
Claude and Codex, loop and pen—
Proof of fixes, gates that hold,
Fresh-eyed wisdom, twice-reviewed gold,
Building workflows brave and bold! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Harden agent relay workflow authoring guidance' accurately and concisely describes the main change—strengthening workflow authoring documentation with review loops and checklists.
Description check	✅ Passed	The description is directly related to the changeset, outlining the four key changes (workflow checklist, review/fix loops, example cleanups, metadata bumps) and providing verification steps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/workflow-review-loop-cleanup

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@skills/writing-agent-relay-workflows/SKILL.md`:
- Around line 1358-1364: The acceptance step 'acceptance-after-codex-review'
currently just runs typecheck/tests and can pass even if an earlier artifact has
status BLOCKED_NO_COMMIT; update this step to perform a pre-check for blocker
artifacts (those marked BLOCKED_NO_COMMIT) before running the tests—e.g., add a
short command or script invocation at the start of the step that queries the
artifact store for any BLOCKED_NO_COMMIT entries (or checks the output of the
'codex-fix-final' dependency) and fail the step immediately with a clear message
if any are found, so the step 'acceptance-after-codex-review' cannot succeed
when blocker artifacts exist.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c3b672d2-ce0d-4101-ba9f-22046a638562

📥 Commits

Reviewing files that changed from the base of the PR and between 3b5fe97 and 50a5878.

📒 Files selected for processing (5)

• README.md
• commands/create-workflow.md
• prpm.json
• skills/relay-80-100-workflow/SKILL.md
• skills/writing-agent-relay-workflows/SKILL.md

[devin-ai-integration]

Devin Review found 2 potential issues.

⚠️ 2 issues in files not directly in the diff

⚠️ Codex review step references stale pre-Claude-fix verification output via {{steps.verify-final.output}} (skills/writing-agent-relay-workflows/SKILL.md:388-398)

In the Conversation shape example, the codex-review step injects {{steps.verify-final.output}} into the Codex reviewer's task. However, verify-final runs before the entire Claude review/fix loop (claude-review → claude-fix → claude-review-final → claude-fix-final). If the Claude fixer modified source or test files, the verification output is stale and no longer represents the current codebase state. The same issue appears in the standalone "Mandatory Claude-Then-Codex Review/Fix Loops" pattern at skills/writing-agent-relay-workflows/SKILL.md:1325. In contrast, the Pipeline shape example correctly omits this stale reference. Since this skill document is the canonical template that agents copy when generating workflows, every generated conversation-shape workflow will propagate stale evidence to the Codex reviewer.

---

⚠️ Conversation and standalone acceptance steps missing BLOCKED_NO_COMMIT guard (skills/writing-agent-relay-workflows/SKILL.md:426-432)

The Pipeline shape acceptance step correctly checks test ! -f .workflow-artifacts/my-workflow/BLOCKED_NO_COMMIT.md before proceeding (skills/writing-agent-relay-workflows/SKILL.md:210). However, the Conversation shape verify-after-review step (line 426-432) and the standalone pattern acceptance-after-codex-review step (skills/writing-agent-relay-workflows/SKILL.md:1358-1364) only run npm run typecheck && npm test without checking for BLOCKED_NO_COMMIT.md. If the codex-fix-final step wrote a BLOCKED_NO_COMMIT.md because a finding couldn't be resolved (as instructed at lines 421-424 and 1350-1356), the acceptance step would still pass as long as tests pass — allowing commit/PR creation to proceed despite an unresolved blocker. This contradicts the skill's own Non-Negotiable Workflow Checklist item 7 (line 35): "write BLOCKED_NO_COMMIT with exact evidence and skip commit/PR creation."

View 4 additional findings in Devin Review.