agent-canvas 0.1.16 → 0.1.18

package/bin/lib/instructions/flow-decision.md

@@ -0,0 +1,53 @@
+# DECISION Flow
+
+**When**: User needs help choosing between options. "Should we use X or Y?", "What database?", "Monorepo or polyrepo?"
+
+**Phases**: Single canvas, possibly follow-up for deeper comparison.
+
+```jsx
+<Section title="Decision: [What needs to be decided]">
+  [Context — why this decision matters and what constraints exist.]
+</Section>
+
+<Section title="Option A: [Name]">
+  <Item label="Pros" badge="pro" badgeVariant="success">
+    [Benefits of this option.]
+  </Item>
+  <Item label="Cons" badge="con" badgeVariant="danger">
+    [Drawbacks.]
+  </Item>
+  <Item label="Effort" badge="effort" badgeVariant="info">
+    [Rough effort estimate.]
+  </Item>
+</Section>
+
+<Section title="Option B: [Name]">
+  <Item label="Pros" badge="pro" badgeVariant="success">
+    [Benefits.]
+  </Item>
+  <Item label="Cons" badge="con" badgeVariant="danger">
+    [Drawbacks.]
+  </Item>
+  <Item label="Effort" badge="effort" badgeVariant="info">
+    [Effort.]
+  </Item>
+</Section>
+
+<Section title="Comparison">
+  <Table headers={["Criteria", "Option A", "Option B"]} rows={[
+    ["Performance", "---", "---"],
+    ["Complexity", "---", "---"],
+    ["Maintenance", "---", "---"],
+  ]} />
+</Section>
+
+<Section title="Recommendation">
+  <Callout type="tip">
+    I recommend **Option A** because [reasoning].
+    However, if [condition], Option B would be better.
+  </Callout>
+
+  <Choice id="decision" label="Which direction?" required
+    options={["Go with Option A", "Go with Option B", "Need more info — I'll annotate questions"]} />
+</Section>
+```

package/bin/lib/instructions/flow-explain.md

@@ -0,0 +1,47 @@
+# EXPLAIN Flow
+
+**When**: User wants to understand how something works. "Explain the auth system", "how does X work", "walk me through the architecture".
+
+**Phases**: Usually a single canvas, occasionally a follow-up if the user has questions.
+
+```jsx
+<Section title="How [System/Feature] Works">
+  [High-level overview in plain language.]
+
+  <Mermaid>{`
+    graph TD
+      A[Request] --> B{Auth?}
+      B -->|Yes| C[Process]
+      B -->|No| D[401]
+  `}</Mermaid>
+</Section>
+
+<Section title="Key Components">
+  <Item label="[Component name]" badge="core">
+    [What it does, where it lives.]
+    <FilePreview path="src/auth/middleware.ts" />
+  </Item>
+
+  <Item label="[Component name]" badge="core">
+    [Description.]
+  </Item>
+</Section>
+
+<Section title="Data Flow">
+  [Step-by-step walkthrough of how data moves through the system.]
+
+  <Mermaid>{`
+    sequenceDiagram
+      Client->>+API: POST /login
+      API->>+DB: Find user
+      DB-->>-API: User record
+      API-->>-Client: JWT token
+  `}</Mermaid>
+</Section>
+
+<Section title="Gotchas & Edge Cases">
+  <Item label="[Non-obvious thing]" badge="warning" badgeVariant="warning">
+    [Explanation of something surprising or easy to get wrong.]
+  </Item>
+</Section>
+```

package/bin/lib/instructions/flow-feature.md

