kakaroto-config

Claude Code configuration for autonomous development workflows.

Quick Install

# Local installation (recommended - installs to ./.claude/)
npx kakaroto-config

# Global installation (installs to ~/.claude/)
npx kakaroto-config --global

Local is recommended because each project can have its own customizations while inheriting the global rules.

Updating

To update to the latest version, run the same command again:

# Update local installation
npx kakaroto-config@latest

# Update global installation
npx kakaroto-config@latest --global

The installer will detect the existing .claude/ folder and ask if you want to overwrite.

Note: If you previously installed globally (~/.claude/) and want to switch to local (./.claude/), just run npx kakaroto-config@latest in your project folder. Both can coexist - Claude Code will use local config when available.

What Gets Installed

.claude/
├── CLAUDE.md              # Global rules (autonomy, coding standards)
├── ARCHITECTURE.md        # Full documentation of the system
├── skills/                # Skill workflows (invoked via /skill)
│   ├── build/SKILL.md         # /build orchestrator
│   ├── build-understand/      # Phase: requirements alignment
│   ├── build-verify/          # Phase: QA verification design
│   ├── build-implement/       # Phase: autonomous implementation
│   ├── build-certify/         # Phase: quality + deploy + prod verification
│   ├── resolve/SKILL.md       # /resolve orchestrator
│   ├── resolve-investigate/   # Phase: diagnosis + QA reproduction
│   ├── resolve-fix/           # Phase: autonomous fix + local QA
│   ├── resolve-certify/       # Phase: quality + deploy + prod QA
│   ├── think/                 # /think - Socratic problem exploration
│   └── deliberate/            # /deliberate - adversarial solution design
├── commands/              # Commands (invoked via /command)
│   └── gate.md            # /gate - quality gate before PR
└── agents/                # 8 specialized subagents
    ├── build-implementer.md
    ├── resolve-fixer.md
    ├── test-fixer.md
    ├── code-reviewer.md
    ├── code-simplifier.md
    ├── functional-validator.md
    ├── terraform-validator.md
    └── memory-sync.md

Skills & Commands

| Name | Type | Trigger | Description | |------|------|---------|-------------| | /think | Skill | Manual | Socratic thinking partner: hypothesis-driven problem exploration, zero implementation | | /deliberate | Skill | Manual | Adversarial solution designer: challenges framing, simulates scenarios as temporal narratives | | /build | Skill | "adicionar", "implementar", "criar" | Full feature workflow: understand -> verify -> implement -> certify | | /resolve | Skill | "bug", "erro", "problema" | Bug resolution: investigate -> fix -> certify | | /gate | Command | Manual | Run quality agents before PR |

Workflow Chain

/think  (optional)     Problem exploration: hypotheses, root causes
   |
/deliberate (optional) Solution design: scenarios, trade-offs, refinement
   |
/build                 Implementation: spec -> verify -> code -> certify

/resolve               Autonomous bug fix: diagnose -> fix -> certify

Agents (Subagents)

| Agent | Model | Blocking | Purpose | |-------|-------|----------|---------| | build-implementer | opus | yes | Autonomous implementation from spec, codes until tests pass | | resolve-fixer | opus | yes | Autonomous bug fix, codes until QA flows pass | | code-reviewer | opus | yes | Security, types, bugs | | test-fixer | sonnet | yes | Runs tests, fixes failures, creates missing tests | | code-simplifier | opus | no | Clarity, DRY, patterns | | functional-validator | sonnet | yes | Validates UI with Playwright (auto-triggered on .tsx/.css changes) | | terraform-validator | sonnet | yes | Validates env vars and Terraform consistency | | memory-sync | haiku | no | Syncs knowledge to MCP Memory |

Philosophy

The configuration enforces autonomous development:

| Principle | Meaning | |-----------|---------| | FAZER, nao perguntar | Agents fix issues automatically, don't ask for confirmation | | BUSCAR, nao pedir contexto | Use MCP Memory and codebase exploration, don't ask user for context | | Codigo sem teste = PR rejeitado | Tests are mandatory (blocking) | | Erros: corrigir e continuar | Fix errors automatically, don't stop workflow |

After Installation

1. Create Project CLAUDE.md (Optional but Recommended)

Create a CLAUDE.md in your project root with project-specific info:

# Project Name

## Commands
- `npm run dev` - Start dev server
- `npm run build` - Build
- `npm run test` - Run tests

## Structure
- `src/` - Source code
- `tests/` - Tests

## MCP Memory Namespace
Prefix: `myproject:`

2. Add Custom Skills (Optional)

Create .claude/commands/your-skill.md for project-specific workflows.

Workflow Examples

Problem Exploration (/think)

User: "/think o sistema de notificacoes ta confuso"
         |
Claude triggers /think
         |
Sequential Thinking + Socratic questioning (1 question at a time)
Anti-anchoring checkpoint after 3rd response
Convergence when hypothesis survives 3+ tests
         |
Saves Problem Brief to .claude/explorations/

Solution Design (/deliberate)

User: "/deliberate como resolver o problema de cache"
         |
Claude triggers /deliberate
         |
Move 1: Challenge the frame (hidden assumptions)
Move 2: Simulate 5+ scenarios as temporal narratives (Dia 1 -> Mes 6)
Move 3: Pre-mortem + collaborative refinement
         |
Saves deliberation with /build command ready

Feature Development (/build)

User: "adiciona filtro de data na listagem"
         |
Claude automatically triggers /build
         |
build-understand -> Aligns on WHAT to build (user approval gate)
build-verify     -> Designs QA-style human-action test scripts (user approval gate)
build-implement  -> Autonomous implementation until verify.sh passes
build-certify    -> Quality agents + deploy + production verification
         |
Done

Bug Resolution (/resolve)

User: "erro ao salvar formulario"
         |
Claude automatically triggers /resolve
         |
resolve-investigate -> Diagnoses root cause + QA reproduction flows
resolve-fix         -> Autonomous fix + local QA verification
resolve-certify     -> Quality agents + deploy + production QA
         |
Done (trivial bugs skip directly from investigate)

Requirements

• Claude Code CLI
• MCP Memory server (optional, for knowledge persistence)
• Playwright MCP (optional, for functional validation)
• Sequential Thinking MCP (optional, for /think and /deliberate)
• Context7 MCP (optional, for library documentation)

Development

Releasing a New Version

This project uses ~/.claude/ as the source of truth. To publish changes:

npm run release

This command will:

1. Sync files from ~/.claude/ to config/ (excluding personal files like audit-command/)
2. Bump the patch version automatically
3. Create a git commit and push
4. Publish to npm

Files synced:

• CLAUDE.md, ARCHITECTURE.md
• skills/ (build, resolve, think, deliberate workflows)
• commands/ (gate)
• agents/ (all subagents)
• templates/ (if present)

Files excluded:

• audit-command/ (personal)
• Session data (plans/, specs/, interviews/, etc.)

License

MIT