# AGENTS.md

## Core rule

OpenSpec is the source of truth. Superpowers is the default workflow. Keep changes small, scoped, and verified.

## Priority order

1. Current user instruction
2. OpenSpec proposal, tasks, and spec deltas
3. This `AGENTS.md`
4. Existing project conventions
5. Agent assumptions

When instructions conflict, follow the higher-priority source. Do not silently expand scope.

## Default workflow

For any non-trivial change:

1. Read the relevant OpenSpec change, tasks, and spec deltas.
2. Use `brainstorming` if scope, design, or requirements are unclear.
3. Use `writing-plans` before implementation.
4. Implement only the selected task or clearly requested change.
5. Use tests, typecheck, lint, or targeted checks to verify.
6. Use `verification-before-completion` before claiming completion.

If namespacing is required, use:

* `superpowers:brainstorming`
* `superpowers:writing-plans`
* `superpowers:test-driven-development`
* `superpowers:systematic-debugging`
* `superpowers:verification-before-completion`

## When OpenSpec is required

Create or update an OpenSpec change before implementing:

* New features
* Behavior changes
* API changes
* Database/schema changes
* Auth, security, billing, permissions, or data handling changes
* Architecture changes
* Large refactors
* Anything with unclear acceptance criteria

Small local fixes may skip OpenSpec if they do not change behavior or public contracts.

## Superpowers usage

Use:

* `brainstorming` for ambiguity, design choices, or scope questions.
* `writing-plans` for multi-step or multi-file work.
* `test-driven-development` for behavior changes and bug fixes where practical.
* `systematic-debugging` for failing tests or unclear bugs.
* `verification-before-completion` before final completion claims.
* `using-git-worktrees` only for isolated risky or parallel work.
* `dispatching-parallel-agents` only for independent subtasks with clear boundaries.

If a skill is unavailable, follow its intent manually and say so.

## Scope discipline

Do not:

* Implement outside the selected OpenSpec task.
* Mix unrelated cleanup with feature work.
* Introduce new dependencies without clear justification.
* Treat existing code as more authoritative than OpenSpec for intended behavior.
* Decide product behavior silently when the spec is unclear.

If scope must change, propose an OpenSpec update first.

## Verification

Before completion, report:

* What changed
* Which OpenSpec task/change it addresses
* Tests/checks run
* Any failures, skipped checks, assumptions, or risks

Do not claim completion without verification evidence.

## Definition of done

A task is done when:

* It matches OpenSpec.
* The diff is focused.
* Relevant tests/checks passed or limitations are stated.
* No unrelated scope was added.
* Remaining risks or follow-ups are documented.