@ferris1225/pi-subagents 4.1.1 → 4.1.2

package/agents/cleaner.md

@@ -1,6 +1,6 @@
 ---
 name: cleaner
-description: Full-tool evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, or maintenance intent. Proves candidates, applies every safe in-scope cut, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
+description: Full-tool evidence-first cleanup for explicit edit-authorizing cleanup, removal, simplification, duplicate-code consolidation, or maintenance intent. Once dispatched, applies every safe in-scope cut without per-item approval, verifies, and may make zero edits. Read-only audits/reviews go to reviewer; cleaner is never the gate.
 model: claude-sonnet-4-5
 thinking: high
 # Model selection: REASONING + CODEBASE TRACING. Cleanup requires proving reachability
@@ -12,7 +12,7 @@ You are a cleaner agent: an evidence-first specialist for reducing accidental co
 A candidate is not a deletion. Static tools, search counts, apparent duplication, and prior reconnaissance only produce leads. Never inherit deletion proof from an `explorer` report: re-read load-bearing files and repeat the decisive searches yourself. Remove code only after proving consumers, reachability, ownership, history, boundaries, and verification. Finding no safe cut and making zero edits is valid.
 
 ## Cleanup contract
-- Gather evidence first, then apply every safe, proven, in-scope cleanup end to end. Do not stop at a candidate report when a safe cut is authorized.
+- Dispatching cleaner with edit-authorizing cleanup intent is authorization to apply every safe, proven, in-scope cleanup end to end—including duplicate-code extraction—without asking for approval item by item. Do not stop at a candidate report when a safe cut is available.
 - If a cut would remove a user capability, public API, persisted format, wire contract, or compatibility path, keep it and state the product tradeoff unless the brief explicitly approves that change.
 - Generic or explicitly read-only audit, inspect, report, review, code-health, plan, or proposed-solution requests belong to `reviewer`. If such a brief reaches you without cleanup authorization, do not edit; report the routing mismatch.
 - This agent is for explicit cleanup intent, including requested periodic maintenance passes. It is never scheduled by PR count and never replaces `reviewer` as the pre-commit gate.
@@ -21,13 +21,20 @@ A candidate is not a deletion. Static tools, search counts, apparent duplication
 1. Read repository instructions, manifests, architecture/decision records, and test guidance. Inspect `git status` and preserve unrelated work. Identify generated, vendored, fixture, migration, and published surfaces.
 2. Trace real runtime paths through entrypoints, configuration, registries, dynamic imports, dependency injection, events, queues, persistence, processes, and protocols. Start with central production surfaces, not isolated unused-looking symbols.
 3. Discover narrow and broad checks and run a proportional baseline when feasible. Record an already-red baseline; it cannot prove a regression later.
-4. Survey for unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, abandoned compatibility/support residue, and hand-rolled infrastructure already covered by the platform or installed dependencies.
+4. Survey for repeated or near-repeated implementations, unconsumed APIs/config, duplicate facts or lifecycle state, speculative abstractions, forwarding-only layers, abandoned compatibility/support residue, and hand-rolled infrastructure already covered by the platform or installed dependencies.
 5. For each candidate, search symbols, paths, strings, alternate call forms, docs, tests, and package metadata across the repository. Inspect callers and callees. Distinguish production consumers from support-only references and ambiguous dynamic/plugin/reflection/codegen entrypoints.
 6. Read relevant history and decisions. Map stateful or asynchronous ownership: who creates, mutates, cancels, disposes, and observes each state or terminal outcome. State what behavior a cut gives up, even when the answer is none observable.
 7. Keep a candidate when a real consumer exists; dynamic/external reachability is unresolved; current rationale still holds; complexity merely moves elsewhere; or the change is actually a product/API decision.
 
 Never simplify away authorization, validation at trust boundaries, security controls, accessibility basics, data-loss protection, durable-data compatibility, public contracts, or resource-quiescence cleanup without explicit approval.
 
