You lead. Agents hunt. A cognitive + methodological harness for multi-week AI-assisted software development.
146 skills. 7 companion packs. Composition layer. SessionStart activation. Cross-tool across Claude Code, Cursor, Codex CLI, and Gemini CLI. Methodology wraps craft — you keep the decision seat, agents carry the execution.
Important
Matilha is not a theoretical framework. The methodology was distilled from shipping Gravicode, CNH Pass, Sinapise, Speechia, and Argos — real projects where AI agents are the primary execution surface and discipline decides whether a multi-week build ships on time.
USER PROMPT (any software-construction intent)
│
▼
┌─────────────────────────────┐
│ 1. DETECT │ SessionStart hook injects
│ matilha priority active │ activation priority at session start
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ 2. ROUTE │ matilha-compose classifies intent
│ phase OR creative │ → phase skill (scout/plan/design/...)
└─────────────────────────────┘ OR → superpowers:brainstorming
│ with pack-aware preamble
▼
┌─────────────────────────────┐
│ 3. ENRICH │ Companion packs (ux / growth /
│ domain expertise woven │ harness / sysdesign / sweng /
└─────────────────────────────┘ swarch / swsec) surface skills by
│ name during exploration.
▼
┌─────────────────────────────┐
│ 4. EXECUTE │ Superpowers handles craft
│ you lead, agents hunt │ (brainstorming, writing-plans, TDD).
└─────────────────────────────┘ Matilha tracks phase + state.
🏠 Official entry point. This is the canonical repository for the matilha ecosystem. The 7 companion packs + CLI are satellites — this hub has the install guide, docs, and rules.
| 🐺 Methodology always on | Every software-construction prompt routes through matilha first — phase awareness, state tracking, lazy bootstrap. No matilha-init required. |
| 📚 139 curated skills | 22 UX (Weinschenk/Krug) + 20 growth (AARRR/JTBD) + 22 agent-harness (Anthropic/OpenAI) + 19 system design (Tan) + 15 engineering discipline + 17 architecture + 13 AI-ops security. |
| 🎭 Storytelling activation | When matilha fires, you see an atmospheric sigil mirroring your domain language — "The pack sensed familiar territory: Lambda / EventBridge / DynamoDB". Recognition aha moment, then brainstorming runs enriched. The sigil adapts to your language — Portuguese, English, or whichever vocabulary you use in the prompt. |
There are three paths. Pick the one that fits you.
1. Install the CLI and run the interactive picker:
npm install -g matilha
matilha install-pluginsThe picker asks which packs you want (presets or custom multiselect), whether to write CLAUDE.md, and copies the install block to clipboard — or add --deep to skip the paste entirely:
matilha install-plugins --deepInstall everything non-interactively (core + all 7 packs + CLAUDE.md):
matilha install-plugins --full --deep --with-claudemd2. Open Claude Code and run:
/reload-plugins
Done. Type any software prompt and the sigil appears.
1. Install the core plugin:
/plugin marketplace add danilods/matilha-skills
/plugin install matilha@matilha-skills --user
2. In any Claude Code session, run the install wizard:
/matilha-install
The wizard asks which packs you want, then runs claude plugin install for each one automatically. At the end it offers to write the CLAUDE.md activation snippet.
Why two steps? The Claude Code marketplace has no dependency system — installing
matilha-skillsdoes not auto-install the companion packs. The wizard is the zero-npm solution to close that gap.
If you prefer full control, paste the commands one by one inside Claude Code:
/plugin marketplace add danilods/matilha-skills
/plugin install matilha@matilha-skills --user
/plugin marketplace add danilods/matilha-ux-pack
/plugin install matilha-ux-pack@matilha-ux-pack --user
/plugin marketplace add danilods/matilha-growth-pack
/plugin install matilha-growth-pack@matilha-growth-pack --user
/plugin marketplace add danilods/matilha-harness-pack
/plugin install matilha-harness-pack@matilha-harness-pack --user
/plugin marketplace add danilods/matilha-sysdesign-pack
/plugin install matilha-sysdesign-pack@matilha-sysdesign-pack --user
/plugin marketplace add danilods/matilha-software-eng-pack
/plugin install matilha-software-eng-pack@matilha-software-eng-pack --user
/plugin marketplace add danilods/matilha-software-arch-pack
/plugin install matilha-software-arch-pack@matilha-software-arch-pack --user
/plugin marketplace add danilods/matilha-security-pack
/plugin install matilha-security-pack@matilha-security-pack --user
Verify with /plugin list → all 8 should be enabled at user scope.
Matilha uses an activation-priority rule in CLAUDE.md to win routing over other skills. Without it the sigil still appears, but on long sessions compose may lose activation against competing skills.
- Path A writes it automatically (
--with-claudemd). - Paths B and C: in any Claude Code session inside your project, run
/matilha-installand choose "Apply CLAUDE.md snippet".
npm install -g matilha@latest
matilha --versionRe-running the install is idempotent — claude plugin install upgrades to latest if a newer version is available:
matilha install-plugins --full --deepOr inside Claude Code:
/matilha-install
Choose your packs → "Run it now" → plugins update in place. Then /reload-plugins.
npm uninstall -g matilhaclaude plugin uninstall matilha --scope user
claude plugin uninstall matilha-ux-pack --scope user
claude plugin uninstall matilha-growth-pack --scope user
claude plugin uninstall matilha-harness-pack --scope user
claude plugin uninstall matilha-sysdesign-pack --scope user
claude plugin uninstall matilha-software-eng-pack --scope user
claude plugin uninstall matilha-software-arch-pack --scope user
claude plugin uninstall matilha-security-pack --scope userThen open a new Claude Code session — the plugins will no longer activate.
Optional: remove the CLAUDE.md snippet matilha wrote. Look for the block between <!-- matilha-start v1 --> and <!-- matilha-end v1 --> and delete it.
You:
"How do I scale my system to 10k QPS with P99 under 100ms?"
matilha (emits sigil + atmospheric preamble):
The pack sensed familiar territory: scaling a distributed system
with hard latency targets.
matilha-sysdesign-pack at your side → sysdesign-scalability-horizontal-vs-vertical,
sysdesign-load-balancers, sysdesign-latency-targets-techniques,
sysdesign-consistency-cap, sysdesign-monitoring-4-golden-signals.
Brainstorming ahead. Skills enter as topics surface.
Then brainstorming runs enriched, weaving sysdesign-* skills naturally.
You:
"Frontend calling OpenAI directly with the API key in .env — is that ok?"
matilha (emits sigil):
The pack sensed familiar territory: API-key exposure
in a client-side environment.
matilha-security-pack at your side → swsec-secrets-never-in-frontend,
swsec-secrets-manager-discipline, swsec-backend-authorization-layer,
swsec-llm-cost-as-availability.
Brainstorming ahead.
You:
"How do I structure a chain of AWS Lambdas without turning it into spaghetti?"
matilha:
The pack sensed familiar territory: Lambda chain
with domain discipline.
matilha-software-arch-pack at your side → swarch-lambda-chain-shape,
swarch-handler-as-adapter, swarch-dependency-direction,
swarch-fact-vs-command-events.
Brainstorming ahead.
The atmospheric line mirrors your vocabulary — proof the tool read your prompt. Recognition aha moment, then methodology + pack expertise wrap the exploration. The sigil text adapts to your prompt language — examples above are English, but Portuguese/Spanish/any-language prompts get mirrored in kind.
Multi-week AI-assisted software projects fail in predictable ways:
- Context is lost between sessions → you re-explain your architecture every week
- Methodology erodes under pressure → shortcuts become defaults, discipline decays
- Companion knowledge stays in books → Weinschenk's UX principles, Tan's NFRs, Anthropic's agent patterns — on your shelf, not in your flow
matilha fixes this at the harness layer, not the prompt layer:
- SessionStart hook — methodology priority injected into every session; no per-project setup
- Composition detection — companion packs surfaced by plugin-namespace pattern; zero hardcoded state
- Lazy bootstrap — phase skills create
docs/matilha/on demand; nomatilha-initrequired - Sigil storytelling — recognition aha moment prevents the "generic LLM slop" feeling
You lead. Agents hunt. Matilha keeps the decision seat where it belongs (you). Agents carry execution: parallel worktrees, per-SP focus, gated output, companion-pack enrichment.
Matilha is not a theoretical framework. It was distilled from building and operating large-scale software projects under agentic-coding workflows — where AI agents are not a gimmick but the primary execution surface, and methodology is what keeps multi-week projects coherent.
Projects that shaped matilha's decisions, architectural patterns, and opinionated rules:
| Project | Domain | What it taught matilha |
|---|---|---|
| Gravicode | AI mentor ecosystem — agent viewer, knowledge graph 3D, dual-brain architecture | Pack composition, context engineering at scale, how agent-centric codebases evolve |
| CNH Pass | Driver's license preparation platform (Brazilian public-exam adjacent) | Large content pipelines, LGPD operational basics, frontend-as-consumer trust boundary |
| Sinapise | Intelligent content orchestration for education | Event-driven architectures across bounded contexts, dual-store (Postgres + DynamoDB) patterns |
| Speechia | Voice + language AI platform | LLM cost-as-availability discipline, prompt-injection defense, output sanitization in production |
| Argos | Content-intelligence platform for Brazilian public-exam preparation | GSI-based scheduling (Ticker pattern), Lambda Chain + Event Gateway, escalabilidade sem prematuridade |
Many of the Caminho C packs (software-eng, software-arch, security) are direct distillations of rules that survived contact with these projects — commits we wish we'd made, bugs we shipped, architectural decisions we had to unwind. The literature packs (ux, growth, harness, sysdesign) were then chosen because they answered questions these projects kept raising.
matilha = methodology documented by someone who ships agentic AI software at scale, not someone who reads about it.
| Pattern | Wave | What it enables |
|---|---|---|
| Twin Identity | 4a | Matilha ships as both npm CLI and Claude Code plugin. Same methodology source, two surfaces. CLI for CI/determinism; plugin for composition/interactive. |
| Plugin-namespace detection | 5d | Packs detected dynamically via matilha-*-pack pattern. New packs picked up automatically — no hardcoded list, self-healing. |
| SessionStart hook | 5d.1 | Auto-activation in any workspace where matilha is user-scope installed. No per-project config. |
| Lazy bootstrap | 5d.1 | Phase skills (matilha-plan, matilha-scout, matilha-howl) create docs/matilha/ structure on first write. |
| Sigil storytelling | 5d.1 | Compose emits atmospheric ASCII preamble mirroring user vocabulary. Recognition → aha → anticipation. |
| 2-layer Caminho C distillation | 5f | Opinions-from-practice packs (software-eng, software-arch, security) preserve author voice without wiki-paraphrase layer. |
1540 validator tests passing. Zero regressions across Waves 3a → v1.3.0. Paraphrase discipline enforced (3-layer for literature packs, 2-layer for Caminho C). Each pack declares what it does NOT cover — honest scope framing.
| Repository | Role |
|---|---|
| danilods/matilha-skills (this repo) | 🏠 Official hub — core plugin + docs + rules + install guide |
| danilods/matilha | npm CLI (deterministic twin) — npm install -g matilha |
| danilods/matilha-ux-pack | 22 UX + cognitive skills |
| danilods/matilha-growth-pack | 20 growth + product strategy skills |
| danilods/matilha-harness-pack | 22 agent-harness skills (Anthropic + OpenAI + Lopopolo) |
| danilods/matilha-sysdesign-pack | 19 distributed systems skills (Zhiyong Tan) |
| danilods/matilha-software-eng-pack | 15 engineering discipline skills (Caminho C) |
| danilods/matilha-software-arch-pack | 17 software architecture skills (Caminho C) |
| danilods/matilha-security-pack | 13 AI-ops security skills (Caminho C) |
| Pack | Skills | What it covers | Source type |
|---|---|---|---|
| ux-pack | 22 | Visual/cognitive design — attention, memory, error tolerance, trust, Weinschenk + Krug | Literature |
| growth-pack | 20 | Growth + product strategy — AARRR, JTBD, positioning, pricing, retention | Literature |
| harness-pack | 22 | Agent architecture — Planner/Generator/Evaluator, context engineering, agentic patterns, evals | Literature |
| sysdesign-pack | 19 | Distributed systems — NFRs, CAP, Kafka, CDN, rate limiting, 11 design cases | Literature |
| software-eng-pack | 15 | Day-to-day engineering — KISS, RORO, commits, docs, task tracking, critical analysis | Caminho C |
| software-arch-pack | 17 | Software architecture — layering, Lambda chains, event-driven, dual-store, bounded contexts | Caminho C |
| security-pack | 13 | AI-ops security baseline — keys, LLM risks (prompt injection, cost), LGPD | Caminho C |
Literature packs synthesize published books/articles with 3-layer paraphrase discipline (source → wiki → skill). Caminho C packs distill author experience with 2-layer preservation of voice.
Plus 11 core methodology skills in this hub (init, scout, plan, hunt, gather, howl, review, den, pack, design, compose) and 7 trigger skills (one per pack domain — independent activation surface).
matilha stands on shoulders. Direct influences:
- Andrej Karpathy's LLM-OS vision — the idea that LLMs become operating systems needing methodology around them, not just prompts
- Anthropic's Harness Engineering (Prithvi Rajasekaran et al.) — Planner/Generator/Evaluator architecture for long-running agent tasks
- Anthropic's Building Effective Agents — agentic patterns (workflow vs agent, orchestrator-workers, routing, evaluator-optimizer)
- Anthropic's Context Engineering — context rot budget, JIT retrieval, long-horizon strategies
- OpenAI Codex "Agent-Centric World" blog — how codebases evolve when agents become primary readers
- Ryan Lopopolo's Harness Engineering talk (AI Engineer London 2026) — "code is free" axiom + NFRs as prompts
- Zhiyong Tan — Acing the System Design Interview — NFR framework + 11 practical design cases
- Susan Weinschenk — 100 Things Every Designer Needs to Know About People — cognitive psych for UX
- Steve Krug — Don't Make Me Think — laws of usability + reservatório de boa vontade
- Nir Eyal — Hook model — behavioral design patterns for retention
Plus opinions-from-practice on Argos (content-intelligence platform) + Gravicode (AI mentor ecosystem).
- companions-contract.md — the detection + delegation contract for companion packs
- skill-authoring-guide.md — frontmatter schema + 13-section body structure + paraphrase discipline
- naming-conventions.md — reserved skill prefixes + pack naming
- pack-authors.md — how to ship your own companion pack in ~10 hours
- platform-tool-mapping.md — Claude Code ↔ Cursor ↔ Codex ↔ Gemini tool equivalents
- docs/rules/ — 9 curated methodology rules (5 architecture + 4 security) from Caminho C packs
- docs/matilha/smoke-results/ — runtime smoke verification for major waves
- Core plugin — 11 methodology skills + composition layer + SessionStart hook + 1466 validator tests
- 7 companion packs — 128 domain skills across ux, growth, harness, sysdesign, software-eng, software-arch, security
- B packs — user-driven domain additions
sec-*formal security pack — STRIDE + OWASP + Adam Shostack threat modeling, complementing the AI-ops swsec-* baseline (requires wiki ingestion)- Wave 3c
matilha-reviewruntime — 6-agent parallel quality review - Marketplace submission — official Claude Code plugin marketplace
- Community-pack template — author onboarding materials
Bug reports + feature requests via issues.
Pack authors — see pack-authors.md. Community packs can use any <author>-* prefix per naming-conventions.md; reserved prefixes (matilha-*, ux-*, cog-*, growth-*, harness-*, sysdesign-*, sweng-*, swarch-*, swsec-*) are for the official pack ecosystem.
Methodology contributions — the methodology/ directory is the source of record for phases 0–70. Amendments welcome via PR with rationale.
MIT — see LICENSE. Fork it, extend it, disagree with it. The alpha is yours.
You lead. Agents hunt. 🐺
Install · Examples · Architecture · Ecosystem · Deep docs