# AGENTS.md

## Core rule

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

## Communication

All agent output, code comments, commit messages, documentation, and artifacts must be in **English** unless the user explicitly requests another language.

## 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.
* Run `docker compose` commands (build, up, down, etc.) without explicit user approval and proper isolation (e.g., feature branches, separate worktrees, or staged rollouts). Docker Compose operations are deployment-level changes that can affect running services, shared volumes, and network state. Always ask first.

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 workflow

### Branching strategy

For every spec change or new functionality:

1. Create a new branch from `dev` with a proper prefix:
   - `feat/` for new features (e.g., `feat/tool-workshop`)
   - `fix/` for bug fixes (e.g., `fix/terminal-tty`)
   - `refactor/` for refactors (e.g., `refactor/api-cleanup`)
   - `docs/` for documentation (e.g., `docs/api-guide`)
   - `chore/` for maintenance (e.g., `chore/update-deps`)
2. Branch name should reference the OpenSpec change name when applicable.
3. Do not commit directly to `main` or `dev`.

### Completion and merge

When implementation is complete and verified:

1. Ensure all tests pass and quality gates are met.
2. Stage all changes with `git add -A`.
3. Create a commit with a proper conventional commit message (see below).
4. Switch to `dev`: `git checkout dev`.
5. Merge the feature branch: `git merge --no-ff <branch-name>`.
6. Push to remote: `git push origin dev`.
7. Delete the local feature branch if desired: `git branch -d <branch-name>`.

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