try-works/role-model / .agents/skills/recursive-mode
recursive-mode
UnverifiedRepository workflow orchestration skill for staged implementation, locked artifacts, late-phase receipts, and durable memory maintenance. Use when executing recursive-mode runs, resuming a run, locking a phase, or verifying locks.
.recursive/README.md
View on GitHub# recursive-mode Maintainer Notes
This file is for maintainers of the `recursive-mode` repository itself.
It is not the canonical workflow spec. The canonical workflow remains:
- `/.recursive/RECURSIVE.md`
It is also not the public package landing page. The GitHub-facing overview remains:
- `/README.md`
Use this file for maintainer-oriented commands, smoke-harness notes, and repo-internal packaging guidance.
If you just need a lightweight routing/index doc for what to read under `/.recursive/`, start with:
- `/.recursive/AGENTS.md`
## Package Surface
Installable entrypoints:
- `/SKILL.md`
- `/skills/recursive-spec/SKILL.md`
- `/skills/recursive-worktree/SKILL.md`
- `/skills/recursive-debugging/SKILL.md`
- `/skills/recursive-tdd/SKILL.md`
- `/skills/recursive-review-bundle/SKILL.md`
- `/skills/recursive-router/SKILL.md`
- `/skills/recursive-subagent/SKILL.md`
- `/skills/recursive-training/SKILL.md`
Optional add-on source doc:
- `/references/benchmark-addon/recursive-benchmark/BENCHMARK-ADDON.md`
## Bootstrap Layout
The installer bootstraps the canonical layout in a target repo:
```text
.recursive/
AGENTS.md
RECURSIVE.md
STATE.md
DECISIONS.md
config/
recursive-router.json
memory/
MEMORY.md
domains/
patterns/
incidents/
episodes/
training/
skills/
SKILLS.md
availability/
usage/
skill-discovery-and-evaluation.md
issues/
patterns/
delegated-verification-and-refresh.md
phase8-skill-memory-promotion.md
archive/
scripts/
recursive-training-*.py / *.ps1
run/
<run-id>/
.codex/AGENTS.md
.agent/PLANS.md
/AGENTS.md (optional mirror only)
```
- `/.recursive/AGENTS.md` is a lightweight internal router/index
- `/.recursive/RECURSIVE.md` remains the only workflow source of truth
- `/.recursive/memory/training/` stores extracted experiential learnings from completed runs, indexed through `/.recursive/memory/MEMORY.md`
- `/.recursive/scripts/` holds the bootstrapped runtime copies of the training scripts used by the installed scaffold
- `/.recursive/config/recursive-router.json` is the canonical user-editable routed delegation policy; when an agent updates it, use the router configure-and-verify path instead of saving unchecked bindings
- `/.recursive/config/recursive-router-discovered.json` is generated locally after router probe or verification, should stay gitignored in target repos, and is not part of the bootstrapped scaffold
- `references/bootstrap/RECURSIVE.md` is the packaged non-hidden bootstrap copy that installers use from installed skill directories; keep it byte-for-byte aligned with `/.recursive/RECURSIVE.md`
## Main Maintainer Commands
Bootstrap a target repo:
```bash
python "<SKILL_DIR>/scripts/install-recursive-mode.py" --repo-root .
bash "<SKILL_DIR>/scripts/install-recursive-mode.sh" --repo-root .
pwsh -NoProfile -File "<SKILL_DIR>/scripts/install-recursive-mode.ps1" -RepoRoot .
```
Notes:
- Python and Bash are the primary cross-platform bootstrap paths.
- PowerShell is optional and mainly relevant on Windows.
Scaffold a run:
```bash
python "<SKILL_DIR>/scripts/recursive-init.py" --repo-root . --run-id "<run-id>" --template feature
pwsh -NoProfile -File "<SKILL_DIR>/scripts/recursive-init.ps1" -RepoRoot . -RunId "<run-id>" -Template feature
```
Check status:
```bash
python "<SKILL_DIR>/scripts/recursive-status.py" --repo-root . --run-id "<run-id>"
pwsh -NoProfile -File "<SKILL_DIR>/scripts/recursive-status.ps1" -RepoRoot . -RunId "<run-id>"
```
Lint a run:
```bash
python "<SKILL_DIR>/scripts/lint-recursive-run.py" --repo-root . --run-id "<run-id>" --strict
pwsh -NoProfile -File "<SKILL_DIR>/scripts/lint-recursive-run.ps1" -RepoRoot . -RunId "<run-id>"
```
Generate a delegated review bundle:
```bash
python "<SKILL_DIR>/scripts/recursive-review-bundle.py" --repo-root . --run-id "<run-id>" --phase "03.5 Code Review" --role code-reviewer --artifact-path "/.recursive/run/<run-id>/03.5-code-review.md" --upstream-artifact "/.recursive/run/<run-id>/00-requirements.md" --upstream-artifact "/.recursive/run/<run-id>/02-to-be-plan.md" --audit-question "Which R# remain incomplete?" --required-output "Findings ordered by severity"
```
Scaffold a late-phase closeout artifact:
```bash
python "<SKILL_DIR>/scripts/recursive-closeout.py" --repo-root . --run-id "<run-id>" --phase 04
pwsh -NoProfile -File "<SKILL_DIR>/scripts/recursive-closeout.ps1" -RepoRoot . -RunId "<run-id>" -Phase 04
```
Lock an artifact:
```bash
python "<SKILL_DIR>/scripts/recursive-lock.py" --repo-root . --run-id "<run-id>" --artifact "<artifact>.md"
pwsh -NoProfile -File "<SKILL_DIR>/scripts/recursive-lock.ps1" -RepoRoot . -RunId "<run-id>" -Artifact "<artifact>.md"
```
Check reusable-repo hygiene:
```bash
python "<SKILL_DIR>/scripts/check-reusable-repo-hygiene.py" --repo-root .
pwsh -NoProfile -File "<SKILL_DIR>/scripts/check-reusable-repo-hygiene.ps1" -RepoRoot .
```
Validate the installed package surface from the current repo checkout:
```bash
npx skills add "<repo-root>" --skill '*' --full-depth --yes
python ".agents/skills/recursive-mode/scripts/install-recursive-mode.py" --repo-root .
```
That path should install the current recursive-mode package, include `recursive-training`, exclude `recursive-benchmark`, and let the installed bootstrap create the training-aware scaffold (`/.recursive/memory/training/`, `/.recursive/scripts/recursive-training-*`, and the stable memory pointer files).
Run the paired benchmark harness:
The benchmark add-on is intentionally not part of the default exported recursive-mode package surface; use it only when benchmarking is explicitly requested.
```bash
python "<SKILL_DIR>/scripts/run-recursive-benchmark.py" --runner all --scenario local-first-planner
python "<SKILL_DIR>/scripts/run-recursive-benchmark.py" --runner kimi --scenario team-capacity-board --arm-mode parallel
python "<SKILL_DIR>/scripts/run-recursive-benchmark.py" --runner opencode --opencode-model opencode/gpt-5-nano --scenario team-capacity-board
pwsh -NoProfile -File "<SKILL_DIR>/scripts/run-recursive-benchmark.ps1" -Runner all -Scenario local-first-planner
```
## Maintainer Smoke Harness
Run the explicit module regression command first; plain `python -m unittest` does not discover this repo's tests:
```bash
python -m unittest scripts.test_install_recursive_mode scripts.test_lint_recursive_run scripts.test_recursive_phase_rules scripts.test_recursive_review_bundle scripts.test_recursive_router scripts.test_recursive_subagent_action scripts.test_recursive_training scripts.test_run_recursive_benchmark
```
Run disposable regression coverage when changing this repo itself:
```bash
python "<SKILL_DIR>/scripts/test-recursive-mode-smoke.py" --scenario quick --toolchain mixed
python "<SKILL_DIR>/scripts/test-recursive-mode-smoke.py" --scenario full --toolchain python --keep-temp
python "<SKILL_DIR>/scripts/test-recursive-mode-smoke.py" --scenario subagent --toolchain mixed
pwsh -NoProfile -File "<SKILL_DIR>/scripts/test-recursive-mode-smoke.ps1" -Scenario quick -Toolchain mixed
pwsh -NoProfile -File "<SKILL_DIR>/scripts/test-recursive-mode-smoke.ps1" -Scenario subagent -Toolchain mixed
```
Notes:
- the harness uses disposable repos only
- `--toolchain python` must work without PowerShell
- `mixed` should skip PowerShell clearly when unavailable
- full mode exercises negative regressions as well as the positive path
- benchmark harness output should stay in temp or disposable workspaces, not committed repo paths
## Delegation And Review
- prefer `recursive-review-bundle` for delegated Phase 3.5 review
- record `Review Bundle Path`
- use `recursive-subagent-action` for durable delegated work records
- verify delegated claims against actual files, diffs, bundles, and recursive artifacts before acceptance
## Reusable-Repo Boundary
When improving this repository itself:
- do not commit concrete `/.recursive/run/<run-id>/` folders
- do not commit run-local evidence logs, review bundles, or subagent action records
- do not commit temp-directory residue
- do not update `STATE.md` or `DECISIONS.md` with current-session implementation history
- keep only reusable product changes in the final diff
Run the hygiene checker before treating the repo as clean.
For final handoff of this repo itself, prefer the strict form:
```bash
python "<SKILL_DIR>/scripts/check-reusable-repo-hygiene.py" --repo-root . --require-clean-git
pwsh -NoProfile -File "<SKILL_DIR>/scripts/check-reusable-repo-hygiene.ps1" -RepoRoot . -RequireCleanGit
```
That final check should pass only when there is no run contamination, no generated local residue, and no dirty worktree state left to hand off.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |