read-book

name	read-book
description	Use when the user wants to read and annotate a book via Kindle Cloud Reader. Supports two modes: project mode (companion-specific notes in reference/) and library mode (companion-neutral notes in org library). Reads in batches of 10 page-flips with resilient note-writing after each flip.
disable-model-invocation	true
argument-hint	[kindle-url] or [--library org kindle-url]

/read-book — Read and Annotate a Book via Kindle Cloud Reader

Read a book through the browser, taking structured notes in batches of 10 page-flips. Supports two modes:

1. Project mode (default) — Produces project-specific applicability notes stored in the companion's reference/ directory
2. Library mode (--library [org]) — Produces comprehensive, companion-neutral notes stored in the organization's library at companion-kits/private-kits/[org]-companion-kit/library/

Usage:

• /read-book [kindle-url] — Read for current companion (project mode)
• /read-book [kindle-url] [client/companion] — Override for specific companion
• /read-book --library [org] [kindle-url] — Read to org library (library mode)
• /read-book --library [org] [subject] [kindle-url] — Library mode with subject category

Examples:

/read-book https://read.amazon.com/?asin=B00RLQXBYS
/read-book --library consortium.team https://read.amazon.com/?asin=B00RLQXBYS
/read-book --library consortium.team creative-writing https://read.amazon.com/?asin=B00RLQXBYS

---

Step 0: Determine Reading Mode

Parse $ARGUMENTS for the --library flag:

If --library [org] is present:

• Library mode — Notes are companion-neutral, stored in companion-kits/private-kits/[org]-companion-kit/library/
• Extract the organization name (e.g., consortium.team)
• If a subject category is provided (e.g., creative-writing), use it for directory placement
• Skip Step 1 (no project needed)
• In Steps 6-7, use library note format instead of project note format (see Step 7b)

If --library is NOT present:

• Project mode — Notes are companion-specific, stored in the project's reference/ directory
• Proceed to Step 1

---

Step 1: Determine the Companion (Project Mode Only)

1. If $ARGUMENTS contains a companion path, use that
2. Otherwise, read tracking/current-companion.md for the current companion
3. If no companion is set:

   No companion set. Use /companion to set or create one first.
   Or use --library [org] to read to the organization's library.
   

Store the companion path and full directory path (companions/[client]/[companion]/).

---

Step 2: Extract the URL and Determine Book Identity

1. Parse the Kindle URL from $ARGUMENTS (the asin=XXXXXXXXXX parameter identifies the book)
2. Extract the ASIN from the URL

---

Step 3: Check for Existing Reference File

In project mode:

1. Search [companion]/reference/ for any file containing the ASIN or that matches the book

In library mode:

1. Search companion-kits/private-kits/[org]-companion-kit/library/ recursively for any file containing the ASIN or that matches the book
2. Also check if a metadata.yaml already exists with a matching ASIN

In either mode: 2. If a reference file exists:

• Read it to find the "Reading paused at page X of Y" marker at the bottom
• Report to the user: "Picking up from page X (Y% complete). Currently in [chapter name]."
• This is a resume — skip to Step 5

3. If no reference file exists:
   • This is a new read — continue to Step 4

---

Compliance Checkpoint 1

For new reads, confirm book identity and destination before proceeding:

New read detected.

Book ASIN: [ASIN]
Mode: [Project / Library]
Destination: [path where notes will be stored]

Proceeding to connect to the browser and identify the book. Ready?

For resumes, confirm the pickup point:

Resuming read.

Book: [title if known]
Paused at: page [X] of [Y] ([Z]%)
Chapter: [chapter name]

Ready to continue?

STOP and wait for user confirmation.

---

Step 4: Create the Reference File (New Read Only)

1. Navigate to the Kindle URL (Step 5 handles browser connection)
2. Once on the book, open the Table of Contents to get the book's structure
3. Identify the book title and author from the page

In project mode: 4. Ask the user to confirm the reference filename (suggest: [author-lastname]-[short-title]-notes.md) 5. Create the reference file in [companion]/reference/ with this header:

# [Book Title] — Key Insights

**Source:** [Author], *[Book Title]* (Kindle Edition, ASIN: [ASIN])
**Purpose:** [Extract from project requirements — what is this book being read for?]
**Method:** Page-by-page reading with synthesis at chapter boundaries

