agentic-qa-boilerplate: Instructions file for Claude Code

AGENTS.md: AI Persistent Memory

AI memory. Loads EVERY session. Heavy detail → skill references/. Project values → .agents/project.yaml. Scripts → READ package.json. User-facing setup → README.md / docs/.

1. CRITICAL RULES: ALWAYS APPLY

1. CREDENTIALS: ALWAYS read from .env. NEVER hardcode/guess. Example keys: LOCAL_USER_EMAIL, STAGING_USER_PASSWORD.
2. PLAN BEFORE CODING: Produce test plan (spec.md / impl plan) BEFORE writing test code. Flow: Plan → Code → Review.
3. NO AI ATTRIBUTION: NEVER include "Generated with AI", harness branding, or AI Co-Authored-By trailers in commits. Commits look human-authored.
4. SHIFT-LEFT: Evaluate ACs for clarity, testability, completeness. Raise questions ONLY when genuine gaps exist, never force questions to fill checklist.
5. PUSH TO PROTECTED = RESOLVE git_strategy.policy.direct_push_to_protected (.agents/project.yaml; protected list = git_strategy.protected): forbidden → NEVER direct-push, route through a PR. confirm → ask explicit user confirmation before EVERY push. allowed → standing authorization, push without asking. git_strategy block missing or null (fresh scaffold) → behave as confirm (safe default: ask). NEVER hardcode the answer here — the variable is the decision.
6. GIT HISTORY (INVARIANTS, not strategy choices — no git_strategy value relaxes them): NEVER rewrite pushed history (rebase/amend on pushed commits). NEVER force-push a branch others may share — at minimum every branch in git_strategy.protected, plus integration/ephemeral trunks in git_strategy.branches. NEVER delete remote branches without confirmation. ALWAYS add forward (new commits, not rewrite). ALWAYS preserve merge history.
7. QUALITY VERIFICATION: After code changes, verify in order: tests → types → lint. No skip steps.
8. FILE OPERATIONS: ALWAYS read file before edit. Preserve formatting + indent. NEVER overwrite without reading.
9. SKILLS-FIRST: All workflows live in .agents/skills/. NEVER paste instructions inline. Invoke matching skill, let it self-load detail. Use [TAG_TOOL] pseudocode + {{VARIABLES}} for dynamic content.
10. MCP CREDENTIAL FAILURE = STOP IMMEDIATELY: MCP fail auth or env var missing (.mcp.json use ${VAR}: Claude Code fail parse if unset; opencode.jsonc use {env:VAR}: OpenCode silently substitute empty → 401/403 is signal). NO workaround. STOP, tell user exact env var, point to .env / .env.example, ask fix .env + RESTART AGENT SESSION (env cached at MCP-spawn time, no refresh mid-session).
11. SCRIPTS = READ package.json DIRECTLY. NEVER quote test/build commands from this file or any doc: drift kills. Open package.json first, then answer.
12. KATA MANIFEST = SOURCE OF TRUTH. kata-manifest.json (root) is authoritative registry of every existing Component + ATC. Before proposing new Page, Api, Steps module, or @atc('PROJ-XXX') ID: MUST load kata-manifest.json and check it. Anti-duplication gate. Stale manifest blocks commits via .husky/pre-commit. Regenerate: bun run kata:manifest. Validate: bun run kata:manifest:check.
13. DEFAULT COMMUNICATION MODE: CAVEMAN: If caveman skill installed user-level (~/.claude/skills/caveman/), respond caveman level full by default (drop articles, fillers, pleasantries; fragments OK; technical terms exact; code/commits/PRs/security warnings always write normal English: caveman built-in boundary). Revert verbose ONLY when user explicitly say "normal mode", "habla normal", "stop caveman", "speak normally", "be verbose", "más detallado" or clear semantic equivalent. If caveman skill not installed, rule = no-op.
14. LANGUAGE DETECTION + MIRRORING: At start of every conversation, READ FULL USER MESSAGE (not just opening words) to detect user's working language. Mirror that language in ALL conversational replies (questions, summaries, explanations, status updates). Repo artifacts ALWAYS English regardless of conversation language: code, code comments, commits, PR titles + bodies, branch names, file names, test names, configuration values, + any external action artifact (Jira issues/comments, GitHub issues/PRs/comments, Slack messages, emails, deploy notes, MCP tool inputs). Override: if user explicitly request another language for specific artifact ("crea el ticket en español", "write this PR description in Spanish"), honor that request only for that artifact + continue defaulting to English for next ones unless re-requested.
15. NO GLOBAL DISCARDS (MULTI-SESSION SAFETY): PROHIBITED to run repo-wide destructive git commands: git restore ., git checkout -- ., git reset --hard, untargeted git stash, git clean -f. Multiple agent sessions may share this working tree without worktrees: a global discard silently destroys another session's uncommitted work, unrecoverably. Discard ONLY explicit paths YOU modified in THIS session (git restore <path>... / git stash push <path>...). Unsure who modified a file → do NOT restore it: ask the user.