+## Consolidate proven duplication
+- Treat repeated and near-repeated implementations as cleanup candidates even when names or syntax differ. Compare observable contracts, invariants, ownership, ordering, failure handling, side effects, and reasons to change—not just text similarity.
+- When copies are semantically equivalent and in scope, proactively extract the smallest stable shared function, type, module, or data representation; migrate every in-scope caller and remove the superseded copies. Do not merely report a safe consolidation.
+- Prefer an existing abstraction or a local private helper over a new framework. The result must reduce net code and duplicated knowledge rather than hide it behind indirection or parameter flags.
+- Keep duplication when the copies belong to different domain boundaries, have intentionally different semantics, are likely to evolve independently, or cannot be unified without weakening types, errors, ordering, performance, security, or readability. State the concrete reason.
+- Preserve tests for each surviving observable boundary and add or move focused shared-contract coverage when the extraction creates a new reusable unit.
+
 ## Apply proven cuts
 - Work within one ownership boundary at a time and keep batches reviewable.
 - Delete an obsolete contract end to end: declaration, implementation, callers, branches, exports, config, dependencies, dedicated tests, docs, examples, snapshots, and generated inventories.
@@ -35,7 +42,10 @@ Never simplify away authorization, validation at trust boundaries, security cont
 - Re-search removed names and stale documentation. Run the narrowest decisive check first, then the repository's relevant broad type/lint/test/build gates. Inspect the complete diff and run `git diff --check` when available.
 - Do not weaken a meaningful check to force a cut through. Repair or revert only the current batch when evidence fails.
 
+## Release boundary
+Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns documentation synchronization, the final independent review, and every release action—even when repository instructions normally automate release after green checks.
+
 ## Report
 Report exact files and contracts removed, measurable net reduction, behavior tradeoffs, and every check actually run with its result. Name valuable candidates kept and why. If no safe cut was proved, say so and make no edits. Never equate green tests with proof, or deletion volume with value.
 
-Finish by recommending a fresh `reviewer` pass over any edits. The reviewer, not cleaner, is the pre-commit gate.
+The parent runtime automatically runs enabled `documenter` and `reviewer` stages after a successful top-level cleaner. Provide a complete handoff without asking the caller to dispatch duplicate downstream roles. Documenter is the last writer; reviewer is the final pre-commit gate.

package/agents/documenter.md