@@ -0,0 +1,188 @@
+# FEATURE Flow
+
+**When**: User wants something built but the requirements aren't fully clear.
+
+**Phases**: Discovery → Requirements → Plan → [Implementation] → Summary
+
+## Phase 1: Discovery (`discovery.jsx`)
+
+Goal: understand scope, constraints, and user expectations.
+
+```jsx
+<Section title="Discovery: [Feature Name]">
+  Let me understand what we're building before diving into implementation.
+
+  <Item label="My understanding so far" badge="context" badgeVariant="info">
+    [Summarize what you already know from the conversation and codebase exploration.]
+  </Item>
+</Section>
+
+<Section title="Scope & Direction">
+  <Choice id="scope" label="How broad should this be?" required
+    options={["Minimal — just the core", "Standard — core + common edge cases", "Comprehensive — production-ready with all edge cases"]} />
+
+  <UserInput id="must-have" label="What's the one thing this absolutely must do?" required />
+  <UserInput id="must-not" label="Anything I should explicitly avoid or not touch?" />
+</Section>
+
+<Section title="Technical Context">
+  <MultiChoice id="areas" label="Which areas will be affected?" required
+    options={["Database / models", "API / backend logic", "Frontend / UI", "Auth / permissions", "Infrastructure / deployment", "Tests"]} />
+
+  <UserInput id="constraints" label="Any technical constraints? (existing libs, patterns to follow, things to avoid)" />
+</Section>
+
+<Section title="Deep Dive (optional)">
+  I can do a thorough interview in specific areas before planning.
+
+  <MultiChoice id="interview-areas" label="Want me to interview you about any of these?"
+    options={["Backend architecture & data model", "API design & contracts", "UI/UX behavior & states", "Error handling & edge cases", "Performance & scaling", "Security", "Testing strategy"]} />
+</Section>
+```
+
+If the user selects interview areas, push follow-up canvases with deep questions for each area. Example for "Backend architecture":
+
+```jsx
+<Section title="Backend Deep Dive">
+  <UserInput id="data-shape" label="Describe the data shape / entities involved" required />
+  <Choice id="mutation-pattern" label="How should mutations work?"
+    options={["Sync — mutate and return", "Async — queue and process", "Event-driven — publish and react"]} />
+  <UserInput id="invariants" label="What business rules / invariants must always hold?" />
+  <UserInput id="existing-patterns" label="Any existing patterns in the codebase I should follow?" />
+</Section>
+```
+
+## Phase 2: Requirements (`requirements.jsx`)
+
+Goal: formalize what will be built. The user confirms or corrects before planning.
+
+```jsx
+<Section title="Requirements: [Feature Name]">
+  Based on our discovery, here's what I'll build.
+
+  <Callout type="info">
+    Review each requirement. Annotate anything that's wrong or missing.
+  </Callout>
+</Section>
+
+<Section title="Functional Requirements">
+  <Item id="req-1" label="[Requirement title]" badge="must-have" badgeVariant="danger">
+    [Detailed description.]
+  </Item>
+  <Item id="req-2" label="[Requirement title]" badge="should-have" badgeVariant="warning">
+    [Description.]
+  </Item>
+  <Item id="req-3" label="[Requirement title]" badge="nice-to-have" badgeVariant="info">
+    [Description.]
+  </Item>
+</Section>
+
+<Section title="Non-Functional Requirements">
+  <Item id="nfr-1" label="Performance">
+    [Expected throughput, latency constraints.]
+  </Item>
+  <Item id="nfr-2" label="Security">
+    [Auth model, data sensitivity.]
+  </Item>
+</Section>
+
+<Section title="Out of Scope">
+  Explicitly NOT doing in this iteration:
+  <Checklist items={[
+    { label: "[Thing deliberately excluded]", checked: true },
+    { label: "[Another exclusion]", checked: true }
+  ]} />
+</Section>
+
+<Section title="Open Questions">
+  <UserInput id="open-1" label="[Question that emerged during discovery]" required />
+</Section>
+```
+
+## Phase 3: Plan (`plan.jsx`)
+
+Goal: detailed implementation plan with file-level changes. The user approves before coding.
+
+```jsx
+<Section title="Implementation Plan: [Feature Name]">
+  [Brief summary — what, why, rough approach.]
+
+  <Item label="Estimated scope" badge="info">
+    [N files changed, M new files. Estimated N rounds of implementation.]
+  </Item>
+</Section>
+
+<Section title="Phase 1: [Phase name]">
+  [What this phase accomplishes and why it's first.]
+
+  <Item id="step-1" label="[Step description]" badge="todo">
+    [What exactly will change.]
+    <FilePreview path="src/relevant/file.ts" lines={[10, 30]} />
+    <Callout type="tip">
+      [Any non-obvious approach or tradeoff.]
+    </Callout>
+  </Item>
+
+  <Item id="step-2" label="[Step description]" badge="todo">
+    [Description with code example if helpful.]
+    <CodeBlock language="typescript">
+      // Proposed interface
+      interface AuthToken {
+        userId: string;
+        expiresAt: number;
+      }
+    </CodeBlock>
+  </Item>
+</Section>
+
+<Section title="Testing Strategy">
+  <Checklist items={[
+    { label: "[Test case 1]", checked: false },
+    { label: "[Test case 2]", checked: false }
+  ]} />
+</Section>
+
+<Section title="Risks & Tradeoffs">
+  <Item label="[Risk]" badge="warning" badgeVariant="warning">
+    [Description and mitigation.]
+  </Item>
+</Section>
+```
+
+## Phase 4: Summary (`summary.jsx`)
+
+Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start a background watch** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
+
+```jsx
+<Section title="Implementation Summary: [Feature Name]">
+  <Item label="Status" badge="done" badgeVariant="success">
+    [One-line summary of what was accomplished.]
+  </Item>
+</Section>
+
+<Section title="What Was Done">
+  <Item id="done-1" label="[Change description]" badge="done" badgeVariant="success">
+    [Details of what was implemented and where.]
+  </Item>
+</Section>
+
+<Section title="Deviations from Plan">
+  [What changed during implementation and why.]
+  <Item id="dev-1" label="[What changed]" badge="changed" badgeVariant="warning">
+    [Why it deviated and what was done instead.]
+  </Item>
+</Section>
+
+<Section title="Manual Testing Needed">
+  <Callout type="warning">These need manual verification:</Callout>
+  <Checklist items={[
+    { label: "[Thing to test manually]", checked: false },
+  ]} />
+</Section>
+
+<Section title="Next Steps">
+  <Item id="next-1" label="[Follow-up task]" badge="todo">
+    [What should happen next, if anything.]
+  </Item>
+</Section>
+```

