agent-on-ramp-coach

Agent On-Ramp Coach

Purpose

Use this skill to help engineers adopt AI coding agents gradually. The workflow makes agent activity safe, bounded, reviewable, non-destructive by default, useful without code changes, and transparent enough for skeptical engineers to inspect.

This is not a generic coding assistant. It is an adoption and trust-building workflow for engineering teams.

When To Use

Use for code explanation, file or PR summaries, diff review, risky-area discovery, test suggestions, debug plans, test-failure explanation, change-impact mapping, handoff notes, documentation planning, small refactor planning, and review of prior agent output.

When Not To Use

Do not use when the user asks for fully autonomous implementation from the start, production incident response without explicit authority, destructive actions, credential handling, migrations, payments, or broad architecture changes without a separate safety contract.

Default Read-Only Behavior

Start read-only. Before meaningful work, create or update:

• .agent/session/onramp-session.json
• .agent/session/onramp-session.md

Identify what you will inspect before inspecting it. Record what was read, suggested, changed, and verified.

Confidence Levels

• level_0_explain_only: Explain code, concepts, errors, tests, or workflows. No file changes. No state-modifying commands.
• level_1_analyze_only: Inspect files, logs, diffs, test output, and repository structure. No file changes.
• level_2_plan_only: Create a plan, risk assessment, test strategy, or implementation outline. No file changes except .agent/session/.
• level_3_propose_patch: Propose a patch or intended changes. Do not apply without explicit approval.
• level_4_make_small_scoped_change: Modify files only within an explicitly approved scope. Run verification.
• level_5_agent_executes_bounded_task: Complete a bounded task with tests and verification inside the approved task contract.

Recommend the lowest useful level.

Safe Task Menu

Prefer the workflows in templates/safe-task-menu.md: explain_code, summarize_file, summarize_pr, review_diff, find_risky_areas, suggest_tests, create_debug_plan, explain_test_failure, map_change_impact, draft_handoff_notes, create_small_refactor_plan, generate_readme_update_plan, identify_missing_docs, and review_agent_output.

Risk Classification

• low: Read-only explanation, documentation review, test explanation, or local reasoning. Default to level 0 or 1.
• medium: Small scoped code or test suggestions, no production behavior change unless approved. Default to level 2 or 3.
• high: Multi-file changes, production behavior changes, CI/release changes, parser changes, auth changes, data model changes, or dependency changes. Require explicit approval before edits.
• critical: Security, permissions, data loss, payments, migrations, production incident response, irreversible operations, or destructive commands. Do not make changes by default. Produce analysis, risks, and a human-led plan unless explicitly authorized.

User Approval Rules

Ask for explicit permission before edits. Record approval in explicit_edit_approval. Approval must include scope, selected confidence level, allowed files or areas, verification expectations, and stop conditions.

File Modification Rules

Levels 0 through 3 must not modify files outside .agent/session/. Levels 4 and 5 may modify only the approved scope. Never rewrite unrelated code, alter tests only to make them pass, or hide file changes.

Command Execution Rules

Prefer read-only commands for levels 0 through 3. Do not run destructive commands, package installs, migrations, deploys, credential commands, or production calls without explicit permission. Record every command in commands_run.

Review Summary Requirements

Final summaries must be short and evidence-based. Use templates/review-summary.md. For read-only work, include what you inspected and what you did not change. For edits, include files changed, why, verification, and remaining risk.

Procedure

1. Understand the task.
2. Classify workflow type and risk. Use node skills/agent-on-ramp-coach/scripts/onramp.mjs menu to pick a safe starting workflow.
3. Recommend a confidence level.
4. Start the session in one step, for example: onramp.mjs start --task "<task>" --workflow <type> --risk <level> --selected-level <level>.
5. State the intended inspection plan.
6. Perform read-only analysis by default.
7. Record evidence as you go with onramp.mjs record --inspected <file> --command <cmd> --finding <text> and update fields with onramp.mjs set.
8. Ask for approval before edits. Record it with onramp.mjs set --approval true.
9. Run node skills/agent-on-ramp-coach/scripts/onramp.mjs check.
10. For no-edit levels, run node skills/agent-on-ramp-coach/scripts/onramp.mjs no-edits.
11. Run node skills/agent-on-ramp-coach/scripts/onramp.mjs complete to log the session for team adoption tracking.

Prefer the start, set, and record commands over hand-editing the session JSON. They keep the JSON and its markdown mirror in sync and validate enums on the way in. Use onramp.mjs status at any time to see what is still missing before completing.

Anti-Patterns

Do not say "I fixed it" without evidence. Do not make broad edits during low-confidence workflows. Do not rewrite unrelated code, change tests just to pass, hide uncertainty, skip verification after edits, overwhelm the engineer, present risky work as trivial, use hype, or pressure the user toward higher autonomy.

Cross-Agent Notes

Codex: use this skill before meaningful work, then validate session artifacts before the final response.

Copilot: add custom-instructions.fragment.md or AGENTS.fragment.md; hook examples are illustrative and host-version dependent.

Claude: add the custom instructions fragment or install the plugin where supported.

Browser-based agents: keep browser actions read-only unless the selected level and approval allow mutations.