AGENTS.md

Agent Instructions

Required Agent Workflow

For every task that changes files, agents must complete this checklist unless the user explicitly says not to:

0. Before starting new work, check whether the previous agent or run left any required follow-through unfinished for the same workstream, including open or unmerged implementation PRs, open or unmerged release PRs, incomplete release publication, or missing cleanup required by these instructions. If any such incomplete follow-through exists, finish that work first before starting the new task.
1. Create a new dedicated Git worktree before editing files. Never reuse an existing worktree for new work, even if it appears idle or related.
2. Make all edits inside the new worktree created for the task.
3. Run relevant validation.
4. Commit the changes with a Conventional Commit message.
5. Stop there unless the user explicitly asks to publish, share, open a pull request, merge, release, or deploy the work.

Do not push branches to GitHub, open pull requests, merge to main, wait for GitHub Actions, publish releases, or delete the task worktree as part of the default local implementation workflow. The default handoff is a committed local branch/worktree that the user can inspect, run locally, amend, or ask to publish later.

When the user explicitly asks to publish local work, complete this checklist:

1. Confirm the intended local branch/worktree and inspect git status.
2. Run relevant validation again if the local commit is stale or unvalidated.
3. Push the local branch to GitHub.
4. Open a pull request with a Conventional Commit title.
5. Monitor the pull request until checks complete and it can merge cleanly.
6. Merge the pull request into main when requested or when the user's publish request clearly asks for a complete merge/release flow.
7. Confirm any required release has completed and any required container image or other artifact has been published.
8. Delete the remote task branch from GitHub after the pull request is fully merged and the complete CI, release, and publication cycle has finished.
9. Remove the task worktree only after its changes have landed on main, all required release or publishing steps are complete, and there is no uncommitted user work in that worktree.
10. Delete the local task branch after the worktree has been removed and the branch is no longer checked out anywhere.

If a pull request has errors, failing checks, or merge conflicts, fix the issue in a new dedicated worktree and open a replacement pull request. Repeat this cycle until all requested code is merged into main and any required release or image publication is complete.

Use this prompt when you want an agent to publish a local branch:

Please publish the local branch for this work. Push the branch to GitHub, open a
pull request with a Conventional Commit title, monitor the checks, and merge it
when it is green. Then confirm any required release or image publication and
clean up the task worktree and both the remote and local task branches.

Out-of-Scope Findings

If you discover an issue while working in a codebase and the issue is outside the scope of the current task, create a focused GitHub issue in the relevant repository before finishing. Include enough detail for another engineer to understand and act on it: what you found, where you found it, why it matters, available reproduction or evidence, and your view on what should be done to fix it. Do not silently ignore the issue, and do not expand the current task's scope unless the user explicitly asks you to fix it now.

Security Expectations

When planning and implementing a feature, ensure the feature would pass an ethical hacking test. Security is paramount: a feature should work well and provide a strong user experience, but not at the expense of abuse resistance, data protection, or defensible backend controls.

Treat client-side controls as UX aids only. Any security rule, authorization check, quota, limit, validation, or workflow restriction enforced in the frontend must also be enforced by the backend or trusted infrastructure.

For forms and other user-controlled inputs:

• Add rate limits to forms and endpoints that accept user input or trigger meaningful work.
• Bound input fields to sensible values and reject unreasonable payloads. For example, if a form allows selecting IP ports to scan, limit the number of ports to a sensible maximum instead of allowing an unbounded list.
• Prevent duplicate submission and make backend handlers idempotent where double submission could create duplicate work, records, payments, scans, or notifications.
• Validate input shape, type, size, encoding, and allowed values on the backend.
• Apply least-privilege authorization checks to every object or action touched by the feature.
• Avoid exposing secrets, internal identifiers, stack traces, or sensitive operational details to users or logs.
• Consider common web security risks such as injection, cross-site scripting, cross-site request forgery, insecure direct object references, server-side request forgery, unsafe file handling, weak session handling, and excessive resource consumption.

These examples are not exhaustive. Consider the broader security implications of the feature, its failure modes, and how it could be abused before shipping.

Testing Expectations

Use test-driven development for new features and meaningful behavior changes. Before writing implementation code, write the relevant tests first. Include unit tests and end-to-end tests where appropriate for the scope and risk of the change.

If the repository does not already have a test suite or test command, add a minimal test harness that fits the technology in use before making the feature change. The harness does not need broad coverage immediately, but it must be able to run in local development and CI, and it must include at least one passing smoke test that proves the harness works.

Choose the harness based on the repository's actual stack and conventions:

