feat: initial companion repo for CC-001 Agent Loop

exercises/01-watch-the-loop.md

@@ -0,0 +1,107 @@
+# Exercise 01: Watch the Loop
+
+**Concept:** The Agent Loop (CC-001)
+**Level:** Basic
+**Time:** ~10 minutes
+
+---
+
+## Objective
+
+Watch Claude Code execute a multi-step task from start to finish.
+You will see the agent loop in action: Claude reads, thinks, picks
+a tool, observes the result, and repeats until done.
+
+This is your first hands-on contact with the agent loop. No prior
+experience with Claude Code required beyond having it installed.
+
+---
+
+## Before You Start
+
+Confirm you have:
+
+- [ ] Claude Code installed (`claude --version` prints a version)
+- [ ] This repo cloned and open in your terminal
+- [ ] Started Claude Code in this directory (`claude`)
+
+---
+
+## Instructions
+
+**Step 1:** Open Claude Code in this repo directory.
+
+```bash
+cd claude-code-agent-loop
+claude
+```
+
+**Step 2:** Paste this prompt into Claude Code:
+
+```
+Create a file called loop-demo.md that contains:
+
+1. Today's date and time
+2. A list of all files in this directory with their sizes
+3. The first 5 lines of README.md
+4. A summary sentence describing what this repo is about
+
+Do not ask me any questions. Just do it.
+```
+
+**Step 3:** Watch the terminal output carefully as Claude works.
+
+You will see Claude make a series of tool calls. Pay attention to:
+- Which tools Claude picks (Bash, Read, Write, Glob)
+- The order it chooses to do things
+- How it uses the output of one step to inform the next
+- That you did not tell it which tools to use or what order
+
+**Step 4:** Read the generated `loop-demo.md` file.
+
+Check that it contains all four items from the prompt. Claude gathered
+information from multiple sources (system clock, file system, file
+contents) and synthesized them into one output file.
+
+---
+
+## Expected Output
+
+After 15-30 seconds, you should see:
+
+- A new file `loop-demo.md` in the repo root
+- It contains today's date (from a Bash call to `date`)
+- It lists files with sizes (from `ls -la` or similar)
+- It includes the first 5 lines of README.md (from Read tool)
+- It ends with a summary sentence about the repo
+
+The exact content varies, but the structure should match.
+
+**How you know the agent loop worked:**
+- Claude made 3-5 tool calls without asking you anything between them
+- Each tool call built on information from the previous one
+- The final file synthesizes data from multiple sources
+
+---
+
+## What You Learned
+
+- **The loop is autonomous:** Claude decided the order and tools on its own
+- **Each step informs the next:** The loop observes results before choosing the next action
+- **The task, not the steps, is what you specify:** You said what you wanted, not how to get it
+
+---
+
+## Clean Up
+
+Delete the generated file so the repo stays clean:
+
+```bash
+rm loop-demo.md
+```
+
+---
+
+## Next
+
+Ready to go further? Move to [Exercise 02: Control the Loop](./02-control-the-loop.md).

exercises/02-control-the-loop.md

@@ -0,0 +1,148 @@
+# Exercise 02: Control the Loop
+
+**Concept:** The Agent Loop (CC-001)
+**Level:** Intermediate
+**Time:** ~15 minutes
+
+---
+
+## Objective
+
+Learn to steer the agent loop instead of just watching it. You will
+use Plan Mode to preview what Claude intends to do before it acts,
+and use /rewind to undo a wrong turn.
+
+Exercise 01 showed the loop running freely. This exercise shows you
+the controls.
+
+---
+
+## Before You Start
+
+Confirm you have:
+
+- [ ] Completed Exercise 01 (or understand the basic loop concept)
+- [ ] Claude Code open in this directory
+
+---
+
+## Part A: Plan Mode
+
+**Step 1:** Press `Shift+Tab` until the mode indicator shows **plan**.
+
+You should see the permission mode change in the bottom bar. In Plan
+Mode, Claude will describe what it plans to do instead of doing it.
+
+**Step 2:** Paste this prompt:
+
+```
+Create a project structure for a simple blog:
+- A folder called blog/ with index.html, style.css, and posts/
+- An about.html page
+- A README.md explaining the structure
+```
+
+**Step 3:** Read Claude's plan.
+
+Claude will describe the files it would create, the structure, and
+the content. It will NOT create anything yet. This is the plan.
+
+**Step 4:** If the plan looks good, type:
+
+```
+Go ahead, execute this plan.
+```
+
+Or press `Shift+Tab` back to a normal mode and re-send the prompt.
+
+Claude now executes, creating the actual files.
+
+**Why this matters:** For complex tasks where a wrong start wastes
+time, Plan Mode lets you course-correct before any files are written.
+
+---
+
+## Part B: Using /rewind
+
+**Step 1:** Give Claude an intentionally vague prompt:
+
+```
+Improve the blog project.
+```
+
+Claude will likely make some changes you did not expect or want.
+That is the point of this exercise.
+
+**Step 2:** After Claude finishes, review what it changed. If the
+changes are not what you wanted, type:
+
+```
+/rewind
+```
+
+This restores your context to the state before Claude's last action.
+The files are unchanged (Claude did write them), but the conversation
+context is rewound so you can try a different approach.
+
+**Step 3:** Now give a more specific prompt:
+
+```
+Add a navigation bar to index.html that links to about.html.
+Do not change anything else.
+```
+
+Notice how specificity gives the loop better direction.
+
+---
+
+## Part C: Stopping a Runaway Loop
+
+**Step 1:** Give Claude a deliberately open-ended task:
+
+```
+Make this blog production-ready.
+```
+
+**Step 2:** As Claude starts working (adding frameworks, build tools,
+etc.), press `Escape` to interrupt.
+
+Claude stops mid-execution. You can then redirect:
+
+```
+Stop. I just want the HTML and CSS to be clean and valid.
+No frameworks, no build tools.
+```
+
+---
+
+## Expected Output
+
+After completing all three parts:
+
+- A `blog/` directory with `index.html`, `style.css`, `posts/`, `about.html`, `README.md`
+- You experienced Plan Mode (preview before execution)
+- You used /rewind to undo a vague prompt
+- You interrupted a runaway loop with Escape
+
+---
+
+## What You Learned
+
+- **Plan Mode previews:** Shift+Tab toggles Plan Mode, where Claude describes its plan before acting
+- **/rewind undoes context:** It rolls back the conversation so you can try a different approach
+- **Escape interrupts:** Press Escape to stop Claude mid-loop when it is going in the wrong direction
+- **Specificity guides the loop:** Vague prompts produce unpredictable results. Specific prompts keep the loop on track.
+
+---
+
+## Clean Up
+
+```bash
+rm -rf blog/ about.html
+```
+
+---
+
+## Next
+
+Ready to design prompts that work with the loop? Move to [Exercise 03: Design for the Loop](./03-design-for-the-loop.md).

