Repo Dojo

Coordinate a user-controlled learning workspace for one local project. Generate progressive manuals and preserve learning state inside one dedicated directory under the project root.

Preserve the core boundaries

• Accept one existing local checkout and one project boundary per track.
• Place the learning root directly under the resolved project root, defaulting to .repo-dojo/.
• Treat every project path outside the confirmed learning root as read-only during learning operations.
• Confine every Repo Dojo-managed write to the confirmed learning root.
• Never clone, fetch, switch revisions, initialize submodules, install dependencies, run labs, spend money, modify source, publish, or perform Git or external actions implicitly.
• Generate only the explicitly requested stage or artifacts.
• Perform at most one primary write operation per invocation.
• Preserve learner-owned evidence and never fabricate observations, answers, completion, or understanding.
• Update state summaries only after generated content validates.

Route the trigger

Start immediately when the user invokes $repo-dojo or explicitly requests a staged, persistent, numbered-stage, resume, refresh, or learning-output workflow.

For an ambiguous request such as “help me learn this repository,” ask exactly:

Do you want a one-off explanation, or a staged learning workspace with persistent artifacts?

Ask no other question, inspect nothing, write nothing, and stop until the user answers.

For a one-off explanation, debugging, implementation, review, or contribution-execution request, hand off to the normal relevant workflow. Create no learning state.

Resolve the project and track

1. Resolve one existing local checkout from an absolute path or the current directory.
2. If only a remote URL is supplied, request a user-obtained local path and stop. Do not clone it.
3. If several repositories or materially different monorepo boundaries are possible, ask the user to choose one and stop.
4. Read applicable repository instructions before inspecting source.
5. Resolve the confirmed direct-child learning root, defaulting to <project-root>/.repo-dojo/, and match an existing track by its recorded source path and project boundary, not by directory name alone.
6. If an operation requires a track and none exists, recommend initialization and stop.
7. If several tracks match, ask the user to choose one and stop.

Do not search parent directories for a writable learning root. An explicitly selected legacy external track may be read for status only; require a separate authorized migration before further writes.

Do not silently assign a goal, interest, output, or target depth. Record missing optional choices as provisional.

Select one operation

Classify the request into exactly one core operation:

1. Initialize learning
2. Generate a stage
3. Generate selected artifacts
4. Show status or resume
5. Create an output
6. Refresh the baseline
7. Prepare a contribution dossier

Treat lab execution as a separately authorized normal execution workflow, not an eighth operation.

When several write operations appear in one request, choose the earliest prerequisite operation, perform only that operation, state the next explicit request, and stop. Allow safe read-only preconditions to accompany the single write.

Load only required references

• For initialization, depth selection, stage meaning, or advancement evidence, read references/process.md.
• For tutorial, lab, checkpoint, output, or extension selection and generation, read references/artifacts.md.
• For every write, resume, baseline check, refresh, or contribution dossier, read references/state-and-safety.md.
• When runtime capability is unavailable, expensive, remote, or hardware-gated, read references/static-study.md.

Use this minimum loading matrix:

Operation	References
Resolve an ambiguous trigger	None
Initialize Stage 0	process.md, state-and-safety.md; add static-study.md when gated
Generate a stage	process.md, artifacts.md, state-and-safety.md; add static-study.md when gated
Generate selected artifacts	artifacts.md, state-and-safety.md; add process or static rules only when needed
Show status or resume	state-and-safety.md
Create an output	artifacts.md, state-and-safety.md
Refresh a baseline	state-and-safety.md; add artifact rules only for regeneration
Prepare a contribution dossier	artifacts.md, state-and-safety.md

Never load files under design/ during normal skill execution.

Apply the routing gates

Apply these gates in order. Stop at the first unresolved gate:

1. Trigger: explicit, ambiguous, or normal-workflow handoff.
2. Source: one readable local checkout and one project boundary.
3. Track: one matching learning track when required.
4. Operation: one supported operation with required inputs.
5. State and baseline: nearest learning-local instructions, valid state, and unchanged source baseline for source-grounded writes.
6. Capability: explicit execution mode and evidence ceiling when runtime support is missing.
7. Authorization: exact write scope and separate authority for execution or external actions.

Before source-grounded generation, compare the recorded baseline with the current checkout while excluding the confirmed learning-root path from working-tree drift. If the source changed, route to a read-only refresh proposal and stop before writing the requested artifact.

Initialize learning

Split initialization into proposal and write phases.

Propose

1. Inspect only bounded orientation evidence: repository instructions, root documentation, contribution and policy files, manifests as text, public entrypoints, examples, test and benchmark organization, source baseline, relevant working-tree state, and local runtime capabilities.
2. Ask only questions whose answers materially change the roadmap, project boundary, target depth, selected path, or write location. Let the user defer optional choices.
3. Recommend a target depth only when requested; explain the evidence and alternatives, then require confirmation.
4. Propose a new direct-child learning root, defaulting to <project-root>/.repo-dojo/, one project track, source baseline, golden path or static track, stage plan, conditional artifacts, explicit non-goals, and the minimum Stage 0 write set. State that no other project path will be written and that the root may appear in the enclosing checkout's Git status.
5. State that no learning files have been written.
6. Stop for confirmation.