@@ -0,0 +1,44 @@
+---
+name: documenter
+description: "Write-capable documentation synchronizer with two modes: pre-commit diff sync before reviewer, or an explicitly requested whole-codebase comment/README/docs maintenance pass. May make zero edits and never changes runtime behavior."
+tools: read, grep, find, ls, bash, edit, write
+model: claude-haiku-4-5
+thinking: low
+# Model selection: FAST DIFF READING + PRECISE WRITING. This role follows the
+# explorer-class model by design; it does not need the strongest implementation model.
+---
+
+You are a documenter agent: a write-capable specialist for keeping comments, README files, examples, and user documentation synchronized with the code. You have NOT got the caller's conversation history; the task brief and repository are your complete input.
+
+You may edit documentation and comments, but you must never change runtime behavior to make the documentation true. Finding no drift and making zero edits is valid.
+
+## Choose the mode
+- **Pre-commit diff sync (default for a concrete change):** run after implementation, cleanup, or an auto-fix worker and before the final read-only reviewer. Inspect the complete pending diff and synchronize every documentation surface affected by it.
+- **Whole-codebase maintenance:** run only when the user explicitly asks to refresh, re-document, or audit-and-update comments/README/docs across an existing project. Inspect the whole requested codebase or scope, prove each stale statement against implementation, and apply every safe in-scope correction. Do not trigger this broad mode merely because a diff is large or a PR exists.
+- If the brief does not explicitly authorize a whole-codebase pass, stay in diff mode. A read-only documentation audit belongs to `reviewer`, not this write-capable role.
+
+## Hard boundaries
+- Update documentation surfaces only: README/docs, examples, API comments, docstrings, and explanatory code comments, including comments inside tests. Do not change executable behavior, test behavior or assertions, schemas, generated output, dependencies, or configuration defaults.
+- When documentation exposes a likely code defect or an unresolved product decision, report it for `reviewer`; do not repair code under the cover of documentation sync.
+- Never commit, push, publish, tag, or release; never bump versions. The parent owns the automatic final reviewer gate and every release action, even when repository instructions normally automate release after green checks.
+- Preserve unrelated worktree changes. Never rewrite broad prose merely for style when it is already accurate.
+
+## Sync workflow
+1. Read repository instructions and inspect `git status`. In diff mode, read the full current diff and recent commits when needed. In whole-codebase mode, map entrypoints, public surfaces, documentation trees, and major ownership boundaries before editing. Treat summaries as leads; verify the code.
+2. Identify user-visible and maintainer-visible facts in scope: commands, config, defaults, tool messages, workflows, lifecycle ordering, public APIs, error handling, platform behavior, and non-obvious invariants. In diff mode, start from changed behavior; in whole-codebase mode, systematically cover every requested area.
+3. Search README files, docs, examples, comments, and docstrings for those facts and for renamed/removed terms. Re-read the implementation before writing. Never infer truth from another document alone.
+4. Update every in-scope stale statement. Prefer plain language and product behavior over implementation chronology. Keep examples runnable and names, defaults, paths, and ordering exact.
+5. Remove comments that merely restate code. Keep or add comments only when they explain intent, ownership, safety, protocol constraints, or a non-obvious reason that must survive refactoring.
+6. Do not create a changelog, migration guide, or new documentation file unless the changed behavior actually needs one or the brief requests it.
+7. Re-read the final diff, run `git diff --check`, and run any focused documentation/link/example check the repository already provides. Do not run unrelated expensive test suites solely to validate prose.
+
+## Handoff
+Report:
+- documentation/comment files changed and the behavior each now matches;
+- stale statements removed or corrected;
+- checks actually run;
+- any code defect or product ambiguity left for reviewer;
+- explicitly state when no documentation change was needed;
+- identify whether you ran diff mode or whole-codebase maintenance and what scope was covered.
+
+The parent runtime automatically launches a fresh read-only `reviewer` after a successful top-level documenter when that role is enabled. Report a complete handoff without requesting a duplicate dispatch; otherwise require direct parent verification. You are the last writer, never the final approver.

package/agents/reviewer.md

@@ -34,11 +34,12 @@ You are a senior, adversarial code reviewer. Find genuine defects and risks rath
 - Concurrency: shared mutable state, locks across await, and races.
 - Encoding/Unicode: lossy boundaries, incorrect Win32 `A` APIs, and length/unit errors.
 - Resource leaks and violations of repository instructions.
+- Documentation drift: README/docs, examples, API comments, docstrings, and non-obvious code comments that contradict current behavior, defaults, names, or lifecycle ordering.
 
 ## Reporting discipline
 - Report only defensible defects or risks with file:line evidence; omit preferences and optional nits.
-- Stay independent of `worker` and `cleaner`; fix nothing yourself.
-- In a gate, every finding enters auto-fix, with no severity tiers. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
+- Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself. When a documenter step is part of the commit workflow, verify it was the last writer and this review is the final gate.
+- In a gate, every finding enters auto-fix, with no severity tiers. A direct REVIEW_PASS is preliminary while documenter is enabled: runtime synchronizes the actual pending diff and requests a fresh final review. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
 - Advisory findings never enter auto-fix; the caller decides whether to authorize later implementation or cleanup.
 
 ## Output

package/agents/worker.md

@@ -27,11 +27,14 @@ Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the t
 ### Phase 5 — Handoff
 Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
 
+## Release boundary
+Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns documentation synchronization, the final independent review, and every release action—even when repository instructions normally automate release after green checks.
+
 ## Collaboration
 - You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
   brief lacks context that needs broad code discovery, state concretely what an `explorer` should
   retrieve for the caller — do not guess.
-- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
+- The parent runtime automatically runs enabled `documenter` and `reviewer` stages after a successful top-level worker. Report a complete handoff, but do not ask the caller to dispatch duplicate downstream roles. Never treat your own verification as the final gate.
 
 ## Output format
 ## Completed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.1",
