train-with-agents

name

train-with-agents

description

Turn AI-assisted software development into deliberate practice without sacrificing delivery speed. Use when a developer wants to learn design logic while an agent plans, implements, debugs, reviews, or validates code; asks to quick-start or try the training workflow; chooses among coach-first, co-design, and adopt-first; creates a project-local training card; or verifies transfer of an engineering decision in a later task. Skip trivial boilerplate, pure status work, and requests that explicitly exclude training.

Train With Agents

Turn real software delivery into deliberate practice. Preserve the user's ability to explain, change, and prove a design decision instead of measuring learning by how much code they typed.

Apply The Operating Contract

• Preserve delivery correctness and safety. Never make a production result worse merely to create a lesson.
• Train one meaningful engineering decision per card. Split large tasks instead of teaching the whole implementation at once.
• Treat mode and depth as separate choices. Use coach-first, co-design, or adopt-first; use lite or standard depth.
• Treat quick-start as an onboarding preset that resolves to an existing mode. Never store or return it as a fourth mode.
• Use evidence from the real task. Do not invent understanding, proof, or transfer.
• Keep project-local state in the project. Keep this skill limited to reusable procedure, templates, schemas, and validators.
• Respond in the user's language unless the project requires another language.

Run The Workflow

1. Establish The Training Target

Identify one decision that matters to the task outcome, such as an API boundary, data model, concurrency rule, failure policy, compatibility constraint, or test strategy.

Record or obtain:

• the task and repository boundary;
• the selected learning target;
• risk and reversibility;
• current implementation or plan evidence;
• the user's requested mode and depth, if explicit.

If no decision has meaningful design value, finish the delivery task normally and use closed_no_training.

2. Resolve Quick Start When Requested

Read quick-start.md when the user asks to quick-start, try, demo, or get started without choosing a mode.

• Default to lite depth and one low-risk, reversible, meaningful decision.
• Prefer adopt-first when a verified solution or implementation is already visible.
• Use co-design when an unresolved design fork has genuine options.
• Use coach-first when the route is still hidden and the user wants to reason before seeing it.
• Announce the selected target, mode, depth, and reason before beginning.

Resolve the preset before creating a card or integration result. Keep all stored mode values within the existing three-mode enum.

3. Apply The Safety Gate

Read risk-and-interruptions.md when the task is high-risk, irreversible, incident-driven, prerequisite-blocked, or unusually large.

Require an explicit pre-apply review for destructive, security-sensitive, financial, production, migration, or otherwise hard-to-reverse work. In these cases, interpret adopt-first as AI-proposes-first, not AI-applies-first.

4. Select Mode And Depth

Honor an explicit user mode. Otherwise, choose with mode-routing.md:

• coach-first: create useful friction before the agent reveals a complete route;
• co-design: alternate decision ownership while building the route;
• adopt-first: let the agent deliver first, then reconstruct and challenge the design.

Use lite for one decision, one counterfactual, and one proof in roughly five minutes. Use standard for multiple options, a failure path, and stronger verification in roughly fifteen to twenty-five minutes.

Read adopt-first.md whenever using adopt-first.

5. Execute The Mode

Keep the real task as the training environment.

For coach-first:

1. Ask for a small baseline artifact before showing the complete route: a prediction, invariant list, interface sketch, failure analysis, or test idea.
2. Offer hints in increasing specificity when needed.
3. Compare the user's artifact with the implemented or proposed design.
4. Ask the user to revise one material choice or explain why it should remain.

For co-design:

1. Frame the problem, constraints, and genuine options.
2. Assign the next material decision to either the user or the agent.
3. Record the owner, selection, rejected route, and tradeoff.
4. Alternate ownership only when another meaningful decision exists; do not manufacture choices.

For adopt-first:

1. Establish that the solution is correct enough to study.
2. Reveal a compact design capsule: problem, constraints, invariants, selected route, rejected routes, failure points, and evidence.
3. Ask the user to reconstruct why the route works.
4. Introduce one counterfactual requirement and ask what must change or remain invariant.
5. Make the user own one proof choice, such as a test, assertion, trace, or rollback check.

6. Apply The Shared Learning Gate

Read transfer-gate.md. Evaluate these stages in order:

1. solution_correctness: evidence supports the design being studied.
2. design_reconstruction: the user can explain the selected route and at least one rejected route or tradeoff.
3. counterfactual_prediction: the user predicts the effect of a changed requirement before the agent supplies the answer.
4. proof_ownership: the user selects or creates evidence that could falsify the design.
5. transfer: the same capability is demonstrated in a materially different later task.

Do not award transfer_verified from the original task. Use transfer_pending until later-task evidence exists.

7. Persist A Training Card

Copy development-training-card.md into a project-local location selected by the project, then replace all placeholders. Prefer a path already used for task artifacts; otherwise use .codex/training/<training_id>.md.

Use one of these statuses:

• active: the training interaction is still in progress;
• closed_no_training: the task had no worthwhile training target;
• adopted_only: the solution was used but the learning gate was not completed;
• transfer_pending: the original-task learning gate passed but no valid later transfer exists;
• transfer_verified: later-task evidence proves transfer;
• abandoned: the training attempt stopped without completion.

Run the bundled validator after editing a card:

python scripts/validate_training_card.py path/to/training-card.md

When invoked from this repository, validate against the versioned schemas in schemas/. When installed as a standalone skill, the Markdown validator remains self-contained.

Integrate With An Orchestrator

Accept a short, versioned design capsule instead of reconstructing the whole task conversation. Read integration-contract.md when another agent, role system, or automation calls this skill.

Keep ownership distinct:

• let the orchestrator own task routing, execution loops, model selection, and callbacks;
• let this skill own mode behavior, learning gates, training-card semantics, and transfer judgment;
• let optional knowledge-base adapters consume only eligible outputs; do not make a knowledge base a runtime dependency.

Return a structured result that states the mode, status, card reference, user-owned artifact, proof, and transfer evidence. Fail closed on unknown contract versions or invalid enum values.

Resolve quick-start before emitting a v1 contract or result. Pass the selected existing mode and lite depth; do not change the contract enum for the preset.

Do Not Claim What Was Not Proven

• Do not equate agreement with understanding.
• Do not equate an explanation copied from the agent with reconstruction.
• Do not equate an original-task test with cross-context transfer.
• Do not turn routine syntax or boilerplate into a mandatory lesson.
• Do not block emergency restoration for a synchronous teaching loop; schedule a deferred debrief instead.
• Do not export a knowledge candidate before transfer_verified.