feat(prompts): add documentation maintenance instructions to agent prompts

src/agents/prompts/templates/implementation.eta

@@ -106,12 +106,15 @@ Use `PostComment` to post a summary on the <%= it.workItemNoun || 'card' %> once
 
 <%~ include("partials/test-protocol") %>
 
+<%~ include("partials/documentation-maintenance") %>
+
 ### Completion Protocol (CRITICAL)
 
 NEVER mark acceptance criteria or checklist items complete until ALL of:
 1. Type checking passes (zero errors)
 2. Tests pass (zero failures)
 3. Lint passes (zero errors)
 4. PR is successfully created (and you have the PR number)
+5. Documentation updated (if changes affect documented behavior)
 
 <%~ include("partials/rules-efficiency") %>

src/agents/prompts/templates/partials/documentation-maintenance.eta

@@ -0,0 +1,42 @@
+### Documentation Maintenance
+
+When your code changes affect documented behavior, update the relevant docs as part of the same PR.
+
+#### When to Update Docs
+
+Check for doc updates if your change:
+- Adds, removes, or renames a public function, class, env var, or config option
+- Changes how a feature behaves from the user or developer perspective
+- Introduces a new architectural pattern or module convention
+- Modifies setup, deployment, or configuration steps
+
+Skip doc updates for: internal refactors with no external behavior change, test-only changes, or
+bug fixes that restore behavior already described in docs.
+
+#### What to Check
+
+- **CLAUDE.md / AGENTS.md** — Developer conventions, setup steps, commands
+- **README.md** — User-facing overview, installation, usage
+- **docs/** — Architecture guides, feature documentation
+- **JSDoc / inline comments** — Function signatures, complex logic explanations
+
+#### How to Find Relevant Docs
+
+Use RipGrep to locate docs that reference the feature or symbol you changed:
+
+```bash
+# Find docs mentioning a function/feature name
+RipGrep(pattern="functionName|FeatureName", glob="**/*.md")
+
+# Find JSDoc for a specific function
+RipGrep(pattern="@param|@returns", glob="src/path/to/file.ts")
+```
+
+#### Documentation Update Checklist
+
+Before marking your work complete, verify:
+- [ ] Public API changes are reflected in JSDoc (params, return types, thrown errors)
+- [ ] New env vars or config options are documented in CLAUDE.md or README
+- [ ] New architectural patterns are noted in the relevant docs/ file
+- [ ] Removed/renamed features no longer appear in docs as current behavior
+

src/agents/prompts/templates/planning.eta

@@ -36,6 +36,7 @@ You are running in a cloned copy of the project repository. Before creating your
 3. **Trace integrations** - Understand how components connect (APIs, event flows, shared state, pub/sub)
 4. **Map dependencies** - What libraries, utilities, and shared modules does related code use?
 5. **Note conventions** - Naming patterns, file organization, error handling, logging practices
+6. **Check documentation** - Scan CLAUDE.md, README.md, and docs/ to identify which docs cover the area being changed; include a doc update step in your plan if the change affects documented behavior (public APIs, env vars, architecture, setup steps)
 
 **When planning your solution:**
 - Reuse existing utilities and abstractions rather than creating new ones

src/agents/prompts/templates/resolve-conflicts.eta

@@ -165,6 +165,8 @@ Use `UpdatePRComment` with the comment ID from session state.
 
 <%~ include("partials/test-protocol") %>
 
+<%~ include("partials/documentation-maintenance") %>
+
 <%~ include("partials/verification-protocol") %>
 
 <%~ include("partials/rules-efficiency") %>

src/agents/prompts/templates/respond-to-ci.eta

@@ -131,6 +131,8 @@ Use `UpdatePRComment` with the comment ID from session state.
 
 <%~ include("partials/test-protocol") %>
 
+<%~ include("partials/documentation-maintenance") %>
+
 <%~ include("partials/verification-protocol") %>
 
 <%~ include("partials/rules-efficiency") %>

src/agents/prompts/templates/respond-to-pr-comment.eta

@@ -91,6 +91,7 @@ Use `UpdatePRComment` with the comment ID from session state.
 - Don't make unrelated changes
 - If the request conflicts with codebase conventions, follow conventions and explain why
 - Follow existing code patterns and conventions
+- If changes affect documented behavior, update relevant docs (CLAUDE.md, README, JSDoc)
 
 ### Code Quality
 - ALWAYS run tests and lint before committing
@@ -99,6 +100,8 @@ Use `UpdatePRComment` with the comment ID from session state.
 
 <%~ include("partials/test-protocol") %>
 
+<%~ include("partials/documentation-maintenance") %>
+
 <%~ include("partials/verification-protocol") %>
 
 <%~ include("partials/rules-efficiency") %>

src/agents/prompts/templates/respond-to-review.eta

@@ -86,6 +86,7 @@ Fixed! Updated the function to handle the edge case by adding a null check at li
 - Reply to EACH comment after fixing it
 - If you can't address a comment (unclear, out of scope, disagree), reply explaining why
 - Follow existing code patterns and conventions
+- If changes affect documented behavior, update relevant docs (CLAUDE.md, README, JSDoc)
 
 ### Code Quality
 - ALWAYS run tests and lint before committing
@@ -94,6 +95,8 @@ Fixed! Updated the function to handle the edge case by adding a null check at li
 
 <%~ include("partials/test-protocol") %>
 
+<%~ include("partials/documentation-maintenance") %>
+
 <%~ include("partials/verification-protocol") %>
 
 <%~ include("partials/rules-efficiency") %>

src/agents/prompts/templates/review.eta

@@ -154,6 +154,17 @@ Style and preferences - mention only if egregious:
 - **Build-time config**: For features requiring build-time injection, verify the injection point exists
 - **When uncertain**: Ask in your review rather than assuming deployment is configured correctly
 
+### Documentation
+- **Currency**: Do CLAUDE.md, README.md, and docs/ still accurately describe features changed by this PR?
+- **New features**: Are user-facing or developer-facing features introduced without any documentation?
+- **Stale references**: Does the PR remove or rename something that's still referenced in docs?
+- **JSDoc**: Are new public functions/classes missing parameter or return type documentation?
+
+Severity guide:
+- Missing docs for a user-facing feature or new env var = **SHOULD_FIX**
+- Missing JSDoc on a new public API = **NITPICK**
+- Actively misleading docs (describe behavior that no longer exists) = **SHOULD_FIX**
+
 ## Strategic Questions
 
 Answer these during Phase 1 — they catch design problems that line-by-line review misses:

tests/unit/agents/prompts.test.ts

@@ -15,6 +15,7 @@ vi.mock('../../../src/agents/definitions/index.js', () => ({
 			'respond-to-planning-comment',
 			'debug',
 			'backlog-manager',
+			'resolve-conflicts',
 		]),
 }));
 
@@ -398,6 +399,7 @@ describe('readTemplateFileSync', () => {
 			'respond-to-planning-comment',
 			'debug',
 			'backlog-manager',
+			'resolve-conflicts',
 		];
 		for (const agentType of builtinTypes) {
 			const content = readTemplateFileSync(agentType);
@@ -655,6 +657,7 @@ describe('duplicate content detection', () => {
 		'respond-to-planning-comment',
 		'debug',
 		'backlog-manager',
+		'resolve-conflicts',
 	];
 
 	for (const agentType of allAgentTypes) {
@@ -827,3 +830,127 @@ describe('squintEnabled template gating', () => {
 		expect(rendered).not.toContain('squint-features');
 	});
 });
+
+describe('documentation-maintenance partial', () => {
+	it('partial exists in getAvailablePartialNames()', () => {
+		const names = getAvailablePartialNames();
+		expect(names).toContain('documentation-maintenance');
+	});
+
+	it('partial contains key doc-update phrases', () => {
+		const content = getRawPartial('documentation-maintenance');
+		expect(content).toContain('CLAUDE.md');
+		expect(content).toContain('README');
+		expect(content).toContain('JSDoc');
+		expect(content).toContain('docs/');
+	});
+
+	it('partial describes when to update docs (conditional guidance)', () => {
+		const content = getRawPartial('documentation-maintenance');
+		expect(content).toContain('When to');
+	});
+
+	it('partial provides a documentation update checklist', () => {
+		const content = getRawPartial('documentation-maintenance');
+		expect(content).toContain('Documentation Update Checklist');
+	});
+});
+
+describe('documentation maintenance in code-modifying agent prompts', () => {
+	it('implementation prompt contains documentation maintenance section', () => {
+		const prompt = getSystemPrompt('implementation');
+		expect(prompt).toContain('Documentation Maintenance');
+		expect(prompt).toContain('CLAUDE.md');
+		expect(prompt).toContain('JSDoc');
+	});
+
+	it('implementation prompt completion protocol includes documentation step', () => {
+		const prompt = getSystemPrompt('implementation');
+		expect(prompt).toContain('Documentation updated');
+	});
+
+	it('respond-to-review prompt contains documentation maintenance section', () => {
+		const prompt = getSystemPrompt('respond-to-review');
+		expect(prompt).toContain('Documentation Maintenance');
+		expect(prompt).toContain('CLAUDE.md');
+	});
+
+	it('respond-to-review prompt scope section mentions documentation updates', () => {
+		const prompt = getSystemPrompt('respond-to-review');
+		expect(prompt).toContain('documented behavior');
+	});
+
+	it('respond-to-ci prompt contains documentation maintenance section', () => {
+		const prompt = getSystemPrompt('respond-to-ci');
+		expect(prompt).toContain('Documentation Maintenance');
+		expect(prompt).toContain('CLAUDE.md');
+	});
+
+	it('respond-to-pr-comment prompt contains documentation maintenance section', () => {
+		const prompt = getSystemPrompt('respond-to-pr-comment');
+		expect(prompt).toContain('Documentation Maintenance');
+		expect(prompt).toContain('CLAUDE.md');
+	});
+
+	it('respond-to-pr-comment prompt scope section mentions documentation updates', () => {
+		const prompt = getSystemPrompt('respond-to-pr-comment');
+		expect(prompt).toContain('documented behavior');
+	});
+
+	it('resolve-conflicts prompt contains documentation maintenance section', () => {
+		const prompt = getSystemPrompt('resolve-conflicts');
+		expect(prompt).toContain('Documentation Maintenance');
+		expect(prompt).toContain('CLAUDE.md');
+	});
+});
+
+describe('documentation review checks in review agent', () => {
+	it('review prompt contains Documentation subsection under What to Verify', () => {
+		const prompt = getSystemPrompt('review');
+		expect(prompt).toContain('### Documentation');
+	});
+
+	it('review prompt covers documentation currency', () => {
+		const prompt = getSystemPrompt('review');
+		expect(prompt).toContain('Currency');
+	});
+
+	it('review prompt covers undocumented new features', () => {
+		const prompt = getSystemPrompt('review');
+		expect(prompt).toContain('New features');
+	});
+
+	it('review prompt covers stale references in docs', () => {
+		const prompt = getSystemPrompt('review');
+		expect(prompt).toContain('Stale references');
+	});
+
+	it('review prompt includes SHOULD_FIX severity for missing user-facing docs', () => {
+		const prompt = getSystemPrompt('review');
+		expect(prompt).toContain('SHOULD_FIX');
+	});
+
+	it('review prompt does NOT include documentation-maintenance partial (reports gaps, does not fix)', () => {
+		const prompt = getSystemPrompt('review');
+		// The partial's checklist heading should not be present in review
+		expect(prompt).not.toContain('Documentation Update Checklist');
+	});
+});
+
+describe('documentation planning in planning agent', () => {
+	it('planning prompt contains documentation check as step 6 in pattern analysis', () => {
+		const prompt = getSystemPrompt('planning');
+		expect(prompt).toContain('Check documentation');
+	});
+
+	it('planning prompt includes guidance to add doc update steps to plans', () => {
+		const prompt = getSystemPrompt('planning');
+		expect(prompt).toContain('doc update step');
+	});
+
+	it('planning prompt does NOT include documentation-maintenance partial', () => {
+		const prompt = getSystemPrompt('planning');
+		// The partial's checklist heading should not be in planning prompt
+		expect(prompt).not.toContain('Documentation Update Checklist');
+	});
+});