• For Next.js or other browser-facing web applications, add an end-to-end test harness such as Playwright, plus any unit/component test harness that is already standard for the repo.
• For Go services, CLIs, and libraries, use Go's built-in testing package unless the repository already standardizes on another Go test framework.
• For Node.js packages that are not browser applications, add a unit test harness that matches the package manager and module system already in use.
• For other stacks, choose the smallest conventional test harness for that language or framework and document how to run it.

Run the new tests before implementation and confirm they fail for the expected reason. Then implement the code needed to make those tests pass. This helps confirm the implementation does what was intended and ensures new behavior has test coverage.

Do not consider implementation work complete, commit it, or open a pull request while relevant tests are failing. Investigate and fix failures caused by the change before finishing. If failures are unrelated or cannot be fixed within the task scope, document the evidence in the PR and clearly call out the residual risk.

If a test-first workflow is not practical for a specific change, document why in the PR and describe the alternative validation that was performed.

Integration and E2E Testing

Use each repository's own testing documentation, fixtures, and helper patterns as the source of truth for integration and end-to-end testing. If the repository documents a specific test harness, follow that harness instead of duplicating or replacing its setup details.

Rules for integration and end-to-end tests:

• When behavior depends on persisted state, migrations, constraints, authentication, authorization, ownership, tenancy, or other infrastructure behavior, prefer the repository's real integration test harness over mocks.
• When a test needs records beyond documented baseline seed data, seed those records explicitly through the existing fixture/helper pattern. Do not rely on state leaked from another test.
• Keep seed data minimal and relevant to the behavior under test. Prefer deterministic values and create the relationships the production code expects, including ownership, tenancy, and scoping fields where applicable.
• For browser-based E2E tests, add stable test selectors for interactions and assertions rather than selecting by generated classes or layout-dependent selectors.

Pull Requests

After finishing the local implementation for a task, commit the work locally with a Conventional Commit message unless the user explicitly asks not to. Do not push the branch, create a pull request, monitor checks, merge, release, or deploy unless the user explicitly asks to publish or share the work.

When the user asks to publish local work, push the branch to GitHub, create a pull request, monitor it, and merge it into main if requested or if the prompt clearly asks for the full publish flow. Always use Conventional Commit names for commits and pull request titles so release automation can function correctly.

Keep monitoring the pull request until all checks pass and the branch can merge without conflict. If checks fail, errors appear, or a merge conflict is detected, fix the issue in a new dedicated worktree and create a replacement pull request. Do not reuse the failed pull request's worktree for the next attempt.

All pull request titles must use Conventional Commit format because squash merges often use the PR title as release automation input.

Use this format:

<type>(<scope>): <summary>

Allowed types are build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test. The scope is optional, but preferred when the affected package or area is clear.

Examples:

feat(api): add token rotation endpoint
fix(auth): reject expired sessions
ci(release): add artifact smoke test
docs(setup): document custom HTTPS ports

Do not open PRs with non-conventional titles such as [codex] add feature.

Progress Tracking

When a new feature is created that satisfies part or all of an existing requirement, update the repository's progress or roadmap tracking if one exists. If the feature fully satisfies the requirement, state that clearly. If it only satisfies part of the requirement, record exactly which part is complete and what remains outstanding.

Completion Cleanup

When published work is complete, remove the dedicated task worktree and delete the associated local and remote task branches. Local-only tasks may keep their task worktree so the user can inspect, run, or amend the local branch before publishing.

Cleanup requires both of these outcomes:

• The worktree is unregistered from Git, for example with git worktree remove <path> from the main repository.
• The task worktree folder no longer exists on the local disk.
• The remote task branch is deleted from GitHub after the pull request is fully merged and the complete CI, release, and publication cycle has finished.
• The local task branch is deleted after no remaining worktree has it checked out.

Do not leave published task worktrees hanging around. Published work that still has a registered Git worktree, an on-disk worktree folder, or leftover local or remote task branches is not actually finished.

Only remove a worktree after its changes are committed, pushed, merged into main, released, and published as appropriate for the task, including publication of new container images or other release artifacts where relevant, or when the user explicitly asks to discard a local-only worktree. Never delete a worktree that contains uncommitted user work or unpublished changes unless the user explicitly asks you to discard it.

When asked to publish or clean up local work, inspect existing registered worktrees. If an existing task worktree is already pushed, its pull request has already been merged, and the required CI, release, and publication cycle is complete, remove that worktree and delete the associated local and remote task branches. Do not delete branches or worktrees for pushed work that has not landed on main unless the user explicitly asks to abandon it.