Decisions
- Pending: Which agent to build first? (researcher is likely most immediately useful)
- Pending: Agent format — own CLAUDE.md-style instructions or just prompt templates?
- Pending: How do agents interact with skills? (e.g., briefing-compiler used by /briefing)
- Pending: Per-agent memory — dedicated memory files per agent or shared memory pool?
- Pending: Persistent sessions — always-on server process or session-start preload from memory files?
- Pending: Reviewer agent — hard gate (blocks build until approved) or advisory (warnings only)?
- Pending: Features specialist — auto-generate full spec from one-liner or require user outline?
User Tasks
Summary
Build specialized sub-agents that handle focused tasks autonomously within Opus.
Problem / Motivation
Many Opus tasks require deep, focused work in a specific domain (research, code review, building features, compiling briefings). Currently these are done ad-hoc with generic Task tool calls. Custom agent definitions would standardize prompts, tools, and behavior for recurring specialized work.
Proposed Solution
Define and implement custom agents as reusable configurations. Each agent gets a definition file in .claude/agents/ with purpose, tools, prompt template, and usage conditions. Agents are invoked via the Task tool from skills or manual calls.
Planned Agents:
| Agent | Purpose |
|---|---|
| researcher | Gather information from web and codebase for deep exploration and analysis |
| reviewer | Quality gate — reviews implementation plans before build, checks conventions, catches edge cases |
| builder | Pick up planned features, implement them, update status on completion |
| briefing-compiler | Compile daily briefings from vault state, git history, and external data |
| features | Spec designer — reads raw ideas and creates full FR documents with AI-generated phases, decisions, test plans, and prerequisites |
Open Questions
1. First Agent Choice
Question: Which agent to build first?
| Option | Description |
|---|---|
| A) researcher | Most immediately useful for exploration tasks |
| B) reviewer | Useful for quality checks |
| C) builder | Useful for implementation |
Recommendation: Option A — researcher is the most broadly useful starting point.
Decision:
2. Agent Definition Format
Question: Should agents have their own CLAUDE.md-style instructions or just prompt templates?
| Option | Description |
|---|---|
| A) Prompt templates | Simple, lightweight, easy to iterate |
| B) Full instruction files | More powerful, more maintenance |
Recommendation: Option A — start simple, upgrade if needed.
Decision:
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | Build first agent (researcher) | — |
| Phase 2 | Build remaining agents | — |
| Phase 3 | Persistent sessions & per-agent memory | — |
Phase 1: First Agent (researcher) —
Goal: Establish agent definition format and build the first working agent.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| Agent definition format | Decide on structure for agent files | mv | — |
| Build researcher agent | Definition + prompt template in .claude/agents/ | opus | — |
| Test researcher | Verify it works via Task tool in a real task | mv | — |
| Update agents README | Document the built agent | opus | — |
Phase 2: Remaining Agents —
Goal: Build the remaining planned agents and integrate them with skills.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| Build reviewer agent | Code/vault review specialization | mv | — |
| Build builder agent | Feature implementation specialization | opus | — |
| Build briefing-compiler | Daily briefing specialization | opus | — |
| Integrate with skills | Wire agents into relevant slash commands | opus | — |
Phase 3: Persistent Sessions & Per-Agent Memory —
Goal: Enable agents to accumulate knowledge across invocations, preserving learnings and context between sessions.
Persistent Sessions: Instead of starting cold each time, each specialist agent:
- Keeps conversation history from previous tasks in its domain
- Writes learnings to persistent memory files
- Reads path-scoped rules that act as “crystallized knowledge” from previous sessions
- On context overflow, key learnings are compressed but preserved
Per-Agent Memory: Each agent gets its own memory file (e.g., .claude/agents/memory/researcher.md) storing:
- File paths it frequently works with
- Patterns learned about the codebase
- Common pitfalls in its domain
- User preferences specific to its specialty
Reviewer Agent (Quality Gate): A dedicated reviewer agent that evaluates plans before implementation:
- Reviews implementation plans against project conventions
- Checks for missed edge cases, security issues, performance concerns
- Can reject a plan and send it back for revision
- Runs as a quality gate in the pipeline strategy (Plan → Review → Build)
| File / Feature | Details | Owner | Status |
|---|---|---|---|
.claude/agents/memory/ directory | Per-agent memory directory structure | opus | — |
| Memory file format | Define standard format for agent memory files (frontmatter + sections) | opus | — |
| Session preload mechanism | On agent start, load relevant memory file into context | opus | — |
| Memory write-back | After task completion, agent writes new learnings to its memory file | opus | — |
| Context compression | When memory file exceeds context budget, compress while preserving key insights | opus | — |
| Reviewer agent definition | Build reviewer agent with quality gate behavior | mv | — |
| Pipeline integration | Wire reviewer into Plan → Review → Build flow for medium-complexity features | mv | — |
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|---|
| REQ-1 | .claude/agents/ directory and README |
Current State
| Component | Status | Details |
|---|---|---|
.claude/agents/ directory | done | Exists with README |
| Agent definitions | — | Only planned, none built |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|---|---|
| Agent definition format decision | Low | No |
| First agent implementation | Med | No |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|---|---|---|
| … | … | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-02-27 | Created | Moved planned agents from .claude/agents/README.md to FR |
| 2026-02-27 | Renumbered | From FR-024 to FR-043 |
| 2026-02-28 | Reformatted | Aligned to feature-request template |
| 2026-03-04 | Expanded | Added persistent sessions, per-agent memory, reviewer agent (inspired by Nexie) |
| 2026-03-04 | Updated | Added features specialist agent (inspired by Nexie’s spec designer) |
References
.claude/agents/README.md— agent ideas originally listed here- FR-037 (Daily Briefings) — briefing-compiler agent
- FR-045 (Complexity Routing) — routes work to agents based on complexity score
- FR-046 (Job Registry & Priority Queue) — dispatches jobs to available agents