exercises/03-design-for-the-loop.md

@@ -0,0 +1,146 @@
+# Exercise 03: Design for the Loop
+
+**Concept:** The Agent Loop (CC-001)
+**Level:** Advanced
+**Time:** ~20 minutes
+
+---
+
+## Objective
+
+Design a multi-step task that takes advantage of the agent loop's
+strengths. You will write a prompt that requires Claude to gather
+information from multiple sources, make decisions based on what it
+finds, and produce a structured output.
+
+This exercise has no step-by-step walkthrough. You get a scenario,
+constraints, and success criteria. How you get there is up to you.
+
+---
+
+## Before You Start
+
+Confirm you have:
+
+- [ ] Completed Exercises 01 and 02
+- [ ] Claude Code open in this directory
+- [ ] Internet access (Claude will use WebSearch)
+
+---
+
+## The Scenario
+
+You want to evaluate whether a specific open-source tool is worth
+adopting for your workflow. Instead of spending an hour researching
+manually, you will write one prompt that makes Claude do the research
+for you.
+
+## Your Task
+
+Write a prompt that makes Claude:
+
+1. **Search** for information about a tool you are curious about
+   (pick any real tool: a CLI tool, a library, a framework)
+2. **Read** the tool's documentation or README
+3. **Compare** it against an alternative you already know
+4. **Write** a structured evaluation to a file called `evaluation.md`
+
+The evaluation file must include:
+- Tool name and what it does (one sentence)
+- Three strengths
+- Three weaknesses or limitations
+- A direct comparison with the alternative
+- A verdict: adopt, wait, or skip
+
+## Constraints
+
+- Your prompt must be a single message (no back-and-forth)
+- Do not tell Claude which tools to use (let the loop decide)
+- The output must be a single file, not multiple files
+- Use Plan Mode first to preview, then execute
+
+## Success Criteria
+
+- [ ] Claude made at least 5 tool calls to complete the task
+- [ ] The evaluation file exists and contains all required sections
+- [ ] The strengths and weaknesses are specific (not generic praise)
+- [ ] The comparison is direct, not just two separate descriptions
+- [ ] The verdict gives a clear recommendation with reasoning
+
+---
+
+## Hints (only if stuck)
+
+<details>
+<summary>Hint 1: Prompt structure</summary>
+
+A good prompt for the agent loop includes:
+- What to research (specific tool name)
+- What to compare against (specific alternative)
+- What output to produce (file name and structure)
+- What NOT to do (no installation, no code generation)
+
+</details>
+
+<details>
+<summary>Hint 2: Example prompt skeleton</summary>
+
+```
+Research [tool X] and compare it to [tool Y] for [use case].
+
+Search the web for recent reviews and the official docs.
+Write an evaluation to evaluation.md with:
+- One-sentence description of each tool
+- 3 specific strengths of [tool X]
+- 3 specific weaknesses of [tool X]
+- Direct comparison table: [tool X] vs [tool Y]
+- Verdict: adopt, wait, or skip, with reasoning
+
+Do not install anything. Do not write code. Research only.
+```
+
+</details>
+
+---
+
+## Reflection
+
+After completing this exercise, consider:
+
+- How many tool calls did Claude make? (Check the terminal output)
+- Did the loop take any detours? Were they useful or wasteful?
+- What would you change in your prompt to get a better result?
+- How long would this research have taken you manually?
+
+The agent loop is most powerful when the task requires gathering
+and synthesizing information from multiple sources. A single prompt
+replaces what used to be 30 minutes of tab-switching and note-taking.
+
+---
+
+## What You Learned
+
+- **Single-prompt, multi-step tasks** are where the agent loop shines
+- **Output structure in the prompt** gives the loop a clear target
+- **Plan Mode first** lets you verify the approach before committing
+- **The loop handles the how:** You specify the what and the where
+
+---
+
+## Clean Up
+
+```bash
+rm evaluation.md
+```
+
+---
+
+## What Comes Next
+
+You now understand the agent loop: what it is (Exercise 01), how to
+control it (Exercise 02), and how to design tasks for it (Exercise 03).
+
+Next concepts to explore:
+- **CC-002 Built-in Tools** - The specific tools the loop uses
+- **CC-010 CLAUDE.md** - How to give the loop standing instructions
+- **CC-006 Permissions** - How to control what the loop is allowed to do