maidn-cli/AGENTS.md

MaidnCLI Review And Delivery Contract

Branches And Pull Requests

• Keep each safe, reviewable change on one scoped branch.
• Do not leave completed work only in a local worktree or a pushed branch.
• Open a Forgejo pull request for every completed branch unless the user explicitly authorizes a direct merge.
• Verify the pull request exists, has the intended head and base, and return its URL.
• Do not claim a pull request is open until it is verified through the Forgejo API or UI.
• Update an existing pull request when follow-up work belongs to its scope; open another only for an independent change.
• Merge only when the user explicitly authorizes the named pull request or branch.

Required Checks

• Before each commit: inspect git status --short, git diff --check, and git log --oneline -10.
• Before review: run the applicable focused and repository checks, then record the commands and results.
• Never commit generated workspaces, .password, SOPS material, kubeconfigs, Terraform state, recovery material, or token files.

Review Handoff Format

Use this exact format whenever user review or merge is required:

Review required
PR: <URL>
Branch: <name>
Purpose: <one sentence>
Checks: <command> - PASS|FAIL|BLOCKED
Risk: <one sentence, or none>
Merge: <merge action the reviewer should take>

API Failure

• Retry with the target repository owner, not a disposable-cluster owner.
• Report the HTTP status and non-sensitive response shape only.
• A compare URL is a fallback only after PR creation has genuinely failed; it is not a substitute for an opened PR.