AGENTS.md Domain Refactor Plan

Objective

Make agent guidance easier to trust by keeping the root AGENTS.md small and moving detailed, domain-specific traps into colocated AGENTS.md files.

Current State

• Root AGENTS.md mixes global workflow guidance with many SLD, sizing, PandaPower, auth, and protection-settings notes.
• Root CLAUDE.md has been removed.
• tasks/todo.md was legacy running history and should not be recreated as a task log.
• Existing scoped instruction files were migrated to AGENTS.md:
• tests/AGENTS.md
• docs/electrical-code/AGENTS.md
• pandapower-service/AGENTS.md
• src/actions/sizing/AGENTS.md
• src/lib/sizing/AGENTS.md
• src/app/(application)/app/(workspace)/sld-editor/AGENTS.md
• src/app/(application)/app/(workspace)/sld-editor/_components/edit-panel/AGENTS.md
• src/lib/ai/AGENTS.md
• src/components/settings/AGENTS.md
• docs/AGENTS.md
• scripts/ralph/AGENTS.md

Target Layout

• AGENTS.md: global repo rules only.
• Local database and migration warnings.
• Project Data REST API verification note.
• Documentation hygiene.
• Pointers to domain files.
• tests/AGENTS.md: testing strategy and Playwright/Vitest conventions.
• pandapower-service/AGENTS.md: PandaPower service architecture, calculation extraction rules, network-builder traps.
• src/actions/sizing/AGENTS.md: server-action sizing orchestration, runtime/preview/apply alignment, persistence behavior.
• src/lib/sizing/AGENTS.md: pure sizing-engine rules and NEC/code-table behavior.
• src/app/(application)/app/(workspace)/sld-editor/AGENTS.md: canvas, React Flow, connection, node, proposal-context, and visual feedback rules.
• src/app/(application)/app/(workspace)/sld-editor/_components/edit-panel/AGENTS.md: edit-panel auto-save, field renderer, form mapper, and stale-status behavior.
• src/lib/ai/AGENTS.md: AI command/tool contracts and schema behavior.
• src/components/settings/AGENTS.md: defaults/settings page conventions.
• docs/AGENTS.md: user-facing docs style and what not to document.
• docs/electrical-code/AGENTS.md: NEC source handling and code-rule reminders.
• scripts/ralph/AGENTS.md: Ralph automation workflow, if still used.

Migration Steps

1. Inventory each root AGENTS.md bullet and assign it to exactly one domain.
2. Rename existing domain CLAUDE.md files to AGENTS.md where they are still current. Completed.
3. Merge root bullets into the closest domain file instead of copying them broadly.
4. Replace cross-references from CLAUDE.md to AGENTS.md. Completed for active instruction files.
5. Trim root AGENTS.md to global guidance plus a short domain index.
6. Run link/path checks for references to deleted or renamed instruction files.
7. Do not migrate stale notes blindly; mark questionable notes for code verification or remove them if the code no longer matches.

Suggested First Pass

1. Move all PandaPower/network-builder/power-flow/short-circuit bullets from root to pandapower-service/AGENTS.md.
2. Move all sizing preview/apply/runtime/cascade bullets to src/actions/sizing/AGENTS.md.
3. Move pure NEC and conductor/OCPD sizing rules to src/lib/sizing/AGENTS.md.
4. Move SLD canvas, connection, optimistic paste, React Flow, and node-label bullets to src/app/(application)/app/(workspace)/sld-editor/AGENTS.md.
5. Move edit-panel form, field-renderer, stale badge, and protection-device form notes to the edit-panel AGENTS.md.
6. Keep root AGENTS.md below roughly 100 lines.

Stale-Information Checks

Before preserving a note, verify:

• The referenced file path still exists.
• The named function/hook/action still exists.
• The behavior is still current, not a solved bug.
• The note prevents a realistic future mistake.
• The note is better as an instruction than as a regression test or code comment.

Likely stale or review-worthy areas:

• Any instruction phrased as "currently" around known bugs or temporary architecture.
• Old broad process rules such as mandatory task logs, mandatory lesson updates, or forced plan mode.
• Domain docs that still say CLAUDE.md - ....
• Older historical docs that point at CLAUDE.md paths.
• Generated or archived worktree paths under .claude/worktrees/; do not update those unless they are intentionally active.

Definition of Done

• Root AGENTS.md is short, current, and points to scoped domain files.
• No active repo instruction references root CLAUDE.md.
• Domain guidance is colocated with the code it describes.
• tasks/todo.md is not recreated.
• rg "CLAUDE.md" returns only intentionally retained historical references or no active instruction references.