Skip to content

AGENTS.md: add Agent Workflow Configuration seam #770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
justin808 wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

AGENTS.md: add Agent Workflow Configuration seam #770

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,74 @@ React on Rails demo app — a Rails application with React, Redux, Tailwind CSS,

- `prompts/`: shared prompt templates for Codex, GPT, and other non-Claude tools

## Agent Workflow Configuration

Shared workflow skills from
[`shakacode/agent-workflows`](https://github.com/shakacode/agent-workflows) are
repo-agnostic: they carry the workflow logic but defer every repo-specific
command, branch, label, path, and policy to this section. When a shared skill
says "run the repo's local validation" or "use the hosted-CI trigger," the
concrete value is here. This is a small tutorial app, so many advanced
process concepts (hosted-CI gating, benchmarks, merge ledgers, coordination
backends) genuinely do not apply and are marked `n/a` with a pointer to the
real file or workflow. Validate this seam with
`agent-workflow-seam-doctor --root . --shared <agent-workflows-root>`. Where a
value is already documented elsewhere in this file, this section references that
section instead of duplicating it.

- **Base branch**: `master` (fetch and compare via `origin/master`; all CI
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

@claude claude Bot Jun 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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

commands through `bin/conductor-exec` (see the **Conductor Compatibility** section).
- **CI change detector**: n/a — there is no suite-routing detector; every PR runs
all three workflows (`.github/workflows/rspec_test.yml`, `lint_test.yml`,
`js_test.yml`) in full.
- **Hosted-CI trigger**: n/a — no `+ci-*` PR-comment commands or hosted-CI labels.
CI runs automatically on push and pull_request to `master`. The separate
`@claude` PR/issue mention triggers the Claude Code agent via
`.github/workflows/claude.yml`.
- **CI parity environment**: n/a — no `act` or local-runner image is documented.
Reproduce CI-only failures from the exact GitHub Actions jobs in
`.github/workflows/*.yml`: `runs-on: ubuntu-latest`, Ruby `3.4.6`, Node `22.x`,
`services.postgres: postgres:11-alpine` (`rspec_test.yml`), and the listed env
vars (`RAILS_ENV=test`, `NODE_ENV=test`, `DATABASE_URL`, `DRIVER=selenium_chrome`,
`RENDERER_PASSWORD`). Record any unverified runner/service gap as `UNKNOWN`.
- **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

@claude claude Bot Jun 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
`RENDERER_PASSWORD`, `GITHUB_TOKEN`, `GH_TOKEN`, and `DATABASE_URL` (contains
`RENDERER_PASSWORD`, `GITHUB_TOKEN`, and `DATABASE_URL` (contains

credentials). These patterns favor conservative over-redaction of logs, prompts,
and issue comments. The repo-specific entries are public identifier names, not
values; list them so agents redact exact aliases even when generic patterns match.
- **Benchmark labels**: n/a — no performance-benchmark workflow or labels in this repo.
- **Follow-up issue prefix**: n/a — no follow-up-issue convention is documented;
default to not opening new issues.
- **Changelog**: `/CHANGELOG.md`, user-visible changes only. There is no changelog
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);

@claude claude Bot Jun 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
`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);

`bundle exec rubocop -a` (Ruby autofix); `yarn lint:eslint` (JS check),
`yarn lint` (ESLint autofix + Prettier write); `yarn lint:prettier` (Prettier

@claude claude Bot Jun 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

@claude claude Bot Jun 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Suggested change
- **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)

via `yarn test:client` or `bundle exec rake ci:js`. The full local gate is
`bin/ci` / `bundle exec rake ci:all`. No separate e2e suite is configured.
- **Build / type checks**: build test assets with `yarn build:test` (and
`yarn res:build` for ReScript). Type checks: n/a — TypeScript is a dependency but
there is no `tsc`/type-check script; ReScript is compiled by `yarn res:build`.
- **Review gate**: `claude-review` — the automated Claude Code review in
`.github/workflows/claude-code-review.yml` runs on every PR (opened, synchronize,
ready_for_review, reopened) and posts inline/PR comments.
- **Approval-exempt change categories**: n/a — no standing approval-exemption policy
is documented; treat all changes as requiring normal review.
- **Coordination backend**: n/a — this repo uses no shared agent-coordination backend;
rely on GitHub PR/issue state and assignment for coordination.

## Build and Test Commands

```bash
Expand Down
Loading