{ "schema_version": 2, "meta": { "build_id": "CODEX-WORKGENTIC-TO-AGENTIC", "slug": "workgentic-to-agentic", "title": "Shifting from Workgentic to Agentic Workflow", "subtitle": "Direct, test, debug and supervise the agent that writes the code.", "description": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "one_sentence_description": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "target_user": "A motivated beginner with permission to work in a private practice folder.", "skill_level": "beginner", "estimated_time": "2–3 hours", "category": "Guided Build", "tags": [ "workgentic-to-agentic", "verified practice", "chatgpt_codex" ], "prerequisites": [ "Permission to use a dedicated workspace", "A browser and terminal", "Read each platform-specific prerequisite before installation" ], "required_accounts": [], "required_software": [ "Modern browser", "Python 3.10+ for downloadable drills" ], "required_hardware": [ "A computer with space for the practice files", "Second drive for the disaster-recovery checkpoint" ], "expected_cost": "Free practice; existing tool accounts may have plan limits.", "final_outcome": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "platforms": [ "windows", "macos", "linux" ], "version": "2.0", "author": "chatgpt_codex", "source_checked": "2026-10-05", "verification_status": "Created; automated browser and project checks recorded separately. Live account/OS verification is never inferred from browser completion." }, "user_outcome": { "before": "The learner has no reproducible, checked workflow for shifting from workgentic to agentic workflow.", "after": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "finished_product": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application." }, "learning_objectives": [ "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "The map distinguishes implementer, assisted programmer and overseer.", "The loop includes observable evidence and a human review boundary.", "The task brief has five concrete fields and the proposed files stay inside the practice folder.", "VERIFY PASS is recorded with a command and exit code.", "The incident report can reproduce the symptom without private credentials." ], "lessons": [ { "lesson_id": "L01", "title": "Prepare the capstone", "purpose": "A dedicated folder makes mistakes easy to diagnose and keeps real project files separate.", "estimated_time": "6 min", "learning_objective": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "lessons_before_this": [], "lessons_after_this": [ "L02" ] }, { "lesson_id": "L02", "title": "1 — Change your role", "purpose": "You still own the outcome; your effort shifts to constraints, environment, evidence and review.", "estimated_time": "6 min", "learning_objective": "The map distinguishes implementer, assisted programmer and overseer.", "lessons_before_this": [ "L01" ], "lessons_after_this": [ "L03" ] }, { "lesson_id": "L03", "title": "2 — Design the control loop", "purpose": "A completion message without output bypasses the part that establishes the result.", "estimated_time": "6 min", "learning_objective": "The loop includes observable evidence and a human review boundary.", "lessons_before_this": [ "L02" ], "lessons_after_this": [ "L04" ] }, { "lesson_id": "L04", "title": "3 — Delegate an outcome", "purpose": "Delegation specifies success and boundaries rather than dictating every line.", "estimated_time": "6 min", "learning_objective": "The task brief has five concrete fields and the proposed files stay inside the practice folder.", "lessons_before_this": [ "L03" ], "lessons_after_this": [ "L05" ] }, { "lesson_id": "L05", "title": "4 — Verify trust", "purpose": "Evidence should be reproducible, relevant to the task, and from the actual version under review.", "estimated_time": "6 min", "learning_objective": "VERIFY PASS is recorded with a command and exit code.", "lessons_before_this": [ "L04" ], "lessons_after_this": [ "L06" ] }, { "lesson_id": "L06", "title": "5 — Give the agent eyes", "purpose": "Logs, traces, screenshots, stderr and environment versions let an agent inspect rather than guess.", "estimated_time": "6 min", "learning_objective": "The incident report can reproduce the symptom without private credentials.", "lessons_before_this": [ "L05" ], "lessons_after_this": [ "L07" ] }, { "lesson_id": "L07", "title": "6 — Prepare the environment", "purpose": "A project environment includes docs, source, tests, logs and saved evidence, not only a clever prompt.", "estimated_time": "6 min", "learning_objective": "AGENTS.md contains reproducible run/test commands and explains the directory structure.", "lessons_before_this": [ "L06" ], "lessons_after_this": [ "L08" ] }, { "lesson_id": "L08", "title": "7 — Work the full loop", "purpose": "Correction should respond to an observed mismatch; do not repeatedly regenerate the project without a diagnosis.", "estimated_time": "6 min", "learning_objective": "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "lessons_before_this": [ "L07" ], "lessons_after_this": [ "L09" ] }, { "lesson_id": "L09", "title": "8 — Recover after a crash", "purpose": "Do not become the agent’s only stack trace; give it direct diagnostic access inside the authorized scope.", "estimated_time": "6 min", "learning_objective": "The recovery plan has eight steps and an observed failure/recovery pair.", "lessons_before_this": [ "L08" ], "lessons_after_this": [ "L10" ] }, { "lesson_id": "L10", "title": "9 — Stop relaying errors", "purpose": "A useful investigator can inspect its environment and explain what it knows and what it has not checked.", "estimated_time": "6 min", "learning_objective": "The diagnosis names a failing case, observed evidence and one testable hypothesis.", "lessons_before_this": [ "L09" ], "lessons_after_this": [ "L11" ] }, { "lesson_id": "L11", "title": "10 — Set delegation levels", "purpose": "Increasing autonomy is a design decision tied to evidence and reversibility, not a global trust switch.", "estimated_time": "6 min", "learning_objective": "The table distinguishes all three levels and requires explicit review for external actions.", "lessons_before_this": [ "L10" ], "lessons_after_this": [ "L12" ] }, { "lesson_id": "L12", "title": "11 — Write your new job description", "purpose": "Human judgment remains necessary for priorities, ambiguous requirements and release risk.", "estimated_time": "6 min", "learning_objective": "The job description names an accountable owner and check for each duty.", "lessons_before_this": [ "L11" ], "lessons_after_this": [ "L13" ] }, { "lesson_id": "L13", "title": "12 — You are the CTO now", "purpose": "sum(set(items)) loses repeated inputs; a failing reproducible check is the starting evidence.", "estimated_time": "12 min", "learning_objective": "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "lessons_before_this": [ "L12" ], "lessons_after_this": [ "L14" ] }, { "lesson_id": "L14", "title": "Build Bot Better — protect and recover", "purpose": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "estimated_time": "30 min", "learning_objective": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "lessons_before_this": [ "L13" ], "lessons_after_this": [] } ], "steps": [ { "title": "Set up the practice folder", "purpose": "A dedicated folder makes mistakes easy to diagnose and keeps real project files separate.", "user_action": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "explanation": "A dedicated folder makes mistakes easy to diagnose and keeps real project files separate.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python --version\nGet-Location\nGet-ChildItem", "macos": "python3 --version\npwd\nls", "linux": "python3 --version\npwd\nls" }, "command_type": "shell", "required_inputs": [], "expected_result": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "resources": [], "checkpoint": { "what_is_being_checked": "Set up the practice folder", "success_condition": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "how_to_verify": "Record python reports version 3.10 or newer and the terminal is in the extracted resource folder. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "Python is 3.10 or newer.", "The listed files match the downloaded resources." ], "tokens": [], "user_visible_success_message": "Evidence saved. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "Python or a file is not found", "likely_cause": "The terminal may be outside the extracted ZIP or Python may not be on PATH.", "diagnostic_question": "Does the file list include the resource named by the next step?", "fix": "Install Python from python.org with the PATH option; reopen the terminal and change into the extracted folder.", "alternative_fix": "Use py -3 on Windows if the Python launcher is installed. macOS/Linux commands use python3.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Install Python from python.org with the PATH option; reopen the terminal and change into the extracted folder." } ], "faqs": [ { "question": "How do I verify set up the practice folder?", "answer": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to set up the practice folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "demo": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Install Python from python.org with the PATH option; reopen the terminal and change into the extracted folder.", "help": "Does the file list include the resource named by the next step?" }, "video": { "purpose": "Demonstrate set up the practice folder", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "on_screen_text": [ "Set up the practice folder", "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ], "screen_recording_instructions": [ "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "Inspect the result: Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ] }, "step_id": "L01-S01", "lesson_id": "L01" }, { "title": "Map the programming evolution", "purpose": "You still own the outcome; your effort shifts to constraints, environment, evidence and review.", "user_action": "Write the sequence books → Stack Overflow → search → ChatGPT → copied code/errors → assisted coding → coding agents → agentic workflow. For one recent task, list what you wrote/debugged manually and what you could direct/verify instead.", "explanation": "You still own the outcome; your effort shifts to constraints, environment, evidence and review.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The map distinguishes implementer, assisted programmer and overseer.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Map the programming evolution", "success_condition": "The map distinguishes implementer, assisted programmer and overseer.", "how_to_verify": "Record the map distinguishes implementer, assisted programmer and overseer. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The map distinguishes implementer, assisted programmer and overseer.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The map distinguishes implementer, assisted programmer and overseer.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify map the programming evolution?", "answer": "The map distinguishes implementer, assisted programmer and overseer. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to map the programming evolution. The map distinguishes implementer, assisted programmer and overseer.", "demo": "Write the sequence books → Stack Overflow → search → ChatGPT → copied code/errors → assisted coding → coding agents → agentic workflow. For one recent task, list what you wrote/debugged manually and what you could direct/verify instead.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate map the programming evolution", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write the sequence books → Stack Overflow → search → ChatGPT → copied code/errors → assisted coding → coding agents → agentic workflow. For one recent task, list what you wrote/debugged manually and what you could direct/verify instead. The map distinguishes implementer, assisted programmer and overseer.", "on_screen_text": [ "Map the programming evolution", "The map distinguishes implementer, assisted programmer and overseer." ], "screen_recording_instructions": [ "Write the sequence books → Stack Overflow → search → ChatGPT → copied code/errors → assisted coding → coding agents → agentic workflow. For one recent task, list what you wrote/debugged manually and what you could direct/verify instead.", "Inspect the result: The map distinguishes implementer, assisted programmer and overseer.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The map distinguishes implementer, assisted programmer and overseer." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write the sequence books → Stack Overflow → search → ChatGPT → copied code/errors → assisted coding → coding agents → agentic workflow. For one recent task, list what you wrote/debugged manually and what you could direct/verify instead.", "The map distinguishes implementer, assisted programmer and overseer." ] }, "step_id": "L02-S01", "lesson_id": "L02" }, { "title": "Draw the evidence loop", "purpose": "A completion message without output bypasses the part that establishes the result.", "user_action": "Write human → objective → agent → code/tools → environment → evidence → agent → human oversight. Circle every place that can fail in the practice project.", "explanation": "A completion message without output bypasses the part that establishes the result.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The loop includes observable evidence and a human review boundary.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Draw the evidence loop", "success_condition": "The loop includes observable evidence and a human review boundary.", "how_to_verify": "Record the loop includes observable evidence and a human review boundary. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The loop includes observable evidence and a human review boundary.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The loop includes observable evidence and a human review boundary.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify draw the evidence loop?", "answer": "The loop includes observable evidence and a human review boundary. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to draw the evidence loop. The loop includes observable evidence and a human review boundary.", "demo": "Write human → objective → agent → code/tools → environment → evidence → agent → human oversight. Circle every place that can fail in the practice project.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate draw the evidence loop", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write human → objective → agent → code/tools → environment → evidence → agent → human oversight. Circle every place that can fail in the practice project. The loop includes observable evidence and a human review boundary.", "on_screen_text": [ "Draw the evidence loop", "The loop includes observable evidence and a human review boundary." ], "screen_recording_instructions": [ "Write human → objective → agent → code/tools → environment → evidence → agent → human oversight. Circle every place that can fail in the practice project.", "Inspect the result: The loop includes observable evidence and a human review boundary.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The loop includes observable evidence and a human review boundary." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write human → objective → agent → code/tools → environment → evidence → agent → human oversight. Circle every place that can fail in the practice project.", "The loop includes observable evidence and a human review boundary." ] }, "step_id": "L03-S01", "lesson_id": "L03" }, { "title": "Write a bounded task brief", "purpose": "Delegation specifies success and boundaries rather than dictating every line.", "user_action": "Adapt delegation.md with objective, scope, constraints, verification and evidence. Tell an installed signed-in agent to inspect app.py and verify.py, then propose one small change without editing yet.", "explanation": "Delegation specifies success and boundaries rather than dictating every line.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The task brief has five concrete fields and the proposed files stay inside the practice folder.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Write a bounded task brief", "success_condition": "The task brief has five concrete fields and the proposed files stay inside the practice folder.", "how_to_verify": "Record the task brief has five concrete fields and the proposed files stay inside the practice folder. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The task brief has five concrete fields and the proposed files stay inside the practice folder.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The task brief has five concrete fields and the proposed files stay inside the practice folder.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify write a bounded task brief?", "answer": "The task brief has five concrete fields and the proposed files stay inside the practice folder. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to write a bounded task brief. The task brief has five concrete fields and the proposed files stay inside the practice folder.", "demo": "Adapt delegation.md with objective, scope, constraints, verification and evidence. Tell an installed signed-in agent to inspect app.py and verify.py, then propose one small change without editing yet.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate write a bounded task brief", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Adapt delegation.md with objective, scope, constraints, verification and evidence. Tell an installed signed-in agent to inspect app.py and verify.py, then propose one small change without editing yet. The task brief has five concrete fields and the proposed files stay inside the practice folder.", "on_screen_text": [ "Write a bounded task brief", "The task brief has five concrete fields and the proposed files stay inside the practice folder." ], "screen_recording_instructions": [ "Adapt delegation.md with objective, scope, constraints, verification and evidence. Tell an installed signed-in agent to inspect app.py and verify.py, then propose one small change without editing yet.", "Inspect the result: The task brief has five concrete fields and the proposed files stay inside the practice folder.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The task brief has five concrete fields and the proposed files stay inside the practice folder." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Adapt delegation.md with objective, scope, constraints, verification and evidence. Tell an installed signed-in agent to inspect app.py and verify.py, then propose one small change without editing yet.", "The task brief has five concrete fields and the proposed files stay inside the practice folder." ] }, "step_id": "L04-S01", "lesson_id": "L04" }, { "title": "Choose acceptable proof", "purpose": "Evidence should be reproducible, relevant to the task, and from the actual version under review.", "user_action": "Run verify.py yourself. Save the command, exit code and complete output. Compare this proof with a sentence claiming “all tests pass.”", "explanation": "Evidence should be reproducible, relevant to the task, and from the actual version under review.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python verify.py", "macos": "python3 verify.py", "linux": "python3 verify.py" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "VERIFY PASS is recorded with a command and exit code.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Choose acceptable proof", "success_condition": "VERIFY PASS is recorded with a command and exit code.", "how_to_verify": "Record vERIFY PASS is recorded with a command and exit code. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "VERIFY PASS is recorded with a command and exit code.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. VERIFY PASS is recorded with a command and exit code.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify choose acceptable proof?", "answer": "VERIFY PASS is recorded with a command and exit code. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to choose acceptable proof. VERIFY PASS is recorded with a command and exit code.", "demo": "Run verify.py yourself. Save the command, exit code and complete output. Compare this proof with a sentence claiming “all tests pass.”", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate choose acceptable proof", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run verify.py yourself. Save the command, exit code and complete output. Compare this proof with a sentence claiming “all tests pass.” VERIFY PASS is recorded with a command and exit code.", "on_screen_text": [ "Choose acceptable proof", "VERIFY PASS is recorded with a command and exit code." ], "screen_recording_instructions": [ "Run verify.py yourself. Save the command, exit code and complete output. Compare this proof with a sentence claiming “all tests pass.”", "Inspect the result: VERIFY PASS is recorded with a command and exit code.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "VERIFY PASS is recorded with a command and exit code." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run verify.py yourself. Save the command, exit code and complete output. Compare this proof with a sentence claiming “all tests pass.”", "VERIFY PASS is recorded with a command and exit code." ] }, "step_id": "L05-S01", "lesson_id": "L05" }, { "title": "Build an incident report", "purpose": "Logs, traces, screenshots, stderr and environment versions let an agent inspect rather than guess.", "user_action": "Fill incident-template.md with working directory, Python version, input, expected result, actual output and one diagnostic. Ask the agent to identify missing observability before it suggests a fix.", "explanation": "Logs, traces, screenshots, stderr and environment versions let an agent inspect rather than guess.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The incident report can reproduce the symptom without private credentials.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Build an incident report", "success_condition": "The incident report can reproduce the symptom without private credentials.", "how_to_verify": "Record the incident report can reproduce the symptom without private credentials. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The incident report can reproduce the symptom without private credentials.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The incident report can reproduce the symptom without private credentials.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify build an incident report?", "answer": "The incident report can reproduce the symptom without private credentials. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to build an incident report. The incident report can reproduce the symptom without private credentials.", "demo": "Fill incident-template.md with working directory, Python version, input, expected result, actual output and one diagnostic. Ask the agent to identify missing observability before it suggests a fix.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate build an incident report", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Fill incident-template.md with working directory, Python version, input, expected result, actual output and one diagnostic. Ask the agent to identify missing observability before it suggests a fix. The incident report can reproduce the symptom without private credentials.", "on_screen_text": [ "Build an incident report", "The incident report can reproduce the symptom without private credentials." ], "screen_recording_instructions": [ "Fill incident-template.md with working directory, Python version, input, expected result, actual output and one diagnostic. Ask the agent to identify missing observability before it suggests a fix.", "Inspect the result: The incident report can reproduce the symptom without private credentials.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The incident report can reproduce the symptom without private credentials." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Fill incident-template.md with working directory, Python version, input, expected result, actual output and one diagnostic. Ask the agent to identify missing observability before it suggests a fix.", "The incident report can reproduce the symptom without private credentials." ] }, "step_id": "L06-S01", "lesson_id": "L06" }, { "title": "Create a project operating manual", "purpose": "A project environment includes docs, source, tests, logs and saved evidence, not only a clever prompt.", "user_action": "Write AGENTS.md in the practice folder: objective, directory map, install/run/test commands, logs location, boundaries and stop condition. Keep verification in a dedicated file.", "explanation": "A project environment includes docs, source, tests, logs and saved evidence, not only a clever prompt.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "AGENTS.md contains reproducible run/test commands and explains the directory structure.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Create a project operating manual", "success_condition": "AGENTS.md contains reproducible run/test commands and explains the directory structure.", "how_to_verify": "Record aGENTS.md contains reproducible run/test commands and explains the directory structure. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "AGENTS.md contains reproducible run/test commands and explains the directory structure.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. AGENTS.md contains reproducible run/test commands and explains the directory structure.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify create a project operating manual?", "answer": "AGENTS.md contains reproducible run/test commands and explains the directory structure. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to create a project operating manual. AGENTS.md contains reproducible run/test commands and explains the directory structure.", "demo": "Write AGENTS.md in the practice folder: objective, directory map, install/run/test commands, logs location, boundaries and stop condition. Keep verification in a dedicated file.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate create a project operating manual", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write AGENTS.md in the practice folder: objective, directory map, install/run/test commands, logs location, boundaries and stop condition. Keep verification in a dedicated file. AGENTS.md contains reproducible run/test commands and explains the directory structure.", "on_screen_text": [ "Create a project operating manual", "AGENTS.md contains reproducible run/test commands and explains the directory structure." ], "screen_recording_instructions": [ "Write AGENTS.md in the practice folder: objective, directory map, install/run/test commands, logs location, boundaries and stop condition. Keep verification in a dedicated file.", "Inspect the result: AGENTS.md contains reproducible run/test commands and explains the directory structure.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "AGENTS.md contains reproducible run/test commands and explains the directory structure." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write AGENTS.md in the practice folder: objective, directory map, install/run/test commands, logs location, boundaries and stop condition. Keep verification in a dedicated file.", "AGENTS.md contains reproducible run/test commands and explains the directory structure." ] }, "step_id": "L07-S01", "lesson_id": "L07" }, { "title": "Practice inspect, test, correct and review", "purpose": "Correction should respond to an observed mismatch; do not repeatedly regenerate the project without a diagnosis.", "user_action": "Write the sequence DEFINE → INSPECT → PLAN → EXECUTE → TEST → OBSERVE → DIAGNOSE → CORRECT → VERIFY → REVIEW. Use the agent for a docstring change, then run verification independently and inspect the diff.", "explanation": "Correction should respond to an observed mismatch; do not repeatedly regenerate the project without a diagnosis.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python verify.py", "macos": "python3 verify.py", "linux": "python3 verify.py" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Practice inspect, test, correct and review", "success_condition": "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "how_to_verify": "Record only the requested docstring changed; VERIFY PASS and a reviewed diff are retained. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify practice inspect, test, correct and review?", "answer": "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to practice inspect, test, correct and review. Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "demo": "Write the sequence DEFINE → INSPECT → PLAN → EXECUTE → TEST → OBSERVE → DIAGNOSE → CORRECT → VERIFY → REVIEW. Use the agent for a docstring change, then run verification independently and inspect the diff.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate practice inspect, test, correct and review", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write the sequence DEFINE → INSPECT → PLAN → EXECUTE → TEST → OBSERVE → DIAGNOSE → CORRECT → VERIFY → REVIEW. Use the agent for a docstring change, then run verification independently and inspect the diff. Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "on_screen_text": [ "Practice inspect, test, correct and review", "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained." ], "screen_recording_instructions": [ "Write the sequence DEFINE → INSPECT → PLAN → EXECUTE → TEST → OBSERVE → DIAGNOSE → CORRECT → VERIFY → REVIEW. Use the agent for a docstring change, then run verification independently and inspect the diff.", "Inspect the result: Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write the sequence DEFINE → INSPECT → PLAN → EXECUTE → TEST → OBSERVE → DIAGNOSE → CORRECT → VERIFY → REVIEW. Use the agent for a docstring change, then run verification independently and inspect the diff.", "Only the requested docstring changed; VERIFY PASS and a reviewed diff are retained." ] }, "step_id": "L08-S01", "lesson_id": "L08" }, { "title": "Write an eight-step recovery plan", "purpose": "Do not become the agent’s only stack trace; give it direct diagnostic access inside the authorized scope.", "user_action": "Record: stop retries, preserve stderr/logs, locate last checkpoint, inspect environment, reproduce minimally, form one hypothesis, delegate smallest repair, independently verify and review. Apply the plan to a deliberately missing practice input.", "explanation": "Do not become the agent’s only stack trace; give it direct diagnostic access inside the authorized scope.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The recovery plan has eight steps and an observed failure/recovery pair.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Write an eight-step recovery plan", "success_condition": "The recovery plan has eight steps and an observed failure/recovery pair.", "how_to_verify": "Record the recovery plan has eight steps and an observed failure/recovery pair. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The recovery plan has eight steps and an observed failure/recovery pair.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The recovery plan has eight steps and an observed failure/recovery pair.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify write an eight-step recovery plan?", "answer": "The recovery plan has eight steps and an observed failure/recovery pair. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to write an eight-step recovery plan. The recovery plan has eight steps and an observed failure/recovery pair.", "demo": "Record: stop retries, preserve stderr/logs, locate last checkpoint, inspect environment, reproduce minimally, form one hypothesis, delegate smallest repair, independently verify and review. Apply the plan to a deliberately missing practice input.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate write an eight-step recovery plan", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Record: stop retries, preserve stderr/logs, locate last checkpoint, inspect environment, reproduce minimally, form one hypothesis, delegate smallest repair, independently verify and review. Apply the plan to a deliberately missing practice input. The recovery plan has eight steps and an observed failure/recovery pair.", "on_screen_text": [ "Write an eight-step recovery plan", "The recovery plan has eight steps and an observed failure/recovery pair." ], "screen_recording_instructions": [ "Record: stop retries, preserve stderr/logs, locate last checkpoint, inspect environment, reproduce minimally, form one hypothesis, delegate smallest repair, independently verify and review. Apply the plan to a deliberately missing practice input.", "Inspect the result: The recovery plan has eight steps and an observed failure/recovery pair.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The recovery plan has eight steps and an observed failure/recovery pair." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Record: stop retries, preserve stderr/logs, locate last checkpoint, inspect environment, reproduce minimally, form one hypothesis, delegate smallest repair, independently verify and review. Apply the plan to a deliberately missing practice input.", "The recovery plan has eight steps and an observed failure/recovery pair." ] }, "step_id": "L09-S01", "lesson_id": "L09" }, { "title": "Ask for system-level diagnosis", "purpose": "A useful investigator can inspect its environment and explain what it knows and what it has not checked.", "user_action": "Give the agent incident-template.md, app.py and verify.py. Request a diagnostic summary citing the exact file/line and failing assertion. Ask it to gather its own command output, then separate facts from hypotheses.", "explanation": "A useful investigator can inspect its environment and explain what it knows and what it has not checked.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The diagnosis names a failing case, observed evidence and one testable hypothesis.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Ask for system-level diagnosis", "success_condition": "The diagnosis names a failing case, observed evidence and one testable hypothesis.", "how_to_verify": "Record the diagnosis names a failing case, observed evidence and one testable hypothesis. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The diagnosis names a failing case, observed evidence and one testable hypothesis.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The diagnosis names a failing case, observed evidence and one testable hypothesis.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify ask for system-level diagnosis?", "answer": "The diagnosis names a failing case, observed evidence and one testable hypothesis. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to ask for system-level diagnosis. The diagnosis names a failing case, observed evidence and one testable hypothesis.", "demo": "Give the agent incident-template.md, app.py and verify.py. Request a diagnostic summary citing the exact file/line and failing assertion. Ask it to gather its own command output, then separate facts from hypotheses.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate ask for system-level diagnosis", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Give the agent incident-template.md, app.py and verify.py. Request a diagnostic summary citing the exact file/line and failing assertion. Ask it to gather its own command output, then separate facts from hypotheses. The diagnosis names a failing case, observed evidence and one testable hypothesis.", "on_screen_text": [ "Ask for system-level diagnosis", "The diagnosis names a failing case, observed evidence and one testable hypothesis." ], "screen_recording_instructions": [ "Give the agent incident-template.md, app.py and verify.py. Request a diagnostic summary citing the exact file/line and failing assertion. Ask it to gather its own command output, then separate facts from hypotheses.", "Inspect the result: The diagnosis names a failing case, observed evidence and one testable hypothesis.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The diagnosis names a failing case, observed evidence and one testable hypothesis." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Give the agent incident-template.md, app.py and verify.py. Request a diagnostic summary citing the exact file/line and failing assertion. Ask it to gather its own command output, then separate facts from hypotheses.", "The diagnosis names a failing case, observed evidence and one testable hypothesis." ] }, "step_id": "L10-S01", "lesson_id": "L10" }, { "title": "Classify the decision boundaries", "purpose": "Increasing autonomy is a design decision tied to evidence and reversibility, not a global trust switch.", "user_action": "Make a three-row table: assisted (you choose each action), supervised (bounded task with review), autonomous (preapproved bounded loop with stop rules). Place code edits, test runs, external messages and production deploys into the appropriate policy.", "explanation": "Increasing autonomy is a design decision tied to evidence and reversibility, not a global trust switch.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The table distinguishes all three levels and requires explicit review for external actions.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Classify the decision boundaries", "success_condition": "The table distinguishes all three levels and requires explicit review for external actions.", "how_to_verify": "Record the table distinguishes all three levels and requires explicit review for external actions. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The table distinguishes all three levels and requires explicit review for external actions.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The table distinguishes all three levels and requires explicit review for external actions.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify classify the decision boundaries?", "answer": "The table distinguishes all three levels and requires explicit review for external actions. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to classify the decision boundaries. The table distinguishes all three levels and requires explicit review for external actions.", "demo": "Make a three-row table: assisted (you choose each action), supervised (bounded task with review), autonomous (preapproved bounded loop with stop rules). Place code edits, test runs, external messages and production deploys into the appropriate policy.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate classify the decision boundaries", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Make a three-row table: assisted (you choose each action), supervised (bounded task with review), autonomous (preapproved bounded loop with stop rules). Place code edits, test runs, external messages and production deploys into the appropriate policy. The table distinguishes all three levels and requires explicit review for external actions.", "on_screen_text": [ "Classify the decision boundaries", "The table distinguishes all three levels and requires explicit review for external actions." ], "screen_recording_instructions": [ "Make a three-row table: assisted (you choose each action), supervised (bounded task with review), autonomous (preapproved bounded loop with stop rules). Place code edits, test runs, external messages and production deploys into the appropriate policy.", "Inspect the result: The table distinguishes all three levels and requires explicit review for external actions.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The table distinguishes all three levels and requires explicit review for external actions." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Make a three-row table: assisted (you choose each action), supervised (bounded task with review), autonomous (preapproved bounded loop with stop rules). Place code edits, test runs, external messages and production deploys into the appropriate policy.", "The table distinguishes all three levels and requires explicit review for external actions." ] }, "step_id": "L11-S01", "lesson_id": "L11" }, { "title": "Define the overseer duties", "purpose": "Human judgment remains necessary for priorities, ambiguous requirements and release risk.", "user_action": "Write the duties for this project: define outcome, constrain scope, provide tools/context, demand evidence, review diffs, protect data, monitor cost and decide whether to release. Assign an owner to every duty.", "explanation": "Human judgment remains necessary for priorities, ambiguous requirements and release risk.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "expected_result": "The job description names an accountable owner and check for each duty.", "resources": [ "delegation.md", "incident-template.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Define the overseer duties", "success_condition": "The job description names an accountable owner and check for each duty.", "how_to_verify": "Record the job description names an accountable owner and check for each duty. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The job description names an accountable owner and check for each duty.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The job description names an accountable owner and check for each duty.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify define the overseer duties?", "answer": "The job description names an accountable owner and check for each duty. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, incident-template.md, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to define the overseer duties. The job description names an accountable owner and check for each duty.", "demo": "Write the duties for this project: define outcome, constrain scope, provide tools/context, demand evidence, review diffs, protect data, monitor cost and decide whether to release. Assign an owner to every duty.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate define the overseer duties", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write the duties for this project: define outcome, constrain scope, provide tools/context, demand evidence, review diffs, protect data, monitor cost and decide whether to release. Assign an owner to every duty. The job description names an accountable owner and check for each duty.", "on_screen_text": [ "Define the overseer duties", "The job description names an accountable owner and check for each duty." ], "screen_recording_instructions": [ "Write the duties for this project: define outcome, constrain scope, provide tools/context, demand evidence, review diffs, protect data, monitor cost and decide whether to release. Assign an owner to every duty.", "Inspect the result: The job description names an accountable owner and check for each duty.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The job description names an accountable owner and check for each duty." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write the duties for this project: define outcome, constrain scope, provide tools/context, demand evidence, review diffs, protect data, monitor cost and decide whether to release. Assign an owner to every duty.", "The job description names an accountable owner and check for each duty." ] }, "step_id": "L12-S01", "lesson_id": "L12" }, { "title": "Break a practice copy and reproduce", "purpose": "sum(set(items)) loses repeated inputs; a failing reproducible check is the starting evidence.", "user_action": "In this practice folder only, copy broken_app.py over app.py. Run verify.py and retain the repeated-input assertion failure. Do not change verify.py.", "explanation": "sum(set(items)) loses repeated inputs; a failing reproducible check is the starting evidence.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "Copy-Item -LiteralPath broken_app.py -Destination app.py\npython verify.py", "macos": "cp broken_app.py app.py\npython3 verify.py", "linux": "cp broken_app.py app.py\npython3 verify.py" }, "command_type": "shell", "required_inputs": [ "broken_app.py", "app.py", "verify.py" ], "expected_result": "The repeated-input case fails before repair; the test remains unchanged.", "resources": [ "broken_app.py", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Break a practice copy and reproduce", "success_condition": "The repeated-input case fails before repair; the test remains unchanged.", "how_to_verify": "Record the repeated-input case fails before repair; the test remains unchanged. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The repeated-input case fails before repair; the test remains unchanged.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The repeated-input case fails before repair; the test remains unchanged.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify break a practice copy and reproduce?", "answer": "The repeated-input case fails before repair; the test remains unchanged. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use broken_app.py, app.py, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to break a practice copy and reproduce. The repeated-input case fails before repair; the test remains unchanged.", "demo": "In this practice folder only, copy broken_app.py over app.py. Run verify.py and retain the repeated-input assertion failure. Do not change verify.py.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate break a practice copy and reproduce", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "In this practice folder only, copy broken_app.py over app.py. Run verify.py and retain the repeated-input assertion failure. Do not change verify.py. The repeated-input case fails before repair; the test remains unchanged.", "on_screen_text": [ "Break a practice copy and reproduce", "The repeated-input case fails before repair; the test remains unchanged." ], "screen_recording_instructions": [ "In this practice folder only, copy broken_app.py over app.py. Run verify.py and retain the repeated-input assertion failure. Do not change verify.py.", "Inspect the result: The repeated-input case fails before repair; the test remains unchanged.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The repeated-input case fails before repair; the test remains unchanged." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "In this practice folder only, copy broken_app.py over app.py. Run verify.py and retain the repeated-input assertion failure. Do not change verify.py.", "The repeated-input case fails before repair; the test remains unchanged." ] }, "step_id": "L13-S01", "lesson_id": "L13" }, { "title": "Direct the repair without writing it", "purpose": "The finished workflow produces a correct outcome through oversight, diagnosis and independent proof. If no agent is available, the offline rehearsal demonstrates the test but not this delegation outcome.", "user_action": "Give your signed-in agent delegation.md and the failure evidence. Ask it to diagnose and fix app.py only. Do not write the fix yourself. Review the minimal diff, independently run verify.py, and record the failure-to-pass pair.", "explanation": "The finished workflow produces a correct outcome through oversight, diagnosis and independent proof. If no agent is available, the offline rehearsal demonstrates the test but not this delegation outcome.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python verify.py", "macos": "python3 verify.py", "linux": "python3 verify.py" }, "command_type": "shell", "required_inputs": [ "delegation.md", "verify.py" ], "expected_result": "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "resources": [ "delegation.md", "verify.py" ], "checkpoint": { "what_is_being_checked": "Direct the repair without writing it", "success_condition": "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "how_to_verify": "Record vERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify direct the repair without writing it?", "answer": "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md, verify.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to direct the repair without writing it. VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "demo": "Give your signed-in agent delegation.md and the failure evidence. Ask it to diagnose and fix app.py only. Do not write the fix yourself. Review the minimal diff, independently run verify.py, and record the failure-to-pass pair.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate direct the repair without writing it", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Give your signed-in agent delegation.md and the failure evidence. Ask it to diagnose and fix app.py only. Do not write the fix yourself. Review the minimal diff, independently run verify.py, and record the failure-to-pass pair. VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "on_screen_text": [ "Direct the repair without writing it", "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact." ], "screen_recording_instructions": [ "Give your signed-in agent delegation.md and the failure evidence. Ask it to diagnose and fix app.py only. Do not write the fix yourself. Review the minimal diff, independently run verify.py, and record the failure-to-pass pair.", "Inspect the result: VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Give your signed-in agent delegation.md and the failure evidence. Ask it to diagnose and fix app.py only. Do not write the fix yourself. Review the minimal diff, independently run verify.py, and record the failure-to-pass pair.", "VERIFY PASS follows a minimal agent-authored fix that preserves repeated inputs and leaves verification intact." ] }, "step_id": "L13-S02", "lesson_id": "L13" }, { "title": "Write a repeatable onboarding checklist", "purpose": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "user_action": "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project.", "explanation": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "onboarding-checklist.md" ], "expected_result": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "resources": [ "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Write a repeatable onboarding checklist", "success_condition": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "how_to_verify": "Record the checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify write a repeatable onboarding checklist?", "answer": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use onboarding-checklist.md. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to write a repeatable onboarding checklist. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "demo": "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate write a repeatable onboarding checklist", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "on_screen_text": [ "Write a repeatable onboarding checklist", "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ], "screen_recording_instructions": [ "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project.", "Inspect the result: The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project.", "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ] }, "step_id": "L14-S01", "lesson_id": "L14" }, { "title": "Demonstrate the variable-path limit safely", "purpose": "A command-text hook can miss a target computed inside a script or variable. This demonstrator checks resolved paths but is not an operating-system sandbox. For a real operation, enforce the resolved boundary at the operation itself; symlinks and races still require care.", "user_action": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "explanation": "A command-text hook can miss a target computed inside a script or variable. This demonstrator checks resolved paths but is not an operating-system sandbox. For a real operation, enforce the resolved boundary at the operation itself; symlinks and races still require care.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python workspace_guard.py --self-test", "macos": "python3 workspace_guard.py --self-test", "linux": "python3 workspace_guard.py --self-test" }, "command_type": "shell", "required_inputs": [ "workspace_guard.py" ], "expected_result": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "resources": [ "workspace_guard.py" ], "checkpoint": { "what_is_being_checked": "Demonstrate the variable-path limit safely", "success_condition": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "how_to_verify": "Record gUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "I can repeat this action from the saved input." ], "tokens": [ "GUARD PASS" ], "user_visible_success_message": "Evidence saved. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify demonstrate the variable-path limit safely?", "answer": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use workspace_guard.py. Work in the same practice folder." } ], "quiz": { "question": "Does a command-text hook guarantee safety for a path computed inside a script?", "answer_type": "single_choice", "choices": [ "No; add enforcement at the resolved operation boundary and independent recovery.", "Yes, because the command looks harmless." ], "correct_answer": 0, "explanation": "The profile-wipe failure can involve a runtime variable whose value the text hook cannot see." }, "coach": { "intro": "We are going to demonstrate the variable-path limit safely. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "demo": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate demonstrate the variable-path limit safely", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "on_screen_text": [ "Demonstrate the variable-path limit safely", "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ], "screen_recording_instructions": [ "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "Inspect the result: GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ] }, "step_id": "L14-S02", "lesson_id": "L14" }, { "title": "Verify the actual protection in your tool", "purpose": "A broken hook that blocks everything can look like protection. Some tools fail open when hooks fail. Codex hook changes need review/trust; Grok Build needs its own deny protocol; Antigravity uses a different JSON protocol. Never treat a prompt rule or an inactive hook as enforcement.", "user_action": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "explanation": "A broken hook that blocks everything can look like protection. Some tools fail open when hooks fail. Codex hook changes need review/trust; Grok Build needs its own deny protocol; Antigravity uses a different JSON protocol. Never treat a prompt rule or an inactive hook as enforcement.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "workspace_guard.py", "onboarding-checklist.md" ], "expected_result": "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "resources": [ "workspace_guard.py", "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Verify the actual protection in your tool", "success_condition": "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "how_to_verify": "Record a harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The harmless command succeeds.", "The boundary dry-run denies a profile target.", "I recorded the tool’s active hook state, or explicitly recorded that this tool has no working local guard." ], "tokens": [], "user_visible_success_message": "Evidence saved. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I install a guard for this tool?", "answer": "Use the linked BBB safety reference for the exact tool/version protocol. Merge into the existing hooks instead of overwriting settings. Review/trust the hook if required, then verify a harmless call and a denied dry-run. The workspace_guard.py file is a teaching demonstration, not a universal hook adapter." }, { "question": "Does Grok Bot have a working local delete guard?", "answer": "The project’s live September 29 tests found no working shell hook. Restrict the tasks and workspace you hand it, keep independent backups, and do not claim local deletion is guarded." } ], "quiz": null, "coach": { "intro": "We are going to verify the actual protection in your tool. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "demo": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate verify the actual protection in your tool", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "on_screen_text": [ "Verify the actual protection in your tool", "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ], "screen_recording_instructions": [ "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "Inspect the result: A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ] }, "step_id": "L14-S03", "lesson_id": "L14" }, { "title": "Enable a real backup of memory and project files", "purpose": "System Restore alone is not a personal-file backup. Previous Versions can disappear as shadow storage fills; OneDrive’s common-folder backup omits hidden agent folders.", "user_action": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "explanation": "System Restore alone is not a personal-file backup. Previous Versions can disappear as shadow storage fills; OneDrive’s common-folder backup omits hidden agent folders.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": ".\\profile-backup.ps1 -Destination D:\\Backups\\llm-profiles", "macos": "bash profile-backup.sh /Volumes/YourBackup/llm-profiles", "linux": "bash profile-backup.sh /media/YourBackup/llm-profiles" }, "command_type": "shell", "required_inputs": [ "profile-backup.ps1", "profile-backup.sh", "onboarding-checklist.md" ], "expected_result": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "resources": [ "profile-backup.ps1", "profile-backup.sh", "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Enable a real backup of memory and project files", "success_condition": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "how_to_verify": "Record a backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The destination is a mounted second drive.", "The hidden memory/settings folders and project files are included.", "An automated backup is enabled and its latest successful run is recorded." ], "tokens": [], "user_visible_success_message": "Evidence saved. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The backup drive is missing or the script reports a failure", "likely_cause": "The destination may be on the same volume, unmounted, or unwritable.", "diagnostic_question": "Can you create a scratch file on the actual second drive?", "fix": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures.", "alternative_fix": "Use the operating system backup application and verify the same folder coverage and successful run.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures." } ], "faqs": [ { "question": "How do I verify enable a real backup of memory and project files?", "answer": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use profile-backup.ps1, profile-backup.sh, onboarding-checklist.md. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to enable a real backup of memory and project files. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "demo": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures.", "help": "Can you create a scratch file on the actual second drive?" }, "video": { "purpose": "Demonstrate enable a real backup of memory and project files", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "on_screen_text": [ "Enable a real backup of memory and project files", "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ], "screen_recording_instructions": [ "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "Inspect the result: A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ] }, "step_id": "L14-S04", "lesson_id": "L14" }, { "title": "Practice a hash-verified restore", "purpose": "A backup becomes useful only when restoration has been practiced. A same-volume practice copy proves the procedure but not protection against disk failure.", "user_action": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "explanation": "A backup becomes useful only when restoration has been practiced. A same-volume practice copy proves the procedure but not protection against disk failure.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": "python restore_drill.py --backup-root D:\\Backups\\bbb-practice --work-root practice", "macos": "python3 restore_drill.py --backup-root /Volumes/YourBackup/bbb-practice --work-root practice", "linux": "python3 restore_drill.py --backup-root /media/YourBackup/bbb-practice --work-root practice" }, "command_type": "shell", "required_inputs": [ "restore_drill.py" ], "expected_result": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "resources": [ "restore_drill.py" ], "checkpoint": { "what_is_being_checked": "Practice a hash-verified restore", "success_condition": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "how_to_verify": "Record rESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The proof file SHA256 hashes match.", "I restored and opened a non-secret memory/settings file from my real backup.", "The restored file is in scratch; the live profile was not overwritten." ], "tokens": [ "RESTORE PASS" ], "user_visible_success_message": "Evidence saved. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "How do I verify practice a hash-verified restore?", "answer": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use restore_drill.py. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to practice a hash-verified restore. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "demo": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate practice a hash-verified restore", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "on_screen_text": [ "Practice a hash-verified restore", "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ], "screen_recording_instructions": [ "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "Inspect the result: RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "Record the evidence and check each criterion." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ] }, "step_id": "L14-S05", "lesson_id": "L14" } ], "resources": [ { "resource_id": "R001", "name": "workspace_guard.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\n\"\"\"Dry-run resolved-path boundary demonstration. This script never deletes anything.\"\"\"\nimport argparse\nfrom pathlib import Path\n\ndef permitted(target, workspace):\n root = Path(workspace).resolve()\n candidate = Path(target).resolve()\n home = Path.home().resolve()\n if root == home or root == root.anchor or root in home.parents:\n return False\n return candidate != root and root in candidate.parents and candidate != home and candidate not in home.parents\n\ndef main():\n p=argparse.ArgumentParser(description=__doc__)\n p.add_argument('--workspace',default='practice')\n p.add_argument('--target')\n p.add_argument('--self-test',action='store_true')\n a=p.parse_args()\n root=Path(a.workspace).resolve()\n if a.self_test:\n assert permitted(root/'proof.txt',root)\n assert not permitted(Path.home(),root)\n assert not permitted(root.parent/'outside.txt',root)\n assert not permitted(root,root)\n variable_target=Path.home()\n assert not permitted(variable_target,root)\n print('GUARD PASS: inside allowed; profile, variable-derived profile, outside, workspace root denied; no deletion executed')\n else:\n if not a.target:p.error('--target required')\n allowed=permitted(a.target,a.workspace)\n print(('ALLOW' if allowed else 'DENY')+': resolved boundary; dry-run only')\n raise SystemExit(0 if allowed else 2)\nif __name__=='__main__':main()\n", "filename": "workspace_guard.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R002", "name": "restore_drill.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\n\"\"\"Backup and restore a new proof file only; never edits an existing file or profile.\"\"\"\nimport argparse,hashlib,json,logging\nfrom datetime import datetime,timezone\nfrom pathlib import Path\nimport shutil\ndef digest(p):return hashlib.sha256(p.read_bytes()).hexdigest()\ndef main():\n a=argparse.ArgumentParser(description=__doc__)\n a.add_argument('--backup-root',required=True)\n a.add_argument('--work-root',default='practice')\n x=a.parse_args()\n run=datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')\n work=Path(x.work_root).resolve()/('restore-'+run)\n backup=Path(x.backup_root).resolve()/('restore-'+run)\n if work==backup or work in backup.parents or backup in work.parents:raise SystemExit('Use separate, non-overlapping work and backup roots')\n work.mkdir(parents=True,exist_ok=False);backup.mkdir(parents=True,exist_ok=False)\n logging.basicConfig(filename=work/'drill.log',encoding='utf-8',level=logging.INFO)\n source=work/'proof.txt';source.write_text('BuildBotsBetter restore proof '+run,encoding='utf-8')\n shutil.copy2(source,backup/'proof.txt')\n restored=work/'restored.txt';shutil.copy2(backup/'proof.txt',restored)\n assert digest(source)==digest(restored)\n receipt={'result':'RESTORE PASS','source_sha256':digest(source),'restored_sha256':digest(restored),'backup_root':str(backup),'off_volume':work.anchor.lower()!=backup.anchor.lower(),'scope':'new proof file only; does not establish a scheduled profile backup'}\n (work/'receipt.json').write_text(json.dumps(receipt,indent=2),encoding='utf-8')\n logging.info('Proof backup and hash-verified restore completed')\n print(json.dumps(receipt,indent=2))\n if not receipt['off_volume']:print('SAME VOLUME: practice passed; configure a second drive for disaster recovery')\nif __name__=='__main__':main()\n", "filename": "restore_drill.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R003", "name": "onboarding-checklist.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Repeatable agent onboarding\nagent:\ntool version:\nrules file:\nmemory/settings location:\nassigned workspace:\npermissions / actions needing approval:\nhook location and protocol:\nguard active (harmless command + denied dry-run):\nvariable-derived path limit understood:\nbackup destination (second drive):\nbackup schedule / last successful run:\nrestored memory file / matching SHA256:\nfinal task / evidence / reviewer:\n\nProtect memory/settings and project files. A prompt rule is not an operating-system boundary.\nA command-text hook can miss a path computed in a script or variable. Resolve paths at the\noperation boundary and fail closed; keep independent backups and monitoring.\nWindows System Restore reverts system components, not a reliable personal-file backup.\nOneDrive folder backup does not automatically include hidden agent folders.\nmacOS: check Time Machine includes hidden agent folders. Linux: Timeshift excludes /home by\ndefault; use a separate home backup or explicitly include it.\n", "filename": "onboarding-checklist.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R004", "name": "profile-backup.ps1", "type": "ps1", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: copy-only explicit profile backup.\nparam([Parameter(Mandatory=$true)][string]$Destination,[string]$ProjectPath=(Get-Location).Path)\n$ErrorActionPreference='Stop'\n$destRoot=[IO.Path]::GetFullPath($Destination)\n$profileRoot=[IO.Path]::GetFullPath($env:USERPROFILE)\nif ([IO.Path]::GetPathRoot($destRoot) -eq [IO.Path]::GetPathRoot($profileRoot)) { throw 'Choose a backup destination on a second drive.' }\nif (-not (Test-Path -LiteralPath ([IO.Path]::GetPathRoot($destRoot)))) { throw 'Backup drive is unavailable.' }\n$runDir=Join-Path $destRoot (Get-Date -Format 'yyyyMMdd-HHmmss-fff')\nNew-Item -ItemType Directory -Path $runDir -ErrorAction Stop | Out-Null\nforeach ($folderName in @('.codex','.claude','.grok','.qwen','.gemini')) {\n $sourceDir=Join-Path $profileRoot $folderName\n if (Test-Path -LiteralPath $sourceDir) {\n $copyDir=Join-Path $runDir $folderName\n & robocopy $sourceDir $copyDir /E /XJ /R:1 /W:1 /COPY:DAT /DCOPY:DAT /NP\n if ($LASTEXITCODE -ge 8) { throw \"Backup failed for $folderName (robocopy $LASTEXITCODE).\" }\n }\n}\n$projectSource=[IO.Path]::GetFullPath($ProjectPath)\nif (-not (Test-Path -LiteralPath $projectSource -PathType Container)) { throw 'Project directory is unavailable.' }\n& robocopy $projectSource (Join-Path $runDir 'project') /E /XJ /R:1 /W:1 /COPY:DAT /DCOPY:DAT /NP\nif ($LASTEXITCODE -ge 8) { throw \"Project backup failed (robocopy $LASTEXITCODE).\" }\n\"PROFILE BACKUP PASS: $runDir\"\n# Copy-only: no /MIR, /PURGE or deletion. Backup may contain credentials; protect the drive.\n# Add the Grok Bot profile and project path explicitly after finding them in your own installation.\n", "filename": "profile-backup.ps1", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R005", "name": "profile-backup.sh", "type": "sh", "purpose": "Working resource used by this Build; inspect before running.", "contents": "#!/usr/bin/env bash\n# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: copy-only explicit profile backup.\nset -euo pipefail\ndest=${1:?Pass a mounted external-drive backup directory}\nproject=${2:-$PWD}\nmkdir -p \"$dest\"\nif [ \"$(df -P \"$HOME\" | tail -1 | awk '{print $1}')\" = \"$(df -P \"$dest\" | tail -1 | awk '{print $1}')\" ]; then\n echo 'Choose a destination on another mounted filesystem.' >&2; exit 2\nfi\nrun=\"$dest/$(date -u +%Y%m%dT%H%M%SZ)-$$\"\nmkdir \"$run\"\nfor name in .codex .claude .grok .qwen .gemini; do\n if [ -d \"$HOME/$name\" ]; then cp -pR \"$HOME/$name\" \"$run/$name\"; fi\ndone\nif [ ! -d \"$project\" ]; then echo 'Project directory is unavailable.' >&2; exit 2; fi\ncp -pR \"$project\" \"$run/project\"\necho \"PROFILE BACKUP PASS: $run\"\n# This backup can contain credentials; protect access to the backup drive.\n", "filename": "profile-backup.sh", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R006", "name": "app.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\ndef total(items):\n return sum(items)\nif __name__ == '__main__':\n print('APP PASS: total=' + str(total([2, 3, 5])))\n", "filename": "app.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R007", "name": "verify.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\nfrom app import total\nassert total([])==0\nassert total([2,3,5])==10\nassert total([-2,2])==0\nassert total([2,2])==4\nprint('VERIFY PASS: empty, ordinary, signed, repeated inputs')\n", "filename": "verify.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R008", "name": "broken_app.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\ndef total(items):\n return sum(set(items))\n", "filename": "broken_app.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R009", "name": "delegation.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Bounded delegation\nObjective: make the supplied total function preserve repeated inputs.\nScope: app.py only; inspect verify.py, do not weaken it.\nConstraints: no network, no dependencies, no external writes, no profile cleanup.\nVerification: run python verify.py; include exit code and complete output.\nEvidence: failing case before, diagnosis, minimal diff, passing case after.\nStop: ask if the fix needs files outside this practice directory.\nReview: human checks the diff and reruns verification independently.\n", "filename": "delegation.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R010", "name": "incident-template.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Incident evidence\nWhat I tried:\nExpected result:\nObserved result / complete error:\nReproduce command and exit code:\nRelevant environment versions:\nWorking directory:\nOne hypothesis:\nSmallest diagnostic:\nCorrective action:\nIndependent verification:\nRecovery point:\n", "filename": "incident-template.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" } ], "bot_coach": { "bot_name": "Buzz", "bot_role": "Offline reviewed step coach", "personality": "patient and concrete", "tone": "plain", "teaching_style": "hint, diagnostic, action, checkpoint", "introduction": "Ask about the current step. I use reviewed local answers and queue unknown questions for review.", "encouragement_style": "Focus on observed results.", "troubleshooting_style": "Ask for the smallest reproducible evidence.", "limits": "This offline coach does not call an LLM or inspect your computer. Unknown questions enter a local exportable review queue, not a shared SQL FAQ." }, "coach_interaction_model": { "stuck": "current diagnostic and first repair", "meaning": "current explanation", "error": "current troubleshooting", "why": "purpose", "skip": "require equivalent evidence", "alternative": "documented alternative", "finished": "record actual output", "start_over": "export then reset only this Build", "progressive_assistance": [ "hint", "diagnostic", "walkthrough", "resource solution" ] }, "website_specification": { "layout": "Lesson outline, actionable step, current-context coach", "features": [ "platform selectors", "command copy with selection fallback", "evidence checklist", "practical quiz", "downloadable resource ZIP", "local progress", "evidence export", "unknown-question review queue" ], "checkpoint_model": "Learner supplies observations/output; tokens check expected shape only, not host truth.", "navigation": "Browse freely; checked next-button progression retains evidence.", "video": "spec-driven walkthrough and optional speech; full rendered media is a downstream production task." }, "final_test": { "test_name": "Repeat the core workflow and restore its evidence", "instructions": "Repeat the last product-specific checkpoint from a fresh practice input, preserve actual output, then complete the Build Bot Better guard and restore checks. Export the evidence.", "required_inputs": [ "workspace_guard.py", "restore_drill.py", "onboarding-checklist.md", "app.py", "verify.py", "broken_app.py", "delegation.md", "incident-template.md" ], "success_conditions": [ "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "Core output can be reproduced", "Guard limit explained", "Backup and restoration evidence retained" ], "automated_tests": "catalog_check.py records browser behavior and executable resources, with explicit scope.", "manual_tests": [ "Review actual account sign-in where needed", "Check source/data assumptions", "Restore one real non-secret memory file" ], "expected_output": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "failure_paths": "Use the specific step diagnostic, retain failure evidence and stop when access is required." }, "extensions": [ { "title": "Use your own input", "action": "Replace the sample with one permitted real input and rerun the same checks." }, { "title": "Add one failure case", "action": "Create a malformed or missing input; prove the workflow fails visibly and recovers." }, { "title": "Automate after review", "action": "Write a bounded schedule with logging and a stop condition; obtain approval for external actions separately." } ], "metadata": { "SEO_title": "Shifting from Workgentic to Agentic Workflow | BuildBotsBetter", "SEO_description": "A bounded agentic development environment with a task brief, operating manual, diagnostic harness and an independently verified agent repair of a deliberately broken application.", "SEO_keywords": [ "workgentic-to-agentic", "guided build", "verified outcome" ], "difficulty": "beginner", "related_builds": [ "dogfooding", "buildbotsbetter-onboarding" ], "next_recommended_build": "dogfooding" }, "automation_map": [ { "output": "website", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "walkthrough", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "bot dialogue", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "resources", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "quiz", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "captions", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "metadata", "generated_from": "BUILD_SPEC.json", "human_review_required": true } ], "quality_assurance_report": { "scope": "Original instructional content, reviewed against shared brief; execution and browser receipts are stored under logs/catalog-acceptance.", "known_limits": [ "macOS branches require verification on a real Mac.", "Account sign-in, eligibility and subscriptions must be verified by the learner.", "Browser evidence completion is self-reported; it is not machine access to a host." ] }, "sources": [ { "title": "Shared 12-module course brief", "url": "../../specs/workgentic-to-agentic.md" } ], "known_uncertainties": [ "External tool interfaces and plan availability can change; check the linked official source and local --help." ] }