AGENTS.md: add Agent Workflow Configuration seam#770
Conversation
Add the portable agent-workflows seam so shared skills from shakacode/agent-workflows can resolve this repo's real commands and policy. All keys reflect verified repo values; concepts that genuinely do not apply to this tutorial app are marked n/a with a pointer to the relevant file/workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
🚀 Quick Review App CommandsWelcome! Here are the commands you can use in this PR:
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| automation (no Rake task or script); edit the file by hand following its existing | ||
| reverse-chronological dated-section format. | ||
| - **Lint / format**: `bundle exec rake lint` (full suite: RuboCop, ESLint, scss_lint); | ||
| `bin/rubocop` or `bundle exec rake "lint:rubocop[fix]"` (Ruby, with autofix); |
There was a problem hiding this comment.
bin/rubocop is a plain Bundler binstub — it does not pass -a and does not autofix. config/ci.rb itself uses bin/conductor-exec bin/rubocop (without -a) as the read-only lint check step. Grouping it under "(Ruby, with autofix)" is misleading; a developer who runs bin/rubocop expecting in-place correction will only get a lint report.
Suggested fix: split the two commands so their intent is clear.
| `bin/rubocop` or `bundle exec rake "lint:rubocop[fix]"` (Ruby, with autofix); | |
| `bin/rubocop` (Ruby lint check); | |
| `bundle exec rake "lint:rubocop[fix]"` or `bundle exec rubocop -a` (Ruby autofix); |
| workflows in `.github/workflows/` trigger on `push`/`pull_request` to `master`). | ||
| - **Pre-push local validation**: `bin/ci` — runs setup, RuboCop, ESLint, the test | ||
| asset build, RSpec, and Jest in order (steps defined in `config/ci.rb`). The | ||
| equivalent Rake entrypoint is `bundle exec rake ci:all`. Run tool-version-sensitive |
There was a problem hiding this comment.
bundle exec rake ci:all and bin/ci are not equivalent; calling them interchangeable will mislead agents.
Key differences verified against config/ci.rb and lib/tasks/ci.rake:
bin/ci |
bundle exec rake ci:all |
|
|---|---|---|
| Setup step | ✅ bin/setup --skip-server |
❌ skipped |
| Order | lint → tests | tests → lint (deps: build_rescript rspec_tests lint js_tests) |
| Asset build | generate_packs && res:build && build:test |
only res:build |
| RSpec runner | bin/conductor-exec bin/rspec |
bare sh "rspec" |
An agent that substitutes rake ci:all for bin/ci in a clean environment will skip setup and run tests before lint.
| equivalent Rake entrypoint is `bundle exec rake ci:all`. Run tool-version-sensitive | |
| equivalent Rake entrypoint is `bundle exec rake ci:all` (note: skips the setup | |
| step and runs tests before lint; prefer `bin/ci` for full parity). Run tool-version-sensitive |
| - **Lint / format**: `bundle exec rake lint` (full suite: RuboCop, ESLint, scss_lint); | ||
| `bin/rubocop` or `bundle exec rake "lint:rubocop[fix]"` (Ruby, with autofix); | ||
| `bundle exec rubocop -a` (Ruby autofix); `yarn lint:eslint` (JS check), | ||
| `yarn lint` (ESLint autofix + Prettier write); `yarn lint:prettier` (Prettier |
There was a problem hiding this comment.
The lint script in package.json is:
"lint": " yarn lint:eslint --fix && yarn lint:prettier --w",
--w is not a recognized Prettier flag — the correct flag is --write. This is a latent bug in package.json itself, but describing yarn lint as "Prettier write" implies it works; agents that rely on it for formatting will get unexpected behavior (Prettier may error or silently skip the write).
Worth either fixing the underlying package.json script (--w → --write) and noting it here, or flagging the limitation.
| check, `.js`/`.jsx`). See the **Build and Test Commands** section. | ||
| - **Merge ledger**: n/a — no machine-checkable per-PR merge-readiness script exists. | ||
| - **Docs checks**: n/a — no markdown link checker or docs-sidebar verifier in this repo. | ||
| - **Tests**: RSpec via `bin/rspec` or `bundle exec rake ci:rspec`; Jest (client JS) |
There was a problem hiding this comment.
bundle exec rake ci:rspec is not a plain RSpec runner — from lib/tasks/ci.rake:
task rspec: %i[environment build_rescript rspec_tests]It always runs yarn res:build (ReScript compilation) first. An agent using it to quickly re-run a failing spec will trigger an unnecessary full ReScript build. If speed matters, bin/rspec is the right choice; the rake form should be documented as "RSpec + ReScript build".
| - **Tests**: RSpec via `bin/rspec` or `bundle exec rake ci:rspec`; Jest (client JS) | |
| - **Tests**: RSpec via `bin/rspec`; or `bundle exec rake ci:rspec` (also rebuilds ReScript first); Jest (client JS) |
| - **Secret redaction patterns**: redact values for environment variables or log | ||
| fields whose names contain `SECRET`, `TOKEN`, `KEY`, `PASSWORD`, `CREDENTIAL`, | ||
| `PASSPHRASE`, or `PRIVATE`, plus the repo-specific names `CLAUDE_CODE_OAUTH_TOKEN`, | ||
| `RENDERER_PASSWORD`, `GITHUB_TOKEN`, `GH_TOKEN`, and `DATABASE_URL` (contains |
There was a problem hiding this comment.
GH_TOKEN does not appear anywhere in the repository's workflow files (checked all five: rspec_test.yml, lint_test.yml, js_test.yml, claude.yml, claude-code-review.yml). Listing it as a repo-specific redaction name implies the repo uses it, which could confuse future audits or editors maintaining this list. It is already covered by the generic TOKEN pattern, so removing it causes no loss of coverage.
| `RENDERER_PASSWORD`, `GITHUB_TOKEN`, `GH_TOKEN`, and `DATABASE_URL` (contains | |
| `RENDERER_PASSWORD`, `GITHUB_TOKEN`, and `DATABASE_URL` (contains |
Review: AGENTS.md Agent Workflow Configuration seamThis PR adds a well-structured agent workflow seam to Findings (most severe first)1. 2. 3. 4. 5. |
1 participant
What
Adds an
## Agent Workflow Configurationsection toAGENTS.md, positioned nearthe top right after the Project Overview (mirroring how
react_on_railspositions its seam).
This is the only file changed (68 insertions, additive).
Why
shakacode/agent-workflowspublishes 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'sreal 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.jsonscripts,.github/workflows/*.yml,CHANGELOG.md, and the existingAGENTS.md. Nothing was fabricated.Validation
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:
workflows in full (
.github/workflows/{rspec_test,lint_test,js_test}.yml).+ci-*commands or hosted-CI labels; CI auto-runs onpush/PR to
master. (The@claudemention triggers.github/workflows/claude.yml.)act/runner image documented; reproduce from theexact job specs in
.github/workflows/*.yml(ubuntu-latest, Ruby 3.4.6, Node22.x, postgres:11-alpine).
tsc/type-check script; ReScript is compiled byyarn res:build.via GitHub PR/issue state.
No keys were left as
UNKNOWN.🤖 Generated with Claude Code