matilha

v1.6.0

Published

a month ago

You lead. Agents hunt. Methodology harness CLI — deterministic engine for guided AI-assisted software development. Twin to the matilha-skills plugin ecosystem (7 companion packs, 146 skills total).

matilha — CLI

You lead. Agents hunt. Methodology harness CLI for AI-assisted software development.

🏠 This is the CLI twin. The official matilha entry point is danilods/matilha-skills — the Claude Code plugin ecosystem with 146 skills across 7 companion packs. This CLI is the low-friction installer and deterministic engine for power-user workflows, CI, and automation.

Fastest Start

For Claude Code users, this is the shortest path:

npm install -g matilha
matilha install --full --deep --with-claudemd

Then in Claude Code:

/reload-plugins

Open a new Claude Code prompt and start working normally. For software work, matilha-compose should route first, then hand off to the right Matilha phase or companion skill.

That installs:

matilha core methodology plugin
all 7 companion packs
the CLAUDE.md activation-priority snippet for reliable routing

If the claude CLI is not available on your PATH, Matilha automatically falls back to a paste block you can copy into Claude Code.

Codex And Cursor

Matilha can also install the same core skills and packs without Claude Code.

Codex

Install globally for Codex:

npm install -g matilha@latest
matilha install --target codex --full --scope user

This writes skills to:

~/.agents/skills/

Restart Codex or open a new session so the skill list refreshes.

For a single project instead of global/user install:

matilha install --target codex --full --scope project

That writes to:

.agents/skills/

Cursor

Run from the project root:

npm install -g matilha@latest
matilha install --target cursor --full

This writes:

.cursor/skills/
.cursor/rules/matilha.mdc

Open a new Cursor Agent chat so the rule and skills refresh.

Pick Packs For Codex Or Cursor

Use the same picker, just change the target:

matilha install --target codex
matilha install --target cursor

For Codex/Cursor, no --deep flag is needed: Matilha installs local skill files directly. --deep is only for Claude Code because it shells out to claude plugin install.

What Gets Installed

Matilha has two layers:

| Layer | Installed by | What it does | |---|---|---| | npm CLI | npm install -g matilha | Gives you the matilha command: start, status, discover, spec, approve, split, merge, install/update packs | | Claude Code plugins | matilha install --deep | Installs matilha-skills and companion packs inside Claude Code | | Codex local skills | matilha install --target codex | Installs skills into ~/.agents/skills or .agents/skills | | Cursor project skills | matilha install --target cursor | Installs skills into .cursor/skills and writes .cursor/rules/matilha.mdc |

Important: updating the npm CLI does not automatically update Claude Code plugins. To update both, run:

npm install -g matilha@latest
matilha install --full --deep --with-claudemd

Then reload Claude Code plugins:

/reload-plugins

Choose Packs

Interactive — pick your packs

matilha install --deep

Launches a guided picker:

Choose a preset or Custom to select packs individually.
Confirm whether to write the CLAUDE.md activation snippet.
Installs directly through claude plugin install.

Presets available: backend · ux · fullstack · security · core-only · custom

If you prefer not to run the Claude CLI, omit --deep:

matilha install

Matilha prints and copies a /plugin marketplace add + /plugin install block for you to paste into Claude Code.

Non-interactive — install everything in one shot

matilha install --full --deep --with-claudemd

What --full --deep --with-claudemd does:

Adds danilods/matilha-skills to the Claude Code marketplace
Runs claude plugin install for each of the 8 plugins (core + 7 packs)
Writes the activation-priority snippet to ./CLAUDE.md

Then in Claude Code: /reload-plugins → done.

Preset examples

matilha install --core-only --deep
matilha install --preset backend --deep --with-claudemd
matilha install --preset ux --deep --with-claudemd
matilha install --preset fullstack --deep --with-claudemd
matilha install --preset security --deep --with-claudemd

All flags

| Flag | Effect | |---|---| | (no flags) | Interactive picker — preset or custom multiselect | | --full | Non-interactive: core + all 7 companion packs | | --core-only | Non-interactive: core plugin only | | --preset <name> | Non-interactive: backend · ux · fullstack · security | | --deep | Run claude plugin install directly instead of emitting a paste block (requires claude CLI on PATH) | | --target <name> | claude (default) · codex · cursor | | --scope <name> | For Codex/Cursor local installs: user or project | | --with-claudemd | Also write/merge the CLAUDE.md activation-priority snippet | | --no-clipboard | Print paste block to stdout instead of copying to clipboard |

Commands

matilha --help

Matilha is state-guided. Commands remain scriptable, but interactive runs show a compact next-step recommendation so you do not have to remember the whole workflow.

matilha status
matilha status --no-guide
matilha --guide status

| Command | Phase | Description | |---|---|---| | install | — | Install Matilha skills and optional companion packs | | start | — | Start or refresh Matilha control files | | status | 0 | Show current project phase + next action | | discover | 00→10 | Map the problem space before planning or coding | | spec <slug> | 10→30 | Create or continue a feature spec + implementation plan | | approve [gate] | any | Validate and approve a phase gate | | progress | any | Show feature artifacts + gate state | | split <slug> | 40 | Split a plan into parallel worktree tasks | | merge <slug> | 40 | Merge completed worktree tasks, run regression, and clean worktrees by default | | jira init | optional | Install the local Jira skill + example JSON contract | | jira validate/preview/apply | optional | Validate, review, then apply Jira task contracts | | jira sync | optional | Sync Matilha completion events to Jira after preview + approval | | list | — | List skills in the matilha registry | | pull <slug> | — | Pull a skill or resource from the registry |

