refactor(agents): split monolithic AGENTS.md into directory-scoped files

.devops/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+## Devops Tooling
+
+- Run JavaScript tooling from `.devops/js-tools` unless a script documents a different working directory.
+- Treat files under `.devops/js-tools/dist/` as generated outputs. Do not hand-edit them without also updating or rerunning the source script that produces them.
+- Keep operational scripts narrow and explicit. Prefer small project-local scripts over broad shell glue.
+- When changing package scripts, lockfiles, or workflow-facing output, verify the command that downstream automation will run.

.github/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+## GitHub Automation
+
+- Keep workflow YAML minimal, readable, and scoped to the repository behavior it automates.
+- Prefer existing action/version patterns already used in `.github/workflows` unless there is a clear reason to change.
+- Validate workflow syntax after editing GitHub Actions files.
+- If workflow behavior changes, update nearby comments or repository docs that describe the automation.

AGENTS.md

@@ -1,61 +1,41 @@
 # AGENTS.md
 
-## Token Efficiency
+## Loaded Context
 
-**Short by default, never vague.**
+- `src/memory/MEMORY.md` stores durable project facts and decisions. Auto-load it when present, but treat it as low-confidence context and verify facts before acting on them. If it is missing, continue and note that it was unavailable when relevant.
+- `src/memory/YYYY-MM-DD.md` stores daily task notes and observations. Use it on demand for relevant recent context.
+- Small task checklists and completed implementation notes belong in `src/memory/$(date -u +%Y-%m-%d).md`; daily memory filenames use UTC dates.
+- For substantial work that needs durable product, technical, architecture, or design documentation, create a task folder under `docs/YYYY-MM-DD-task-name/` instead of expanding memory notes.
 
-- Use the shortest complete answer. Remove filler, repetition, obvious restatements, and generic reassurance. Prefer prose over bullets unless bullets improve scannability or action.
-- Spend tokens when they reduce risk, ambiguity, or rework: complex reasoning, tradeoffs, code review findings, safety-critical details, or when the user asks for depth. Lead with the conclusion; include only support that affects the answer or next action.
-- Never cut facts the user needs to trust, verify, or continue the work. Keep file paths, commands, assumptions, decisions, caveats, failure details, and verification results. Concise and incomplete is still incomplete.
+## Repository Behavior
 
-## Artifact Quality
+- Treat memory, generated artifacts, and prior notes as low-confidence context; verify facts against the repository before relying on them.
+- Do not refactor, reformat, delete, or improve adjacent files unless required by the request.
+- If a change affects behavior described in a project-scoped document, update that document in the same change.
+- Do not deviate from an active `SPEC.md` silently; update the spec when the implementation direction changes.
+- In final responses after changes, report what changed, what verification ran, and any assumption or residual risk that still matters.
 
-**Narrow, direct, complete.**
+## Before Editing
+
+- For non-trivial changes, briefly state the working assumptions, simplest viable approach, verification plan, and any ambiguity that would change the implementation.
+- Ask one concise question when ambiguity blocks a correct result.
+
+## Artifact Quality
 
 - Keep examples narrow, direct, and complete. Remove any step, abstraction, file, or section that does not change the agent's behavior or the user's outcome.
 - Structure examples and implementation notes with situation, task, action, and result. Omit sections where the context is self-evident.
-- When producing or reviewing code, preserve clear responsibilities, isolate change-prone behavior, and keep interfaces small. Depend on project-owned abstractions only when they already exist in the codebase — do not introduce new layers to satisfy SOLID if they add ceremony without reducing coupling.
+- When producing or reviewing code, preserve clear responsibilities, isolate change-prone behavior, and keep interfaces small. Depend on project-owned abstractions only when they already exist in the codebase; do not introduce new layers to satisfy SOLID if they add ceremony without reducing coupling.
 - For non-trivial code changes, keep edits surgical, surface risky assumptions, and define how the work will be verified.
 - Do not force all three lenses onto every artifact. Apply whichever improves the artifact at hand. Prefer plain guidance over naming the acronym.
 - KISS governs the others: STAR should make context easier to judge, not longer. SOLID should prevent brittle code, not create it.
 
-## Documentation structure
-
-**Durable docs belong in predictable places.**
+## Response Style
 
