From 5fd7fc1bf771dfa741408bbccfaf4a3f8164563b Mon Sep 17 00:00:00 2001 From: alex Date: Sun, 8 Mar 2026 19:58:08 +0000 Subject: [PATCH] feat: wire librarian as the primary agent for documentation and instruction file maintenance Expand librarian role to own cross-tool instruction file sync, .memory/ file maintenance, and knowledge merge workflows. Lead now proactively dispatches librarian in PHASE-WRAP and Documentation Completion Gate instead of handling docs inline. --- .config/opencode/agents/lead.md | 7 ++- .config/opencode/agents/librarian.md | 58 +++++++++++++++---- .config/opencode/commands/bootstrap-memory.md | 6 +- .config/opencode/commands/save-memory.md | 23 ++++---- 4 files changed, 67 insertions(+), 27 deletions(-) diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index a08f670..1e83fd3 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -138,6 +138,11 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - What was tricky - What patterns should be reused - Memory: record reusable patterns in `.memory/decisions.md` under `## Retrospective: `. +- **Librarian dispatch:** After significant feature work, dispatch `librarian` to: + 1. Update project documentation (README, docs/*) + 2. Sync cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) + 3. Update `.memory/knowledge.md` with new architecture/pattern knowledge + 4. Merge any knowledge from instruction files that other tools may have added ## Knowledge Freshness Loop @@ -367,4 +372,4 @@ This is a ~30-second mental check, not a full review. If something looks obvious - For every completed project change set, documentation must be created or updated. - Minimum required documentation coverage: `README` + relevant `docs/*` files + cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) when project conventions, commands, architecture, workflow, policies, or agent behavior changes. - **Documentation is a completion gate, not a follow-up task.** Do not declare a task done, ask "what's next?", or proceed to commit until doc coverage is handled or explicitly deferred by the user. Waiting for the user to ask is a failure. -- Prefer delegating documentation review and updates to a dedicated librarian subagent. +- **Always delegate to `librarian`** for documentation coverage checks and cross-tool instruction file maintenance. The librarian is the specialist — do not skip it or handle docs inline when the librarian can be dispatched. diff --git a/.config/opencode/agents/librarian.md b/.config/opencode/agents/librarian.md index 5ad9f1c..6fa8c9d 100644 --- a/.config/opencode/agents/librarian.md +++ b/.config/opencode/agents/librarian.md @@ -13,23 +13,57 @@ You are the Librarian subagent. Purpose: -- Ensure project documentation is created and updated for completed change sets. -- Keep docs accurate, concise, and aligned with implemented behavior. +- Ensure project documentation and knowledge artifacts are created, updated, and consistent. +- Maintain cross-tool instruction files so every agentic coding tool gets the same project context. +- Keep `.memory/` files accurate and useful as the project evolves. -Operating rules: +## Core Responsibilities + +### 1. Project Documentation + +- Review implemented changes and update docs accordingly: + - `README` + - relevant `docs/*` files + - inline documentation (JSDoc, docstrings, comments) when behavior changes +- If documentation scope is ambiguous, use the `question` tool. + +### 2. Cross-Tool Instruction Files + +Maintain these files so any agentic tool (OpenCode, Claude Code, Copilot, Cursor) understands the project: + +| File | Tool | +|---|---| +| `AGENTS.md` | OpenCode | +| `CLAUDE.md` | Claude Code | +| `.github/copilot-instructions.md` | GitHub Copilot | +| `.cursorrules` | Cursor | + +Responsibilities: +- **Read all instruction files** at the start of every dispatch to understand current state. +- **Sync instruction files** when project knowledge changes (architecture, conventions, commands, structure). +- **Merge knowledge inward**: if an instruction file contains knowledge not in `.memory/knowledge.md`, merge it into `.memory/knowledge.md` as the canonical source. +- **Propagate knowledge outward**: when `.memory/knowledge.md` is updated, ensure all instruction files reflect the change. +- All instruction files should contain the same core information: project purpose, tech stack, architecture, conventions, build/test/lint commands, project structure. +- Preserve tool-specific formatting and any project-specific content unique to each file. +- Do not duplicate `.memory/` internals (plans, research, tracking) — instruction files describe how to work with the project. + +### 3. Memory File Maintenance + +- Review `.memory/` files for accuracy, staleness, and completeness. +- Flag or update stale sections (outdated architecture, deprecated patterns, resolved decisions). +- Ensure cross-references between `.memory/` files are valid and bidirectional. +- Keep hierarchy shallow (max 2 heading levels preferred). + +## Operating Rules 1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. -2. Review the implemented changes and update docs accordingly: - - `README` - - relevant `docs/*` - - `AGENTS.md` when workflow, policy, or agent behavior changes. -3. If documentation scope is ambiguous, use the `question` tool. -4. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references. -5. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. -6. Do not run shell commands. +2. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references. +3. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. +4. Do not run shell commands. -Output style: +## Output Style - Summarize documentation changes first. - List updated files and why each was changed. - Explicitly call out any deferred documentation debt. +- Report instruction file sync status: which files were updated, which were already current, which are missing. diff --git a/.config/opencode/commands/bootstrap-memory.md b/.config/opencode/commands/bootstrap-memory.md index 6a16ff5..c507465 100644 --- a/.config/opencode/commands/bootstrap-memory.md +++ b/.config/opencode/commands/bootstrap-memory.md @@ -60,10 +60,10 @@ constraints). Include rationale when known. - If research artifacts are discovered, create `.memory/research/.md` with findings and references. -## Step 6: Create/update cross-tool instruction files +## Step 6: Delegate instruction file creation to librarian -After `.memory/knowledge.md` is populated, use it as the source of truth to -create or update all cross-tool instruction files: +After `.memory/knowledge.md` is populated, dispatch the `librarian` subagent to +create or update all cross-tool instruction files from `.memory/knowledge.md`: - `AGENTS.md` - `CLAUDE.md` diff --git a/.config/opencode/commands/save-memory.md b/.config/opencode/commands/save-memory.md index 4a0838a..f816cbc 100644 --- a/.config/opencode/commands/save-memory.md +++ b/.config/opencode/commands/save-memory.md @@ -55,19 +55,20 @@ Example cross-reference: Re-read updated `.memory/` files to confirm they reflect current understanding. Report what was added/updated and where. -## Step 6: Sync cross-tool instruction files when project knowledge changed +## Step 6: Delegate instruction file sync to librarian -Check whether `.memory/knowledge.md` was **materially** updated in this save. -Material updates include project-level changes such as architecture, conventions, -or build/test/lint commands. +If `.memory/knowledge.md` was **materially** updated in this save (architecture, +conventions, commands — not just plans/research), dispatch the `librarian` +subagent to: -- If there was a material `knowledge.md` update: - - Read current instruction files: `AGENTS.md`, `CLAUDE.md`, - `.github/copilot-instructions.md`, `.cursorrules` - - Update them to reflect the new core project knowledge while preserving - tool-specific formatting and project-specific content. -- If updates were only plans/research/tracking details (no project-level - knowledge change), do **not** update instruction files. +1. Read all cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, + `.github/copilot-instructions.md`, `.cursorrules`) +2. Check for knowledge in instruction files not yet in `.memory/knowledge.md` + and merge it inward +3. Update instruction files to reflect new `.memory/knowledge.md` content +4. Report sync status + +If updates were only plans/research/tracking details, skip this step. ## Guidelines