---

In library mode: 4. Determine the library directory:

• If subject was provided: companion-kits/private-kits/[org]-companion-kit/library/[subject]/[author-short-title]/
• If no subject: ask the user which subject category to use (e.g., creative-writing, game-design, product-management)

5. Create the directory if it doesn't exist
6. Create notes.md in the library directory with this header:

# [Book Title] — Comprehensive Notes

**Source:** [Author], *[Book Title]* (Kindle Edition, ASIN: [ASIN])
**Purpose:** Companion-neutral comprehensive notes for the [org] library
**Method:** Page-by-page reading with synthesis at chapter boundaries

---

7. Create or update metadata.yaml in the same directory:

title: "[Book Title]"
author: "[Author]"
asin: "[ASIN]"
subjects: [suggested subject tags]
related_personas: [suggested based on subject]
source_projects: []
status: "in-progress"

8. Close the Table of Contents and navigate to page 1 (or the Preface/Introduction)

---

Step 5: Connect to the Browser

Try Claude in Chrome extension first:

1. Call tabs_context_mcp with createIfEmpty: true
2. If connected: Create a new tab, navigate to the Kindle URL
3. If "No Chrome extension connected" error:
   • Tell the user: "The Claude in Chrome extension isn't connected. Please:
     1. Open Chrome (if not running)
     2. Click the Claude in Chrome extension icon in the toolbar
     3. Click 'Connect' if prompted
     4. Let me know when it's ready"
   • Wait for user confirmation, then retry

If Chrome extension doesn't work, try Playwright:

1. Call browser_navigate with the Kindle URL
2. If "Failed to launch" error (Chrome already running):
   • Tell the user: "Playwright can't launch because Chrome is already running. Please quit Chrome completely (Cmd+Q), then let me know."
   • Wait for user confirmation, then retry

Once connected and navigated:

3. Take a screenshot to confirm the book is loaded
4. If a "Most Recent Page Read" dialog appears:
   • If resuming: Click "Yes" to go to the last page, then navigate to the page noted in the reference file
   • If new read: Click "No" to stay at the beginning
5. If the reader is at the wrong page, tell the user which page you need and ask for help navigating there

---

Step 6: Read in Batches of 10 Flips

This is the core reading loop. Repeat this step until the book is complete.

For each flip (repeat 10 times per batch):

1. Read the current two-page spread — Take a screenshot and carefully read both visible pages
2. Write notes to the reference file — Append notes for the pages just read, following the note format (see Step 7). If a chapter has ended on this spread, write the Chapter Synthesis before continuing.
3. Flip to the next spread — Click the right-side arrow (typically around coordinate [1425, 405] but verify with screenshot)

Repeat steps 1-3 until you've done 10 flips.

Why write after every flip, not after the batch: Context compaction can hit at any time. If notes are written after every 2 pages, a compaction only loses the current spread. If notes are batched to the end, a compaction on flip 8 loses everything. This is the critical resilience mechanism.

Chapter boundary handling:

• When you reach the end of a chapter on a spread, write the chapter's Chapter Synthesis to the reference file as part of step 2 for that flip
• The synthesis should capture: chapter thesis, key frameworks applicable to the project
• Then continue reading into the next chapter on the next flip

After completing 10 flips:

4. Update the reading position marker at the bottom of the reference file (see Step 8)
5. Report to the user:

   Notes written through page [X] of [total] ([Y]%), in [Chapter Name].
   
   Say **next** when you're ready for the next batch.
   

6. STOP and wait for the user to say "next" — Do not continue reading without user confirmation

Compliance Checkpoint 2

After every batch of 10 flips, this is a mandatory pause point. Do not proceed to the next batch until the user explicitly says "next" or equivalent. This gives the user pacing control and a natural breakpoint.

---

Step 7: Note Format (Project Mode)

Follow this structure for each batch of notes appended to the reference file:

## Chapter [N] | [Chapter Title] (pp. [start]-[end])

### Pages [X]-[Y]

**Key concepts:**

1. **[Concept name]** — [Description of the concept in your own words, capturing the essential insight]

2. **[Concept name]** — [Description]

