Developer
2254ba7496
- Require all agent output, comments, commits, docs, and artifacts to be in English unless explicitly requested otherwise
158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|