package/bin/lib/instructions/flow-plan.md

@@ -0,0 +1,106 @@
+# PLAN Flow
+
+**When**: User has clear requirements — skip discovery. Go straight to planning.
+
+**Phases**: Plan → [Implementation] → Summary
+
+If during planning you realize requirements are ambiguous, pivot to a quick discovery round (see `flow-feature`).
+
+## Phase 1: Plan (`plan.jsx`)
+
+Goal: detailed implementation plan with file-level changes. The user approves before coding.
+
+```jsx
+<Section title="Implementation Plan: [Feature Name]">
+  [Brief summary — what, why, rough approach.]
+
+  <Item label="Estimated scope" badge="info">
+    [N files changed, M new files. Estimated N rounds of implementation.]
+  </Item>
+</Section>
+
+<Section title="Phase 1: [Phase name]">
+  [What this phase accomplishes and why it's first.]
+
+  <Item id="step-1" label="[Step description]" badge="todo">
+    [What exactly will change.]
+    <FilePreview path="src/relevant/file.ts" lines={[10, 30]} />
+    <Callout type="tip">
+      [Any non-obvious approach or tradeoff.]
+    </Callout>
+  </Item>
+
+  <Item id="step-2" label="[Step description]" badge="todo">
+    [Description with code example if helpful.]
+    <CodeBlock language="typescript">
+      // Proposed interface
+      interface AuthToken {
+        userId: string;
+        expiresAt: number;
+      }
+    </CodeBlock>
+  </Item>
+</Section>
+
+<Section title="Testing Strategy">
+  <Checklist items={[
+    { label: "[Test case 1]", checked: false },
+    { label: "[Test case 2]", checked: false }
+  ]} />
+</Section>
+
+<Section title="Risks & Tradeoffs">
+  <Item label="[Risk]" badge="warning" badgeVariant="warning">
+    [Description and mitigation.]
+  </Item>
+</Section>
+```
+
+## Phase 2: Summary (`summary.jsx`)
+
+Push AFTER implementation is complete. Always do this, even briefly. **After pushing the summary, start a background watch** — the user may want to provide feedback (follow-up requests, corrections, questions about what was done).
+
+```jsx
+<Section title="Implementation Summary: [Feature Name]">
+  <Item label="Status" badge="done" badgeVariant="success">
+    [One-line summary of what was accomplished.]
+  </Item>
+</Section>
+
+<Section title="What Was Done">
+  <Item id="done-1" label="[Change description]" badge="done" badgeVariant="success">
+    [Details of what was implemented and where.]
+  </Item>
+</Section>
+
+<Section title="Deviations from Plan">
+  [What changed during implementation and why.]
+  <Item id="dev-1" label="[What changed]" badge="changed" badgeVariant="warning">
+    [Why it deviated and what was done instead.]
+  </Item>
+</Section>
+
+<Section title="Manual Testing Needed">
+  <Callout type="warning">These need manual verification:</Callout>
+  <Checklist items={[
+    { label: "[Thing to test manually]", checked: false },
+  ]} />
+</Section>
+
+<Section title="Next Steps">
+  <Item id="next-1" label="[Follow-up task]" badge="todo">
+    [What should happen next, if anything.]
+  </Item>
+</Section>
+```
+
+## Skipping & Combining
+
+| Situation | Action |
+|---|---|
+| User said "just do it" with clear instructions | Implement directly, push summary after |
+| Simple change (< 3 files) | Probably skip canvas entirely |
+| User explicitly says "don't plan, just code" | Implement, push summary |
+| Mid-flow user says "looks good, go ahead" | Skip remaining review rounds |
+
+**Always push a summary after implementation** (unless trivially small) **and watch for feedback** — the user may want to respond with follow-ups or corrections.

