Skip to main content
recursive-mode is installed in two steps: add the skill package to your agent environment, then bootstrap the target repository with the scaffold. Bootstrapping happens automatically the first time you invoke recursive-mode.

​
Prerequisites

Before installing, confirm you have:
  • A git repository to bootstrap
  • The skills CLI available (npx skills)
  • Python 3, PowerShell (pwsh), or Bash — depending on which bootstrap script you use
  • An agent environment that supports the skills CLI

​
Install options

The skills CLI is the preferred way to install and manage recursive-mode in your agent environment.Install the main skill
npx skills add try-works/recursive-mode
List everything in the package
npx skills add try-works/recursive-mode --list
Add --full-depth to list nested subskills as well:
npx skills add try-works/recursive-mode --list --full-depth
Install all included skills
npx skills add try-works/recursive-mode --skill '*' --full-depth
Install a single subskillTo install only one subskill instead of the full package, pass its name with --skill:
npx skills add try-works/recursive-mode --skill recursive-tdd --full-depth
Replace recursive-tdd with any of the available subskills: recursive-worktree, recursive-debugging, recursive-review-bundle, or recursive-subagent.

​
What gets installed

Running the bootstrap script creates the following layout in your repository: 
/.recursive/
├── RECURSIVE.md          # Canonical workflow spec
├── STATE.md              # Current repository state
├── DECISIONS.md          # Decisions ledger
├── run/                  # Run artifact directory
│   └── .gitkeep
└── memory/
    ├── MEMORY.md         # Durable memory router
    ├── domains/          # Stable functional-area knowledge
    ├── patterns/         # Reusable playbooks and solution patterns
    ├── incidents/        # Recurring failure signatures and fixes
    ├── episodes/         # Distilled lessons from specific runs
    ├── archive/          # Historical or deprecated memory docs
    └── skills/
        ├── SKILLS.md     # Skill memory router
        ├── availability/ # Environment-specific skill availability notes
        ├── usage/        # Stable usage guidance per skill
        ├── issues/       # Recurring skill failures and limitations
        └── patterns/     # Reusable multi-skill operating patterns

​
Key files

FilePurpose
/.recursive/RECURSIVE.mdThe canonical workflow contract. Your agent reads this to understand phase order, audit rules, lock rules, and memory maintenance.
/.recursive/STATE.mdTracks current repository state. Updated during closeout phases.
/.recursive/DECISIONS.mdLedger of decisions made across runs.
/.recursive/memory/MEMORY.mdMemory router. Agents read this before loading any memory docs.
/.recursive/run/Each run gets a subdirectory here: /.recursive/run/<run-id>/.

​
The memory router

The memory layer under /.recursive/memory/ stores durable project knowledge — domain context, reusable patterns, recurring incidents, and skill guidance — separately from current repository state and individual run artifacts. This separation lets the workflow distinguish between what is true right now, what happened in one run, and what has been learned across many runs. Agents load only the memory docs relevant to the current task rather than reading the full memory tree on every run.

​
Subskills included

The package ships these installable subskills alongside the root recursive-mode skill:
SubskillPurpose
recursive-worktreeIsolates implementation work in a dedicated git worktree
recursive-tddStrict or pragmatic TDD with recorded RED/GREEN evidence
recursive-debuggingStructured debugging with durable artifact capture
recursive-review-bundlePackages delegated reviews into canonical review bundles
recursive-subagentRecords and verifies subagent contributions before acceptance
Install the full set with --skill '*' --full-depth, or install individual subskills by name.