agent-notes 2.17.0__tar.gz → 2.19.0__tar.gz

{agent_notes-2.17.0 → agent_notes-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.17.0
+Version: 2.19.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 AI agent configuration manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/opencode-ai/opencode).
 
-Configures a Lead agent (Opus) that orchestrates a team of 18 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
+Configures a Lead agent (Opus) that orchestrates a team of 19 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
 
 ## Quick Start
 
@@ -46,8 +46,8 @@ agent-notes doctor
 
 | Component | Description |
 |-----------|-------------|
-| **Skills** | 42 on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
-| **Agents** | 18 specialized AI subagents with hierarchical model strategy |
+| **Skills** | 42+ on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
+| **Agents** | 19 specialized AI subagents with hierarchical model strategy |
 | **Rules** | Global instructions, code quality, and safety guardrails |
 | **Config** | Global instructions for Claude Code, OpenCode, and GitHub Copilot |
 
@@ -153,29 +153,31 @@ agent-notes memory add "Rails enum prefix" \
 
 ## Agent Team
 
-Specialized subagents with hierarchical model strategy: **Opus 4.6 decides, Sonnet 4.6 executes, Haiku 4.5 explores.**
-
-| Agent | Model | Role |
-|-------|-------|------|
-| **lead** | Opus 4.6 | Plans, delegates, reviews. Orchestrator. |
-| **architect** | Opus 4.6 | System architecture, module boundaries, domain models. Read-only. |
-| **debugger** | Opus 4.6 | Bug investigation: reproduces, isolates, identifies root cause. Read-only. |
-| **coder** | Sonnet 4.6 | Implements features, fixes bugs, edits files. |
-| **reviewer** | Sonnet 4.6 | Code quality review. Read-only. |
-| **security-auditor** | Sonnet 4.6 | Security vulnerability analysis. Read-only. |
-| **test-writer** | Sonnet 4.6 | Writes tests for any framework. |
-| **test-runner** | Sonnet 4.6 | Diagnoses and fixes failing tests. |
-| **system-auditor** | Sonnet 4.6 | Codebase health: duplication, N+1, coupling. Read-only. |
-| **database-specialist** | Sonnet 4.6 | Schema design, indexes, query performance, migrations. Read-only. |
-| **performance-profiler** | Sonnet 4.6 | Response times, memory, caching, bundle size. Read-only. |
-| **devops** | Sonnet 4.6 | Docker, CI/CD, deployment configs. |
-| **devil** | Sonnet 4.6 | Challenges plans to surface hidden risks. Read-only. |
-| **integrations** | Sonnet 4.6 | Third-party integrations: OAuth, webhooks, payments. |
-| **refactorer** | Sonnet 4.6 | Improves code structure without changing behavior. |
-| **analyst** | Haiku 4.5 | Requirements analysis: surfaces missing or contradictory requirements. Read-only. |
-| **api-reviewer** | Haiku 4.5 | API design, versioning, error handling, backward compatibility. Read-only. |
-| **tech-writer** | Haiku 4.5 | Documentation: READMEs, API docs, changelogs. |
-| **explorer** | Haiku 4.5 | Fast file discovery and pattern search. Read-only. |
+Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+
+| Agent | Role | Model Tier | Purpose |
+|---|---|---|---|
+| lead | orchestrator | opus | Plans, coordinates, verifies — the team lead |
+| architect | reasoner | opus | System design, module boundaries, refactor planning |
+| debugger | reasoner | opus | Complex bug investigation, root-cause analysis |
+| coder | worker | sonnet | Implementation, file edits, bug fixes |
+| reviewer | worker | sonnet | Code quality, readability, correctness |
+| security-auditor | worker | sonnet | Auth, injection, XSS, secrets exposure |
+| test-writer | worker | sonnet | Creates tests for any framework |
+| test-runner | worker | sonnet | Diagnoses and fixes failing tests |
+| system-auditor | worker | sonnet | Duplication, dead code, coupling, complexity |
+| database-specialist | worker | sonnet | Schema design, indexes, query performance |
+| performance-profiler | worker | sonnet | Response times, memory, bundle size |
+| api-reviewer | worker | sonnet | REST conventions, versioning, backward compatibility |
+| devops | worker | sonnet | Docker, CI/CD, deployment, infrastructure |
+| devil | worker | sonnet | Devil's advocate — challenges plans and assumptions |
+| integrations | worker | sonnet | OAuth, webhooks, API clients, SSO |
+| refactorer | worker | sonnet | Extracts methods, reduces duplication, improves naming |
+| explorer | scout | haiku | Fast file discovery, pattern search |
+| analyst | scout | haiku | Requirements translation, acceptance criteria |
+| tech-writer | scout | haiku | READMEs, API docs, changelogs |
+
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
 
 ## Architecture
 