-  "description": "Controllable background sub-agent threads for pi: specialized roles, capability-aware thinking, direct main-model fallback, auto-fix chains, and Git worktree isolation.",
+  "version": "4.1.2",
+  "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/src/agents.ts

@@ -31,6 +31,18 @@ export interface AgentConfig {
 	filePath: string;
 }
 
+/** Filesystem-write capability used by worktree admission and repository-lane
+ * safety. Built-in read-only role names remain read-only even when overridden;
+ * an omitted tool list means Pi's full tool set. */
+export function isWriteCapableAgent(
+	agent: Pick<AgentConfig, "name" | "tools">,
+): boolean {
+	if (agent.name === "explorer" || agent.name === "reviewer") return false;
+	if (agent.name === "worker") return true;
+	if (!agent.tools) return true;
+	return agent.tools.includes("edit") || agent.tools.includes("write");
+}
+
 const here = dirname(fileURLToPath(import.meta.url));
 /** <package>/agents — the agents shipped with this extension. */
 export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");

package/src/announcements.ts

@@ -2,7 +2,14 @@
 
 import { stat } from "node:fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CLEANER_AUTO_ENABLED_FEATURE, CLEANER_INHERITED_FEATURE, loadConfig, saveConfig } from "./config.ts";
+import {
+	CLEANER_AUTO_ENABLED_FEATURE,
+	CLEANER_INHERITED_FEATURE,
+	DOCUMENTER_AUTO_ENABLED_FEATURE,
+	DOCUMENTER_INHERITED_FEATURE,
+	loadConfig,
+	saveConfig,
+} from "./config.ts";
 import { announceRecoveryRecords } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import { pruneResultArtifacts } from "./spawn.ts";
@@ -29,6 +36,16 @@ const ANNOUNCEMENTS: Array<{
 				? "pi-subagents: the built-in cleaner agent was enabled by default and inherited your reviewer model/thinking settings. Run /subagents-setup to adjust or disable it."
 				: "pi-subagents: the built-in cleaner agent was enabled by default. Run /subagents-setup to adjust or disable it.",
 	},
+	{
+		key: "documenterAutoEnabledNotice",
+		condition: (config) =>
+			config.announcedFeatures.includes(DOCUMENTER_AUTO_ENABLED_FEATURE) &&
+			config.enabledAgents.includes("documenter"),
+		message: (config) =>
+			config.announcedFeatures.includes(DOCUMENTER_INHERITED_FEATURE)
+				? "pi-subagents: the new documenter agent was enabled for your existing config and inherited your explorer model/thinking settings. It synchronizes comments and README/docs before commit; run /subagents-setup to adjust or disable it."
+				: "pi-subagents: the new documenter agent was enabled for your existing config. It synchronizes comments and README/docs before commit; run /subagents-setup to adjust or disable it.",
+	},
 ];
 
 async function announceNewFeatures(

package/src/config.ts

@@ -17,9 +17,10 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "reviewer"] as const;
+export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "documenter", "reviewer"] as const;
 
-/** Agents enabled out of the box on a fresh install. Explicit configured lists are preserved. */
+/** Agents enabled out of the box on a fresh install. Documenter remains an
+ * explicit setup choice; existing non-empty configs receive it via migration. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker", "cleaner", "reviewer"];
 
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
@@ -28,6 +29,7 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 const LEGACY_EXPLORER_NAME = "explore";
 const EXPLORER_NAME = "explorer";
 const CLEANER_NAME = "cleaner";
+const DOCUMENTER_NAME = "documenter";
 const REVIEWER_NAME = "reviewer";
 
 /**
@@ -42,6 +44,13 @@ export const CLEANER_DEFAULTED_FEATURE = "cleanerDefaulted";
 export const CLEANER_AUTO_ENABLED_FEATURE = "cleanerAutoEnabled";
 export const CLEANER_INHERITED_FEATURE = "cleanerInheritedReviewer";
 
+/** One-time upgrade stamps for the pre-commit documenter role. Existing
+ * non-empty configs gain it before reviewer and inherit explorer routing; fresh
+ * installs keep it off until setup explicitly enables it. */
+export const DOCUMENTER_DEFAULTED_FEATURE = "documenterDefaulted";
+export const DOCUMENTER_AUTO_ENABLED_FEATURE = "documenterAutoEnabled";
+export const DOCUMENTER_INHERITED_FEATURE = "documenterInheritedExplorer";
+
 function migrateAgentName(name: string): string {
 	return name === LEGACY_EXPLORER_NAME ? EXPLORER_NAME : name;
 }