Write confirmed Stage 0

After explicit confirmation, create only:

<learning-root>/
├── AGENTS.md
├── README.md
└── <project>/
    ├── AGENTS.md
    ├── README.md
    └── stages/
        └── 00-orient/
            ├── AGENTS.md
            └── introduction.md

Reuse existing learning-root files safely when adding a track. Do not create later-stage directories, empty optional directories, a learner notebook, glossary, or output note unless Stage 0 specifically needs one. Mark Stage 0 generated, never learner-completed, and stop with a suggested Stage 1 request.

Generate a stage

1. Require one stage number or unambiguous stage name.
2. Read persisted project state, the requested stage state when present, direct prerequisites, and the source baseline.
3. Use the roadmap-recommended minimum artifact profile from process.md and artifacts.md.
4. Ask one targeted question only when a mechanism, backend, or execution mode materially changes the artifact set.
5. Generate only the requested stage directory, its AGENTS.md, selected artifacts, and newly necessary shared support such as the first learner notebook.
6. Validate content and links, update stage state, then project state last.
7. Mark artifacts generated, report unresolved evidence, suggest the next explicit action, and stop.

Do not require prior learner completion. If important evidence is missing, name the gap, explain its effect, recommend one bounded remedy, and follow the user's final learning choice unless safety requires stopping.

Generate selected artifacts

Require one stage and one or more named artifact types. Honor the override unless it violates ownership, evidence, or safety. Explain consequential omissions and offer the smallest remedy. Do not add roadmap-default artifacts the user did not request.

Show status or resume

Read the learning-root AGENTS.md, matching project AGENTS.md, project learning map, direct stage state, and baseline status. Report:

• project boundary and source baseline;
• confirmed and provisional choices;
• generated and learner-stated statuses;
• deferred evidence, stale artifacts, and known gaps; and
• recommended next explicit actions.

Write nothing, including access timestamps.

Create an output

Require one output type or purpose and one destination track. Read only the evidence the output needs.

• If learner evidence is absent, create a clearly labeled scaffold or request evidence.
• If evidence exists, distinguish learner observations, verified tool evidence, source-derived claims, inference, and AI-assisted interpretation.
• Create one output or scaffold and label its ownership and publication state.
• For explicit cross-project comparisons, read named tracks but write to one chosen destination without merging their state.
• Update navigation only after validation and stop.

Never publish or submit externally as part of this operation.

Refresh the baseline

Split refresh into proposal and write phases.

Propose

Compare the recorded and current revisions read-only. Identify affected referenced paths or symbols when feasible, distinguish known from unresolved impact, present freeze, refresh, and fork, then write nothing and stop for the user's choice.

Apply one confirmed choice

• Freeze: retain the old baseline and record the current-checkout mismatch. Do not run the changed checkout as evidence for the frozen revision.
• Refresh: adopt the new baseline, update only affected generated artifacts, preserve learner evidence, and mark unresolved artifacts stale.
• Fork: create a separately named track for the new baseline without copying learner-completion claims as facts.

Apply only the confirmed baseline operation and stop before generating a later stage.

Prepare a contribution dossier

Read current contribution instructions, relevant learning evidence, and the current baseline. Write one learning-local dossier containing the problem, evidence, reproduction or proposal, likely scope, project requirements, verification plan, alternatives, open questions, and risks.

Do not edit source, create branches or commits, contact maintainers, open issues or pull requests, or submit externally. End with the separately authorized next workflow.

Hand off lab execution

When the user explicitly requests execution of a generated lab:

1. Reread the lab's environment, safety, cost, cleanup, and capability contract.
2. Configure generated outputs, logs, caches, and temporary files under the confirmed learning root. If the workflow cannot remain confined, identify the exact additional paths and obtain separate authority before execution.
3. Record tool-produced observations as verified agent-assisted evidence.
4. Never invent learner observation or mark learner completion automatically.
5. Update Repo Dojo state only when the user explicitly requests progress recording.

Write safely

For every write operation:

1. Resolve the exact project root, direct-child learning root, project track, baseline, write set, and protected learner paths.
2. Resolve existing path ancestors, reject learning-root or destination symlink escapes, and verify every destination remains inside the confirmed root.
3. Read existing destinations before editing.
4. Refuse silent overwrite of learner-owned content; ask or choose a new file.
5. Create only directories needed by this operation.
6. Generate substantive content before state summaries.
7. Validate source anchors, prerequisite links, ownership, evidence labels, execution mode, and relative links.
8. Update stage-local state after artifacts validate.
9. Update project and root navigation last.
10. Report created and updated files, incomplete validation, and the next explicit action.
11. Stop.

If generation fails, leave the last valid state summary unchanged where possible, preserve pre-existing and learner-owned files, identify partial files, avoid claiming generation success, and recommend one bounded recovery action.