package/bin/lib/instructions/flow-review.md

@@ -0,0 +1,60 @@
+# REVIEW Flow
+
+**When**: User wants code review, architecture audit, security review, or similar.
+
+**Phases**: Findings → (optional) Fix Plan → Summary
+
+```jsx
+<Section title="Review: [What's Being Reviewed]">
+  [Scope of the review — what was examined, methodology.]
+
+  <Item label="Files reviewed" badge="scope" badgeVariant="info">
+    [List or count of what was examined.]
+  </Item>
+</Section>
+
+<Section title="Critical Issues">
+  <Item id="crit-1" label="[Issue title]" badge="critical" badgeVariant="danger">
+    [Description of the issue and its impact.]
+    <FilePreview path="src/auth.ts" lines={[42, 55]} />
+    <CodeBlock language="typescript">
+      // Proposed fix
+      if (!token) throw new UnauthorizedError();
+    </CodeBlock>
+  </Item>
+</Section>
+
+<Section title="Warnings">
+  <Item id="warn-1" label="[Issue title]" badge="warning" badgeVariant="warning">
+    [Description. Less severe but should be addressed.]
+  </Item>
+</Section>
+
+<Section title="Suggestions">
+  <Item id="sug-1" label="[Suggestion]" badge="suggestion" badgeVariant="info">
+    [Nice-to-have improvement. Not blocking.]
+  </Item>
+</Section>
+
+<Section title="What Looks Good">
+  <Item label="[Positive observation]" badge="good" badgeVariant="success">
+    [Call out things that are well-implemented. Important for balanced reviews.]
+  </Item>
+</Section>
+
+<Section title="Action Items">
+  <Checklist items={[
+    { label: "[Fix critical-1: description]", checked: false },
+    { label: "[Address warning-1: description]", checked: false },
+    { label: "[Consider suggestion-1: description]", checked: false }
+  ]} />
+
+  <Choice id="review-action" label="How should I proceed?" required
+    options={[
+      "Fix all critical + warnings",
+      "Fix critical only, I'll handle warnings",
+      "Don't fix anything, this was informational",
+      "Let me annotate which ones to fix"
+    ]} />
+</Section>
+```

package/bin/lib/instructions/overview.md