**Applicable to [project context]:**
- [How this concept applies to the specific project]
- [Specific editorial/design/build implications]

### Pages [X]-[Y]

[Continue for each spread in the batch...]

### Chapter [N] Synthesis

**Chapter thesis:** [One-paragraph summary of the chapter's core argument]

**Key frameworks for [project]:**

1. **[Framework name]** — [Description and how it applies]
2. **[Framework name]** — [Description and how it applies]

---

Note-taking principles (project mode):

• Capture concepts in your own words — do not copy large passages verbatim
• Every few spreads, include an "Applicable to [project]" section connecting insights to the specific project
• Be specific about applicability — "this is relevant" is useless; "this means the companion should X when Y" is useful
• At chapter boundaries, synthesize into named frameworks that can be referenced later
• Use the project's requirements.md and decisions.md to inform applicability notes

---

Step 7b: Library Note Format (Library Mode Only)

In library mode, notes are comprehensive and companion-neutral. Instead of "Applicable to [project]" sections, use broader tagging.

## Chapter [N] | [Chapter Title] (pp. [start]-[end])

### Pages [X]-[Y]

**Key concepts:**

1. **[Concept name]** — [Description of the concept in your own words, capturing the essential insight]

2. **[Concept name]** — [Description]

**Subject tags:** [craft-technique, character-development, pacing, etc.]

### Pages [X]-[Y]

[Continue for each spread in the batch...]

### Chapter [N] Synthesis

**Chapter thesis:** [One-paragraph summary of the chapter's core argument]

**Key frameworks:**

1. **[Framework name]** — [Description — what it is, when it applies, how to use it]
2. **[Framework name]** — [Description]

**Potential applicability:**
- Personas: [which persona types might use this — e.g., writing-mentor, game-designer]
- Capabilities: [which capabilities this relates to — e.g., mentor-framework, craft-assessment]

---

Library note-taking principles:

• Capture EVERYTHING notable — err on the side of more, not less
• Do NOT filter for any specific companion's needs — capture comprehensively
• Tag with broad subject categories rather than companion-specific applicability
• At chapter boundaries, note which persona types and capabilities the material relates to
• The goal is raw material that any companion can later contextualize from

---

Step 8: Update Reading Position

After each batch of notes, update the footer of the reference file:

*Reading paused at page [X] of [total] ([Y]% complete). Currently in Chapter [N]: [Chapter Title].*

This marker is how the command knows where to resume on the next invocation.

---

Step 9: Book Completion

When you reach the end of the book:

1. Write final chapter notes and synthesis
2. Replace the "Reading paused" marker with:

   *Reading complete. [Total pages] pages, [N] chapters.*
   

3. Tell the user the reading is complete

In project mode: 4. Do not create the master synthesis yet — that's a separate step the user may want to direct

In library mode: 4. Update metadata.yaml to set status: "complete" 5. Create synthesis.md in the same library directory with a master synthesis:

• Key frameworks distilled from the notes
• Major themes and their subject tags
• Potential applicability to different persona types

6. Tell the user the library entry is complete and ready for contextualization by any companion

---

Troubleshooting

Kindle reader won't load:

• The reader requires an active Amazon login. Ask the user to sign into Amazon in the browser first.

Page won't flip:

• The click target may have shifted. Take a screenshot and look for the right-arrow navigation element. Try clicking directly on it.

Reader shows wrong page after resume:

• Tell the user which page you need (from the reference file's "Reading paused" marker) and ask them to navigate there manually.

Context buffer hits 20MB cap:

• The user will start a new Cowork session. On resume, they'll invoke /read-book again with the same URL. Step 3 will find the existing reference file and pick up where it left off.

Chrome extension disconnects mid-read:

• Ask the user to reconnect (click extension icon then Connect). Then take a screenshot to verify the reader is still on the right page.

---

Design Rationale

• 10 flips per batch balances reading depth with note-writing frequency. More flips risks losing detail; fewer flips creates excessive overhead.
• Notes before flipping ensures nothing is lost if the session is interrupted.
• User says "next" gives the user control over pacing and lets them step away between batches.
• Chapter synthesis at boundaries creates named frameworks that the rest of the project can reference.
• Applicability notes throughout ensure the reading is always connected to the project's needs, not just abstract note-taking.