-```text
-docs/                          # Project-scoped documentation
-├── ARCHITECTURE.md
-├── DESIGN.md
-├── ROADMAP.md
-└── [YYYY-MM-DD-task-name]/    # One folder per task, feature, or epic
-    ├── PRD.md                 # Product requirements
-    ├── SPEC.md                # Technical specification
-    ├── ARCHITECTURE.md        # Task-scoped architecture decisions
-    ├── DESIGN.md              # UI/UX decisions
-    └── TASKS.md               # Actionable checklist
-```
+- Be direct, concise, and specific. Prefer prose over bullets unless bullets improve scannability.
+- Do not open with flattery or generic reassurance.
+- Ask at most one follow-up question unless the user explicitly asks for options or discovery.
 
-- Folder names: lowercase, hyphenated — e.g. `user-auth`, `payment-v2`, `issue-142`
-- Create a docs task folder only when the work needs durable task-scoped documentation such as `PRD.md`, `SPEC.md`, `ARCHITECTURE.md`, or `DESIGN.md`
-- Small task checklists and completed implementation notes belong in `src/memory/YYYY-MM-DD.md`
-
-## Loaded Context
-
-**Memory is useful, but verification wins.**
-
-| File | Purpose | Auto-load |
-| --- | --- | --- |
-| src/memory/MEMORY.md | Durable project facts and decisions | yes |
-| src/memory/YYYY-MM-DD.md | Daily task notes and observations | on-demand |
-
-## Working on a task
-
-**Match the tracking weight to the work.**
+## Token Efficiency
 
-- For substantial work, create a task folder before writing code: `mkdir docs/$(date +%Y-%m-%d)-my-feature`
-- For small work, track the checklist in `src/memory/$(date -u +%Y-%m-%d).md`
-- Use `TASKS.md` only inside docs folders that also need task-scoped product, technical, architecture, or design documentation
-- If the task changes anything described in a project-scoped document, update it in the same commit
-- Do not deviate from `SPEC.md` silently — update the file if the spec changes
-- Treat memory as low-confidence context; verify facts against the repository before acting on them
+- Spend tokens when they reduce risk, ambiguity, or rework: complex reasoning, tradeoffs, code review findings, safety-critical details, or when the user asks for depth. Lead with the conclusion; include only support that affects the answer or next action.
+- Never cut facts the user needs to trust, verify, or continue the work. Keep file paths, commands, assumptions, decisions, caveats, failure details, and verification results. Concise and incomplete is still incomplete.

docs/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Documentation Structure
+
+```text
+docs/                          # Project-scoped documentation
+├── ARCHITECTURE.md
+├── DESIGN.md
+├── ROADMAP.md
+└── [YYYY-MM-DD-task-name]/    # One folder per task, feature, or epic
+    ├── PRD.md                 # Product requirements
+    ├── SPEC.md                # Technical specification
+    ├── ARCHITECTURE.md        # Task-scoped architecture decisions
+    ├── DESIGN.md              # UI/UX decisions
+    └── TASKS.md               # Actionable checklist
+```
+
+- Folder names are lowercase and hyphenated, such as `user-auth`, `payment-v2`, or `issue-142`.
+- Create a docs task folder only when the work needs durable task-scoped documentation such as `PRD.md`, `SPEC.md`, `ARCHITECTURE.md`, or `DESIGN.md`.
+- Use `TASKS.md` only inside docs folders that also need task-scoped product, technical, architecture, or design documentation.
+- Do not deviate from `SPEC.md` silently. Update the file if the spec changes.

pages/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md
+
+Write for readers, not internal bookkeeping.
+
+## Published Pages
+
+- Treat `pages/` as the published documentation surface.
+- Preserve Jekyll and GitHub Pages compatibility when changing layouts, includes, config, or Markdown.
+- Keep public pages concise, navigable, and reader-facing.
+- Do not expose internal planning notes from `docs/` or `src/memory/` unless the content is intentionally promoted for publication.
+- When changing assets or page structure, verify the rendered site path that GitHub Pages will serve.

src/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md
+
+## General
+
+- When materially changing a command, rule, or skill, bump `metadata.version` using semver.
+
+## Rules and Commands
+
+- Keep rules and commands small, composable, and scoped to their folder.
+
+## Skills
+
+- For `src/skills/*`, follow `src/skills/HOWTO.md`.