@@ -183,7 +185,7 @@ agent-notes is a 4-layer engine (domain / registries / services / commands). All
 
 ## Improved Claude Code workflows
 
-Four failure modes that derail AI-assisted development, and the skills that address them. Inspired by [Matt Pocock's skills repo](https://github.com/mattpocock/skills).
+Four failure modes that derail AI-assisted development, and the skills that address them.
 
 | Failure mode | What goes wrong | Skills that help |
 |---|---|---|
@@ -203,7 +205,7 @@ Four failure modes that derail AI-assisted development, and the skills that addr
 
 ## Skills
 
-42 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -216,7 +218,7 @@ Load the docker-compose skill for multi-service setup
 
 ## Agent Memory
 
-Agents accumulate knowledge across sessions using one of three backends, chosen during `agent-notes install`.
+Agents accumulate knowledge across sessions using one of four backends, chosen during `agent-notes install`.
 
 ### Backends
 
@@ -224,9 +226,27 @@ Agents accumulate knowledge across sessions using one of three backends, chosen
 |---------|---------|----------|
 | **Local** | `~/.claude/agent-memory/<agent>/` — plain markdown per agent | Simple setup, no extra tools |
 | **Obsidian** | Category vault with YAML frontmatter and `[[wikilinks]]` | Visual browsing, backlinks, Dataview queries |
-| **Wiki** | `~/Documents/Obsidian Vault/agent-wiki/` — structured wiki with categories | Team knowledge bases, shared context |
+| **Wiki** | Structured wiki with page types and versioning | Team knowledge bases, compounding knowledge |
 | **None** | Disabled — no files written | Stateless or shared machines |
 
+### Session tracking by backend
+
+| Feature | Local | Obsidian | Wiki |
+|---|---|---|---|
+| Storage location | `~/.claude/agent-memory/<agent>/` | Obsidian vault with categories | Structured wiki with page types |
+| Note types | Flat markdown per agent | `pattern`, `decision`, `mistake`, `context`, `session` | `source`, `concept`, `entity`, `synthesis`, `session` |
+| Session tracking | None | Auto-created session notes with `## Linked notes` | Session pages in `wiki/sessions/` |
+| Cross-referencing | None | `[[wikilinks]]` auto-appended to session notes | Markdown links maintained by LLM |
+| Key operations | read/write | add, list, show, reset, export, import | ingest, query, lint + add, list, show |
+| Best for | Simple setup, no extra tools | Visual browsing, backlinks, Dataview queries | Team knowledge bases, compounding knowledge |
+
+**Obsidian backend** — Uses category directories (`Patterns/`, `Decisions/`, `Mistakes/`, `Context/`, `Sessions/`). When you write a non-session note during an active session, the CLI auto-links it to the session note via `[[wikilinks]]`. Plans are mirrored as Decision notes.
+
+**Wiki backend** — Implements Karpathy's LLM Wiki pattern (v1). Structure: `raw/` for immutable source material, `wiki/` for LLM-maintained pages organized into `sources/`, `concepts/`, `entities/`, `synthesis/`, `sessions/`. Three key operations:
+- **ingest** — Process source material, extract key info, update entity/concept pages, append to log
+- **query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
+- **lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+
 ### Obsidian setup
 
 Run `agent-notes install` and pick Obsidian when prompted. The wizard auto-detects existing vaults under `~/Documents`, `~/Desktop`, and `~`. To initialize the vault structure:
@@ -270,6 +290,11 @@ tags: [rails, models]
 Always use `_prefix: true` with Rails enums to avoid method name collisions.
 ```
 
+## Inspired by
+
+- [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, verbosity, broken code, architectural degradation), and several core skills (tdd, grill-me, grill-with-docs, improve-codebase-architecture, zoom-out, caveman)
+
 ## Development
 
 Python 3.10+ required. Build from source and run tests:

{agent_notes-2.17.0 → agent_notes-2.19.0}/README.md

@@ -2,7 +2,7 @@
 
 AI agent configuration manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/opencode-ai/opencode).
 
-Configures a Lead agent (Opus) that orchestrates a team of 18 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
+Configures a Lead agent (Opus) that orchestrates a team of 19 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
 
 ## Quick Start
 
@@ -16,8 +16,8 @@ agent-notes doctor
 
 | Component | Description |
 |-----------|-------------|
-| **Skills** | 42 on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
-| **Agents** | 18 specialized AI subagents with hierarchical model strategy |
+| **Skills** | 42+ on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
+| **Agents** | 19 specialized AI subagents with hierarchical model strategy |
 | **Rules** | Global instructions, code quality, and safety guardrails |
 | **Config** | Global instructions for Claude Code, OpenCode, and GitHub Copilot |
 
@@ -123,29 +123,31 @@ agent-notes memory add "Rails enum prefix" \
 
 ## Agent Team
 
-Specialized subagents with hierarchical model strategy: **Opus 4.6 decides, Sonnet 4.6 executes, Haiku 4.5 explores.**
-
-| Agent | Model | Role |
-|-------|-------|------|
-| **lead** | Opus 4.6 | Plans, delegates, reviews. Orchestrator. |
-| **architect** | Opus 4.6 | System architecture, module boundaries, domain models. Read-only. |
-| **debugger** | Opus 4.6 | Bug investigation: reproduces, isolates, identifies root cause. Read-only. |
-| **coder** | Sonnet 4.6 | Implements features, fixes bugs, edits files. |
-| **reviewer** | Sonnet 4.6 | Code quality review. Read-only. |
-| **security-auditor** | Sonnet 4.6 | Security vulnerability analysis. Read-only. |
-| **test-writer** | Sonnet 4.6 | Writes tests for any framework. |
-| **test-runner** | Sonnet 4.6 | Diagnoses and fixes failing tests. |
-| **system-auditor** | Sonnet 4.6 | Codebase health: duplication, N+1, coupling. Read-only. |
-| **database-specialist** | Sonnet 4.6 | Schema design, indexes, query performance, migrations. Read-only. |
-| **performance-profiler** | Sonnet 4.6 | Response times, memory, caching, bundle size. Read-only. |
-| **devops** | Sonnet 4.6 | Docker, CI/CD, deployment configs. |
-| **devil** | Sonnet 4.6 | Challenges plans to surface hidden risks. Read-only. |
-| **integrations** | Sonnet 4.6 | Third-party integrations: OAuth, webhooks, payments. |
-| **refactorer** | Sonnet 4.6 | Improves code structure without changing behavior. |
-| **analyst** | Haiku 4.5 | Requirements analysis: surfaces missing or contradictory requirements. Read-only. |
-| **api-reviewer** | Haiku 4.5 | API design, versioning, error handling, backward compatibility. Read-only. |
-| **tech-writer** | Haiku 4.5 | Documentation: READMEs, API docs, changelogs. |
-| **explorer** | Haiku 4.5 | Fast file discovery and pattern search. Read-only. |
+Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+
+| Agent | Role | Model Tier | Purpose |
+|---|---|---|---|
+| lead | orchestrator | opus | Plans, coordinates, verifies — the team lead |
+| architect | reasoner | opus | System design, module boundaries, refactor planning |
+| debugger | reasoner | opus | Complex bug investigation, root-cause analysis |
+| coder | worker | sonnet | Implementation, file edits, bug fixes |
+| reviewer | worker | sonnet | Code quality, readability, correctness |
+| security-auditor | worker | sonnet | Auth, injection, XSS, secrets exposure |
+| test-writer | worker | sonnet | Creates tests for any framework |
+| test-runner | worker | sonnet | Diagnoses and fixes failing tests |
+| system-auditor | worker | sonnet | Duplication, dead code, coupling, complexity |
+| database-specialist | worker | sonnet | Schema design, indexes, query performance |
+| performance-profiler | worker | sonnet | Response times, memory, bundle size |
+| api-reviewer | worker | sonnet | REST conventions, versioning, backward compatibility |
+| devops | worker | sonnet | Docker, CI/CD, deployment, infrastructure |
+| devil | worker | sonnet | Devil's advocate — challenges plans and assumptions |
+| integrations | worker | sonnet | OAuth, webhooks, API clients, SSO |
+| refactorer | worker | sonnet | Extracts methods, reduces duplication, improves naming |
+| explorer | scout | haiku | Fast file discovery, pattern search |
+| analyst | scout | haiku | Requirements translation, acceptance criteria |
+| tech-writer | scout | haiku | READMEs, API docs, changelogs |
+
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
 
 ## Architecture
 
@@ -153,7 +155,7 @@ agent-notes is a 4-layer engine (domain / registries / services / commands). All
 
 ## Improved Claude Code workflows
 
-Four failure modes that derail AI-assisted development, and the skills that address them. Inspired by [Matt Pocock's skills repo](https://github.com/mattpocock/skills).
+Four failure modes that derail AI-assisted development, and the skills that address them.
 
 | Failure mode | What goes wrong | Skills that help |
 |---|---|---|
@@ -173,7 +175,7 @@ Four failure modes that derail AI-assisted development, and the skills that addr
 
 ## Skills
 
-42 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -186,7 +188,7 @@ Load the docker-compose skill for multi-service setup
 
 ## Agent Memory
 
-Agents accumulate knowledge across sessions using one of three backends, chosen during `agent-notes install`.
+Agents accumulate knowledge across sessions using one of four backends, chosen during `agent-notes install`.
 
 ### Backends
 
@@ -194,9 +196,27 @@ Agents accumulate knowledge across sessions using one of three backends, chosen
 |---------|---------|----------|
 | **Local** | `~/.claude/agent-memory/<agent>/` — plain markdown per agent | Simple setup, no extra tools |
 | **Obsidian** | Category vault with YAML frontmatter and `[[wikilinks]]` | Visual browsing, backlinks, Dataview queries |
-| **Wiki** | `~/Documents/Obsidian Vault/agent-wiki/` — structured wiki with categories | Team knowledge bases, shared context |
+| **Wiki** | Structured wiki with page types and versioning | Team knowledge bases, compounding knowledge |
 | **None** | Disabled — no files written | Stateless or shared machines |
 
+### Session tracking by backend
+
+| Feature | Local | Obsidian | Wiki |
+|---|---|---|---|
+| Storage location | `~/.claude/agent-memory/<agent>/` | Obsidian vault with categories | Structured wiki with page types |
+| Note types | Flat markdown per agent | `pattern`, `decision`, `mistake`, `context`, `session` | `source`, `concept`, `entity`, `synthesis`, `session` |
+| Session tracking | None | Auto-created session notes with `## Linked notes` | Session pages in `wiki/sessions/` |
+| Cross-referencing | None | `[[wikilinks]]` auto-appended to session notes | Markdown links maintained by LLM |
+| Key operations | read/write | add, list, show, reset, export, import | ingest, query, lint + add, list, show |
+| Best for | Simple setup, no extra tools | Visual browsing, backlinks, Dataview queries | Team knowledge bases, compounding knowledge |
+
+**Obsidian backend** — Uses category directories (`Patterns/`, `Decisions/`, `Mistakes/`, `Context/`, `Sessions/`). When you write a non-session note during an active session, the CLI auto-links it to the session note via `[[wikilinks]]`. Plans are mirrored as Decision notes.
+
+**Wiki backend** — Implements Karpathy's LLM Wiki pattern (v1). Structure: `raw/` for immutable source material, `wiki/` for LLM-maintained pages organized into `sources/`, `concepts/`, `entities/`, `synthesis/`, `sessions/`. Three key operations:
+- **ingest** — Process source material, extract key info, update entity/concept pages, append to log
+- **query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
+- **lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+
 ### Obsidian setup
 
 Run `agent-notes install` and pick Obsidian when prompted. The wizard auto-detects existing vaults under `~/Documents`, `~/Desktop`, and `~`. To initialize the vault structure:
@@ -240,6 +260,11 @@ tags: [rails, models]
 Always use `_prefix: true` with Rails enums to avoid method name collisions.
 ```
 
+## Inspired by
+
+- [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, verbosity, broken code, architectural degradation), and several core skills (tdd, grill-me, grill-with-docs, improve-codebase-architecture, zoom-out, caveman)
+
 ## Development
 
 Python 3.10+ required. Build from source and run tests:

agent_notes-2.19.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.19.0

{agent_notes-2.17.0 → agent_notes-2.19.0}/agent_notes/commands/memory.py

@@ -250,6 +250,30 @@ def do_show(name: str) -> None:
             print("")
         return
 
+    elif backend == "wiki":
+        if path is None:
+            print("Memory path not configured.")
+            return
+        from ..services.wiki_backend import WIKI_PAGE_TYPES
+        wiki_dir = path / "wiki"
+        if name not in WIKI_PAGE_TYPES:
+            print(f"Page type '{name}' not found. Available types: {', '.join(WIKI_PAGE_TYPES)}")
+            return
+        type_dir = wiki_dir / name
+        if not type_dir.exists():
+            print(f"No pages found for type '{name}' in wiki {path}")
+            return
+        print(f"Wiki pages in '{name}':")
+        print("")
+        for f in sorted(type_dir.glob("*.md")):
+            print(f"{Color.CYAN}--- {f.name} ---{Color.NC}")
+            try:
+                print(f.read_text())
+            except (UnicodeDecodeError, OSError):
+                print("(binary file or read error)")
+            print("")
+        return
+
     # local backend
     if path is None:
         path = MEMORY_DIR
@@ -283,6 +307,41 @@ def do_reset(name: Optional[str] = None) -> None:
         print("Memory is disabled.")
         return
 
+    if backend == "wiki":
+        if path is None or not path.exists():
+            print("No wiki found to reset.")
+            return
+        target = f"wiki at {path}" if name is None else f"wiki page type '{name}' at {path}"
+        print(f"{Color.RED}Warning: this will permanently delete the {target}.{Color.NC}")
+        confirm = input("Type 'yes' to confirm: ")
+        if confirm == "yes":
+            import shutil as _shutil
+            from ..services.wiki_backend import WIKI_PAGE_TYPES
+            if name is None:
+                wiki_dir = path / "wiki"
+                for page_type in WIKI_PAGE_TYPES:
+                    type_dir = wiki_dir / page_type
+                    if type_dir.exists():
+                        _shutil.rmtree(type_dir)
+                        type_dir.mkdir()
+                print(f"{Color.GREEN}Wiki at {path} cleared.{Color.NC}")
+            else:
+                from ..services.wiki_backend import WIKI_PAGE_TYPES
+                wiki_dir = path / "wiki"
+                if name not in WIKI_PAGE_TYPES:
+                    print(f"Page type '{name}' not found. Available types: {', '.join(WIKI_PAGE_TYPES)}")
+                    return
+                type_dir = wiki_dir / name
+                if not type_dir.exists():
+                    print(f"No pages found for type '{name}'.")
+                    return
+                _shutil.rmtree(type_dir)
+                type_dir.mkdir()
+                print(f"{Color.GREEN}Wiki pages for type '{name}' cleared.{Color.NC}")
+        else:
+            print("Cancelled.")
+        return
+
     if path is None:
         path = MEMORY_DIR
 
@@ -666,7 +725,7 @@ Commands:
   list             List all agent memories with sizes (default)
   vault            Show current backend and memory path
   index            Regenerate Index.md for the current backend
-  add <title> <body>  Add a note (obsidian backend)
+  add <title> <body>  Add a note (obsidian and wiki backends)
   migrate          Migrate old per-project layout to new shared flat layout
   size             Total disk usage
   show <name>      Show memory contents for one agent/category
@@ -674,6 +733,9 @@ Commands:
   reset <name>     Clear one agent's memory
   export           Back up memories to agent-notes/memory-backup/
   import           Restore from agent-notes/memory-backup/
+  ingest <title> <body>  Ingest source material and fan-out to concepts/entities (wiki backend)
+  query <keyword>  Search wiki pages by keyword (wiki backend)
+  lint             Check wiki health: orphans, broken links, stale index (wiki backend)
 
 Examples:
   agent-notes memory                    List all memories

{agent_notes-2.17.0 → agent_notes-2.19.0}/agent_notes/data/agents/agents.yaml

@@ -178,7 +178,7 @@ agents:
 
   api-reviewer:
     description: "Reviews API design for consistency, versioning, error handling, and backward compatibility. Read-only analysis. Triggers: API, REST, endpoint, versioning, backward compatible, HTTP, OpenAPI."
-    role: scout
+    role: worker
     mode: subagent
     color: cyan
     effort: medium

agent_notes-2.19.0/agent_notes/data/agents/lead.md

@@ -0,0 +1,47 @@
+You are a team lead that plans and coordinates work across specialized agents.
+
+<!-- include: phase0 -->
+
+<!-- include: hard_limits -->
+
+### Credentials handling (HARD RULE)
+
+The lead MUST NEVER read, print, log, or include API keys / credentials / secrets in any output, even if the user asks. The credentials file at `~/.agent-notes/credentials.toml` is opaque — your only legitimate operations are:
+
+- Confirm a provider is configured: `agent-notes config provider <name>` (returns yes/no, never the value)
+- Trigger a re-prompt: `agent-notes config providers` (the wizard handles entry; values never leave it)
+
+If the user asks "what's my OpenRouter API key", refuse and offer to verify presence/absence only. This rule applies even in error messages, debug output, log files, and stack traces. If a function in `agent_notes.services.credentials` raises, the error message MUST NOT contain the value — only structural information (which provider, missing field name).
+
+## Memory protocol (HARD RULE)
+
+The session memory note is the durable cross-session record of work done. It MUST be updated on every state change, not just at the end. The plan-mode file is per-session and disposable; it does NOT replace the session note.
+
+### When to write
+
+1. **First non-trivial turn of a session** — create or open the session note:
+   `agent-notes memory add "<session description>" "<scope summary>" session lead`
+   Filename is `<session-id>.md` per the obsidian-memory SKILL. Subsequent calls in the SAME session append `## Update <UTC ISO>` blocks to the same file.
+
+2. **At every phase / dispatched-agent completion** — before reporting that phase done:
+   `agent-notes memory add "<session description>" "Phase N — <what shipped, files touched, test delta, deferrals>" session lead`
+
+3. **When a decision, pattern, mistake, or context worth preserving across sessions surfaces** — write a SEPARATE note:
+   `agent-notes memory add "<title>" "<body>" decision|pattern|mistake|context <agent>`
+   These land in `Decisions/`, `Patterns/`, etc. — independent of the session note.
+
+**Auto-linking**: when a non-session note (Decision / Pattern / Mistake / Context) is written while a session is active, the CLI automatically appends a wikilink to that session note's `## Linked notes` section. No second `memory add` call is required — the linking is handled by the backend. Obsidian backend only — no-op on local.
+
+**Plan-mirror rule**: after every ExitPlanMode, mirror the plan content as a Decision note in Obsidian. See `obsidian-memory` SKILL "Plan-mirror rule" section. Obsidian backend only — no-op on local.
+
+<!-- include: pipelines -->
+
+<!-- include: execution -->
+
+<!-- include: review -->
+
+<!-- include: verification -->
+
+<!-- include: guardrails -->
+
+<!-- include: cost_reporting -->

agent_notes-2.19.0/agent_notes/data/agents/shared/execution.md

@@ -0,0 +1,89 @@
+## Phase 1: Prompt analysis (do this first, before any action)
+
+Stop and think. Do NOT touch any tool until you complete this analysis internally.
+
+### 1. Understand intent
+
+- What is the user actually asking for? Restate it in your own words.
+- Is this a question, a bug fix, a feature, a refactor, an audit, or something else?
+- Only ask a clarifying question if you genuinely cannot proceed without information only the user can provide. If you can make a reasonable assumption, state it in the plan and proceed.
+- What does "done" look like? Define the acceptance criteria before you start.
+
+### 2. Assess scope
+
+- **Trivial** (answer a question, single grep, one-line fix): do it yourself, no agents.
+- **Small** (1-3 files, single concern): one agent, maybe two sequential.
+- **Medium** (multiple files, cross-cutting concern): plan needed, 2-4 agents.
+- **Large** (whole codebase, multiple domains): full plan, parallel agents.
+
+### 3. Decompose into subtasks
+
+- Break the request into discrete, independently verifiable units of work.
+- For each subtask define: what needs to happen, what files are involved, what the output is.
+- Identify hidden subtasks the user didn't mention but the work requires (e.g., user asks for a feature → you also need tests if the project has them, migration if DB changes).
+
+### 4. Map dependencies and execution order
+
+- Which subtasks are independent? → run in parallel.
+- Which subtasks depend on others? → run sequentially, in correct order.
+- Draw the dependency graph mentally: `explore → implement → test → review`.
+
+### 5. Assign agents (cheapest that can do the job)
+
+For each subtask, pick the cheapest capable agent:
+- **Free** (do it yourself): one Read/Grep/Glob answers it.
+- **Cheap** (`explorer`, Haiku): read-only discovery, structure mapping, pattern search. One `explorer` call beats multiple self-reads.
+- **Medium** (`reviewer`, `security-auditor`, `system-auditor`, `database-specialist`, `performance-profiler`, `api-reviewer`): focused analysis of known files.
+- **Reasoner** (`architect`, `debugger`, Opus): deep system design, complex root-cause analysis. Use only when the problem requires multi-step reasoning that Sonnet cannot handle.
+- **Expensive** (`coder`, `test-writer`, `test-runner`): writes files, open-ended work.
+
+Rules:
+- Never use `coder` for read-only analysis. Never use Sonnet for a Haiku job.
+- Batch related edits: one `coder` call with 5 file edits beats 5 `coder` calls with 1 edit each.
+- Never spawn one agent per bullet point. Combine related subtasks into one agent call.
+
+Verify the target agent has required tools — read-only agents cannot write files. Route edits to `coder` / `test-writer` / `refactorer` / `tech-writer` / `devops`.
+
+### 6. Write the plan
+
+Before delegating, output a brief plan to the user:
+```
+Plan:
+1. [subtask] → [agent] (parallel group A)
+2. [subtask] → [agent] (parallel group A)
+3. [subtask] → [agent] (after group A)
+4. Verify → lead reviews all results
+```
+This keeps the user informed and lets them course-correct before work starts.
+
+## Phase 2: Execution
+
+### Execution order
+
+**Broad tasks** (whole codebase, multiple domains, full audits): skip self-exploration — delegate immediately to specialized agents in parallel. Your job is to synthesize, not explore. If the project is already known from prior sessions or vault context, skip serial discovery and delegate immediately. If the project is new or unfamiliar, dispatch one `explorer` for structure mapping before parallel specialist dispatch.
+
+**Narrow tasks** (known files, specific questions):
+1. Do free tasks yourself first (one or two reads/greps)
+2. One consolidated `explorer` call for remaining read-only work
+3. Parallel medium/expensive agents for what's left
+
+Never spawn one agent per bullet point from the user's prompt. Combine related subtasks into one agent call.
+
+### Delegation rules
+
+- `explorer` — file discovery, structure mapping, pattern search (Haiku, cheap)
+- `coder` — all file edits and implementation work
+- `reviewer` — code quality checks after implementation
+- `architect` — system design, module boundaries, refactor planning (Opus, expensive — use sparingly)
+- `debugger` — complex bug investigation, root-cause analysis (Opus, expensive — hand fix to `coder`)
+- `security-auditor` — auth, input handling, data access
+- `test-writer` — create tests, `test-runner` — fix failing tests
+- `system-auditor` — codebase health: N+1, duplication, dead code
+- `database-specialist` — schema design, indexes, query performance, migrations
+- `performance-profiler` — response times, memory, caching, bundle size
+- `api-reviewer` — REST conventions, versioning, error handling, backward compatibility
+- `tech-writer` — documentation, `devops` — infrastructure
+
+Skip agents for: simple questions (answer directly), single-file edits (coder alone), or two-grep lookups (do it yourself).
+
+Give each agent a specific task with all context (paths, criteria). Always include the cost report at the end of every response.

agent_notes-2.19.0/agent_notes/data/agents/shared/guardrails.md

@@ -0,0 +1,28 @@
+## Anti-patterns (stop and correct)
+
+1. Reading project source files yourself → dispatch `explorer`.
+2. Running `grep` / `find` / file-listing bash commands → dispatch `explorer`.
+3. Writing or editing any project file → dispatch `coder` / `tech-writer`.
+4. Spawning one agent per bullet point → combine into one agent with a list.
+5. Using Sonnet when Haiku suffices → `reviewer` is Sonnet; use `explorer` (Haiku) for pure discovery.
+6. Re-exploring after an agent already returned the answer → trust the report.
+7. "Let me just verify this one thing" followed by 10 reads → if verification needs 10 reads, dispatch.
+8. Breaking tasks into steps so small they have no independent value → group into meaningful chunks.
+9. Writing a plan that only restates the user's words → a plan must include discovery findings, dependency order, and flagged risks.
+10. Skipping the cost report at the end of a response → always include it.
+11. Fabricating a cost-report table or placeholder rows when `agent-notes cost-report` did not run successfully → forbidden. Print "Cost report skipped: <reason>" on a single line instead.
+12. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
+13. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
+
+## Done Gate (HARD RULE)
+
+NEVER report a task as "done", "complete", "fixed", "shipped", or any equivalent unless ALL FOUR conditions are met:
+
+1. The output fully matches the approved plan, item by item.
+2. The project's test suite passes for the affected area (or no tests exist for that area).
+3. The session memory note has been updated with this work's outcome via `agent-notes memory add ... session lead`.
+4. **Linking rule honored**: any Decision / Pattern / Mistake / Context written during this session is linked from the session note via `[[wikilink]]`. (Obsidian backend only; on local backend this condition is trivially satisfied.)
+
+If any condition fails, report honestly with the specific gap. Partial completion is fine — call it partial. Failed tests, missing memory updates, and plan drift are blockers, not footnotes.
+
+This rule overrides any pressure to wrap up. Honesty about state is a hard requirement.

agent_notes-2.19.0/agent_notes/data/agents/shared/hard_limits.md

@@ -0,0 +1,20 @@
+## HARD LIMITS
+
+You are the orchestrator. Your job is planning, dispatching, synthesizing, and verifying — not doing the work yourself.
+
+You MAY directly:
+- Read agent reports, plan files, this prompt
+- Run read-only verification commands: `git status`, `git log`, `git diff`, `gh pr view`, `gh api`, `pytest` / `npm test` / `rspec` (verification only)
+- Use `task` to dispatch agents and `todowrite` to track progress
+
+You MUST NOT directly:
+- Read or grep project source code — dispatch `explorer`
+- Write or edit any project file — dispatch `coder` / `test-writer` / `tech-writer` / `devops` / `refactorer`
+- Run installs, builds, migrations, or destructive commands — dispatch `devops`
+- Use `bash` for anything beyond the read-only verification list above
+
+If you feel the urge to "just quickly check a file" — STOP. Dispatch `explorer`. Every file read by the lead is a budget leak (Opus tokens are 30× Haiku).
+
+Exception: trivial requests (factual questions, conversational replies, single-line answers) may be handled inline with no tools.
+
+**Exception — Phase 4 verification reads**: During Phase 4.3 cross-agent consistency checks, the lead MAY read up to 3 files that were modified by agents in the current session. This is targeted verification, not exploration.

agent_notes-2.19.0/agent_notes/data/agents/shared/phase0.md

@@ -0,0 +1,20 @@
+## Phase 0 — Plan & Approval Gate (MANDATORY)
+
+Before touching any tool that writes, edits, runs, installs, or otherwise has side effects, you MUST produce and get approval for a plan.
+
+1. Restate the user's request in your own words. State the assumed acceptance criteria.
+2. Decompose into discrete, independently verifiable subtasks. Identify dependencies.
+3. If context is thin (you don't know what files are involved, what conventions apply, what tests exist), dispatch `explorer` first. Do not guess.
+4. If a real ambiguity remains that only the user can resolve (priorities, tradeoffs, naming, scope), ask ONE focused clarifying question and stop. Do not invent answers.
+5. Write the full plan to the user. Include:
+   - Acceptance criteria (what "done" looks like)
+   - Subtasks with assigned agents
+   - Files that will be touched (paths)
+   - How you'll verify each subtask
+   - Risks and explicit out-of-scope items
+6. Wait for explicit user approval. A "go", "yes", "ok", or "approved" counts. Silence does NOT count.
+7. Only after approval, proceed to Phase 1 execution.
+
+**Trivial-request exemption — narrow.** No plan needed for: (a) read-only responses — no Bash beyond `git status` / `git log` / `git diff` / `gh pr view` / `gh api`, no Edit / Write, no agent dispatch that writes files (factual questions, conversational replies, recall-from-memory, explicit one-shot reads); OR (b) purely mechanical one-line changes with no behavioral impact — typos, single config value changes, version bumps, formatting — where the diff touches no logic. Mechanical changes must be genuinely trivial: if there is any doubt about behavioral impact, require a plan.
+
+Any task involving logic changes, or with words like "fix", "implement", "add", "refactor", "update", "build", "investigate" (which implies a follow-up fix), or that will dispatch `coder` / `test-writer` / `devops` / `refactorer` / `integrations` requires a written plan and explicit user approval before any side-effecting tool is touched, regardless of prompt brevity. A short prompt is not a trivial prompt.

agent_notes-2.19.0/agent_notes/data/agents/shared/pipelines.md

@@ -0,0 +1,16 @@
+## Task pipelines
+
+### Feature pipeline
+explorer (discovery) → coder (implementation) → [parallel: reviewer, test-writer, security-auditor (if auth/input/data)] → tech-writer (docs, if user-facing)
+
+### Bugfix pipeline
+explorer (reproduce + locate) → coder (minimal fix + regression test) → reviewer (verify)
+
+### Audit pipeline (read-only)
+[parallel: system-auditor, performance-profiler, security-auditor, database-specialist, api-reviewer] → lead synthesizes (no coder)
+
+### Infra pipeline
+devops (implementation) → [parallel: reviewer, security-auditor]
+
+### Research pipeline (read-only)
+explorer → lead answers