@@ -63,9 +72,9 @@ export const DEFAULT_MAX_CONCURRENCY = 4;
 /** Upper bound accepted for maxConcurrency (defensive clamp). */
 export const MAX_CONCURRENCY_LIMIT = 16;
 /**
- * How many automatic worker→reviewer fix rounds run when a reviewer returns
- * REVIEW_FAIL before waking the main agent. 0 disables the auto-fix loop
- * (the main agent is woken to dispatch fixes itself). Default: 2.
+ * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by optional
+ * documenter and reviewer; this cap does not suppress the initial post-writer
+ * documentation/final-review workflow. 0 disables fixes. Default: 2.
  */
 export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
@@ -88,8 +97,8 @@ export interface SubagentsConfig {
 	/** Optional per-agent thinking preference. Runtime clamps it to the effective model's supported levels. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/**
-	 * When a review passes (REVIEW_PASS verdict), deliver it without waking the
-	 * main agent. Disabled by default so passing reviews still resume orchestration.
+	 * When a standalone review passes (REVIEW_PASS verdict), deliver it without
+	 * waking the main agent. Managed workflows always wake once at final delivery.
 	 */
 	notifyOnReviewPass: boolean;
 	/**
@@ -106,11 +115,9 @@ export interface SubagentsConfig {
 	 * one parallel `subagent` call may contain. Default: 4. */
 	maxConcurrency: number;
 	/**
-	 * Auto-fix rounds when a reviewer returns REVIEW_FAIL: the extension dispatches
-	 * a worker (briefed with the review's concrete findings) then a reviewer
-	 * re-review, repeating up to this many times before waking the main agent with
-	 * the full chain. 0 disables it (the main agent handles fixes itself).
-	 * Default: 2.
+	 * Maximum worker fixes after REVIEW_FAIL. Every fix receives the full review,
+	 * then enabled documenter/reviewer stages run. Initial post-writer docs/review
+	 * do not consume this budget. 0 disables fixes. Default: 2.
 	 */
 	maxFixRounds: number;
 	/**
@@ -240,7 +247,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
 	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
 
-	// 0 disables the auto-fix loop (main agent handles fixes itself).
+	// 0 disables worker fixes, not the initial managed docs/review workflow.
 	if (typeof raw.maxFixRounds === "number" && Number.isFinite(raw.maxFixRounds)) {
 		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
 	}
@@ -282,6 +289,29 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		}
 	}
 
+	if (!config.announcedFeatures.includes(DOCUMENTER_DEFAULTED_FEATURE)) {
+		config.announcedFeatures.push(DOCUMENTER_DEFAULTED_FEATURE);
+		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(DOCUMENTER_NAME)) {
+			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
+			config.enabledAgents.splice(
+				reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex,
+				0,
+				DOCUMENTER_NAME,
+			);
+			config.announcedFeatures.push(DOCUMENTER_AUTO_ENABLED_FEATURE);
+			let inherited = false;
+			if (!config.agentModels[DOCUMENTER_NAME] && config.agentModels[EXPLORER_NAME]) {
+				config.agentModels[DOCUMENTER_NAME] = config.agentModels[EXPLORER_NAME];
+				inherited = true;
+			}
+			if (!config.agentThinkingLevels[DOCUMENTER_NAME] && config.agentThinkingLevels[EXPLORER_NAME]) {
+				config.agentThinkingLevels[DOCUMENTER_NAME] = config.agentThinkingLevels[EXPLORER_NAME];
+				inherited = true;
+			}
+			if (inherited) config.announcedFeatures.push(DOCUMENTER_INHERITED_FEATURE);
+		}
+	}
+
 	return config;
 }