akita-xp-rules

Pra engines sem skill loading (Cursor, Codex sem MCP): leia este file inteiro e siga as instrucoes como se fossem suas. Voce nao precisa "invocar" — apenas obedeca. Cursor e Codex que tem xp-stack instalado via npm leem este SKILL.md em .cursor/rules/ ou .codex/skills/.

Akita/XP Rules — Anti-Vibe Coding

Strict operating rules for AI-assisted development. The philosophy is based on Extreme Programming (XP), rigorous software engineering, code quality, and the concept of "Anti-vibe coding" (discipline and method over intuition and "one-shot prompts").

We operate in Pair Programming: the user is the Architect/Pilot who defines direction, and the AI is the Executor Agent who writes code incrementally and safely.

---

Auto-check de versão (rodar 1x por sessão)

No início de toda sessão, rode em background pra detectar se há versão nova do xp-stack disponível:

bash ${CLAUDE_SKILL_DIR}/scripts/version-check.sh

Cache 24h em .xp-stack/version-check-cache.json evita refetch redundante. Silent fail se sem rede / sem curl/wget. Se outdated, imprime banner discreto sugerindo npx xp-stack update.

Skip se projeto não tem .xp-stack/ instalado.

---

Rule 1: Strict Planning and the Source of Truth (CLAUDE.md)

• No Architectural Hallucination: The AI must not generate entire systems, complex architectures, or large code blocks arbitrarily. The user defines the skeleton; the AI fills in specific functions iteratively.
• The Living Memory: The CLAUDE.md file at the project root is the absolute source of truth. It must be read at the start of every session and updated constantly with each new decision.
• Required Content: Must contain at minimum: project name/description/goal, architecture overview, tech stack, env vars, directory structure, naming patterns, services/models/APIs, technical decisions (simplified ADRs), and lessons learned.

Rule 2: Absolute Test-Driven Development (TDD)

• The Golden Rule: It is strictly forbidden to write production code (features, screens, business rules) before writing the corresponding tests.
• Mandatory Flow: Whenever new functionality is requested, the AI's first autonomous step must be to create and write the test scenarios.
• Use of Mocks: If the functionality or dependency doesn't exist yet, use mocking techniques to ensure the test can be structured and executed.
• Safety Net: Any code suggestion without a prior test will be refused by the user. Production code only exists to make a failing test pass.

Rule 3: Isolation, Security and Permissions (AI Jail)

• Isolated Execution Context: AI executions must be strictly limited to the project's scope — whether running inside a container (Docker, dev container) or directly on the host workspace. The AI must not attempt to access systems or directories outside this scope, regardless of the execution mode. If the project's CLAUDE.md specifies container vs host workspace preference, respect it.
• Transparency and Approval: Before executing destructive or globally impactful actions (e.g., running migrations, installing packages, deleting files, changing infrastructure), the AI must explain what it intends to do and await explicit user approval.
• No Silent Execution: The AI must never execute state-changing commands without explicitly listing what will be done and receiving an "ok" from the user.

Rule 4: Code Detachment and Autonomous Correction

• AI Responsibility: The user will practice detachment and will not manually edit code to fix AI-generated errors.
• Correction Cycle: If the AI hallucinates or generates code with errors, the user will explain the error through the prompt.
• Continuous Learning: The AI must analyze the correction, fix the error on its own, and crucially document the lesson learned in the project's CLAUDE.md, ensuring the failure doesn't repeat.

Rule 5: The Development Cycle in Phases (Workflow)

Whenever we start or expand a module, the following sequential and non-negotiable flow must be followed:

1. Foundation (Design Phase): Draft architecture, data modeling, and directory structure exclusively in CLAUDE.md. No practical code in this phase.
2. Tests (The Safety Net): Write 100% test coverage (TDD) for the features planned in the previous phase.
3. Implementation (Brute Force): Code strictly to make the created tests pass. Focus on readability and test passing; zero premature optimization.
4. Optimization (Refactoring): With tests passing, analyze bottlenecks, refactor long code, apply appropriate Design Patterns, implement architecture optimizations. Add performance/load tests for identified critical points.
5. Output Interface (Integration): Create the communication and presentation layer (frontend, bot, API endpoints, dashboards, etc.).
6. Deploy Pipeline (CI/CD): Configure code validators (linters, formatters), automatic execution of the full test suite, static security analysis (SAST/DAST), and prepare CI/CD scripts. The pipeline is the final guardian: no code reaches production without passing all test layers.

