Add Claude Code documentation agents and workflow#444
Add Claude Code documentation agents and workflow#444samgutentag wants to merge 13 commits intomainfrom
Conversation
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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Explainers enhance existing docs with examples and scenarios based on customer questions, with guidelines to keep workflow guides clean. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Agents now extract and attach all URLs from notes files — Slack, Slite, Loom, Google Docs, Notion, and any other context links. All are attached to Linear tickets and referenced in PR bodies. Template field renamed from "Slack Links" to "Context Links". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
|
Claude finished @samgutentag's task in 2m 49s —— View job Review complete
SummaryOverall this is a well-structured addition. The agent definitions are clear, the pipeline is well-documented with Mermaid diagrams, and the template/gitignore setup is sensible. Three issues flagged inline:
No typos or grammar issues found in any of the 9 changed files. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| information came from and check accuracy against primary sources. | ||
|
|
||
|
|
||
| Based on everything gathered, write the documentation changes: |
There was a problem hiding this comment.
Missing Phase 3 header
The document has phases 1, 2, 2.5, then jumps directly to Phase 4. The draft documentation instructions starting here are effectively "Phase 3" but the section heading is absent, making the structure inconsistent and harder to follow.
| Based on everything gathered, write the documentation changes: | |
| ### Phase 3: Draft Documentation | |
| Based on everything gathered, write the documentation changes: |
| - **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) |
There was a problem hiding this comment.
Inconsistent sources file location
This agent writes a .sources.md file alongside the notes file (e.g., .claude/drafts/my-feature.sources.md), but notes-processor.md writes sources to .claude/tmp/sources/sources-<featurename>.md and the README's directory structure shows tmp/sources/ as the canonical location.
When doc-researcher is invoked directly (not through notes-processor), the output ends up in a different place. Consider aligning both to use .claude/tmp/sources/ so the directory structure section in README stays accurate.
| - Search existing docs to find what needs updating | ||
| - Draft the documentation changes | ||
| - Apply changes to the repo | ||
| - Create a branch (`sam/<topic>`), commit, push, and open a PR |
There was a problem hiding this comment.
Hardcoded sam/ branch prefix
The branch prefix sam/<topic> is hardcoded in both the README (here and line 81) and in notes-processor.md. This is fine for personal use, but consider adding a note that other contributors should update the author name in notes-processor.md/branch-manager.md, or parametrize it with a config variable so the tooling is ready for team adoption.
|
/trunk merge |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
🚫 This pull request was closed by @samgutentag, so it was removed from the merge queue. See more details here. |
|
Superseded by new PR from renamed branch |
1 participant
Summary
Claude Code agent system for documentation workflows. Five agents that turn raw notes (Slack threads, engineer scribbles, Linear tickets) into polished docs with full project tracking.
Agents
notes-processordoc-writerdoc-researcherchangelog-writerbranch-managerPipeline (8 phases)
Files
.claude/agents/— 5 agent definitions + README with Mermaid diagrams.claude/drafts/TEMPLATE.md— notes file template.claude/tmp/(gitignored) — all agent outputs (report.html, changelogs/, slack/, sources/)Key conventions
[TRUNK-XXXXX] Short descriptive title.claude/tmp/Validated with 8 documentation PRs
Test plan
[TRUNK-XXXXX]🤖 Generated with Claude Code