code-stroll 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# code-stroll
+
+Interactive code review learning mode for [opencode](https://github.com/anthropics/opencode).
+
+## What it does
+
+Turns code review into a learning session. Presents diff changes grouped
+semantically, one chunk at a time, with Q&A and proactive explanations.
+
+## Requirements
+
+- [Bun](https://bun.sh) v1.0+
+- [opencode](https://github.com/anthropics/opencode) installed in your project
+- Git
+
+## Installation
+
+### Quick install
+
+Clone the repo and run the install script, passing your project directory:
+
+```bash
+git clone https://github.com/bronteee/code-stroll.git
+cd code-stroll
+./install.sh /path/to/your/project
+```
+
+This copies the command and agent files into your project's `.opencode/` directory and builds the plugin.
+
+### Manual install
+
+1. Copy the command file into your project:
+
+```bash
+cp config/commands/code-stroll.md /path/to/your/project/.opencode/commands/
+```
+
+2. Copy the agent file:
+
+```bash
+cp config/agents/review-agent.md /path/to/your/project/.opencode/agents/
+```
+
+3. Build the plugin:
+
+```bash
+bun install
+bun run build
+```
+
+### Verify installation
+
+After installing, check that the files are in place:
+
+```
+your-project/
+  .opencode/
+    commands/
+      code-stroll.md     ← slash command entry point
+    agents/
+      review-agent.md    ← conversational review agent
+```
+
+## Usage
+
+```
+/code-stroll                          # review current branch vs main
+/code-stroll --depth skim             # flag concerns only
+/code-stroll --focus auth,api         # only review these directories
+/code-stroll --base develop           # diff against develop instead of main
+/code-stroll --resume                 # continue previous session
+```
+
+### Depth modes
+
+- **deep** (default): Explains architectural rationale, notes patterns and alternatives.
+- **skim**: Flags high-severity concerns only (security issues, missing error handling). Keeps explanations under 3 sentences.
+
+### Session controls
+
+During a review session, use these signals to advance:
+
+- `next`, `continue`, `move on` — advance to next chunk
+- `skip` — skip current chunk
+- `done` — end session early
+
+Ask questions at any point — the review agent will answer before moving on.
+
+### Resume
+
+Sessions are persisted to `.opencode/review-session.json`. Use `--resume` to pick up where you left off.
+
+## How it works
+
+1. Plugin creates an isolated git worktree for the branch under review
+2. Runs `git diff` between the branch and base
+3. LLM pre-analysis groups diff hunks semantically (falls back to file-based grouping on error)
+4. Groups are presented one at a time with concerns flagged
+5. Review agent opens Q&A for each group
+6. Session state is saved after each chunk advance
+
+## Design
+
+See `docs/plans/2026-03-01-code-stroll-design.md` for full architecture.

package/config/agents/review-agent.md

@@ -0,0 +1,155 @@
+---
+name: review-agent
+description: Interactive code review learning session
+tools:
+  read: true
+  write: true
+  bash: true
+  code_stroll_start: true
+  code_stroll_cleanup: true
+---
+
+You are guiding an engineer through an interactive code review learning session.
+
+## Starting a session
+
+Use the `code_stroll_start` tool (not bash — it is a registered tool, not a shell
+command) with the parameters provided by the user. The tool returns all diff hunks
+from the branch under review.
+
+## Findings file
+
+At the start of the session, create a findings file using the `write` tool at:
+
+```
+reviews/{YYYY-MM-DD}-{branch}.md
+```
+
+Where `{branch}` is the branch name with `/` replaced by `-`
+(e.g. `reviews/2026-03-03-feat-auth-overhaul.md`).
+
+Initialize it with this header:
+
+```markdown
+# Code Review: {branch}
+
+**Date:** {YYYY-MM-DD}
+**Base:** {base branch}
+**Depth:** {depth}
+
+---
+```
+
+Write findings to this file **incrementally** — append after each chunk is
+reviewed and whenever new findings emerge during Q&A. Every finding MUST
+include the source file path and line number(s) in the original code.
+
+Use this format for each entry:
+
+```markdown
+## Group {N}/{Total}: {label}
+
+### Concerns
+
+- **{short title}** — `{file}:{line}` — {description}
+
+### Observations
+
+- **{short title}** — `{file}:{line}` — {description}
+
+### Q&A findings
+
+- **{short title}** — `{file}:{line}` — {description}
+```
+
+Rules for the findings file:
+- Omit a subsection (Concerns, Observations, Q&A findings) if it has no entries.
+- **Q&A findings** captures new insights that surface during discussion — things
+  the user asked about, connections you discovered while answering, or concerns
+  that only became apparent through conversation.
+- Line numbers must refer to the **original source file** in the repo, not diff
+  line offsets. Use the `read` tool to confirm line numbers when uncertain.
+- Append to the file after each chunk completes. If new findings emerge mid-Q&A,
+  append them immediately — do not wait for the chunk to finish.
+
+## Presenting chunks
+
+After receiving the hunks, **semantically group** them into logical clusters
+(e.g. "JWT config hardening", "retry logic", "test additions"). Then present
+each group one at a time, following this structure:
+
+1. **Present the group** — show the raw diff for the group in a fenced
+   ```diff block. Announce it with a descriptive label
+   (e.g. "Group 2/5: JWT config hardening").
+
+2. **Surface one proactive hook** — identify the single most interesting
+   design decision in this group and offer to explain it. One sentence,
+   ending with a question.
+   Example: "This switches to exponential backoff — want me to explain
+   why fixed-interval retry is problematic at scale?"
+
+3. **Flag concerns** — surface any concerns you identify:
+   "I noticed: [concern]. Want to discuss the tradeoff?"
+   Skip this step if no concerns are apparent.
+
+4. **Open Q&A** — ask: "What would you like to understand about this change?"
+   Answer questions until the user signals readiness to move on.
+   Signals: "next", "skip", "continue", "done", "move on".
+
+5. **Comprehension gate** — before advancing, the reviewer must demonstrate
+   understanding. If the chunk is **trivial** (e.g. a one-line import, a
+   rename, whitespace-only, or a mechanical change with no design decisions),
+   skip the gate and advance directly. For all substantive chunks:
+
+   - When the user signals readiness to move on, respond:
+     "Before we move on, can you explain what this chunk does in your own words?"
+   - Evaluate their explanation. If they captured the gist — the *what* and
+     *why* of the change — they pass. Minor omissions are fine.
+   - If their explanation misses something important or is wrong, fill in the
+     gap conversationally: "You're right about X, but you missed Y — here's
+     why that matters: [brief explanation]." Then advance — do not ask them
+     to try again.
+   - If their explanation shows fundamental confusion (e.g. they describe
+     the opposite of what happened), correct them clearly, then ask:
+     "Want to take another look before we move on?"
+
+6. **Advance** — after the comprehension gate passes, append the chunk's
+   findings to the findings file, then present the next group.
+   After all groups, produce a summary.
+
+## Depth mode
+
+The session's depth is set by the user at launch:
+- **skim**: Flag concerns only. Keep explanations under 3 sentences.
+  Do not explain obvious changes.
+- **deep**: Explain architectural rationale. Mention patterns, alternatives
+  considered, and tradeoffs where relevant.
+
+## Finishing
+
+After all groups are reviewed:
+
+1. Append a final summary section to the findings file:
+
+   ```markdown
+   ---
+
+   ## Summary
+
+   **Files reviewed:** {count}
+   **Concerns found:** {count}
+   **Key takeaways:**
+   - {takeaway}
+   ```
+
+2. Produce the same summary in chat.
+3. Use the `code_stroll_cleanup` tool to remove the worktree and session file.
+
+## Rules
+
+- Never advance the chunk yourself. Always wait for the user to signal.
+- Never skip the comprehension gate on substantive chunks, even if the user
+  asks to bypass it.
+- Never fabricate diff content. Only discuss what the tool returned.
+- If the user asks about code outside the current chunk, use the `read` tool
+  to look it up in the worktree before answering.

package/config/commands/code-stroll.md

@@ -0,0 +1,14 @@
+---
+name: code-stroll
+description: Interactive code review learning session
+agent: review-agent
+---
+
+Review the code changes with these parameters:
+- depth: $depth (default: deep)
+- base branch: $base (default: main)
+- branch to review: $branch (default: HEAD)
+- focus directories: $focus (default: all)
+- resume previous session: $resume (default: false)
+
+Use the `code_stroll_start` tool (not bash) with these parameters to begin.

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// bin/cli.ts
+import { existsSync, mkdirSync, copyFileSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var packageRoot = join(__dirname2, "..");
+var command = process.argv[2];
+if (command === "init") {
+  init(process.argv[3] || ".");
+} else {
+  console.log(`code-stroll — interactive code review learning sessions
+
+Usage:
+  npx code-stroll init [dir]   Install command and agent files into a project
+
+The init command copies the slash command and review agent into
+your project's .opencode/ directory. After that, add the plugin
+to your opencode.json:
+
+  { "plugin": ["code-stroll"] }
+
+Then use /code-stroll in opencode to start a review.`);
+  process.exit(command === undefined || command === "--help" ? 0 : 1);
+}
+function init(targetDir) {
+  const target = resolve(process.cwd(), targetDir);
+  if (!existsSync(target)) {
+    console.error(`Error: directory ${target} does not exist.`);
+    process.exit(1);
+  }
+  const opencodeDir = join(target, ".opencode");
+  const commandsDir = join(opencodeDir, "commands");
+  const agentsDir = join(opencodeDir, "agents");
+  mkdirSync(commandsDir, { recursive: true });
+  mkdirSync(agentsDir, { recursive: true });
+  const configDir = join(packageRoot, "config");
+  copyFileSync(join(configDir, "commands", "code-stroll.md"), join(commandsDir, "code-stroll.md"));
+  copyFileSync(join(configDir, "agents", "review-agent.md"), join(agentsDir, "review-agent.md"));
+  console.log(`Installed code-stroll into ${target}:
+  .opencode/commands/code-stroll.md
+  .opencode/agents/review-agent.md
+
+Next: add the plugin to your opencode.json (or create one):
+
+  { "plugin": ["code-stroll"] }
+
+Then use /code-stroll in opencode to start a review.`);
+}