AGENTS.md

AGENTS.md

@@ -19,6 +19,7 @@ Before substantive work, read [product scope](docs/product.md),
 
 - Preserve user changes and avoid unrelated edits.
 - Make small, cohesive changes with verification appropriate to their risk.
+- After each implementation, start the local app and verify its health endpoint before reporting completion.
 - Use isolated Git worktrees for concurrent implementation that could overlap.
 - Design and plan substantial subsystems before implementing them.
 - Report assumptions, checks performed, and unresolved risks accurately.
@@ -38,3 +39,80 @@ real data only in ignored local directories or local databases. Never commit
 raw data, identifying excerpts, snapshots, logs, screenshots, reports, or dumps.
 Committed fixtures must be synthetic or irreversibly sanitized. Follow the
 [full data policy](docs/data-policy.md) before handling source documents.
+
+# Superpowers productivity policy
+
+Use Superpowers with proportional rigor.
+
+Optimize for correctness per unit of engineering effort, not maximum process.
+
+## Risk scaling
+
+Default to the lightest process that provides reasonable confidence.
+
+For ordinary low-risk work:
+- use targeted repository exploration;
+- treat the task as bounded unless architecture genuinely changes;
+- use a short in-chat design;
+- implement inline rather than with subagents;
+- target 1-3 focused new tests;
+- run targeted verification during development;
+- self-review the final diff;
+- avoid separate review agents unless warranted.
+
+Increase rigor for changes involving:
+- security or authorization;
+- destructive operations;
+- financial calculations;
+- concurrency;
+- persistence/data integrity;
+- public interfaces;
+- broad architectural changes;
+- historically fragile components.
+
+## Scope
+
+Follow YAGNI aggressively.
+Do not add speculative features, tests, abstractions, refactors, or cleanup.
+
+## Context
+
+Explore on demand. Start with directly relevant files, callers, and tests.
+Expand only when evidence indicates that more context is required.
+
+## Tasks
+
+Prefer cohesive behavioral tasks over tiny procedural tasks.
+Batch small mechanically similar edits.
+Do not create separate tasks for routine test/run/commit operations.
+
+## Tests
+
+Tests provide confidence proportional to risk, not maximum coverage.
+For ordinary changes, target no more than 1-3 new tests.
+One sufficient regression test is better than several speculative tests.
+
+## Verification
+
+Use narrow verification while iterating.
+Run broader verification once at completion when appropriate.
+Do not repeatedly execute expensive full-suite verification without a
+specific reason.
+
+## Reviews
+
+Scale reviews to the size and risk of the diff.
+Avoid redundant implementer review + task review + final review for small
+changes.
+
+## Agents and models
+
+Do not use subagents when the current agent can comfortably complete the task.
+Use cheaper models for mechanical work and stronger models for judgment,
+debugging, architecture, and genuinely difficult reviews.
+
+## Communication
+
+Keep process narration minimal.
+Surface decisions, discoveries, failures, scope changes, and verification
+results rather than routine operations.