headquarter/AGENTS.md

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.