Legacy aliases still work: install-plugins, init, howl, scout, plan, attest, plan-status, hunt, and gather.

Context Control

matilha start keeps provider control files intentionally small.

Instead of growing CLAUDE.md, AGENTS.md, or .cursor/rules/matilha.mdc with full methodology text, Matilha writes compact pointers and creates:

docs/matilha/context.md

Clean-session restore order:

Read project-status.md
Read docs/matilha/context.md
Open only the relevant spec, plan, wave, or skill files for the current task

This keeps Claude Code, Codex, Cursor, and other agent CLIs under their control-file limits while preserving durable context across fresh sessions.

Worktree Hygiene

matilha split <slug> creates one worktree per parallel SP. After a successful wave, matilha merge <slug> now removes completed SP worktrees and deletes merged SP branches by default.

Use this only when you want to inspect the worktrees after merge:

matilha merge <slug> --keep-worktrees

Optional Jira Flow

Jira automation is optional and contract-first. The agent turns Matilha specs, plans, waves, and SPs into a generic work item JSON contract; the CLI validates, previews, and only mutates Jira after explicit approval.

Bootstrap the local skill and example contract:

matilha jira init

This writes:

.agents/skills/matilha-jira/SKILL.md
docs/matilha/jira/tasks.example.json
docs/matilha/jira/tutorial.md

Read the tutorial first when wiring this into a real sprint:

cat docs/matilha/jira/tutorial.md

Recommended flow:

matilha jira validate docs/matilha/jira/tasks.json
matilha jira preview docs/matilha/jira/tasks.json
matilha jira apply docs/matilha/jira/tasks.json --yes

From spec/plan to tasks:

Read project-status.md plus the accepted spec and plan for <feature>.
Create docs/matilha/jira/tasks.json using schema_version 1.
Generate one generic work item per independently executable task.
If the plan contains 100 tasks, include all 100 tasks in tasks[].
Run matilha jira validate and matilha jira preview.
Do not apply until I approve the preview.

Contract shape:

{
  "schema_version": 1,
  "project_key": "MAT",
  "defaults": {
    "issue_type": "Task",
    "labels": ["matilha", "ai-assisted"],
    "story_points_field": "customfield_10016"
  },
  "tasks": [
    {
      "external_id": "feat-auth-SP1",
      "summary": "Implement login flow",
      "description_markdown": "Build login, logout, and session validation.",
      "story_points": 0.5
    }
  ]
}

For large batches, there is no special mode: every item in tasks[] is validated, previewed, and applied. If preview shows 100 task(s) ready, matilha jira apply docs/matilha/jira/tasks.json --yes attempts to create all 100 issues, preserving each external_id as Matilha traceability metadata. For readability, large previews show the full task table and omit the converted Jira payload dump; the JSON contract remains the source of truth.

For real Jira calls, set:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="..."
export JIRA_PROJECT_KEY="MAT"
export JIRA_STORY_POINTS_FIELD="customfield_10016"

Matilha converts descriptions/comments to Jira ADF, stores external_id as an issue property, keeps source.spec/source.plan/source.sp as traceability metadata, and refuses apply unless --yes is present.

Completion Hook

After matilha merge <slug> successfully merges an SP, passes regression tests, and marks it as completed, Matilha writes a local completion event:

docs/matilha/events/outbox/*.json

That hook is local and durable. It does not call Jira by itself. To update Jira comments, worklogs, story points, and Matilha issue properties, run:

matilha jira sync --preview
matilha jira sync --yes

Synced events move to:

docs/matilha/events/processed/

To enrich a completion update, the SP can add optional tracking metadata to SP-DONE.md:

tracking:
  story_points: 0.25
  worklog: "15m"
  comment_markdown: "Implemented, tested, and merged by Matilha."
  observations:
    - "No migration rollback needed."

Use matilha merge <slug> --no-events only when you intentionally want to skip local completion-event emission.

Plugin ecosystem

The CLI is one of two install surfaces. The other is the Claude Code plugin:

| Surface | Install | Best for | |---|---|---| | npm CLI (matilha) | npm install -g matilha | CI, scripts, headless automation, power users | | Plugin (matilha-skills) | matilha install --deep or /matilha-install wizard | Interactive development inside Claude Code |

Both share the same methodology content from danilods/matilha-skills.

Contributing

Contributions are welcome, especially around CLI compatibility, skill quality, methodology docs, and real-world agent workflows.

Good first areas:

Improve installers for Codex, Cursor, Claude Code, Gemini CLI, and other AI coding CLIs.
Add or refine high-quality skills in the companion pack ecosystem.
Improve Matilha phase docs, gates, templates, and examples.
Report rough edges from real Claude Code, Codex, Cursor Agent, or multi-agent development sessions.
Propose methodology improvements inspired by practical AI software development patterns, including Karpathy-style workflows.

Before opening a PR:

npm install
npm run typecheck
npm test
npm run build

For skill and pack contributions, start in danilods/matilha-skills. For CLI installers, commands, packaging, and automation, use this repository.

Search terms: AI agents, agent skills, Claude Code, Claude skills, Codex skills, OpenAI Codex, Cursor Agent, Gemini CLI, Karpathy, prompt engineering, vibe coding, AI-assisted software development.

Update

npm install -g matilha@latest
matilha --version

To also update Claude Code plugins and packs:

matilha install --full --deep --with-claudemd