Imported from try-works/role-model (AGENTS.md). Install upstream with npx skills add try-works/role-model. Copyright stays with the author.

role-model agent instructions

These instructions apply to all work in this repository.

Git and delivery workflow

• Start ordinary feature, fix, dependency, and recursive/* work from the current origin/dev tip.
• Commit work on a non-long-lived branch and open its pull request against dev.
• Ordinary pull requests into dev normally squash merge after required checks, one maintainer approval, and resolved conversations.
• Never push directly to dev, stage, or main. Never force-push or delete those branches.
• Promote with reviewed merge-commit pull requests in order: dev -> stage, then stage -> main.
• Do not target stage or main from an ordinary branch. The only production exception is a reviewed hotfix/* -> main pull request created from main; forward the merged hotfix to stage and dev afterward.
• Treat GitHub's promotion-guard and protected-branch checks as mandatory. Do not bypass, disable, or rename required checks merely to merge.
• Keep the docs site on its simpler main-only deployment path; do not create dev/stage docs deployments unless the repository policy is intentionally revised.

Before opening or merging a pull request, read CONTRIBUTING.md and docs/operations/02-ci-and-release-flow.md.

Runtime channels

• Production: role-model, port 3456.
• Stage: role-model-stage, port 3457.
• Development: role-model-dev, port 3458.

Keep channel state, logs, locks, process identity, and artifacts isolated. Use the lowercase project name role-model in current user-facing names.

recursive-mode

When starting or resuming recursive-mode work, read .codex/AGENTS.md and the canonical .recursive/RECURSIVE.md before acting. Durable workflow memory lives under .recursive/memory/.

recursive-mode bridge

This repository uses recursive-mode.

The single canonical workflow spec lives in /.recursive/RECURSIVE.md. Read that file before starting or resuming any recursive-mode work.

For Codex, the primary AGENTS bridge target is /.codex/AGENTS.md. If the repo also carries other AGENTS.md files, they may mirror this same bridge block.

Bridge guidance only:

• Treat this file as a harness adapter, not as a second workflow spec.
• If this file conflicts with /.recursive/RECURSIVE.md, follow /.recursive/RECURSIVE.md.
• Control-plane docs live under /.recursive/.
• Runs live under /.recursive/run/<run-id>/.
• Durable memory lives under /.recursive/memory/.
• If recursive-mode is invoked in a repo that does not yet contain the /.recursive/ scaffold, bootstrap it automatically with the supported install script before continuing. Do not require the user to run a separate manual bootstrap step unless no supported runtime is available.

How users can invoke the skill:

• Treat short prompts such as Implement the run, Implement run 75, Implement the plan, Create a new run based on the plan, and Start a recursive run as valid recursive-mode entry commands.
• If a run id is given, use that run.
• If no run id is given and exactly one active/incomplete run exists, resume that run.
• If the user asks to implement/start based on a plan, create a new run only when a unique source plan or requirements artifact can be identified from repo docs or immediate task context.
• If the command is ambiguous, ask for the run id or the repo path of the source plan/requirements artifact.
• Prompts are still commands, not specifications: read the repo docs that define the run before proceeding.

Required recursive-mode audit behavior:

• Audited phases must follow draft -> audit -> repair -> re-audit -> pass -> lock.
• When subagents are unavailable, perform the same audit as self-audit; do not weaken or skip it.
• Delegate audits only when you can provide the full context bundle:
  • phase name and artifact path
  • upstream artifact paths reread for the audit
  • diff basis from 00-worktree.md
  • changed file list and targeted code references
  • phase-specific audit questions/checklist
• If the context bundle is incomplete, do not delegate; perform the audit yourself and record Audit Execution Mode: self-audit.
• If subagents are available and the context bundle is complete, delegated audit/review is the default path.
• If subagents are available but the controller still chooses self-audit, record a concrete Delegation Override Reason.
• Do not set Coverage: PASS or Approval: PASS for an audited phase unless the artifact ends with Audit: PASS.
• Record Subagent Capability Probe and Delegation Decision Basis in every audited phase.
• If meaningful subagent work contributes to a phase, require a durable action record under /.recursive/run/<run-id>/subagents/ and verify it against actual files, actual recursive artifacts, and the actual diff before acceptance. For review/audit delegation, prefer a stable reviewed artifact for Current Artifact.
• Store routed assistant output, raw transcripts, stdout/stderr captures, and invocation metadata under /.recursive/run/<run-id>/evidence/router/; cite them from action records rather than placing raw transcript Markdown directly under subagents/.
• Store initial routed prompt bundles only under run-scoped paths such as /.recursive/run/<run-id>/router-prompts/; do not bootstrap top-level /.recursive/router-prompts/.
• Treat success: false or any nonzero routed-assistant exit code as a failed attempt: preserve diagnostics, instruct the bounded routed role to repair owned issues when applicable, rerun the route, then verify the result before acceptance or record an explicit fallback.
• If delegated work is accepted after main-agent checks reveal issues, record the concrete repair performed after verification; do not accept stale delegated context silently.
• For Phase 3, declare TDD Mode: strict|pragmatic. Strict mode requires RED and GREEN evidence paths. Pragmatic mode requires an explicit exception rationale plus compensating evidence.
• For Phase 5, declare QA Execution Mode: human|agent-operated|hybrid. Human and hybrid require user sign-off. Agent-operated and hybrid require execution metadata plus evidence paths.
• For delegated review, prefer recursive-review-bundle and record Review Bundle Path in Phase 3.5 when review is delegated.
• Treat addenda as authoritative effective inputs. If relevant addenda exist, list them in Inputs, re-read them, and reconcile them explicitly.
• Review bundles should include relevant addenda automatically, and the written review should cite upstream artifacts, relevant addenda, prior recursive evidence, and changed files/code refs from that bundle in the review narrative.
• Audited phases must include machine-checkable Requirement Completion Status entries for every in-scope R#; Traceability alone is not enough.
• implemented and verified requirement dispositions must cite concrete Changed Files, and verified also requires distinct verification evidence.
• 00-worktree.md is the source of truth for diff basis. Record baseline type/reference, comparison reference, normalized baseline/comparison, and normalized diff command; do not silently substitute a different basis later.
• Diff audit ignores incidental runtime byproducts such as __pycache__/, *.pyc, .pytest_cache/, .mypy_cache/, and .ruff_cache/ unless the repo intentionally tracks them.
• Treat Phase 6, Phase 7, and Phase 8 receipts as concise delta receipts that point to final control-plane docs instead of duplicating them.
• Phase 8 should capture run-local skill usage and update skill memory under /.recursive/memory/skills/ when the run teaches the repo something durable about skill availability, skill fit, delegated-review quality, or skill-discovery outcomes.
• If a run needs missing specialized capability, prefer the find-skills skill when available. Otherwise use the Skills CLI (npx skills find, npx skills add, npx skills check, npx skills update) and record the outcome when skill usage is relevant.
• When working inside a reusable skill/workflow repo, do not leave committed run residue such as concrete /.recursive/run/<run-id>/ folders, evidence logs, review bundles, action records, or temp-path references unless they are intentional fixtures or examples.

Useful helpers:

Invoke these helper names from the installed recursive-mode skill directory or the source package checkout:

• install-recursive-mode
• recursive-init
• recursive-status
• lint-recursive-run
• recursive-review-bundle
• recursive-closeout
• recursive-subagent-action
• recursive-training-grpo
• recursive-training-extract
• recursive-training-phase8-trigger
• recursive-training-sync
• recursive-training-loader
• recursive-training-mcp
• recursive-lock
• verify-locks
• check-reusable-repo-hygiene

Diff ownership rules:

• Phase 2 owns planned product/worktree scope only.
• Phase 3, Phase 3.5, and Phase 4 own actual product/worktree drift reconciliation.
• Phase 6 owns /.recursive/DECISIONS.md.
• Phase 7 owns /.recursive/STATE.md.
• Phase 8 owns /.recursive/memory/**.
• Do not treat later control-plane or memory churn as retroactive invalidation of earlier locked phases.

Locking rule:

• Use recursive-lock as the primary supported way to write Status: LOCKED, LockedAt, and LockHash.