feat: proactive library usage for domain-specific coding tasks

[barkain]

Summary

Makes the agent proactively consult the knowledge library when writing code that involves domain-specific parameters, protocols, standards, or configurations — without the user explicitly asking.

Changes

• Expanded skill triggers (skills/agentlib-knowledge/SKILL.md): The skill now auto-triggers on coding tasks involving domain-specific values, not just explicit research questions like "look up" or "what does the book say". The "do NOT trigger on code editing" exclusion was narrowed to "general programming tasks" to avoid suppressing domain-specific coding triggers.

• Root CLAUDE.md (new): Always-loaded instructions telling the agent to check the library before writing domain-specific code, prefer library values over memory, and cite sources in comments. Clear exclusions for general programming, git operations, and simple edits.

Example behavior

Before: User says "set up a GROMACS simulation" → agent writes code from memory, might use wrong parameters.

After: User says "set up a GROMACS simulation" → agent checks library for simulation protocols → uses verified parameters with source citations in comments.

Test plan

• Start a session with the plugin loaded (ccw --plugin-dir <path>)
• Ask a domain-specific coding question related to an ingested book
• Verify the agent proactively invokes /agentlib-knowledge without being asked
• Verify general programming tasks do NOT trigger library lookup

🤖 Generated with Claude Code

[qodo-code-review]

Review Summary by Qodo

Enable proactive library usage for domain-specific coding

✨ Enhancement

Walkthroughs

Description

• Enables proactive library consultation for domain-specific coding tasks
• Expands skill triggers to include code writing with domain parameters
• Adds root CLAUDE.md with agent instructions for library usage
• Clarifies exclusions to prevent triggering on general programming

Diagram

flowchart LR
  User["User requests domain-specific code"] -->|triggers expanded skill| Skill["agentlib-knowledge skill"]
  Skill -->|consults| Library["Knowledge library"]
  Library -->|returns verified values| Agent["Agent writes code"]
  Agent -->|cites sources| Output["Code with source comments"]
  RootInstructions["CLAUDE.md root instructions"] -->|guides| Agent

Loading

File Changes

1. CLAUDE.md 📝 Documentation +23/-0

Root instructions for proactive library consultation

• New file providing always-loaded instructions for proactive library usage
• Specifies when to consult library: domain-specific parameters, protocols, standards,
 configurations
• Lists exclusions: general programming, git operations, file management, simple edits
• Directs agent to prefer library values over memory and cite sources in comments

CLAUDE.md

---

2. skills/agentlib-knowledge/SKILL.md ✨ Enhancement +1/-1

Expand skill triggers for domain-specific coding

• Expanded skill description to trigger on domain-specific code writing tasks
• Added triggers for code involving domain parameters, protocols, standards, configurations
• Added triggers for technical terms and domain methodology/best practices queries
• Narrowed exclusions from "code editing" to "general programming tasks" to allow domain-specific
 triggers

skills/agentlib-knowledge/SKILL.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 📐 Spec deviations (0)

1. Trigger guidance contradicts itself 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md says not to use the library for simple code edits/bug fixes unrelated to domain knowledge,
but the updated skill description now explicitly triggers on code-writing scenarios (and even
“encountering technical terms”). This mismatch will cause unexpected auto-invocations in cases
CLAUDE.md says should be excluded, making behavior inconsistent and hard to predict.

Code

skills/agentlib-knowledge/SKILL.md[3]

+description: "Knowledge library navigation. Trigger on: research questions, book references, domain knowledge queries, 'according to', 'what does the book say', 'look up', 'find in', or any question that may be answered by ingested books/documents/papers. Also trigger when: writing code that involves domain-specific parameters, protocols, standards, or configurations; encountering technical terms that might be defined in the library; the user asks about methodology, best practices, or procedures from a specific domain. Do NOT trigger on: general programming tasks (loops, data structures, algorithms), git operations, file management, web browsing requests."

Evidence

The new always-loaded policy explicitly excludes “simple code edits or bug fixes unrelated to domain
knowledge”, while the skill’s trigger text was broadened to activate during code-writing scenarios
and only excludes “general programming tasks”, creating conflicting guidance about when the skill
should fire.

CLAUDE.md[12-18]
skills/agentlib-knowledge/SKILL.md[1-3]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CLAUDE.md` and `skills/agentlib-knowledge/SKILL.md` now disagree about whether/when library lookup should happen during code edits.
## Issue Context
- `CLAUDE.md` says *do not* use the library for “simple code edits or bug fixes unrelated to domain knowledge”.
- The skill description now says to *also trigger* when “writing code that involves domain-specific parameters…” and even when “encountering technical terms…”, but does **not** exclude simple edits/bugfixes.
## Fix Focus Areas
- Decide the intended behavior, then make the two documents consistent:
- Either update `CLAUDE.md` to explicitly allow domain-specific code edits to trigger the library (and clarify what “simple edits” means),
- Or tighten the skill description’s trigger clause (e.g., remove/limit “encountering technical terms…”) and/or add “simple code edits/bug fixes unrelated to domain knowledge” to the skill’s do-not-trigger list.
### Fix Focus Areas (exact locations)
- skills/agentlib-knowledge/SKILL.md[1-3]
- CLAUDE.md[12-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Library path override missing ☑ 🐞 Bug ✓ Correctness

Description

The new always-loaded CLAUDE.md hardcodes the library location to
~/.claude/plugins/agentlib/library/, but the codebase resolves the library root from
AGENTLIB_DATA when set to an absolute path. With a custom AGENTLIB_DATA, the new guidance
(including browsing via /agentlib:agentlib-library) will direct the agent to the wrong directory
and break proactive lookup despite the library existing.

Code

CLAUDE.md[R19-23]

+## Library location
+
+`~/.claude/plugins/agentlib/library/`
+
+Use `/agentlib:agentlib-library` to browse what's available.

Evidence

CLAUDE.md introduces a single fixed library path. In contrast, lib/storage.py explicitly
supports overriding the library root with AGENTLIB_DATA, and the /agentlib:agentlib-library
command doc currently reads from the default hardcoded path, so the new always-loaded guidance can
be wrong for valid configurations.

CLAUDE.md[19-23]
lib/storage.py[50-60]
commands/agentlib-library.md[12-14]
commands/agentlib-configure.md[14-35]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CLAUDE.md` hardcodes a single library path, but the runtime supports `AGENTLIB_DATA` overriding the library root. This makes the new always-loaded guidance incorrect for a supported configuration.
## Issue Context
- `lib/storage.py` uses `AGENTLIB_DATA` (if set to an absolute path) as the data root.
- `CLAUDE.md` and `commands/agentlib-library.md` point to `~/.claude/plugins/agentlib/library/` only.
## Fix Focus Areas
- Update `CLAUDE.md` to say this path is the **default**, and document the `AGENTLIB_DATA` override (and/or `CLAUDE_PLUGIN_DATA` conventions if that’s the intended source of truth).
- Update `/agentlib:agentlib-library` command instructions to read from the override location when configured (e.g., instruct: “if `AGENTLIB_DATA` is set, read from `${AGENTLIB_DATA}`; otherwise use the default path”).
### Fix Focus Areas (exact locations)
- CLAUDE.md[19-23]
- lib/storage.py[50-60]
- commands/agentlib-library.md[12-14]
- commands/agentlib-configure.md[14-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more