AGENTS.md: add Agent Workflow Configuration seam

[justin808]

What

Adds an ## Agent Workflow Configuration section to AGENTS.md, positioned near
the top right after the Project Overview (mirroring how react_on_rails
positions its seam).

This is the only file changed (68 insertions, additive).

Why

shakacode/agent-workflows publishes portable agent skills (issue/PR batching,
review-comment triage, verification, changelog updates, CI routing, etc.). Each
skill carries the workflow logic but defers every repo-specific command, branch,
label, path, and policy to a small, validated seam in the consumer repo's
AGENTS.md. Adding this seam lets those shared skills resolve this repo's
real commands and policy instead of guessing.

The contract and rationale live in
shakacode/agent-workflows
(docs/seam-design.md).

How values were determined

Every value was read from the repo on master — config/ci.rb, bin/ci,
lib/tasks/*.rake, package.json scripts, .github/workflows/*.yml,
CHANGELOG.md, and the existing AGENTS.md. Nothing was fabricated.

Validation

$ agent-workflow-seam-doctor --root . --shared <agent-workflows-root>
PASS agent workflow seam is complete

All 16 required seam keys are present and no key contains an unresolved
<placeholder> value.

Keys marked n/a (concept genuinely does not apply to this tutorial app)

Each points at the real file/workflow that governs the concept:

• CI change detector — no suite-routing detector; every PR runs all three
  workflows in full (.github/workflows/{rspec_test,lint_test,js_test}.yml).
• Hosted-CI trigger — no +ci-* commands or hosted-CI labels; CI auto-runs on
  push/PR to master. (The @claude mention triggers .github/workflows/claude.yml.)
• CI parity environment — no act/runner image documented; reproduce from the
  exact job specs in .github/workflows/*.yml (ubuntu-latest, Ruby 3.4.6, Node
  22.x, postgres:11-alpine).
• Benchmark labels — no benchmark workflow or labels exist.
• Follow-up issue prefix — no follow-up-issue convention documented.
• Merge ledger — no per-PR merge-readiness script exists.
• Docs checks — no markdown link checker or docs-sidebar verifier.
• Build / type checks → type checks — TypeScript is a dependency but there is no
  tsc/type-check script; ReScript is compiled by yarn res:build.
• Approval-exempt change categories — no standing approval-exemption policy.
• Coordination backend — no shared agent-coordination backend; coordination is
  via GitHub PR/issue state.

No keys were left as UNKNOWN.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 010a6a87-26f8-4f7d-b781-0bac01e2290e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/agent-workflow-config-seam

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🚀 Quick Review App Commands

Welcome! Here are the commands you can use in this PR:
They require the repository to have cpflow review apps configured, including the CPLN_TOKEN_STAGING secret.

+review-app-deploy

Deploy your PR branch for testing.

+review-app-delete

Remove the review app when done.

+review-app-help

Show detailed instructions, environment setup, and configuration options.

Comment +review-app-help for full setup details.

[claude]

Review: AGENTS.md Agent Workflow Configuration seam

This PR adds a well-structured agent workflow seam to AGENTS.md — the structure is sound and most values are accurate (CI triggers, Ruby/Node versions, Postgres image, CHANGELOG path, claude-code-review.yml triggers all verified correct). Five concrete inaccuracies were found by cross-checking the referenced files.

Findings (most severe first)

1. bin/rubocop mislabeled as autofix (line 57)
bin/rubocop is a plain Bundler binstub with no -a flag. config/ci.rb uses it as a read-only check. Grouping it with rake lint:rubocop[fix] under "(Ruby, with autofix)" is incorrect.

2. bundle exec rake ci:all ≠ bin/ci (line 28)
The two pipelines differ materially: ci:all skips the setup step, runs tests before lint, and uses a bare sh "rspec" instead of the conductor-exec-wrapped runner. Calling it "the equivalent Rake entrypoint" will mislead agents in clean environments.

3. yarn lint Prettier flag is broken upstream (line 59)
package.json's lint script uses --w (not --write), which is not a recognized Prettier flag. The AGENTS.md description "Prettier write" implies this works; it likely doesn't. Worth either fixing package.json or noting the caveat here.

4. bundle exec rake ci:rspec runs ReScript build first (line 63)
ci.rake declares task rspec: %i[environment build_rescript rspec_tests], so rake ci:rspec always rebuilds ReScript before running specs. Presenting it alongside bin/rspec as a plain RSpec alternative understates what it does.

5. GH_TOKEN is a phantom repo-specific entry (line 46)
GH_TOKEN does not appear in any of the five workflow files. It is already covered by the generic TOKEN pattern, so the repo-specific listing creates a false impression that this repo uses it.

[justin808]

Address-review summary

Scan scope: full PR history through 2026-07-18T11:10:10Z; no previous address-review cutoff existed.

PR #770 is superseded by merged PR #778, whose .agents command/config seam is on master. No code changes were made to the obsolete branch.

Mattered

• Declined and resolved discussion_r3487149322: the current seam routes lint through .agents/bin/lint and yarn lint:eslint; changing the pre-existing yarn lint package script is outside this superseded-PR closeout.

Skipped

• Declined and resolved discussion_r3487149084: chore: add agent workflow seam #778 removed the obsolete autofix wording and routes validation through .agents/bin/validate.
• Declined and resolved discussion_r3487149256: chore: add agent workflow seam #778 uses .agents/bin/test and makes no ci:all equivalence claim.
• Declined and resolved discussion_r3487149457: chore: add agent workflow seam #778 no longer presents ci:rspec as a plain RSpec alternative.
• Declined and resolved discussion_r3487149534: chore: add agent workflow seam #778 contains no repository-specific redaction-name list.
• Claude review summary: duplicate of the five inline findings; no separate action.
• CodeRabbit status: review-skipped status only; no action.
• GitHub Actions help: command-help status only; no action.

Deferred-work tracking: none; the merged replacement is the durable resolution.

Next default scan starts after this comment. Say check all reviews to rescan the full PR.

[github-actions]

✅ Review App Deleted

Review app for PR #770 is deleted

🎮 Control Plane Console
📋 View Workflow Logs