AGENTS.md

1# AGENTS.md — Agent Skill Routing for ORGII
2 
3This file orients Codex / orgii agents working in this repo. It tells you **which audit / methodology skill to invoke** for which kind of task, and what to deliver before declaring work done.
4 
5> Cursor IDE users: live UI-feature delivery rules live in `.cursor/rules/ui-feature-workflow.mdc`. This file does **not** replace those — it's about skill routing for AI agents, not unit-test gates.
6 
7This is **advisory**, not a hard contract. Use judgment based on PR size and risk.
8 
9---
10 
11## Skill Routing Table
12 
13| Scenario                                                                                                                   | Skill to invoke                     | When                                                                                                                                          |
14| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
15| Rust / TypeScript architecture, types, dead code, FSM, naming overload, wire protocol, init parity                         | `architecture-audit`                | Before finalizing a refactor plan; before cleanup/unification PRs; when reviewing a domain rewrite                                            |
16| Frontend UI consistency, design-system component usage, arbitrary Tailwind values, a11y basics, visual-pattern duplication | `frontend-ui-audit`                 | Before delivering a PR that touches `*.tsx` under `src/components/` or `src/modules/**/components/` (component refactors, UI cleanup batches) |
17| React performance, re-renders, async waterfalls, bundle size, heavy dependencies, virtualization, high-frequency events    | `react-best-practices`              | For performance-focused React implementation/review; not for routine styling, copy, or single-file bug fixes without a performance concern    |
18| Both architecture and React performance change together                                                                    | Run both, keep findings categorized | Apply `architecture-audit` to ownership/boundaries and `react-best-practices` to measured React runtime concerns                              |
19| E2E test surface (Playwright / WebDriver), test stability                                                                  | `e2e-testing`                       | When adding or repairing rendered E2E specs                                                                                                   |
20| Polling, timers, caches, subscriptions, workers, streaming, sync, scans, pagination, multi-instance lifecycle              | `org2-performance-guard`            | Before delivering any change that can consume CPU/RAM/I/O while active, idle, hidden, or across repeated open/close cycles                    |
21 
22Skills live at:
23 
24- `~/.orgii/skills/architecture-audit/SKILL.md` (user-global)
25- `~/.orgii/skills/frontend-ui-audit/SKILL.md` (user-global)
26- `.orgii/skills/architecture-audit/SKILL.md` (workspace copy, if present)
27- `.orgii/skills/react-best-practices/SKILL.md` (workspace; ORGII overlay for Vercel's React guidance)
28- `.orgii/skills/e2e-testing/SKILL.md` (workspace)
29- `.orgii/skills/org2-performance-guard/SKILL.md` (workspace)
30 
31If the skill block isn't already prefetched in your context, read its `SKILL.md` before acting on it.
32 
33---
34 
35## Default Delivery Flow
36 
37### Touching `*.tsx` files (UI work)
38 
39Before declaring a UI-touching task complete, ask:
40 
411. **Is this a single-file bug fix?** If yes, skip `frontend-ui-audit` (its own "When NOT To Use" rules out single bug fixes — noise-to-value ratio is too high).
422. **Is this a component refactor, UI cleanup, or "should this use the design system?" question?** If yes, run `frontend-ui-audit` over the changed files and drop a report in `docs/frontend-ui-audit-YYYY-MM-DD/<ComponentName>.md` using the skill's output format. Summarize fix / keep-with-reason / abstract counts in the delivery message so the user can see verdicts without opening the file.
433. **Did you find a fix-candidate that spans multiple files?** Don't fix site-by-site silently. Surface it as a sweep candidate per the skill's `Systematic Sweep Discipline` section and let the user decide whether to land a config-level change.
44 
45### React performance-focused work
46 
47Use `react-best-practices` only when performance is part of the task: re-renders, async waterfalls, bundle/startup cost, heavy dependencies, virtualization, high-frequency events, or subscription scope. Apply its ORGII filter before upstream guidance: Next.js/RSC/server-only rules are inapplicable, SWR is not introduced by default, and runtime performance claims require measurement rather than typecheck-only evidence.
48 
49### Touching Rust / backend / type-level / cross-layer code
50 
51Before finalizing a refactor plan, walk the 10-layer `architecture-audit` checklist (or at least the layers the change clearly touches). State which layers you covered and which you intentionally skipped.
52 
53### When multiple methodologies apply
54 
55Run every applicable skill. Keep architecture, React performance, and UI-consistency findings clearly categorized. Only skills that define an audit-report format require a report; `react-best-practices` is implementation/review guidance and does not create a report by default.
56 
57### Touching background work or retained state
58 
59Run `org2-performance-guard` whenever a change adds or modifies polling, timers, retries, subscriptions, workers, streaming hot paths, caches, scans, sync loops, pagination, or multi-instance state. Apply its lifecycle matrix and rejection rules even when performance is not the feature's headline. State the performance verdict and concrete verification in the delivery message.
60 
61### Pull request contract
62 
63Every pull request created or updated by an agent MUST follow these rules.
64 
65#### Single responsibility
66 
67- One PR solves one problem or delivers one feature. Do not combine multiple
68  features, unrelated bug fixes, opportunistic refactors, cleanup, formatting,
69  or documentation changes in the same PR.
70- Supporting tests and documentation belong in the same PR only when they
71  directly verify or explain that PR's single change.
72- If requested work contains independent changes, split them into separate
73  branches/worktrees and separate PRs.
74- If a new unrelated request arrives after a PR has been opened, do not append
75  it to the existing branch. Create a separate PR.
76- Before handoff, compare the branch against its base and confirm every changed
77  file maps directly to the PR's stated problem or solution.
78 
79#### Description format
80 
81The PR description MUST begin with these top-level sections in this exact
82order:
83 
84```markdown
85## Problem
86 
87<What is wrong, who or what is affected, and the root cause.>
88 
89## Solution
90 
91<What changed, the resulting invariant or behavior, and why this approach was chosen.>
92 
93## Potential risks
94 
95<Concrete regressions, compatibility concerns, unverified paths, or operational tradeoffs.>
96```
97 
98- Do not replace these sections with `Summary`, `Overview`, or `Test plan`.
99- Do not leave a required section blank. If no material risk remains, state
100  that explicitly and explain why.
101- Additional sections such as `Audit`, `Verification`, screenshots, or rollout
102  notes may follow the three required sections.
103- Before handing off a PR, read back the published description (for example
104  with `gh pr view`) and verify the section names and order.
105 
106#### Base and diff integrity
107 
108- Start from the intended target branch. Before handoff, fetch its latest state
109  and check whether the PR needs to be updated or conflicts resolved.
110- After resolving conflicts or incorporating target-branch changes, rerun the
111  checks affected by that integration.
112- Keep the published description synchronized with the final diff. Remove
113  claims about approaches, files, or behavior that are no longer present.
114- Avoid unrelated merge commits and generated churn. Do not rewrite published
115  history after review begins unless necessary; if history must change, use the
116  safest available method and tell reviewers what changed.
117 
118#### Verification evidence
119 
120- List the exact commands and meaningful manual checks that actually ran,
121  together with their outcomes.
122- State which relevant checks were not run and why. Do not write unsupported
123  claims such as "all tests pass" or infer runtime/performance improvement from
124  typecheck or code shape alone.
125- Verification must be proportional to risk and cover the changed behavior at
126  its owning boundary, not only a helper or selector.
127 
128#### Risk, compatibility, and rollback
129 
130- `Potential risks` must name concrete compatibility, data, concurrency,
131  lifecycle, platform, rollout, and unverified-path concerns that apply. Do not
132  use a generic "no risk" statement to avoid analysis.
133- Dependency or lockfile changes, database/schema migrations, configuration or
134  persistence format changes, and public API/IPC/wire changes must state why
135  they are necessary, how compatibility is handled, and how to roll back or
136  recover.
137- Destructive or difficult-to-reverse behavior requires an explicit rollback
138  or recovery plan before the PR is ready for review.
139 
140#### UI and security evidence
141 
142- User-visible UI changes should include screenshots or recordings appropriate
143  to the change, including relevant themes, viewport constraints, and
144  loading/empty/error states. If visual evidence is not useful, say why.
145- Before handoff, inspect the diff for secrets, tokens, personal paths, private
146  configuration, debug logs, build artifacts, caches, and unrelated formatting
147  changes. None may be included.
148 
149#### Draft, ready, and review lifecycle
150 
151- Keep the PR in Draft while material design choices, known blockers, required
152  migrations, or risk-proportionate verification remain incomplete.
153- Mark the PR ready only when its acceptance criteria are met and the
154  description reflects the current implementation.
155- If scope, behavior, or the chosen solution changes materially after review
156  begins, update the description and notify reviewers instead of silently
157  changing direction.
158 
159---
160 
161## What This File Does NOT Do
162 
163- It does **not** force every PR to produce an audit report. Single bug fixes, copy tweaks, hotfix patches → just ship.
164- It does **not** make `react-best-practices` a gate for every `*.tsx` edit. Styling, copy, ordinary UI assembly, and routine single-file bug fixes do not trigger it unless performance is explicitly in scope.
165- It does **not** replace the skills' own `When NOT To Use` rules.
166- It does **not** replace `.cursor/rules/ui-feature-workflow.mdc` for human/Cursor flow (unit tests + TEST_CASES.md + acceptance criteria). Those gates are about delivery quality; this routing is about which methodology to apply.
167- It does **not** mandate any commit-message format (commitlint handles that), any lint rule, or any pre-commit hook. Audit reports are docs, not gates.
168- It does **not** lock in skill content. If `~/.orgii/skills/*/SKILL.md` updates, this file's routing still applies — read the current SKILL.md, not your memory of it.
169 
170---
171 
172## Audit Report Conventions
173 
174- **Location:** `docs/<skill-name>-YYYY-MM-DD/<ComponentName>.md` (one date-stamped folder per audit batch, one file per audited component).
175- **Format:** follow the `## Output Format` section in the relevant skill verbatim — tables with Line / Element / Verdict / Reason / Suggested change columns.
176- **`keep with reason` rows MUST fill the Reason column.** That's the audit's value-add — preventing the next pass from re-flagging the same hit.
177- **Don't modify source code in an audit-only PR.** Audit and fix are separate concerns; mixing them makes review impossible.
178 
179---
180 
181## When You're Unsure
182 
183- If you don't know which skill applies, **lean toward running `frontend-ui-audit` for UI changes and `architecture-audit` for type/control-flow changes**. Both being run when only one was needed costs nothing; missing one is a real gap.
184- If you're certain the user wants direct implementation and not an audit (e.g. "just fix this bug"), do that — don't insert an audit pass unprompted.
185- If the user asks "why didn't audit catch X?", check whether X is in scope for the skill they're invoking before assuming the audit failed. (`architecture-audit` is type/architecture, not UI consistency — see `frontend-ui-audit` for the latter.)
186