agents-setup

Communication

• Drop articles, filler, pleasantries, hedging
• Fragments OK, short synonyms, technical terms exact
• Code blocks unchanged
• Safety override: clear wording for destructive ops, then resume caveman

Phase 1: Plan Mode

"Modo plan: Preguntame todo lo que necesites para realizar correctamente esta tarea."

• Project name / purpose (if not obvious from package.json or README)
• LLMs/tools in use beyond Claude Code (Cursor? Copilot? OpenCode? Zed?)
• Any existing rules in current AI config files worth preserving?
• Team-specific PR policies, branch conventions, or deployment notes to include?

Phase 2: Auto-Detection

Detect stack

1. Root package.json — name, scripts, dependencies, devDependencies
2. Workspace package.json files — monorepo packages (look for

   workspaces

   field or multiple

   package.json

   in subdirs)
3. Other stack indicators:

   pyproject.toml

   /

   requirements.txt

   (Python),

   go.mod

   (Go),

   Cargo.toml

   (Rust),

   pom.xml

   /

   build.gradle

   (Java),

   Gemfile

   (Ruby),

   composer.json

   (PHP)
4. Build tools: vite.config., webpack.config., turbo.json, nx.json
5. Test framework: jest.config., vitest.config., pytest.ini, .mocharc.*
6. Lint/format: .eslintrc., .prettierrc., pyproject.toml [tool.ruff], etc.
7. Package manager: presence of bun.lock, pnpm-lock.yaml, yarn.lock, package-lock.json

Detect existing AI config

• AGENTS.md

• .claude/CLAUDE.md

• .github/copilot-instructions.md

• .cursorrules

• .windsurfrules

• .agents/rules/*.md

  (list all)

• MEMORY.md

Detect project structure

Phase 3: Generate AGENTS.md

Template

# AGENTS.md — Project Rules

## Stack

[Fill from auto-detection. Be specific: versions, framework names, key libraries.]
[For monorepos: list each package and its role.]

## Commands

[Extract real commands from package.json scripts or equivalent.]
[Group by: dev, build, test, lint/format, any project-specific workflows.]

## Project Structure

[List top-level dirs with one-line purpose each.]
[For monorepos: list packages + roles.]

## Communication Style

Default mode for all AI assistants in this project: **caveman** (full intensity).

Rules:

- Load `/caveman` skill (level: full) before any response
- Apply to: chat replies, planning steps, tool preambles, progress updates, summaries
- Disable only on explicit: `stop caveman` or `normal mode`
- Fallback if skill unavailable: emulate caveman style directly
- Safety override: use clear wording for destructive/irreversible ops, then resume caveman

## Plan Before Act

Always present plan and wait for explicit approval before implementing any non-trivial change.

Non-trivial = anything beyond single-line fix. Includes: new files, refactors, features, dependency changes, config changes.

Format:

1. State what you found
2. List proposed changes (files + what changes)
3. Flag risks or unknowns
4. Wait for "go" / "yes" / "proceed"

Do NOT write code until approved.

## PR Policy

[Fill from project conventions or use sensible defaults:]

- One concern per PR
- Run lint + format before committing
- Tests required for new logic
- No TODO left in merged code

Rules for filling the template

• Stack: exact versions from package.json, not ranges (React 19, not ^19). For monorepos list each package's role.
• Commands: use actual script names from package.json. If

  bun run dev

  is the real command, write that — not

  npm run dev

  .
• Structure: only include dirs that exist. Skip boilerplate explanation for obvious names (src/, tests/ need no explanation).
• Preserve: any rules from satellite files not already in the template — add them under a relevant section or a new section.
• Length: if approaching 200 lines, cut structure detail first, keep commands and stack exact.

Phase 4: Wire Satellite Files

.claude/CLAUDE.md

Strictly follow the rules in ./AGENTS.md

.github/copilot-instructions.md

Strictly follow the rules in ./AGENTS.md

.cursorrules (only if file already exists)

Strictly follow the rules in ./AGENTS.md

.windsurfrules (only if file already exists)

Strictly follow the rules in ./AGENTS.md

.agents/rules/ (if directory exists)

• Read content
• If content is fully covered by AGENTS.md → delete file
• If content has rules NOT in AGENTS.md → port those rules to AGENTS.md, then delete file
• Tell user which files were deleted and what (if anything) was ported

MEMORY.md

# MEMORY.md — Agent Lessons

Human-reviewed lessons from past sessions. Agent writes candidates; human approves before merging.

---

<!-- Add lessons below. Format: date | lesson | why it matters -->

Phase 5: Report

Done. Changes:
- AGENTS.md: [created/updated]
- .claude/CLAUDE.md: [created/updated] → pointer
- .github/copilot-instructions.md: [created/updated] → pointer
- .agents/rules/: [N files deleted, M rules ported to AGENTS.md]
- MEMORY.md: [created/already existed]
- [any other files touched]

Single source of truth: AGENTS.md