Juan José Mata
157daf5176
* Document instruction inventory and preservation decisions Trace main history from September 2025 through September 2026, including earlier policy origins. Record preserved requirements, detailed-guide destinations, stale facts, harness boundaries and explicit policy-strength decisions before consolidating instruction sources. * Consolidate repository instructions into shared guidance Keep AGENTS concise and vendor neutral, move detailed conventions into shared guides, and use thin adapters with preserved Cursor scopes. Preserve the strict pre-PR checks globally and document the stronger scope, retired migration pin and rule-generation trigger. Update existing API guidance verification without changing application behavior. * Narrow the always-on Cursor UI adapter and correct the SimpleFIN comment Split the design-system guidance out of docs/llm-guides/ui.md into docs/llm-guides/design-system.md. The ui-ux-design-guidelines rule is alwaysApply: true, so importing all of ui.md loaded the Stimulus, localization and ViewComponent guidance (previously confined to scoped rules) on every Cursor session; the always-on adapter now imports only the design-system guide, matching the scope it had before the consolidation. view_conventions and stimulus_conventions keep the full UI guide. Also correct the stale Provider::Simplefin header comment: pending inclusion defaults on and is resolved by the importer (explicit argument, then SIMPLEFIN_INCLUDE_PENDING, then Setting.syncs_include_pending); the previous comment described the flag as default-off. * Read guidance files as UTF-8 in the API consistency validators The frontmatter regex match ran against content read with the locale default external encoding; the Cursor rule's description contains an em dash, so under US-ASCII (LC_ALL=C) Regexp#match raised ArgumentError, breaking the standalone no-Rails fallback the docs point contributors to. Read all checked files with an explicit UTF-8 encoding in both the standalone script and the Rails test.
8.3 KiB
Instruction adapters and maintenance
AGENTS.md contains the shared repository requirements and links to detailed guides. Harness entry points load or direct readers to that guidance. The preservation map records the sources, history and intentional policy decisions behind this structure.
Supported entry points
| Harness | Repository entry point | Loading behavior |
|---|---|---|
| AGENTS-compatible tools | AGENTS.md | Read the root instructions and applicable linked guides. |
| Claude Code | CLAUDE.md | Native @AGENTS.md import loads the canonical file at session start. |
| Cursor | AGENTS.md, project rules | Root guidance is supported natively; retained .mdc rules include shared guides with @ references and preserve their existing applicability. |
| GitHub Copilot | copilot-instructions.md | Repository-wide instructions explicitly direct the agent to read AGENTS and its applicable guides. |
| Junie | AGENTS.md, legacy guidelines | Current Junie discovers root AGENTS; the legacy entry point directs older clients to the same guidance. |
| Gemini Code Assist on GitHub | config.yaml | Existing review configuration is retained unchanged; this is configuration, not an instruction adapter. |
Claude documents @AGENTS.md as an import from CLAUDE.md. Relative imports
resolve from the importing file. Using the import keeps both files ordinary text
files, including on Windows. Claude Code memory documentation
Cursor supports root and nested AGENTS.md files. Project rules require the
.mdc extension, frontmatter and @ file references to include shared content.
The adapters below use repository-root paths. Cursor rules documentation
Copilot's support for agent instruction files varies across GitHub, CLI and IDE
features. Keep its repository-wide entry point rather than relying on universal
AGENTS.md discovery. Its explicit read/follow link is an instruction to the
agent, not a claim that every Copilot surface automatically expands Markdown
links. Copilot CLI separately supports @ relative-file imports in
copilot-instructions.md, AGENTS.md and CLAUDE.md.
Copilot support matrix,
Copilot CLI instruction imports
Current Junie checks .junie/AGENTS.md first, then root AGENTS.md, then the
legacy .junie/guidelines.md or guidelines directory. Do not introduce a separate
.junie/AGENTS.md copy: it would take precedence over the shared root file. The
legacy adapter uses an explicit read/follow link rather than an undocumented
import directive. Junie guidelines and memory
Gemini Code Assist's .gemini/config.yaml controls GitHub review behavior. Its
code_review.disable: true, summary settings, severity threshold and ignore
patterns are preserved. Code Assist supports .gemini/styleguide.md for review
instructions, but this repository has no such file and this consolidation does
not add one. Gemini Code Assist repository configuration
Gemini CLI is a separate integration: it uses GEMINI.md, supports @ imports,
and can change context filenames through context.fileName in settings.json.
There is no tracked Gemini CLI context configuration here; the review YAML does
not configure it. Gemini CLI context documentation
Cursor applicability retained
These are the existing frontmatter values. alwaysApply: true retains global
loading even where a rule also lists globs. Empty description and globs on the
Stimulus rule preserve manual availability; adding either could change discovery.
| Rule | Shared content | globs |
alwaysApply |
|---|---|---|---|
| general-rules.mdc | AGENTS.md | * |
true |
| project-design.mdc | Architecture | * |
true |
| testing.mdc | Testing | test/** |
false |
| view_conventions.mdc | UI | app/views/**,app/javascript/**,app/components/**/*.js |
false |
| stimulus_conventions.mdc | UI | empty | false |
| ui-ux-design-guidelines.mdc | Design system | app/views/**,app/helpers/**,app/javascript/controllers/** |
true |
| api-endpoint-consistency.mdc | API endpoint consistency | app/controllers/api/v1/**/*.rb, spec/requests/api/v1/**/*.rb, test/controllers/api/v1/**/*.rb |
false |
The former project-conventions.mdc content now lives with architecture guidance;
the always-on architecture adapter keeps those conventions available. The generic
cursor_rules.mdc template and automatic self_improve.mdc rule-generation
trigger are retired, as recorded in the preservation map.
Maintaining guidance
- Put common requirements in AGENTS and detailed explanations, examples and procedures in the appropriate shared guide. Keep adapters limited to loading and routing guidance.
- Update guidance when code, a workflow or a reviewed requirement changes. Verify examples against current files; keep links accurate and remove resolved temporary advice with an explanation in the change description.
- Review parallel entry points before changing a rule. Record intentional changes to mandatory checks, permission requirements or harness applicability explicitly.
- Change existing shared guidance before adding a new document or rule. Repeated code alone is not a trigger to generate more harness-specific policy files.
- When editing an adapter, verify its target and applicable loading syntax. Compare complete Cursor metadata values, rather than accepting substring matches that permit extra globs or duplicate values. The existing API checker protects the API guide and its scoped adapter.
Skills considered
Adding a securities provider and
gating a preview feature are bounded, repeatable
workflows and therefore plausible skill candidates. Skills have real ecosystem
support: both Copilot and Junie document the open format and shared
.agents/skills/ locations.
Copilot customization reference,
Junie agent skills
No skill wrapper is introduced. The shared guides already make these procedures available across harnesses; the repository also has Rails provider generators. A wrapper would add another discovery and maintenance layer without a demonstrated invocation, template-packaging or execution benefit. The wealth guides describe product integration and operation, not a repository coding skill.
Legacy helpers and local context
bin/update_structure.sh is an optional generated
tree helper. Its ignored .cursor/rules/structure.mdc output is not a shared
policy source. The existing script writes alwaysApply to a different path and
then overwrites its generated header; repairing the generator is separate work.
The ignored agent.mdc, dev_workflow.mdc and taskmaster.mdc paths likewise
remain local/generated context.
bin/codex-env is a legacy Linux environment bootstrap, not the standard setup procedure or a skill. It installs system packages, changes PostgreSQL authentication, and can comment out the Ruby requirement and mark Gemfiles assume-unchanged when versions differ. It remains unchanged; use the maintained development guide for repository setup and checks.