# 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.

## Git branch policy

- **Default working branch:** `dev` — all commits and pushes target `dev` unless the user explicitly requests otherwise.
- `main` is the stable/production branch; merge to `main` only when explicitly instructed.
- After committing, push to `origin/dev`.
- If `dev` does not exist locally, create it from `main` or fetch it from origin.

## Git workflow

### Auto-commit on spec completion

When an OpenSpec change is fully implemented and all tasks are complete:

1. Stage all changes with `git add -A`
2. Create a commit with a proper conventional commit message
3. The commit message should:
   - Use conventional commit format (`feat:`, `fix:`, `refactor:`, etc.)
   - Reference the OpenSpec change name and relevant user stories
   - Include a brief summary of what changed
   - Mention quality gate results (tests passed, etc.)
   - Example:
     ```
     feat: implement user profile management
     
     - Add authenticated profile endpoints (GET/PUT /users/me)
     - Add avatar upload with file validation
     - Create frontend profile page
     
     Quality gates: pytest (50 passed), ruff, mypy
     ```

### Commit scope

- One commit per completed OpenSpec change (or related group of changes)
- Do not commit untested or broken code
- Do not commit secrets, .env files, or credentials

## 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.
* Changes are committed with a proper conventional commit message.