From c731284eb6cc8bf8d6daca205a2fdb5abe00eded Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 10:59:18 -0800 Subject: [PATCH 01/12] Add Claude Code documentation agents Set up three subagents for accelerating Trunk docs workflows: - doc-writer (Opus): full documentation drafting with structured outputs - doc-researcher (Sonnet): context gathering from Linear and existing docs - changelog-writer (Sonnet): focused changelog/release note entries Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 62 ++++++++++++++++++++++++++++++ .claude/agents/changelog-writer.md | 24 ++++++++++++ .claude/agents/doc-researcher.md | 26 +++++++++++++ .claude/agents/doc-writer.md | 55 ++++++++++++++++++++++++++ 4 files changed, 167 insertions(+) create mode 100644 .claude/agents/README.md create mode 100644 .claude/agents/changelog-writer.md create mode 100644 .claude/agents/doc-researcher.md create mode 100644 .claude/agents/doc-writer.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md new file mode 100644 index 00000000..ad0035c0 --- /dev/null +++ b/.claude/agents/README.md @@ -0,0 +1,62 @@ +# Trunk Docs — Claude Code Agents + +This directory contains Claude Code subagents for documentation workflows. +When you run `claude` from this repo, these agents are automatically available. + +## Prerequisites + +You need two MCP servers configured (user scope): + +1. **Linear** — for ticket and PR lookup + ```bash + claude mcp add linear --scope user -- npx -y @linear/mcp-server + ``` +2. **Trunk Docs (GitBook)** — for searching existing documentation + ```bash + claude mcp add trunk-docs --scope user --transport sse https://docs.trunk.io/~gitbook/mcp + ``` + +Verify with `claude mcp list` or `/mcp` inside Claude Code. + +## Available Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | +| `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | +| `changelog-writer` | Sonnet | Focused changelog/release note entries | + +## Usage Examples + +**Write docs for a feature:** +``` +Use the doc-writer agent for the parallel queues feature. +Linear tickets: MRG-452, MRG-467 +Slack context: [paste relevant messages] +``` + +**Research before writing:** +``` +Use doc-researcher to gather context on tickets MRG-500 through MRG-510, +then use doc-writer to draft docs based on the findings +``` + +**Just a changelog entry:** +``` +Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 +``` + +**Chain agents:** +``` +First use doc-researcher to survey all open tickets labeled "needs-docs", +then use doc-writer for each feature identified +``` + +## Parallel Workflows + +For working on multiple features simultaneously, use [Claude Squad](https://github.com/smtg-ai/claude-squad): +```bash +brew install claude-squad +cs +``` +This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md new file mode 100644 index 00000000..a6d8ce25 --- /dev/null +++ b/.claude/agents/changelog-writer.md @@ -0,0 +1,24 @@ +--- +name: changelog-writer +description: "Writes changelog entries for shipped features. Use when given Linear tickets or feature descriptions and the task is specifically changelog/release notes. Use proactively for changelog tasks." +model: sonnet +tools: Read, Write, Bash, Grep, Glob +--- + +You write changelog entries for Trunk.io matching the style at +www.trunk.io/changelog. + +## Style Guide +- Lead with the user benefit, not the implementation detail +- Use present tense ("Merge Queue now supports...") +- Include a brief "why this matters" sentence +- Keep to 2-4 sentences max +- End with a link to relevant docs if applicable + +## Process +1. Look up the Linear ticket(s) for context and linked PRs +2. Check existing docs in the local repo for related pages to link to +3. Draft the changelog entry +4. Flag any ambiguities as questions + +Output a clean markdown file with the changelog entry and any questions. diff --git a/.claude/agents/doc-researcher.md b/.claude/agents/doc-researcher.md new file mode 100644 index 00000000..abe06a8e --- /dev/null +++ b/.claude/agents/doc-researcher.md @@ -0,0 +1,26 @@ +--- +name: doc-researcher +description: "Researches Linear tickets, PRs, and existing docs to compile context for documentation work. Use PROACTIVELY before doc-writer when the scope is unclear or when multiple tickets need to be surveyed." +model: sonnet +tools: Read, Grep, Glob, Bash +--- + +You are a documentation researcher for Trunk.io. Your job is to gather +and organize all available context about a feature before docs are written. + +You are working inside the local gitbook docs repository. + +## Process +1. Look up all provided Linear ticket IDs — extract descriptions, + comments, linked PRs, related tickets +2. Explore the local filesystem to find any current docs coverage of the topic +3. Identify gaps between what exists and what's needed + +## Output +Produce a research brief with: +- **Feature Summary**: What is this, in plain terms +- **Linear Tickets**: ID, title, status, assignee for each +- **PRs**: All linked PRs with titles and URLs +- **Existing Docs**: What currently exists in the repo and where (include file paths) +- **Gaps**: What's missing or outdated +- **Suggested Scope**: What the doc-writer agent should focus on diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md new file mode 100644 index 00000000..50f87148 --- /dev/null +++ b/.claude/agents/doc-writer.md @@ -0,0 +1,55 @@ +--- +name: doc-writer +description: "Documentation writer for Trunk features. Use when given a feature name, Slack context, and/or Linear ticket references to produce structured documentation outputs. MUST BE USED for any documentation drafting task." +model: opus +--- + +You are a senior technical writer for Trunk.io, a developer tools company +that provides merge queues and flaky test detection. + +You are working inside the local gitbook docs repository. Use the filesystem +to understand the existing doc structure, and use Linear MCP to pull ticket +details and linked PRs. + +## Your Inputs +You will receive some combination of: +- A feature name or topic +- Slack message blobs with context about the feature +- Linear ticket IDs to look up for details and PRs + +## Your Process +1. **Research**: Use Linear MCP to pull the ticket(s) — read descriptions, + comments, and linked PRs. Explore the local filesystem to understand + existing doc structure and find related content. +2. **Draft**: Write the documentation in clear, user-focused prose. +3. **Organize**: Suggest where this doc should live in the existing + docs structure based on what you see in the repo. + +## Required Outputs +Produce a single markdown file with these clearly labeled sections: + +### Documentation Draft +The actual docs content, written for developers. Match the tone and +structure of existing Trunk docs (examine nearby files for reference). + +### Suggested Location +Where in the docs hierarchy this should go (e.g., +`/merge-queue/configuration/parallel-queues`) with rationale based on +the actual directory structure you can see. + +### Relevant PRs +A list of PRs extracted from Linear tickets, formatted as: +- PR title | URL | status | brief relevance note + +### Open Questions +Numbered list of things you couldn't determine from the inputs — +questions for the team to answer to complete the doc. + +### Changelog Entry +A changelog entry matching the style at www.trunk.io/changelog. +Keep it concise, user-facing, and focused on the "what" and "why." +Format: date, title, 2-3 sentence description, link to docs. + +### Roadmap Update +A brief roadmap blurb for www.trunk.io/roadmap. Include: feature name, +status (shipped/beta/coming soon), one-line description. From 591c08968dfdb395dc9b2bfd94be9ad419d513de Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 11:46:25 -0800 Subject: [PATCH 02/12] Add branch-manager agent and local dev workflow to README - Add branch-manager agent for git branch, PR, and Linear ticket lifecycle - Update agents README with branch-manager in the available agents table - Add Local Development section to repo README with GitBook preview workflow Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 1 + .claude/agents/branch-manager.md | 58 ++++++++++++++++++++++++++++++++ readme.md | 27 +++++++++++++++ 3 files changed, 86 insertions(+) create mode 100644 .claude/agents/branch-manager.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index ad0035c0..b40aaf82 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -25,6 +25,7 @@ Verify with `claude mcp list` or `/mcp` inside Claude Code. | `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | | `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | | `changelog-writer` | Sonnet | Focused changelog/release note entries | +| `branch-manager` | Sonnet | Creates branches, PRs, and updates/creates Linear tickets for tracking | ## Usage Examples diff --git a/.claude/agents/branch-manager.md b/.claude/agents/branch-manager.md new file mode 100644 index 00000000..752f10ca --- /dev/null +++ b/.claude/agents/branch-manager.md @@ -0,0 +1,58 @@ +--- +name: branch-manager +description: "Manages git branches, PRs, and Linear ticket updates for documentation work. Use after doc-writer produces changes to split them into clean branches, create PRs, and update or create Linear tickets for tracking." +model: sonnet +tools: Read, Write, Edit, Bash, Grep, Glob +--- + +You manage the git and project-tracking lifecycle for Trunk documentation changes. + +## Your Inputs +You will receive: +- A description of the changes to commit +- File paths that belong to the change +- A Linear ticket ID (if one exists) to link/update +- The author's name for branch naming (default: sam) + +## Process + +### 1. Branch Setup +- Create a new branch from `main` named `/` (e.g., `sam/document-multi-branch-merge-queues`) +- If changes are already staged or in the working tree, stash them first, switch branches, then re-apply only the relevant files + +### 2. Commit +- Stage only the files relevant to this change +- Write a clear, concise commit message summarizing the change +- Include `Co-Authored-By: Claude Opus 4.6 ` + +### 3. Push and PR +- Push the branch to origin +- Create a PR using `gh pr create` with: + - A short, descriptive title + - A body containing: summary of changes, list of files modified, link to the Linear ticket if applicable, and open questions if any +- Include the Linear ticket ID in the PR body so it auto-links + +### 4. Linear Ticket Update +- **Always include the full PR URL** (e.g., `https://github.com/trunk-io/docs/pull/123`) in any Linear comment or description. Never reference a PR without its link. +- If a Linear ticket ID was provided: + - Add a comment to the ticket with: + - The PR URL as a clickable link + - A brief summary of what the docs change covers + - List of files modified + - Any open questions + - Update the ticket status to "In Review" + - Assign the ticket to the author if unassigned +- If no ticket exists: + - Create a new Linear ticket in the Trunk Engineering team + - Assign it to the specified author (default: "me") + - Label it with `docs` + - Include the PR URL as a clickable link in the description + - Report the new ticket ID + +## Output +Report: +- Branch name +- Commit SHA +- PR URL +- Linear ticket ID (existing or newly created) +- Any issues encountered diff --git a/readme.md b/readme.md index c1ef8e52..2b0c0c78 100644 --- a/readme.md +++ b/readme.md @@ -6,6 +6,33 @@ This repository is the official repo for [docs.trunk.io][docs]. If you see any mistakes or any improvements that can be made, we'd love your contributions! +## Local Development + +This repo is synced with [GitBook](https://www.gitbook.com/) via Git Sync. Content pushed to `main` is automatically published to [docs.trunk.io][docs]. To preview changes before publishing: + +### Setup + +1. Push your feature branch to GitHub: + ```bash + git push -u origin your-branch-name + ``` +2. In the GitBook editor, create a **Change Request** linked to your branch. +3. GitBook will render your branch content in a preview, separate from the published docs. + +### Workflow + +``` +Edit locally → git push → GitBook auto-syncs branch → Preview in GitBook editor + ↓ + Review & iterate + ↓ + Merge PR on GitHub → publishes to docs.trunk.io +``` + +- Every push to your branch updates the GitBook preview automatically +- Edits made in the GitBook web editor push commits back to your branch +- Nothing goes live on docs.trunk.io until the branch merges to `main` + ## Contributing If you see any mistakes or any improvements that can be made, we'd love your contributions! Just fork the repo and open a PR with your changes. While you're browsing [docs.trunk.io][docs], you can get to the GitHub source for that page via the `...` menu → `Edit on GitHub`: From 5502373354857fbbeb9e6690489a63edb47c148c Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 12:51:31 -0800 Subject: [PATCH 03/12] Add notes-processor agent and drafts workflow - Add notes-processor agent for end-to-end pipeline: notes file in, branch/PR/Linear ticket out - Add .claude/drafts/ directory with template for Slack pastes and engineer notes - Update agents README with new workflow documentation - Add .gitignore rules to keep personal drafts out of git Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 70 ++++++++++++++++++-- .claude/agents/notes-processor.md | 105 ++++++++++++++++++++++++++++++ .claude/drafts/TEMPLATE.md | 26 ++++++++ .gitignore | 4 ++ 4 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 .claude/agents/notes-processor.md create mode 100644 .claude/drafts/TEMPLATE.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index b40aaf82..3c5be2a0 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -22,14 +22,61 @@ Verify with `claude mcp list` or `/mcp` inside Claude Code. | Agent | Model | Purpose | |-------|-------|---------| +| `notes-processor` | Opus | End-to-end pipeline: reads a notes file, researches, drafts docs, creates branch/PR, updates Linear | | `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | | `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | | `changelog-writer` | Sonnet | Focused changelog/release note entries | | `branch-manager` | Sonnet | Creates branches, PRs, and updates/creates Linear tickets for tracking | +## Quick Start: Notes-Based Workflow + +The fastest way to turn Slack conversations and engineer notes into docs: + +### 1. Create a notes file + +Copy the template and fill it in: +```bash +cp .claude/drafts/TEMPLATE.md .claude/drafts/my-feature.md +``` + +Paste in your Slack messages, engineer notes, Linear ticket IDs — don't +worry about formatting. Raw paste is fine. + +### 2. Process the notes + +``` +Process the notes file at .claude/drafts/my-feature.md +``` + +The `notes-processor` agent will: +- Parse the notes and extract what changed +- Look up any Linear tickets for additional context +- Search existing docs to find what needs updating +- Draft the documentation changes +- Apply changes to the repo +- Create a branch (`sam/`), commit, push, and open a PR +- Update or create a Linear ticket with the PR link + +### 3. Review and iterate + +Check the PR and GitBook preview. The agent will list any open questions +for things it couldn't determine from the notes alone. + +### Batch processing + +To process multiple notes files: +``` +Process all notes files in .claude/drafts/ that haven't been processed yet +``` + ## Usage Examples -**Write docs for a feature:** +**Process a notes file (recommended):** +``` +Process the notes file at .claude/drafts/parallel-queues.md +``` + +**Write docs for a feature (manual):** ``` Use the doc-writer agent for the parallel queues feature. Linear tickets: MRG-452, MRG-467 @@ -47,10 +94,9 @@ then use doc-writer to draft docs based on the findings Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 ``` -**Chain agents:** +**Survey the backlog:** ``` -First use doc-researcher to survey all open tickets labeled "needs-docs", -then use doc-writer for each feature identified +Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` ## Parallel Workflows @@ -61,3 +107,19 @@ brew install claude-squad cs ``` This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. + +## Directory Structure + +``` +.claude/ + agents/ + notes-processor.md # End-to-end pipeline orchestrator + doc-writer.md # Documentation drafting + doc-researcher.md # Context gathering + changelog-writer.md # Changelog entries + branch-manager.md # Git/PR/Linear lifecycle + README.md # This file + drafts/ + TEMPLATE.md # Notes file template + *.md # Your notes files (gitignored) +``` diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md new file mode 100644 index 00000000..6ea5656e --- /dev/null +++ b/.claude/agents/notes-processor.md @@ -0,0 +1,105 @@ +--- +name: notes-processor +description: "Processes a notes/drafts file into documentation changes. Use when given a markdown file from .claude/drafts/ containing Slack conversations, engineer notes, or feature descriptions. Orchestrates the full pipeline: research, write, apply changes, branch, PR, and Linear updates." +model: opus +--- + +You are a documentation pipeline orchestrator for Trunk.io. You take raw, +unstructured input (Slack threads, engineer scribbles, feature descriptions) +and produce polished documentation changes with full project tracking. + +## Your Input +A path to a markdown notes file (typically in `.claude/drafts/`). The file +may contain any combination of: +- Slack message pastes (messy formatting is expected) +- Engineer notes and bullet points +- Linear ticket references +- Feature names or descriptions +- Links to PRs, code, or external resources + +## Your Process + +### Phase 1: Parse and Understand +1. Read the notes file completely +2. Extract: + - **Feature/change name** — what is this about? + - **Linear ticket IDs** — any TRUNK-XXXXX references + - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup + - **Change type** — new feature, update, fix, or deprecation + - **Key details** — what changed, why, any configuration involved + - **Priority** — if specified, otherwise infer from context + +### Phase 2: Research +1. If Linear ticket IDs were found, look them up via Linear MCP: + - Read descriptions, comments, linked PRs + - Check for related tickets +2. Search the local docs repo for existing coverage: + - Use Glob to find related files + - Use Grep to find references to the feature/topic + - Read existing docs to understand current state +3. Search GitBook docs MCP for published content on the topic +4. Identify gaps between what exists and what the notes describe + +### Phase 3: Draft Documentation +Based on everything gathered, write the documentation changes: +- Match the tone and structure of existing Trunk docs (read nearby files) +- For **new pages**: write the full page content +- For **updates**: show the exact edits needed (old text → new text) +- For **fixes**: identify and correct the specific issues + +### Phase 4: Apply Changes +Apply the documentation changes directly to the repo files: +- Edit existing files in place using the Edit tool +- Create new files using the Write tool +- Update `summary.md` if adding new pages + +### Phase 5: Branch, PR, and Linear +After changes are applied: + +1. **Branch**: Create a branch from `main` named `sam/` + - Stash any unrelated working tree changes first + - Apply only the files relevant to this change +2. **Commit**: Stage and commit with a clear message, include + `Co-Authored-By: Claude Opus 4.6 ` +3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: + - Short descriptive title + - Body with: summary, files changed, Linear ticket link, open questions +4. **Linear update**: + - If a ticket exists: add comment with PR link, update status to "In Review" + - If no ticket: create one in Trunk Engineering team, label `docs`, + assign to "me", include PR link +5. **Return to original branch**: Switch back to the branch you started on + and restore any stashed changes + +## Output Format +When complete, report: + +``` +## Processed: [Feature Name] + +### Changes Made +- [list of files created/modified] + +### Branch & PR +- Branch: sam/[branch-name] +- PR: [URL] + +### Linear +- Ticket: [TRUNK-XXXXX] — [status] + +### Open Questions +1. [questions for team review] + +### Notes File +- Source: [path to notes file] +- Status: Processed +``` + +## Important Rules +- **Always include PR links** in Linear comments and descriptions +- **One notes file = one PR**. If a notes file describes multiple unrelated + changes, flag this and ask the user how to split them +- **Preserve the notes file** — don't delete or modify it. It's the audit trail. +- **Ask before guessing** — if the notes are too ambiguous to determine what + docs change is needed, output your best interpretation and list specific + questions rather than making assumptions diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md new file mode 100644 index 00000000..695f7ace --- /dev/null +++ b/.claude/drafts/TEMPLATE.md @@ -0,0 +1,26 @@ +# [Feature/Change Title] + +## Type + + +## Priority + + +## Linear Tickets + +- TRUNK-XXXXX + +## What Changed + + +## Target Docs + + +## Context + diff --git a/.gitignore b/.gitignore index b534937b..7658a23b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ # Mac .DS_Store /.idea/workspace.xml + +# Agent drafts (notes files are personal, template is committed) +.claude/drafts/*.md +!.claude/drafts/TEMPLATE.md From 2c45f95e77ab39918318fc2fec34ab153fa39a79 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 12:58:01 -0800 Subject: [PATCH 04/12] Add GitHub PRs field to notes template and processor agent Co-Authored-By: Claude Opus 4.6 --- .claude/agents/notes-processor.md | 1 + .claude/drafts/TEMPLATE.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 6ea5656e..f929bcc0 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -24,6 +24,7 @@ may contain any combination of: 2. Extract: - **Feature/change name** — what is this about? - **Linear ticket IDs** — any TRUNK-XXXXX references + - **GitHub PR URLs** — any github.com PR links. Use `gh pr view ` to read PR descriptions, changed files, and review comments for additional context - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup - **Change type** — new feature, update, fix, or deprecation - **Key details** — what changed, why, any configuration involved diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md index 695f7ace..125e283e 100644 --- a/.claude/drafts/TEMPLATE.md +++ b/.claude/drafts/TEMPLATE.md @@ -1,25 +1,37 @@ # [Feature/Change Title] ## Type + ## Priority + ## Linear Tickets + + - TRUNK-XXXXX ## What Changed + +## GitHub PRs + + + ## Target Docs + ## Context + + ## Priority From a154a9cfeb638c75a8e443de88c589d05174b037 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:03:28 -0800 Subject: [PATCH 06/12] Add sources file generation to documentation agents Agents now produce a .sources.md file alongside each notes file, listing every Linear ticket, GitHub PR, existing doc, code snippet, and external reference used as input. Provides a human-readable audit trail for accuracy checks and cross-referencing. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/doc-researcher.md | 16 ++++++++--- .claude/agents/doc-writer.md | 9 ++++++ .claude/agents/notes-processor.md | 48 ++++++++++++++++++++++++++++++- 3 files changed, 68 insertions(+), 5 deletions(-) diff --git a/.claude/agents/doc-researcher.md b/.claude/agents/doc-researcher.md index abe06a8e..5389ae82 100644 --- a/.claude/agents/doc-researcher.md +++ b/.claude/agents/doc-researcher.md @@ -13,14 +13,22 @@ You are working inside the local gitbook docs repository. ## Process 1. Look up all provided Linear ticket IDs — extract descriptions, comments, linked PRs, related tickets -2. Explore the local filesystem to find any current docs coverage of the topic -3. Identify gaps between what exists and what's needed +2. Look up any GitHub PR URLs using `gh pr view ` — extract + descriptions, changed files, and review comments +3. Explore the local filesystem to find any current docs coverage of the topic +4. Identify gaps between what exists and what's needed ## Output Produce a research brief with: - **Feature Summary**: What is this, in plain terms -- **Linear Tickets**: ID, title, status, assignee for each -- **PRs**: All linked PRs with titles and URLs +- **Linear Tickets**: ID, title, status, assignee for each, with links +- **PRs**: All linked PRs with titles, URLs, status, and key changes - **Existing Docs**: What currently exists in the repo and where (include file paths) +- **Key Code References**: Any relevant code snippets, configs, or schemas from PRs - **Gaps**: What's missing or outdated - **Suggested Scope**: What the doc-writer agent should focus on + +If a notes file path was provided, also write a `.sources.md` file +alongside it (same directory, same name with `.sources.md` suffix) +containing all the above in a structured, human-readable format for +cross-referencing and accuracy checks. diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 50f87148..801e3a73 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -25,6 +25,15 @@ You will receive some combination of: 3. **Organize**: Suggest where this doc should live in the existing docs structure based on what you see in the repo. +## Sources File +Before drafting, write a `.sources.md` file alongside any notes file +you were given (same directory, same name with `.sources.md` suffix). +If no notes file path was given, include a `### Sources` section in +your output instead. This should list every Linear ticket, GitHub PR, +existing doc file, code snippet, and external reference you used as +input, with links and brief descriptions. Use `gh pr view ` to +read GitHub PR details. This lets reviewers verify accuracy. + ## Required Outputs Produce a single markdown file with these clearly labeled sections: diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 9f6beed8..7ac92162 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -41,7 +41,53 @@ may contain any combination of: 3. Search GitBook docs MCP for published content on the topic 4. Identify gaps between what exists and what the notes describe -### Phase 3: Draft Documentation +### Phase 2.5: Generate Sources File +Write a sources file alongside the notes file at the same path with a +`.sources.md` suffix (e.g., `.claude/drafts/my-feature.sources.md`). +This file is a human-readable manifest of everything the agent found +and used as input. It should be easy to scan for accuracy and +cross-referencing. + +Format: + +```markdown +# Sources: [Feature Name] +Generated: [date] + +## Linear Tickets +For each ticket found: +- **[TRUNK-XXXXX](linear-url)** — [title] + - Status: [status] | Assignee: [name] + - Summary: [1-2 sentence description from ticket] + +## GitHub PRs +For each PR found (from notes file, Linear tickets, or discovered): +- **[PR title](github-url)** — [repo] #[number] + - Status: [merged/open/closed] | Author: [name] + - Summary: [1-2 sentence description from PR body] + - Key changes: [list of notable files or areas changed] + +## Existing Docs +Files in the repo that are relevant to this change: +- `[file path]` — [brief description of what it covers and its relevance] + +## Key Code References +Any code snippets, config examples, API schemas, or technical details +extracted from PRs, tickets, or Slack context that informed the docs: +- Source: [where it came from] + ``` + [the relevant snippet] + ``` + +## External References +Any external URLs, docs, or resources referenced: +- [title](url) — [why it's relevant] +``` + +This file serves as an audit trail so reviewers can verify where +information came from and check accuracy against primary sources. + + Based on everything gathered, write the documentation changes: - Match the tone and structure of existing Trunk docs (read nearby files) - For **new pages**: write the full page content From 6b803c6bf4e75e70f3ed8c42fec63446ff10bc70 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:35:05 -0800 Subject: [PATCH 07/12] Add review reports, Slack link capture, and Linear ticket linking - Add review report generation (Phase 6) to notes-processor agent - Add Slack link extraction and attachment to Linear tickets - Add automatic search and linking of related engineering tickets - Enrich PR bodies with Slack context and related ticket references - Add Slack Links field to notes template - Create session report at .claude/reports/2026-02-17-docs-backlog.md - Replace Claude Squad references with sequential workflow docs - Add "What the Agent Does" section to README explaining all 6 phases Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 53 ++++-- .claude/agents/doc-writer.md | 16 +- .claude/agents/notes-processor.md | 107 ++++++++++-- .claude/drafts/TEMPLATE.md | 5 + .claude/reports/2026-02-17-docs-backlog.md | 188 +++++++++++++++++++++ 5 files changed, 347 insertions(+), 22 deletions(-) create mode 100644 .claude/reports/2026-02-17-docs-backlog.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 3c5be2a0..1f1e6f35 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -57,18 +57,31 @@ The `notes-processor` agent will: - Create a branch (`sam/`), commit, push, and open a PR - Update or create a Linear ticket with the PR link -### 3. Review and iterate +### 3. Review the report + +After processing, the agent appends a review card to the daily report at +`.claude/reports/YYYY-MM-DD-.md`. Each card includes: +- PR and Linear links +- Links back to the draft and sources files +- A **Review focus** field highlighting what the reviewer should check +- Open questions the agent couldn't resolve + +### 4. Review and iterate Check the PR and GitBook preview. The agent will list any open questions for things it couldn't determine from the notes alone. ### Batch processing -To process multiple notes files: +To process multiple notes files sequentially: ``` -Process all notes files in .claude/drafts/ that haven't been processed yet +Process each notes file in .claude/drafts/ one at a time. +For each file: research, draft, apply changes, create branch/PR, update Linear, then move to the next. ``` +Each file gets its own branch (`sam/`), PR, and Linear ticket. +The agent processes them one at a time to avoid git conflicts. + ## Usage Examples **Process a notes file (recommended):** @@ -76,6 +89,14 @@ Process all notes files in .claude/drafts/ that haven't been processed yet Process the notes file at .claude/drafts/parallel-queues.md ``` +**Process several notes files sequentially:** +``` +Process each of these notes files one at a time: +- .claude/drafts/feature-a.md +- .claude/drafts/feature-b.md +- .claude/drafts/feature-c.md +``` + **Write docs for a feature (manual):** ``` Use the doc-writer agent for the parallel queues feature. @@ -99,14 +120,23 @@ Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` -## Parallel Workflows +## What the Agent Does -For working on multiple features simultaneously, use [Claude Squad](https://github.com/smtg-ai/claude-squad): -```bash -brew install claude-squad -cs -``` -This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. +When you process a notes file, the `notes-processor` agent runs through +six phases sequentially: + +1. **Parse** — extracts feature name, Linear tickets, GitHub PRs, Slack + links, and product area from the notes +2. **Research** — looks up Linear tickets, searches for related engineering + tickets, scans existing docs for coverage gaps +3. **Sources** — writes a `.sources.md` audit trail with every ticket, PR, + Slack thread, and doc file it used as input +4. **Draft** — writes or edits documentation, matching existing Trunk style +5. **Branch/PR/Linear** — creates branch, commits, pushes, opens PR, updates + or creates Linear ticket with PR link, attaches Slack links, and links + docs ticket to related engineering tickets +6. **Report** — appends a review card to `.claude/reports/` with PR link, + Linear link, review focus areas, and open questions ## Directory Structure @@ -122,4 +152,7 @@ This lets you run multiple Claude Code sessions in parallel, each with its own g drafts/ TEMPLATE.md # Notes file template *.md # Your notes files (gitignored) + *.sources.md # Source audit trails (gitignored) + reports/ + *.md # Review reports (committed to repo) ``` diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 801e3a73..54f635e2 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -15,14 +15,17 @@ details and linked PRs. You will receive some combination of: - A feature name or topic - Slack message blobs with context about the feature +- Slack thread links (`trunk-io.slack.com` URLs) - Linear ticket IDs to look up for details and PRs ## Your Process 1. **Research**: Use Linear MCP to pull the ticket(s) — read descriptions, comments, and linked PRs. Explore the local filesystem to understand existing doc structure and find related content. -2. **Draft**: Write the documentation in clear, user-focused prose. -3. **Organize**: Suggest where this doc should live in the existing +2. **Find related tickets**: Search Linear for engineering tickets related + to the feature being documented. Collect their IDs for linking later. +3. **Draft**: Write the documentation in clear, user-focused prose. +4. **Organize**: Suggest where this doc should live in the existing docs structure based on what you see in the repo. ## Sources File @@ -50,6 +53,15 @@ the actual directory structure you can see. A list of PRs extracted from Linear tickets, formatted as: - PR title | URL | status | brief relevance note +### Slack Context +List any Slack links found in the input. These should be attached to the +Linear ticket and referenced in the PR body. + +### Related Linear Tickets +List any related engineering tickets found during research. These should +be linked as relations on the docs ticket so engineers can see the docs +work from their feature tickets. + ### Open Questions Numbered list of things you couldn't determine from the inputs — questions for the team to answer to complete the doc. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 7ac92162..b4f2ebb4 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -25,6 +25,9 @@ may contain any combination of: - **Feature/change name** — what is this about? - **Linear ticket IDs** — any TRUNK-XXXXX references - **GitHub PR URLs** — any github.com PR links. Use `gh pr view ` to read PR descriptions, changed files, and review comments for additional context + - **Slack links** — any `trunk-io.slack.com` URLs. Collect all of them. + These are important context breadcrumbs — they will be attached to + Linear tickets and referenced in the PR body - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup - **Change type** — new feature, update, fix, deprecation, or explainer - **Key details** — what changed, why, any configuration involved @@ -32,14 +35,23 @@ may contain any combination of: ### Phase 2: Research 1. If Linear ticket IDs were found, look them up via Linear MCP: - - Read descriptions, comments, linked PRs - - Check for related tickets -2. Search the local docs repo for existing coverage: + - Read full descriptions, comments, attachments, and linked PRs + - Note any Slack links already attached to the ticket + - Check for related tickets linked from the ticket +2. **Search Linear for related work tickets** — this is critical for + linking docs work to the engineering work it documents: + - Search by feature name, product area keywords, and relevant terms + - Search by project if the ticket belongs to a project + - Look for engineering tickets (bugs, features, tasks) that describe + the same functionality being documented + - Collect the IDs of all related tickets found — you will link these + in Phase 5 +3. Search the local docs repo for existing coverage: - Use Glob to find related files - Use Grep to find references to the feature/topic - Read existing docs to understand current state -3. Search GitBook docs MCP for published content on the topic -4. Identify gaps between what exists and what the notes describe +4. Search GitBook docs MCP for published content on the topic +5. Identify gaps between what exists and what the notes describe ### Phase 2.5: Generate Sources File Write a sources file alongside the notes file at the same path with a @@ -79,6 +91,17 @@ extracted from PRs, tickets, or Slack context that informed the docs: [the relevant snippet] ``` +## Slack Threads +Links to Slack conversations that provided context: +- [channel/thread description](slack-url) — [what context it provided] + +## Related Linear Tickets +Tickets discovered via search that relate to the same feature/area +(these will be linked as relations on the docs ticket): +- **[TRUNK-XXXXX](linear-url)** — [title] + - Relationship: [documents / is documented by / related to] + - Why: [brief reason this is related] + ## External References Any external URLs, docs, or resources referenced: - [title](url) — [why it's relevant] @@ -123,14 +146,75 @@ After changes are applied: `Co-Authored-By: Claude Opus 4.6 ` 3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - Short descriptive title - - Body with: summary, files changed, Linear ticket link, open questions -4. **Linear update**: - - If a ticket exists: add comment with PR link, update status to "In Review" - - If no ticket: create one in Trunk Engineering team, label `docs`, - assign to "me", include PR link + - Body must include: + - **Summary** — bullet list of changes + - **Linear tickets** — link every related ticket, not just the docs ticket + - **Slack context** — list any Slack thread links from the notes file + so reviewers can trace back to the original conversation + - **Files changed** — list of files created/modified + - **Open questions** — things the agent couldn't confirm + - **Test plan** — checklist for reviewer +4. **Linear update** — this is a multi-step process: + + **4a. Create or update the docs ticket:** + - If a ticket exists: update its description to be comprehensive. + Include: what docs were changed, why, links to the PR, links to + any Slack threads found in the notes, and a summary of what the + reviewer should check. Add a comment with the PR link. + Update status to "In Review". + - If no ticket exists: create one in Trunk Engineering team with + label `docs`, assigned to "me". Write a thorough description + (not just a title) covering: what changed, why, the PR link, + Slack context links, and open questions. Include PR link. + + **4b. Attach Slack links to the ticket:** + - For every Slack URL found in the notes file, add it as a link + attachment on the Linear ticket using the `links` field in + `update_issue` or `create_issue`. Use a descriptive title like + "Slack: [channel] — [brief topic]" for each link. + + **4c. Link related tickets:** + - For every related Linear ticket discovered during Phase 2 research, + add a `relatedTo` relation on the docs ticket. This creates a + bidirectional link so engineers can see the docs work from their + feature tickets. + - For tickets that were explicitly referenced in the notes file + (specified by the user), also add them as relations. + - Use `update_issue` with the `relatedTo` field to set all relations + at once. Include both the specified tickets and the discovered ones. + 5. **Return to original branch**: Switch back to the branch you started on and restore any stashed changes +### Phase 6: Generate Review Report +After the PR is created, append an entry to the daily report file at +`.claude/reports/YYYY-MM-DD-.md`. If the file doesn't +exist yet, create it with a header. Each entry should be a self-contained +review card with everything a human reviewer needs. + +Report entry format: + +```markdown +### PR #[number] — [short title] +| | | +|---|---| +| **Branch** | `sam/[branch-name]` | +| **PR** | [full GitHub PR URL] | +| **Linear** | [TRUNK-XXXXX](linear-url) — [status] | +| **Sources** | `.claude/drafts/[notes-file].sources.md` | +| **Draft** | `.claude/drafts/[notes-file].md` | +| **Type** | [new-feature / update / fix / deprecation / explainer] | +| **Changes** | [1-2 sentence summary of files created/modified] | +| **Slack context** | [List of Slack links, or "None"] | +| **Related tickets** | [List of linked TRUNK-XXXXX IDs, or "None"] | +| **Review focus** | [What the human reviewer should pay attention to — accuracy risks, open questions, things the agent wasn't sure about] | +| **Open questions** | [Numbered list, or "None"] | +``` + +The **Review focus** field is critical. Be honest about what you're +uncertain about — flag any details you inferred rather than confirmed, +any placeholder content, and any areas where the docs could be wrong. + ## Output Format When complete, report: @@ -147,6 +231,9 @@ When complete, report: ### Linear - Ticket: [TRUNK-XXXXX] — [status] +### Review Report +- Entry added to: .claude/reports/[filename].md + ### Open Questions 1. [questions for team review] diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md index d7697524..9ddadc94 100644 --- a/.claude/drafts/TEMPLATE.md +++ b/.claude/drafts/TEMPLATE.md @@ -25,6 +25,11 @@ +## Slack Links + + + ## Target Docs -## Slack Links +## Context Links - + ## Target Docs From c48c6d24be6531691197d990ab220cd69ae2e883 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:58:36 -0800 Subject: [PATCH 09/12] Add changelog staging, HTML reports, and context link capture - Changelog entries now staged to .claude/staging/changelog/ for DatoCMS upload - Review reports output as HTML (open in browser with clickable links and checkboxes) - Remove old markdown report format - Add .claude/staging/ and .claude/reports/*.html to .gitignore - Update notes-processor with Phase 5.5 (changelog) and updated Phase 6 (HTML report) - Broaden template "Slack Links" to "Context Links" (Slack, Slite, Loom, etc.) Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 20 ++- .claude/agents/changelog-writer.md | 27 ++- .claude/agents/notes-processor.md | 104 +++++++++--- .claude/reports/2026-02-17-docs-backlog.md | 188 --------------------- .gitignore | 4 + 5 files changed, 123 insertions(+), 220 deletions(-) delete mode 100644 .claude/reports/2026-02-17-docs-backlog.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index cff87471..8d8d1dc1 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -59,12 +59,10 @@ The `notes-processor` agent will: ### 3. Review the report -After processing, the agent appends a review card to the daily report at -`.claude/reports/YYYY-MM-DD-.md`. Each card includes: -- PR and Linear links -- Links back to the draft and sources files -- A **Review focus** field highlighting what the reviewer should check -- Open questions the agent couldn't resolve +After processing, the agent: +- Appends a review card to `.claude/reports/YYYY-MM-DD-.html` + (open in browser for easy scanning — PR links, Linear links, review focus) +- Stages a changelog entry at `.claude/staging/changelog/` for DatoCMS upload ### 4. Review and iterate @@ -136,8 +134,10 @@ six phases sequentially: or creates Linear ticket with PR link, attaches all context links (Slack, Slite, Loom, etc.), and links docs ticket to related engineering tickets -6. **Report** — appends a review card to `.claude/reports/` with PR link, - Linear link, review focus areas, and open questions +6. **Changelog** — stages a changelog entry at `.claude/staging/changelog/` + for manual DatoCMS upload +7. **Report** — appends an HTML review card to `.claude/reports/` with PR + link, Linear link, review focus areas, and open questions ## Directory Structure @@ -155,5 +155,7 @@ six phases sequentially: *.md # Your notes files (gitignored) *.sources.md # Source audit trails (gitignored) reports/ - *.md # Review reports (committed to repo) + *.html # Review reports (gitignored, open in browser) + staging/ + changelog/ # Changelog entries for DatoCMS upload (gitignored) ``` diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md index a6d8ce25..c6d3f84a 100644 --- a/.claude/agents/changelog-writer.md +++ b/.claude/agents/changelog-writer.md @@ -6,7 +6,7 @@ tools: Read, Write, Bash, Grep, Glob --- You write changelog entries for Trunk.io matching the style at -www.trunk.io/changelog. +www.trunk.io/changelog. Entries are staged for manual upload to DatoCMS. ## Style Guide - Lead with the user benefit, not the implementation detail @@ -14,6 +14,7 @@ www.trunk.io/changelog. - Include a brief "why this matters" sentence - Keep to 2-4 sentences max - End with a link to relevant docs if applicable +- Format: date, title, description, docs link ## Process 1. Look up the Linear ticket(s) for context and linked PRs @@ -21,4 +22,26 @@ www.trunk.io/changelog. 3. Draft the changelog entry 4. Flag any ambiguities as questions -Output a clean markdown file with the changelog entry and any questions. +## Output +Write the changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md` +using this format: + +```markdown +--- +date: YYYY-MM-DD +title: [Short, punchy title] +product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] +status: draft +linear: [TRUNK-XXXXX URL if applicable] +docs_pr: [GitHub PR URL if applicable] +--- + +[2-4 sentence description. Lead with user benefit. Present tense.] + +[Learn more →](https://docs.trunk.io/path/to/relevant/page) +``` + +If processing multiple features, write one file per changelog entry. + +After writing, list all staged files in your response so the user knows +what's ready for DatoCMS upload. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index fc1f2ba9..84ce4717 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -197,29 +197,88 @@ After changes are applied: 5. **Return to original branch**: Switch back to the branch you started on and restore any stashed changes -### Phase 6: Generate Review Report -After the PR is created, append an entry to the daily report file at -`.claude/reports/YYYY-MM-DD-.md`. If the file doesn't -exist yet, create it with a header. Each entry should be a self-contained -review card with everything a human reviewer needs. +### Phase 5.5: Stage Changelog Entry +Write a changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md`. +These are staged for manual upload to DatoCMS. -Report entry format: +Use this format: ```markdown -### PR #[number] — [short title] -| | | -|---|---| -| **Branch** | `sam/[branch-name]` | -| **PR** | [full GitHub PR URL] | -| **Linear** | [TRUNK-XXXXX](linear-url) — [status] | -| **Sources** | `.claude/drafts/[notes-file].sources.md` | -| **Draft** | `.claude/drafts/[notes-file].md` | -| **Type** | [new-feature / update / fix / deprecation / explainer] | -| **Changes** | [1-2 sentence summary of files created/modified] | -| **Context links** | [List of Slack/Slite/Loom/other links, or "None"] | -| **Related tickets** | [List of linked TRUNK-XXXXX IDs, or "None"] | -| **Review focus** | [What the human reviewer should pay attention to — accuracy risks, open questions, things the agent wasn't sure about] | -| **Open questions** | [Numbered list, or "None"] | +--- +date: YYYY-MM-DD +title: [Short, punchy title — lead with user benefit] +product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] +status: draft +linear: [TRUNK-XXXXX URL if applicable] +docs_pr: [GitHub PR URL] +--- + +[2-4 sentence description. Lead with user benefit. Present tense. +Include a "why this matters" sentence.] + +[Learn more →](https://docs.trunk.io/path/to/relevant/page) +``` + +### Phase 6: Generate Review Report +After the PR is created, append an entry to the daily report file at +`.claude/reports/YYYY-MM-DD-.html`. If the file doesn't +exist yet, create it with a full HTML document including basic styling. +Each entry should be a self-contained review card with everything a +human reviewer needs. The HTML format makes it easy to open in a browser +for quick scanning. + +If the file already exists, append the new card inside the `
` element. + +HTML template for new files: + +```html + + + + + Docs Review Report — [date] + + + +

