Add first version of dev sandbox

.pi/agent/skills/planning/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: planning
+description: Creates and maintains a structured plan document for multi-step tasks. The plan lives at PLAN.md and contains an ordered, checkbox-driven task list the agent keeps in sync as work progresses. Use when the user asks for a plan, when a task has multiple non-trivial steps, or when you need to track progress across a longer session.
+---
+
+# Planning
+
+Track a multi-step project using a markdown checklist.
+
+## When to use
+
+Use this skill when any of the following is true:
+- The user explicitly asks for a plan, todo list, or breakdown.
+- Work will continue across several turns and progress needs to be tracked.
+- You need to confirm scope with the user before executing.
+
+For trivial one-shot edits, do not create a plan.
+
+## Plan location
+
+- Default path: `./PLAN.md` in the current working directory.
+- If a plan path is specified by the user, use that instead.
+- If `PLAN.md` already exists, read it first and update it in place rather than overwriting unrelated content.
+
+## Plan document format
+
+The plan is plain Markdown. Every task is a GitHub-style checkbox list item. Keep it scannable.
+
+```markdown
+# Plan: <short title of the overall goal>
+
+<1–3 sentence summary of the goal and any important constraints.>
+
+## Tasks
+
+- [ ] 1. <First concrete, verifiable task>
+- [ ] 2. <Next task>
+  - [ ] 2a. <Sub-step, if the task naturally decomposes>
+  - [ ] 2b. <Sub-step>
+- [ ] 3. <...>
+
+## Notes
+- <Open questions, assumptions, decisions, links, or context worth preserving.>
+```
+
+Rules for tasks:
+- One action per checkbox. If a step has "and" in it, consider splitting.
+- Each task must be concrete and verifiable ("Add `--json` flag to `cli.ts` and update `--help` output"), not vague ("improve CLI").
+- Number tasks so they can be referenced in conversation ("done with 2, starting 3").
+- Use nested checkboxes for sub-steps only when it adds clarity.
+- Prefer 3–12 top-level tasks. If you have more, group them under `##` section headings.
+
+Checkbox states:
+- `[ ]` not started
+- `[~]` in progress (optional; use when a task spans multiple turns)
+- `[x]` done
+- `[-]` skipped or no longer applicable (add a short reason in the same line or in Notes)
+
+## Workflow
+
+1. **Draft.** On first use, read any existing `PLAN.md`, then write a complete plan with all tasks as `[ ]`. Keep the plan focused on the user's current goal.
+2. **Confirm (when useful).** If scope is ambiguous or the work is large, show the plan to the user and ask for confirmation before executing. For clear requests, proceed.
+3. **Execute one task at a time.** Before starting a task, mark it `[~]` (or announce which task you're starting). After finishing, mark it `[x]` and update `Last updated` and `Current step`.
+4. **Keep the plan in sync.** If you discover new work, add new checkboxes. If a task becomes unnecessary, mark it `[-]` with a brief reason rather than deleting it, so the history stays readable.
+5. **Summarize at the end.** When every task is `[x]` or `[-]`, add a short `## Summary` section describing what was done and any follow-ups.
+
+## Editing the plan
+
+- Use the `edit` tool to flip individual checkboxes and update the `Status` block — avoid rewriting the whole file.
+- Only use `write` when creating the plan for the first time or doing a full restructure.
+- Never silently drop tasks. Either complete them, skip them with `[-]` and a reason, or move them to a `## Deferred` section.
+
+## Example
+
+See [example-plan.md](example-plan.md) for a fully worked example of a small feature broken into tasks.

.pi/agent/skills/planning/example-plan.md

@@ -0,0 +1,18 @@
+# Plan: Add `--json` output mode to the `report` CLI
+
+Add a `--json` flag to the existing `report` command so it can emit machine-readable output in addition to the current human-readable table. Must not change default behavior.
+
+## Tasks
+
+- [x] 1. Read `src/cli/report.ts` and identify where output is currently rendered.
+- [x] 2. Define a `ReportJson` type in `src/cli/report-types.ts` matching the existing table columns.
+- [~] 3. Add `--json` flag parsing to `src/cli/report.ts` and thread it through to the renderer.
+  - [x] 3a. Register the flag with the arg parser.
+  - [ ] 3b. Branch on the flag in `renderReport()` to call a new `renderJson()` helper.
+- [ ] 4. Implement `renderJson()` that prints `JSON.stringify(data, null, 2)` and exits 0.
+- [ ] 5. Update `--help` text and `README.md` usage section to document `--json`.
+- [ ] 6. Add a test in `test/cli/report.test.ts` covering `--json` output shape.
+
+## Notes
+- Keep default (non-`--json`) output byte-identical to current behavior — existing snapshot tests must still pass.
+- Open question: should errors also be JSON when `--json` is set? Assuming yes; will confirm with user before step 4.