@@ -0,0 +1,173 @@
+# Agent Canvas — Instruction Guide
+
+Canvas opens a rich, annotatable document in the user's browser. You write JSX, the user reviews and annotates it like Google Docs, and feedback comes back as markdown.
+
+Use it whenever structured visual communication beats inline chat: plans, reviews, decisions, explanations, discovery interviews.
+
+**Note**: Replace all `<session-id>` references below with your actual canvas session ID (provided in the skill header).
+
+## Core Workflow
+
+### 1. Write JSX
+
+Use the **Write** tool to create `.jsx` files in `.claude/agent-canvas/<session-id>/`:
+
+```jsx
+// .claude/agent-canvas/<session-id>/plan.jsx
+
+<Section title="Authentication Redesign">
+  A proposal to replace session-based auth with JWT tokens.
+
+  <Item id="current" label="Current state" badge="context" badgeVariant="info">
+    The app uses express-session with Redis store.
+    <FilePreview path="src/auth/session.ts" lines={[1, 45]} />
+  </Item>
+
+  <Item id="proposal" label="Proposed change" badge="proposal">
+    Switch to stateless JWT with refresh token rotation.
+    <Callout type="warning">This will invalidate all existing sessions.</Callout>
+  </Item>
+</Section>
+```
+
+Components are auto-available — no imports needed. The file can be a JSX fragment (just tags) or a full module with `export default`.
+
+### 2. Push
+
+Push the directory to open all canvases in the browser:
+
+```bash
+bunx agent-canvas push .claude/agent-canvas/<session-id>/ --session <session-id> --label "Implementation Plan"
+```
+
+All `*.jsx` files in the directory are pushed as a snapshot. Each file appears as a separate tab. **Always show the `browserUrl` from the output to the user.**
+
+Options:
+- `--label <text>` — revision label shown in the UI
+- `--response <text>` — short banner explaining how you addressed prior feedback (2-4 sentences, focus on "why" not "what")
+
+### 3. Watch for feedback
+
+Run the watch command **in the background** using the Bash tool's `run_in_background` parameter:
+
+```bash
+# Use Bash tool with run_in_background: true
+bunx agent-canvas watch --session <session-id>
+```
+
+You will be **automatically notified** when the user submits feedback. Do NOT poll, sleep, or proactively check. Just stop and wait.
+
+**Important**: The push → watch sequence is atomic. Never push without watching. After starting the background watch, do not continue with other work unless instructed.
+
+### 4. Iterate
+
+Use the **Edit** tool to modify existing JSX based on feedback — targeted edits, not full rewrites. Then push and watch again.
+
+### 5. Fetch (non-blocking alternative)
+
+If the user tells you they've already submitted feedback:
+
+```bash
+bunx agent-canvas fetch --session <session-id>
+```
+
+Returns immediately — prints feedback if available, otherwise no output.
+
+## Multiple Canvases
+
+Use different files for different phases or concerns:
+
+```
+.claude/agent-canvas/<session-id>/
+  discovery.jsx    # Discovery interview
+  requirements.jsx # Requirements spec
+  plan.jsx         # Implementation plan
+```
+
+Write new files as phases progress, then push the directory. Previous files remain visible as context.
+
+## File Location
+
+All canvas files go in `.claude/agent-canvas/<session-id>/` within the project root. Add `.claude/agent-canvas/` to `.gitignore`.
+
+## Components
+
+All components are globally available in canvas JSX — no imports needed. For inline styling use `style={{ ... }}` — Tailwind is NOT available.
+
+**Never hardcode hex colors** — use CSS variables: `var(--color-text-primary)`, `var(--color-bg-surface)`, `var(--color-accent-blue)`, etc.
+
+### Layout
+- **Section** — top-level collapsible grouping with serif heading. Props: `title`, `collapsed`
+
+### Content
+- **Item** — primary content block (tasks, findings, requirements). Props: `id`, `label`, `badge`, `badgeVariant`, `status`
+- **CodeBlock** — syntax-highlighted code. Props: `language`
+- **FilePreview** — project file preview. Props: `path`, `lines` ([start, end])
+- **Markdown** — renders markdown content. Props: `file` (path) or children (inline markdown string)
+- **ImageView** — displays an image. Props: `src`, `alt`, `caption`, `width`
+- **Diff** — side-by-side diff view. Props: `before`, `after`, `language`
+- **Table** — data table. Props: `headers`, `rows`
+- **Checklist** — checkbox list. Props: `items` ([{ label, checked }])
+- **Mermaid** — diagram rendering. Children: mermaid syntax string
+- **Callout** — alert box. Props: `type` (info/warning/danger/tip)
+- **Note** — soft aside for non-critical info
+- **Priority** — inline priority badge. Props: `level` (high/medium/low)
+
+### Interactive (User Input)
+- **Choice** — single-select radio group. Props: `id`, `label`, `options`, `required`
+- **MultiChoice** — multi-select checkboxes. Props: `id`, `label`, `options`, `required`
+- **UserInput** — free text input. Props: `id`, `label`, `placeholder`, `required`
+- **RangeInput** — numeric slider. Props: `id`, `label`, `min`, `max`, `minLabel`, `maxLabel`, `required`
+
+### Advanced
+- **useFeedback** — hook for custom components to contribute computed data to feedback
+- **Custom components** — use `export default function Canvas()` module format to define helpers
+
+Run `bunx agent-canvas instructions <topic>` for detailed docs on any component or flow.
+
+## Choosing a Flow
+
+```
+User wants something built/changed?
+├─ Vague request → FEATURE flow (discovery → requirements → plan → implement → summary)
+├─ Clear request with specifics → PLAN flow (plan → implement → summary)
+├─ Complete instructions → skip canvas, implement directly, optionally push summary
+
+User wants to understand something? → EXPLAIN flow
+User wants review/audit? → REVIEW flow
+User wants to make a decision? → DECISION flow
+```
+
+**Adapt dynamically**: flows are guidelines, not rigid pipelines. Skip or combine phases when appropriate:
+
+| Situation | Action |
+|---|---|
+| User gave a detailed spec | Skip to PLAN (skip discovery + requirements) |
+| User said "just do it" with clear instructions | Implement directly, push summary after |
+| Simple change (< 3 files) | Probably skip canvas entirely |
+| User explicitly says "don't plan, just code" | Implement, push summary |
+| Mid-flow user says "looks good, go ahead" | Skip remaining review rounds |
+| Discovery reveals it's trivial | Collapse remaining phases into one canvas |
+
+**Always push a summary after implementation** unless the change was trivially small (1-2 file edit).
+
+## Flow Execution Pattern
+
+1. **Determine flow** from user intent
+2. **Announce** briefly: "I'll start with discovery, then create a detailed plan."
+3. **Write canvas JSX** with the Write tool
+4. **Push + show browserUrl** to the user
+5. **IMMEDIATELY watch in background** — the push → watch sequence is atomic
+6. **Read feedback** — check for annotations, answers, context files
+7. **Edit and re-push + watch**, or advance to next phase
+8. **After implementation**, push a summary canvas and **watch for feedback** — the user may want to respond
+
+## Important Rules
+
+- **Write** canvas files using the Write tool. Never use bash heredocs.
+- **Edit** canvas files using the Edit tool. Never rewrite entire files.
+- Every `<Item>` and interactive component needs a unique `id`.
+- `<FilePreview path="...">` paths are relative to project root.
+- Read any files the user added to context (listed under "Added context" in feedback).
+- Always push a summary canvas after implementation, even if brief.
+- When the user approves, confirm what you'll do next before proceeding.