Docs Review Report — [date]

+
+
+ + +``` + +Card format to append inside `
`: + +```html +
+

PR #[number] — [short title]

+ + + + + + + + + + +
Branchsam/[branch-name]
PR[url]
LinearTRUNK-XXXXX — [status]
Sources.claude/drafts/[notes-file].sources.md
Draft.claude/drafts/[notes-file].md
Type[new-feature / update / fix / deprecation / explainer]
Changes[1-2 sentence summary]
Context links[Slack/Slite/Loom links as clickable anchors, or "None"]
Related tickets[Linked TRUNK-XXXXX as clickable anchors, or "None"]
+
Review focus: [what the reviewer should check]
+
Open questions:
  1. [questions]
+
``` The **Review focus** field is critical. Be honest about what you're @@ -243,7 +302,10 @@ When complete, report: - Ticket: [TRUNK-XXXXX] — [status] ### Review Report -- Entry added to: .claude/reports/[filename].md +- Entry added to: .claude/reports/[filename].html + +### Changelog +- Staged at: .claude/staging/changelog/[filename].md ### Open Questions 1. [questions for team review] diff --git a/.claude/reports/2026-02-17-docs-backlog.md b/.claude/reports/2026-02-17-docs-backlog.md deleted file mode 100644 index d23f74ba..00000000 --- a/.claude/reports/2026-02-17-docs-backlog.md +++ /dev/null @@ -1,188 +0,0 @@ -# Docs Backlog Processing Report -Generated: 2026-02-17 - -## Summary -14 PRs created across P1-P2 documentation backlog tickets. All Linear tickets moved to "In Review". Each PR requires manual review for accuracy before merging. - ---- - -## P1: Quick Fixes - -### PR #430 — Multi-branch merge queue docs -| | | -|---|---| -| **Branch** | `sam/document-multi-branch-merge-queues` | -| **PR** | https://github.com/trunk-io/docs/pull/430 | -| **Linear** | [TRUNK-17546](https://linear.app/trunk/issue/TRUNK-17546) — In Review | -| **Type** | new-feature | -| **Changes** | New `multi-branch-queues.md` page, FAQ correction in `common-problems.md`, cross-link in `advanced-settings.md` | -| **Review focus** | Verify multi-branch queue behavior matches product; confirm FAQ answer about multiple queues per repo | - -### PR #431 — Fix codeowners link -| | | -|---|---| -| **Branch** | `sam/fix-codeowners-link` | -| **PR** | https://github.com/trunk-io/docs/pull/431 | -| **Linear** | [TRUNK-17095](https://linear.app/trunk/issue/TRUNK-17095) — In Review | -| **Type** | fix | -| **Changes** | Fixed broken CODEOWNERS link in `flaky-tests/dashboard.md`, added manual override note to `detection.md` | -| **Review focus** | Quick check — link fix and minor prose addition | - -### PR #432 — Fix deprecated flakytests CLI refs -| | | -|---|---| -| **Branch** | `sam/fix-deprecated-flakytests-cli` | -| **PR** | https://github.com/trunk-io/docs/pull/432 | -| **Linear** | [TRUNK-17167](https://linear.app/trunk/issue/TRUNK-17167) — In Review | -| **Follow-up** | [TRUNK-17573](https://linear.app/trunk/issue/TRUNK-17573) — broader cleanup of remaining deprecated refs | -| **Type** | fix | -| **Changes** | Fixed 4 high-priority files: `jasmine.md`, `other-test-frameworks.md`, `otherci.md`, `uploader.md` | -| **Review focus** | Verify CLI command names match current product (`trunk flakytests` vs deprecated forms) | - ---- - -## Draft-based Changes - -### PR #433 — Merge queue graph UI docs -| | | -|---|---| -| **Branch** | `sam/merge-queue-graph-ui-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/433 | -| **Linear** | [TRUNK-17575](https://linear.app/trunk/issue/TRUNK-17575) — In Review | -| **Draft** | `.claude/drafts/new-merge-graph-ui.md` | -| **Type** | update | -| **Changes** | Rewrote `monitor-queue-status.md` with graph view UI details | -| **Review focus** | Verify UI descriptions match actual graph view; screenshots may be needed | - -### PR #434 — Manual test status overrides -| | | -|---|---| -| **Branch** | `sam/flaky-test-manual-overrides` | -| **PR** | https://github.com/trunk-io/docs/pull/434 | -| **Linear** | [TRUNK-17576](https://linear.app/trunk/issue/TRUNK-17576) — In Review | -| **Draft** | `.claude/drafts/flaky-tests-rules-engine.md` | -| **Type** | update | -| **Changes** | Expanded manual override section in `detection.md` | -| **Review focus** | Confirm override behaviors and status options match product | - -### PR #435 — Cypress junit plugin recommendation -| | | -|---|---| -| **Branch** | `sam/cypress-junit-plugin-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/435 | -| **Linear** | [TRUNK-17577](https://linear.app/trunk/issue/TRUNK-17577) — In Review | -| **Draft** | `.claude/drafts/falky-test-cyprus.md` | -| **Type** | update | -| **Changes** | Added `cypress-junit-plugin` recommendation to `cypress.md` | -| **Review focus** | Verify plugin name, install instructions, and config example | - -### PR #436 — Bamboo CI provider docs -| | | -|---|---| -| **Branch** | `sam/bamboo-ci-provider-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/436 | -| **Linear** | [TRUNK-17578](https://linear.app/trunk/issue/TRUNK-17578) — In Review | -| **Draft** | `.claude/drafts/atlassian-bamboo.md` | -| **Type** | new-feature | -| **Changes** | New `bamboo.md` CI provider page, added to `summary.md` and CI providers include | -| **Review focus** | Verify Bamboo script task syntax and variable names match actual Bamboo CI | - -### PR #437 — Concurrency settings clarification -| | | -|---|---| -| **Branch** | `sam/concurrency-settings-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/437 | -| **Linear** | [TRUNK-17579](https://linear.app/trunk/issue/TRUNK-17579) — In Review | -| **Draft** | `.claude/drafts/concurrency-settings.md` | -| **Type** | explainer | -| **Changes** | Clarified concurrency wording in `advanced-settings.md` and `batching.md` | -| **Review focus** | Confirm bisection concurrency behavior matches product | - -### PR #438 — Google Cloud Build CI provider docs -| | | -|---|---| -| **Branch** | `sam/google-cloud-build-ci-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/438 | -| **Linear** | [TRUNK-17580](https://linear.app/trunk/issue/TRUNK-17580) — In Review | -| **Draft** | `.claude/drafts/google-cloud.md` | -| **Type** | new-feature | -| **Changes** | New `google-cloud-build.md` CI provider page, added to `summary.md` and CI providers include | -| **Review focus** | Verify GCB `cloudbuild.yaml` syntax, substitution variables, and `gcloud` commands | - -### PR #439 — Merge Queue API reference improvements -| | | -|---|---| -| **Branch** | `sam/merge-queue-api-reference` | -| **PR** | https://github.com/trunk-io/docs/pull/439 | -| **Linear** | [TRUNK-17581](https://linear.app/trunk/issue/TRUNK-17581) — In Review | -| **Draft** | `.claude/drafts/merge-queue-api-endpoints.md` | -| **Type** | update | -| **Changes** | Rewrote `merge.md` API reference with curl examples | -| **Review focus** | Verify API endpoints, request/response schemas, and authentication method | - ---- - -## P2: Backlog Tickets - -### PR #440 — FAQ: missing repos in dropdown -| | | -|---|---| -| **Branch** | `sam/merge-faq-repo-not-in-dropdown` | -| **PR** | https://github.com/trunk-io/docs/pull/440 | -| **Linear** | [TRUNK-16724](https://linear.app/trunk/issue/TRUNK-16724) — In Review | -| **Sources** | `.claude/drafts/merge-faq-repo-dropdown.sources.md` | -| **Type** | explainer | -| **Changes** | New FAQ entry in `common-problems.md` about repos not appearing in dropdown | -| **Review focus** | Verify the troubleshooting steps match actual product behavior | - -### PR #441 — SSO and Authentication docs -| | | -|---|---| -| **Branch** | `sam/improve-sso-login-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/441 | -| **Linear** | [TRUNK-16793](https://linear.app/trunk/issue/TRUNK-16793) — In Review | -| **Sources** | `.claude/drafts/sso-documentation.sources.md` | -| **Type** | new-feature | -| **Changes** | New `sso-and-authentication.md` page, cross-links from `connecting-to-trunk.md`, `managing-your-organization.md`, `billing.md` | -| **Review focus** | Confirm supported IdPs, SSO setup flow, and whether SSO-only enforcement is supported. This page is high-level since SSO is configured server-side — verify nothing is inaccurate. | - -### PR #442 — GitHub IP allow list docs -| | | -|---|---| -| **Branch** | `sam/github-ip-allow-lists-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/442 | -| **Linear** | [TRUNK-16633](https://linear.app/trunk/issue/TRUNK-16633) — In Review | -| **Sources** | `.claude/drafts/github-ip-allowlist.sources.md` | -| **Type** | new-feature | -| **Changes** | New `github-ip-allow-lists.md` page, cross-reference from `github-app-permissions.md` | -| **Review focus** | **IP addresses are placeholders** — infra team must confirm actual IPs before merging. Watch the [Loom video](https://www.loom.com/share/9a3627f6ff264fbf8e11309c237efe0c) to verify steps. | - -### PR #443 — Flaky Tests onboarding improvements -| | | -|---|---| -| **Branch** | `sam/improve-flaky-tests-onboarding-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/443 | -| **Linear** | [TRUNK-16920](https://linear.app/trunk/issue/TRUNK-16920) — In Review | -| **Sources** | `.claude/drafts/flaky-tests-onboarding.sources.md` | -| **Type** | explainer | -| **Changes** | Rewrote Getting Started page, new `test-identification.md` page, enhanced `otherci.md` and `uploader.md` | -| **Review focus** | Confirm test identification explanation matches backend behavior (@eli/@gabe). Verify credential path in UI. Check env var callouts are accurate. | - ---- - -## Review Checklist - -- [ ] PR #430 — Multi-branch merge queues -- [ ] PR #431 — Codeowners link fix -- [ ] PR #432 — Deprecated CLI refs -- [ ] PR #433 — Graph UI docs -- [ ] PR #434 — Manual overrides -- [ ] PR #435 — Cypress plugin -- [ ] PR #436 — Bamboo CI -- [ ] PR #437 — Concurrency settings -- [ ] PR #438 — Google Cloud Build -- [ ] PR #439 — API reference -- [ ] PR #440 — FAQ repo dropdown -- [ ] PR #441 — SSO docs -- [ ] PR #442 — IP allow list (needs infra input) -- [ ] PR #443 — FT onboarding (needs eng input) diff --git a/.gitignore b/.gitignore index 7658a23b..913e0cbf 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,7 @@ # Agent drafts (notes files are personal, template is committed) .claude/drafts/*.md !.claude/drafts/TEMPLATE.md + +# Agent outputs (local working files) +.claude/staging/ +.claude/reports/*.html From d9d7682191ae6c9b636fd1b55e4edf85d3184cfe Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 16:02:11 -0800 Subject: [PATCH 10/12] Consolidate agent outputs under .claude/tmp/ and add Slack post phase - Move all agent outputs to .claude/tmp/ (report.html, changelogs/, slack/, sources/) - Add Phase 5.6: Slack post generation for internal team notification - Remove console text summary output format - Require clickable Linear links in all sources files - Simplify .gitignore to single .claude/tmp/ entry - Clean up old staging/, reports/, and drafts/*.sources.md locations Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 32 ++++++------ .claude/agents/changelog-writer.md | 2 +- .claude/agents/doc-writer.md | 9 ++-- .claude/agents/notes-processor.md | 80 ++++++++++++++---------------- .gitignore | 5 +- 5 files changed, 63 insertions(+), 65 deletions(-) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 8d8d1dc1..28da2c42 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -57,12 +57,13 @@ The `notes-processor` agent will: - Create a branch (`sam/`), commit, push, and open a PR - Update or create a Linear ticket with the PR link -### 3. Review the report +### 3. Review the outputs -After processing, the agent: -- Appends a review card to `.claude/reports/YYYY-MM-DD-.html` - (open in browser for easy scanning — PR links, Linear links, review focus) -- Stages a changelog entry at `.claude/staging/changelog/` for DatoCMS upload +After processing, the agent writes to `.claude/tmp/`: +- `report.html` — open in browser for easy scanning (PR links, Linear links, review focus) +- `changelogs/changelog-.md` — copy to DatoCMS for changelog +- `slack/slack-.md` — copy/paste into Slack to notify the team +- `sources/sources-.md` — audit trail of all inputs and citations ### 4. Review and iterate @@ -127,16 +128,17 @@ six phases sequentially: links (Slack, Slite, Loom, etc.), and product area from the notes 2. **Research** — looks up Linear tickets, searches for related engineering tickets, scans existing docs for coverage gaps -3. **Sources** — writes a `.sources.md` audit trail with every ticket, PR, - Slack thread, and doc file it used as input +3. **Sources** — writes a sources audit trail to `tmp/sources/` with every + ticket, PR, Slack thread, and doc file it used as input 4. **Draft** — writes or edits documentation, matching existing Trunk style 5. **Branch/PR/Linear** — creates branch, commits, pushes, opens PR, updates or creates Linear ticket with PR link, attaches all context links (Slack, Slite, Loom, etc.), and links docs ticket to related engineering tickets -6. **Changelog** — stages a changelog entry at `.claude/staging/changelog/` - for manual DatoCMS upload -7. **Report** — appends an HTML review card to `.claude/reports/` with PR +6. **Changelog** — stages a changelog entry at `tmp/changelogs/` for DatoCMS +7. **Slack post** — writes a copy-paste-ready Slack message to `tmp/slack/` + with PR and Linear links for internal notification +8. **Report** — appends an HTML review card to `tmp/report.html` with PR link, Linear link, review focus areas, and open questions ## Directory Structure @@ -153,9 +155,9 @@ six phases sequentially: drafts/ TEMPLATE.md # Notes file template *.md # Your notes files (gitignored) - *.sources.md # Source audit trails (gitignored) - reports/ - *.html # Review reports (gitignored, open in browser) - staging/ - changelog/ # Changelog entries for DatoCMS upload (gitignored) + tmp/ # All agent outputs (gitignored) + report.html # Review report (open in browser) + changelogs/ # Changelog entries for DatoCMS upload + slack/ # Slack posts for internal notification + sources/ # Source audit trails and citations ``` diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md index c6d3f84a..21fdc9f0 100644 --- a/.claude/agents/changelog-writer.md +++ b/.claude/agents/changelog-writer.md @@ -23,7 +23,7 @@ www.trunk.io/changelog. Entries are staged for manual upload to DatoCMS. 4. Flag any ambiguities as questions ## Output -Write the changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md` +Write the changelog entry to `.claude/tmp/changelogs/changelog-.md` using this format: ```markdown diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 89fc0343..69f0330e 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -29,13 +29,14 @@ You will receive some combination of: docs structure based on what you see in the repo. ## Sources File -Before drafting, write a `.sources.md` file alongside any notes file -you were given (same directory, same name with `.sources.md` suffix). +Before drafting, write a sources file to +`.claude/tmp/sources/sources-.md` (kebab-case feature name). If no notes file path was given, include a `### Sources` section in your output instead. This should list every Linear ticket, GitHub PR, existing doc file, code snippet, and external reference you used as -input, with links and brief descriptions. Use `gh pr view ` to -read GitHub PR details. This lets reviewers verify accuracy. +input, with links and brief descriptions. **All Linear ticket references +must be clickable links.** Use `gh pr view ` to read GitHub PR +details. This lets reviewers verify accuracy. ## Required Outputs Produce a single markdown file with these clearly labeled sections: diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 84ce4717..a0cedde9 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -59,11 +59,14 @@ may contain any combination of: 5. Identify gaps between what exists and what the notes describe ### Phase 2.5: Generate Sources File -Write a sources file alongside the notes file at the same path with a -`.sources.md` suffix (e.g., `.claude/drafts/my-feature.sources.md`). +Write a sources file to `.claude/tmp/sources/sources-.md`. +Use a kebab-case feature name derived from the notes file name (e.g., +`google-cloud` from `google-cloud.md`). + This file is a human-readable manifest of everything the agent found and used as input. It should be easy to scan for accuracy and -cross-referencing. +cross-referencing. **All Linear ticket references must be clickable +links** using `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`. Format: @@ -73,7 +76,7 @@ Generated: [date] ## Linear Tickets For each ticket found: -- **[TRUNK-XXXXX](linear-url)** — [title] +- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - Status: [status] | Assignee: [name] - Summary: [1-2 sentence description from ticket] @@ -104,7 +107,7 @@ Loom, Google Docs, external references, etc.): ## Related Linear Tickets Tickets discovered via search that relate to the same feature/area (these will be linked as relations on the docs ticket): -- **[TRUNK-XXXXX](linear-url)** — [title] +- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - Relationship: [documents / is documented by / related to] - Why: [brief reason this is related] @@ -198,7 +201,7 @@ After changes are applied: and restore any stashed changes ### Phase 5.5: Stage Changelog Entry -Write a changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md`. +Write a changelog entry to `.claude/tmp/changelogs/changelog-.md`. These are staged for manual upload to DatoCMS. Use this format: @@ -219,13 +222,36 @@ Include a "why this matters" sentence.] [Learn more →](https://docs.trunk.io/path/to/relevant/page) ``` +### Phase 5.6: Generate Slack Post +Write a Slack-ready internal announcement to +`.claude/tmp/slack/slack-.md`. This file is meant to be +copied and pasted into Slack to notify the team about the docs change. + +Use this format: + +```markdown +**[Feature Name] — docs update ready for review** + +[1-2 sentence summary of what changed in the docs.] + +- PR: [GitHub PR URL] +- Linear: [Linear ticket URL] +- Preview: [GitBook preview URL if available, otherwise omit] + +Open questions for the team: +- [list any items needing eng confirmation] +``` + +Keep it concise — this is a Slack message, not a document. Use bold for +the title line. Include the PR and Linear links so people can click +through directly. + ### Phase 6: Generate Review Report After the PR is created, append an entry to the daily report file at -`.claude/reports/YYYY-MM-DD-.html`. If the file doesn't -exist yet, create it with a full HTML document including basic styling. -Each entry should be a self-contained review card with everything a -human reviewer needs. The HTML format makes it easy to open in a browser -for quick scanning. +`.claude/tmp/report.html`. If the file doesn't exist yet, create it +with a full HTML document including basic styling. Each entry should be +a self-contained review card with everything a human reviewer needs. +The HTML format makes it easy to open in a browser for quick scanning. If the file already exists, append the new card inside the `
` element. @@ -269,7 +295,7 @@ Card format to append inside `
`: Branchsam/[branch-name] PR[url] LinearTRUNK-XXXXX — [status] - Sources.claude/drafts/[notes-file].sources.md + Sources.claude/tmp/sources/sources-[featurename].md Draft.claude/drafts/[notes-file].md Type[new-feature / update / fix / deprecation / explainer] Changes[1-2 sentence summary] @@ -285,36 +311,6 @@ The **Review focus** field is critical. Be honest about what you're uncertain about — flag any details you inferred rather than confirmed, any placeholder content, and any areas where the docs could be wrong. -## Output Format -When complete, report: - -``` -## Processed: [Feature Name] - -### Changes Made -- [list of files created/modified] - -### Branch & PR -- Branch: sam/[branch-name] -- PR: [URL] - -### Linear -- Ticket: [TRUNK-XXXXX] — [status] - -### Review Report -- Entry added to: .claude/reports/[filename].html - -### Changelog -- Staged at: .claude/staging/changelog/[filename].md - -### Open Questions -1. [questions for team review] - -### Notes File -- Source: [path to notes file] -- Status: Processed -``` - ## Important Rules - **Always include PR links** in Linear comments and descriptions - **One notes file = one PR**. If a notes file describes multiple unrelated diff --git a/.gitignore b/.gitignore index 913e0cbf..1ee334fe 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,5 @@ .claude/drafts/*.md !.claude/drafts/TEMPLATE.md -# Agent outputs (local working files) -.claude/staging/ -.claude/reports/*.html +# Agent outputs (local working files, all under tmp/) +.claude/tmp/ From 63c5ad88f366d80d7c54a471a28649ee48db1b03 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 21:41:53 -0800 Subject: [PATCH 11/12] Add [TRUNK-XXXXX] prefix convention to PR titles in agents Ensure GitHub PRs and Linear tickets cross-reference each other by requiring a Linear ticket ID prefix in PR titles and clickable Linear URLs in PR bodies. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/branch-manager.md | 6 +++--- .claude/agents/notes-processor.md | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.claude/agents/branch-manager.md b/.claude/agents/branch-manager.md index 752f10ca..dab074b5 100644 --- a/.claude/agents/branch-manager.md +++ b/.claude/agents/branch-manager.md @@ -28,9 +28,9 @@ You will receive: ### 3. Push and PR - Push the branch to origin - Create a PR using `gh pr create` with: - - A short, descriptive title - - A body containing: summary of changes, list of files modified, link to the Linear ticket if applicable, and open questions if any -- Include the Linear ticket ID in the PR body so it auto-links + - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix with the Linear ticket ID in brackets if one exists + - A body containing: summary of changes, list of files modified, link to the Linear ticket as a clickable URL (e.g., `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`), and open questions if any +- The Linear ticket link in the body and the `[TRUNK-XXXXX]` prefix in the title ensure cross-referencing between GitHub and Linear ### 4. Linear Ticket Update - **Always include the full PR URL** (e.g., `https://github.com/trunk-io/docs/pull/123`) in any Linear comment or description. Never reference a PR without its link. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index a0cedde9..ba7fd105 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -154,7 +154,8 @@ After changes are applied: 2. **Commit**: Stage and commit with a clear message, include `Co-Authored-By: Claude Opus 4.6 ` 3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - - Short descriptive title + - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix + with the Linear ticket ID in brackets (use the docs ticket ID) - Body must include: - **Summary** — bullet list of changes - **Linear tickets** — link every related ticket, not just the docs ticket From e8ac16ea7c18276635c86d20ea94290dedae45ff Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 21:46:59 -0800 Subject: [PATCH 12/12] Add Mermaid pipeline and agent collaboration diagrams to README Visual diagrams showing the 8-phase notes-processor pipeline flow and how the 5 agents collaborate with external services. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 63 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 28da2c42..e0a85536 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -119,10 +119,71 @@ Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` +## Pipeline Flow + +```mermaid +flowchart TD + A["📝 Notes File
.claude/drafts/my-feature.md"] --> B["1. Parse
Extract feature name, Linear IDs,
PR URLs, context links, product area"] + + B --> C["2. Research
Look up Linear tickets & PRs
Search for related eng tickets
Scan existing docs for gaps"] + + C --> D["3. Sources
Write audit trail to
tmp/sources/"] + + D --> E["4. Draft
Write or edit docs
matching Trunk style"] + + E --> F["5. Branch / PR / Linear"] + + F --> F1["Create branch
sam/<topic>"] + F1 --> F2["Commit & push"] + F2 --> F3["Create PR
[TRUNK-XXXXX] Title"] + F3 --> F4["Update Linear ticket
Link PR, attach context,
link related eng tickets"] + + F4 --> G["6. Changelog
Stage entry to
tmp/changelogs/"] + + G --> H["7. Slack Post
Write announcement to
tmp/slack/"] + + H --> I["8. Report
Append review card to
tmp/report.html"] + + I --> J{"More drafts?"} + J -- Yes --> K["Clean working tree
Return to base branch"] --> A + J -- No --> L["✅ Done
Open report.html to review"] + + style A fill:#e8f4fd,stroke:#2563eb + style L fill:#d1fae5,stroke:#059669 + style F fill:#fef3c7,stroke:#d97706 + style F1 fill:#fef3c7,stroke:#d97706 + style F2 fill:#fef3c7,stroke:#d97706 + style F3 fill:#fef3c7,stroke:#d97706 + style F4 fill:#fef3c7,stroke:#d97706 +``` + +### Agent Collaboration + +```mermaid +flowchart LR + NP["notes-processor
Orchestrator
Opus"] + + NP -- "research context" --> DR["doc-researcher
Context gathering
Sonnet"] + NP -- "draft docs" --> DW["doc-writer
Documentation
Opus"] + NP -- "branch & PR" --> BM["branch-manager
Git / PR / Linear
Sonnet"] + NP -- "changelog" --> CW["changelog-writer
Release notes
Sonnet"] + + DR -- "Linear MCP" --> LIN[(Linear)] + DR -- "GitBook MCP" --> GB[(GitBook)] + DR -- "gh CLI" --> GH[(GitHub)] + BM -- "gh CLI" --> GH + DW -- "Linear MCP" --> LIN + + style NP fill:#e8f4fd,stroke:#2563eb + style LIN fill:#f3e8ff,stroke:#7c3aed + style GB fill:#f3e8ff,stroke:#7c3aed + style GH fill:#f3e8ff,stroke:#7c3aed +``` + ## What the Agent Does When you process a notes file, the `notes-processor` agent runs through -six phases sequentially: +eight phases sequentially: 1. **Parse** — extracts feature name, Linear tickets, GitHub PRs, context links (Slack, Slite, Loom, etc.), and product area from the notes