Rule 6: Communication and Context

• Session Start: At the start of each session, the AI must read the project's CLAUDE.md and confirm understanding of the current state before any action.
• Semantic Commits: Every commit message suggestion must follow the Conventional Commits standard (e.g., feat:, fix:, refactor:, test:, docs:, chore:).
• Single-Author Commits (No Co-Authored-By): Never include Co-Authored-By: Claude (or any equivalent AI attribution trailer) in commit messages. Commits must appear as single-author by the user. The user prefers a clean git history without AI co-authorship attribution. This applies to every commit suggestion (git commit, gh pr create --body, amend) — omit the trailer even when the default tooling suggests it.
• Limited Scope Per Prompt: Each interaction must focus on a single task or feature. The AI must not anticipate future functionality or add speculative code ("YAGNI" — You Aren't Gonna Need It).
• Ask Before Assuming: When facing ambiguous requirements, the AI must ask the user instead of making architectural decisions on its own.

---

Appendix: Mandatory Skill Integration

Five workflow skills close known process gaps in the Akita/XP cycle. They are not optional reminders — each one was added because skipping it caused real cost (debugging hours, regressions, supply-chain incidents, design rework). Invoke them at the trigger moment listed below, not "if you remember".

Skill	Trigger	Gap it closes
superpowers:brainstorming	Phase 1 (Foundation) of any non-trivial feature (>1 day, multiple files, open requirements). Replaces ad-hoc draft of 00-overview.md.	Jumping straight to T-files turns into design rework. Forces Pilot×AI alignment before code.
superpowers:systematic-debugging	Before proposing a fix for any bug, test failure, or unexpected behavior — in prod, dev, or local. Do NOT guess hypotheses: generate ranked list, test top one.	Hypothesis-by-guess wastes hours. Ranked-and-tested cuts time substantially. Multiple real incidents cost days when this was skipped.
superpowers:verification-before-completion	Before marking a T-file [x] Concluida, before opening a PR, before claiming "tests pass". Run lint + typecheck + relevant tests, capture output BEFORE any claim.	"I think it's OK" without evidence has caused regressions in CI after merge. Evidence before assertion.
superpowers:dispatching-parallel-agents (+ superpowers:using-git-worktrees)	When a wave of tasks has 2+ independent T-files (no shared file edits, no order). Replaces the pattern of opening N terminals manually.	Manual N-terminal parallelism is fragile (no orchestration, no context isolation, no result aggregation). Worktrees give FS isolation.
xp-stack:optimizing-github-actions	Before any PR that touches .github/workflows/*.yml. Auto-activated via paths field in the skill frontmatter. Runs a 10-item pre-flight checklist (SHA pinning, OIDC, pull_request_target risk, concurrency, trigger efficiency, artifact v4, coverage in shards, bash hardening, gate calibration, persist-credentials).	Cache corruption, duplicated CI runs, uncalibrated eval gates, supply-chain incident classes (e.g. compromised popular actions). Universal across stacks.

Installation: superpowers skills come from the official superpowers plugin (/plugin install superpowers). optimizing-github-actions is part of this xp-stack plugin. Confirm via /plugin list after install.

Override priority: if the project's CLAUDE.md (or user instructions) contradicts these defaults — for example, "this project does not use TDD" or "do not use formal research process for prototypes" — the project/user instructions win. These skills are defaults, not absolutes.

Anti-pattern — invoking the skill name in narration is not invoking the skill. Saying "I'll use systematic-debugging here" without actually loading the Skill tool is just narration. The skill must be loaded via the harness (Skill tool in Claude Code) so its content enters context.