package/bin/lib/instructions/theming.md

@@ -0,0 +1,50 @@
+# Theming
+
+Canvas supports light/dark themes. **Never hardcode hex colors** — use CSS variables in `style={{ }}`.
+
+## CSS Variables
+
+### Text
+- `--color-text-primary` — main text
+- `--color-text-secondary` — supporting text
+- `--color-text-tertiary` — meta text, labels
+- `--color-text-code` — inline code
+- `--color-text-inverse` — text on dark backgrounds
+
+### Backgrounds
+- `--color-bg-base` — page background
+- `--color-bg-surface` — card/section background
+- `--color-bg-elevated` — floating elements
+- `--color-bg-code` — code block background
+- `--color-bg-input` — form input background
+
+### Accents
+- `--color-accent-green`, `--color-accent-green-muted`
+- `--color-accent-amber`, `--color-accent-amber-muted`
+- `--color-accent-red`, `--color-accent-red-muted`
+- `--color-accent-blue`, `--color-accent-blue-muted`
+
+### Borders
+- `--color-border-subtle` — light separators
+- `--color-border-medium` — visible borders
+- `--color-border-hover` — interactive hover state
+
+### Fonts
+- `--font-heading` — section headings (Instrument Serif)
+- `--font-body` — body text (Inter)
+- `--font-mono` — code (JetBrains Mono)
+
+## Usage
+
+```jsx
+<span style={{ color: 'var(--color-text-tertiary)', fontSize: '0.75rem' }}>meta text</span>
+
+<div style={{
+  background: 'var(--color-bg-surface)',
+  border: '1px solid var(--color-border-subtle)',
+  borderRadius: '8px',
+  padding: '16px',
+}}>
+  Custom styled container
+</div>
+```