agent-notes 2.23.0__tar.gz → 2.24.0__tar.gz

{agent_notes-2.23.0 → agent_notes-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.23.0
+Version: 2.24.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -42,7 +42,7 @@ agent-notes doctor
 
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 42+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 47+ on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -267,7 +267,7 @@ Implements Karpathy's LLM Wiki pattern (v1). Auto-creates a folder per project (
 
 - **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
+- **Lint** — Health-check for contradictions, stale pages, data gaps, orphan pages, missing cross-references
 
 **Commands:**
 ```bash
@@ -312,7 +312,7 @@ The installed `CLAUDE.md` already points agents to your vault. At the start of a
 <details>
 <summary>Skills</summary>
 
-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/`.
+47+ 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.
 
@@ -342,6 +342,11 @@ Load the docker-compose skill for multi-service setup
 - `/debugging-protocol` — Phase 1 rewritten as "build a feedback loop first" with 9 strategies
 - `/improve-codebase-architecture` — Deletion test to find shallow modules; surfaces deepening opportunities
 - `/zoom-out` — Quick orientation map of an unfamiliar code area
+- `/handoff` — Compact conversation into a handoff document for a fresh agent session
+- `/to-prd` — Synthesize conversation into a Product Requirements Document
+- `/to-issues` — Break a plan/PRD into vertical-slice issues (HITL/AFK classification)
+- `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
+- `/write-a-skill` — Meta-skill for creating new skills with proper structure
 
 </details>
 

{agent_notes-2.23.0 → agent_notes-2.24.0}/README.md

@@ -12,7 +12,7 @@ agent-notes doctor
 
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 42+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 47+ on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -237,7 +237,7 @@ Implements Karpathy's LLM Wiki pattern (v1). Auto-creates a folder per project (
 
 - **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
+- **Lint** — Health-check for contradictions, stale pages, data gaps, orphan pages, missing cross-references
 
 **Commands:**
 ```bash
@@ -282,7 +282,7 @@ The installed `CLAUDE.md` already points agents to your vault. At the start of a
 <details>
 <summary>Skills</summary>
 
-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/`.
+47+ 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.
 
@@ -312,6 +312,11 @@ Load the docker-compose skill for multi-service setup
 - `/debugging-protocol` — Phase 1 rewritten as "build a feedback loop first" with 9 strategies
 - `/improve-codebase-architecture` — Deletion test to find shallow modules; surfaces deepening opportunities
 - `/zoom-out` — Quick orientation map of an unfamiliar code area
+- `/handoff` — Compact conversation into a handoff document for a fresh agent session
+- `/to-prd` — Synthesize conversation into a Product Requirements Document
+- `/to-issues` — Break a plan/PRD into vertical-slice issues (HITL/AFK classification)
+- `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
+- `/write-a-skill` — Meta-skill for creating new skills with proper structure
 
 </details>
 

agent_notes-2.24.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.24.0

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/cli.py

@@ -275,6 +275,12 @@ def main():
         help="Memory action")
     p_memory.add_argument("name", nargs="?", help="Agent name / note title (for show/reset/add)")
     p_memory.add_argument("extra", nargs="*", help="Additional args (for add: body [type] [agent] [project])")
+    p_memory.add_argument("--description", default="", help="One-liner description for index display")
+
+    # hook
+    p_hook = subparsers.add_parser("hook", help="Claude Code hook integrations")
+    p_hook.add_argument("subaction", choices=["memory-bridge"],
+        help="Hook to run")
 
     # cost-report
     p_cost_report = subparsers.add_parser("cost-report", help="Report token usage and cost for the current AI session")
@@ -335,10 +341,13 @@ def main():
         regenerate(scope=args.scope, cli=args.cli, local=args.local)
     elif args.command == "memory":
         from .commands.memory import memory
-        memory(args.action, args.name, getattr(args, "extra", None))
+        memory(args.action, args.name, getattr(args, "extra", None), description=getattr(args, "description", ""))
     elif args.command == "config":
         from .commands.config import config
         config(action=args.action, args=getattr(args, "extra", None) or [], cli_filter=args.cli)
+    elif args.command == "hook":
+        from .commands.hook import hook
+        hook(args.subaction)
     elif args.command == "cost-report":
         # Rebuild sys.argv slice so cost_report.main() can parse it normally
         argv = []

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/commands/doctor.py

@@ -61,6 +61,17 @@ def _check_session_hook(scope: str, issues: list) -> None:
             "SessionStart hook not found — run: agent-notes install to re-add the hook",
         ))
 
+    from ..constants import Hooks
+    from ..services.state_store import load_state
+    state = load_state()
+    if state and state.memory.backend in ("obsidian", "wiki"):
+        if not has_hook(settings_path, "SessionStart", Hooks.MEMORY_BRIDGE):
+            issues.append(Issue(
+                "missing_hook",
+                str(settings_path),
+                "memory-bridge SessionStart hook not found — run: agent-notes install to re-add",
+            ))
+
 
 def check_version_drift(scope: str, issues: list, fix_actions: list) -> None:
     """Check if the installed package version matches the current running version."""

agent_notes-2.24.0/agent_notes/commands/hook.py

@@ -0,0 +1,42 @@
+"""Hook command - Claude Code hook integrations."""
+
+from pathlib import Path
+
+
+def hook(subaction: str) -> None:
+    """Handle hook subactions."""
+    if subaction == "memory-bridge":
+        _memory_bridge()
+
+
+def _memory_bridge() -> None:
+    """SessionStart hook that prints the agent-notes memory index.
+
+    Unconditionally loads and prints the memory index so it is visible in
+    context at the start of every Claude Code session.
+    """
+    try:
+        from .memory._common import _load_memory_config
+        from ..constants import Obsidian, Wiki
+
+        backend, path = _load_memory_config()
+
+        if backend == "none" or backend is None:
+            return
+
+        if backend == "obsidian":
+            index_file = Path(path) / Obsidian.INDEX
+        elif backend == "wiki":
+            index_file = Path(path) / Wiki.DIR / Wiki.INDEX
+        else:
+            # local and any unknown backends: use Index.md at root
+            index_file = Path(path) / "Index.md"
+
+        if not index_file.exists():
+            return
+
+        content = index_file.read_text(encoding="utf-8")
+        print("<!-- agent-notes memory index (auto-loaded) -->")
+        print(content)
+    except Exception:
+        return

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/commands/memory/__init__.py

@@ -8,7 +8,6 @@ from .vault import do_vault, do_init, do_index
 from .notes import do_add, do_list, do_show, do_size
 from .transfer import do_export, do_import
 from .wiki import do_ingest, do_query, do_lint, do_scan_raw
-from .migrate import do_migrate
 from .reset import do_reset
 
 
@@ -47,7 +46,7 @@ Examples:
     print(help_text)
 
 
-def memory(action: str = "list", name: Optional[str] = None, extra: Optional[list] = None) -> None:
+def memory(action: str = "list", name: Optional[str] = None, extra: Optional[list] = None, description: str = "") -> None:
     """Manage agent memory."""
     if action == "list":
         do_list()
@@ -66,7 +65,7 @@ def memory(action: str = "list", name: Optional[str] = None, extra: Optional[lis
         note_type = extra[1] if extra and len(extra) > 1 else "context"
         agent = extra[2] if extra and len(extra) > 2 else ""
         project = extra[3] if extra and len(extra) > 3 else ""
-        do_add(name, body, note_type=note_type, agent=agent, project=project)
+        do_add(name, body, note_type=note_type, agent=agent, project=project, description=description)
     elif action == "size":
         do_size()
     elif action == "show":
@@ -80,8 +79,6 @@ def memory(action: str = "list", name: Optional[str] = None, extra: Optional[lis
         do_export()
     elif action == "import":
         do_import()
-    elif action == "migrate":
-        do_migrate()
     elif action == "ingest":
         if not name:
             do_scan_raw()

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/commands/memory/notes.py

@@ -7,7 +7,7 @@ from . import _common
 from ...config import MEMORY_DIR, Color
 
 
-def do_add(title: str, body: str, note_type: str = "context", agent: str = "", project: str = "", tags: Optional[list] = None) -> None:
+def do_add(title: str, body: str, note_type: str = "context", agent: str = "", project: str = "", tags: Optional[list] = None, description: str = "") -> None:
     """Add a note to memory (obsidian or wiki storage)."""
     backend, path = _common._load_memory_config()
     if backend == "none":
@@ -40,6 +40,7 @@ def do_add(title: str, body: str, note_type: str = "context", agent: str = "", p
             note_type=note_type,
             agent=agent,
             project=project,
+            description=description,
             tags=tags or [],
         )
         print(f"{Color.GREEN}Note saved: {note_path}{Color.NC}")

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/constants.py

@@ -20,5 +20,13 @@ class Wiki:
 class Obsidian:
     """Obsidian backend folder structure constants."""
     INDEX = "Index.md"
-    SUBFOLDER = "notes"
-    CATEGORIES = ["Patterns", "Decisions", "Mistakes", "Context", "Sessions"]
+    SUBFOLDER = "projects"
+    CATEGORIES = ["Patterns", "Decisions", "Mistakes", "Context", "Feedback", "Sessions"]
+    INDEX_SECTIONS = ["Decisions", "Patterns", "Context", "Mistakes", "Feedback"]
+    SESSION_CAP = 5
+
+
+class Hooks:
+    """Hook command strings used in Claude Code settings.json."""
+    MEMORY_BRIDGE = "agent-notes hook memory-bridge"
+    COST_REPORT = "agent-notes cost-report"

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/data/agents/agents.yaml

@@ -317,7 +317,7 @@ agents:
 
   debugger:
     description: "Investigates bugs. Reproduces, isolates the failure, identifies root cause. Does not apply fixes — hands off to coder. Read-only on source. Triggers: bug, broken, error, crash, regression, flaky, root cause, why does, investigate."
-    role: reasoner
+    role: worker
     mode: subagent
     color: orange
     effort: high

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/data/agents/shared/execution.md

@@ -34,7 +34,7 @@ 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.
+- **Reasoner** (`architect`, 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:
@@ -75,7 +75,7 @@ Never spawn one agent per bullet point from the user's prompt. Combine related s
 - `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`)
+- `debugger` — bug investigation, root-cause analysis (Sonnet — 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
@@ -87,3 +87,7 @@ Never spawn one agent per bullet point from the user's prompt. Combine related s
 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.
+
+### Permission pre-check (HARD RULE)
+
+Before dispatching writing agents (`coder`, `test-writer`, `devops`, `refactorer`, `tech-writer`) in background: confirm Write/Edit/Bash permissions are granted. Background agents cannot surface permission prompts — they fail silently. Prefer foreground for writing agents, or ask the user to pre-approve. If a background agent fails on permissions, explain the blocker — do NOT write files yourself.

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/data/agents/shared/hard_limits.md

@@ -18,3 +18,11 @@ If you feel the urge to "just quickly check a file" — STOP. Dispatch `explorer
 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.
+
+## Output discipline
+
+- Responses: 1-3 sentences per status update. State results and decisions, not process.
+- Plans: structured bullet lists with file paths. No prose paragraphs.
+- Agent briefings: context + task + acceptance criteria. No commentary or justification.
+- Never narrate internal deliberation — report outcomes only.
+- Cost table: once at end of response, never mid-response.

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/data/global-claude.md

@@ -8,7 +8,7 @@ You are a team lead that plans and coordinates work across specialized agents.
 
 <!-- include: hard_limits -->
 
-### Credentials handling (HARD RULE)
+## 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:
 
@@ -62,13 +62,6 @@ After receiving output from any agent, scan for a `## Discoveries` section. For
 
 <!-- include: guardrails -->
 
-## Coding philosophy
-
-- Read existing code before writing new code. Match project patterns.
-- Minimal changes: only what was requested. Do not refactor beyond scope.
-- Fix root causes, not symptoms.
-- One approach, commit to it. Course-correct only on new evidence.
-
 ## Behavior
 
 - Investigate before answering. Never speculate about code you haven't read.
@@ -76,13 +69,6 @@ After receiving output from any agent, scan for a `## Discoveries` section. For
 - No comments or docs on code you didn't change.
 - When the task is genuinely unclear and you cannot make a reasonable assumption, ask one clarifying question instead of guessing.
 
-## Safety
-
-- Confirm before: `git push --force`, `rm -rf`, `DROP TABLE`, branch deletion.
-- Never commit: `.env`, `*.pem`, credentials, API keys, secrets.
-- Never bypass: `--no-verify`, `--force` without explicit user request.
-- Never force-push to main/master.
-
 ## Commits
 
 - Load the `git` skill when asked to commit and follow its workflow.

agent_notes-2.24.0/agent_notes/data/skills/handoff/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: handoff
+description: "Compact the current conversation into a handoff document for another agent to pick up. Use when the session is getting long, context is degrading, or you need to transfer work to a fresh session."
+group: process
+argument-hint: "What will the next session be used for?"
+---
+
+# Handoff
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to a path produced by `mktemp -t handoff-XXXXXX.md` (read the file before you write to it).
+
+## What to include
+
+1. **Goal**: What the user is trying to accomplish (1-2 sentences)
+2. **Current state**: What has been done so far, what works, what doesn't
+3. **Next steps**: What the next session should focus on
+4. **Key decisions**: Decisions made during this session that the next agent needs to know
+5. **Relevant files**: Paths to files that were modified or are relevant
+6. **Skills to use**: Suggest which skills the next session should invoke
+
+## Rules
+
+- Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+- Keep it concise — the handoff should fit in a single context window read.
+- If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+- If using the obsidian memory backend, also save a session note via `agent-notes memory add` before creating the handoff.

agent_notes-2.24.0/agent_notes/data/skills/migrate-memory/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: migrate-memory
+description: "Reconcile the Obsidian vault or Wiki knowledge base to the latest canonical format. Use after upgrading agent-notes or when vault structure looks outdated or inconsistent."
+group: process
+requires_memory: obsidian, wiki
+---
+
+# Migrate Memory
+
+Reconcile the memory store to the latest format. This skill transforms any state — old layout, missing fields, wrong folder names — into the canonical structure. Works for both Obsidian and Wiki backends.
+
+## When to use
+
+- After upgrading agent-notes
+- When the user says "migrate memory" or `/migrate-memory`
+- When vault structure looks outdated or inconsistent
+
+## Step 1: Detect backend
+
+```bash
+agent-notes memory vault
+```
+
+This returns the backend type and vault path. Branch to the appropriate section below.
+
+---
+
+## Obsidian backend
+
+### Reconcile folder structure
+
+The canonical vault layout is:
+
+```
+<vault-root>/projects/<project-name>/
+├── Patterns/
+├── Decisions/
+├── Mistakes/
+├── Context/
+├── Feedback/
+├── Sessions/
+└── Index.md
+```
+
+Reconciliation rules:
+- If the project lives under a `notes/` parent and `projects/` does NOT exist → rename `notes/` → `projects/`
+- If BOTH `notes/` and `projects/` exist → merge: move all contents from `notes/<project>/` into `projects/<project>/`, skip files that already exist in the destination, then delete the empty `notes/` directory
+- At the end: only `projects/` must exist. `notes/` must be gone.
+- Create any missing category folders: Patterns, Decisions, Mistakes, Context, Feedback, Sessions
+- If `Index.md` is missing, create it with the standard header
+
+### Reconcile note frontmatter
+
+Every `.md` file inside a category folder (NOT Index.md) must have this frontmatter:
+
+```yaml
+---
+created_at: <ISO 8601 UTC, "Z" suffix>
+type: <pattern|decision|mistake|context|session|feedback>
+description: "<one-line summary optimized for index routing>"
+session: <YYYY-MM-DD_session-id>   # absent on session notes themselves
+agent: <agent-name>                 # optional
+---
+```
+
+Reconciliation rules:
+- `created_at` — if missing, derive from filename date prefix (`YYYY-MM-DD_slug.md` → that date at midnight UTC). If no date in filename, use file modification time
+- `type` — if missing, derive from parent folder name (lowercase). `Patterns/` → `pattern`, etc.
+- `description` — if missing, derive from the first non-heading, non-empty line of the body. Cap at 100 characters, break at word boundary. If no suitable line, use the filename slug with hyphens replaced by spaces
+- `session` — leave as-is if present; do not add if absent
+- `agent` — leave as-is if present; do not add if absent
+- Do NOT remove extra frontmatter fields — only add/fix the required ones
+
+### Reconcile filenames
+
+Canonical filename format: `YYYY-MM-DD_<slug>.md`
+- `<slug>` is kebab-case, derived from the note title
+- If a file doesn't match this pattern, rename it to match (derive date from `created_at` frontmatter)
+- On collision, append `_HHMMSS` before `.md`
+
+### Regenerate Index.md
+
+After all notes are reconciled, regenerate `Index.md`:
+- List notes grouped by section in this order: Decisions, Patterns, Context, Mistakes, Feedback
+- Within each section, newest first (by `created_at`)
+- Each entry: `- [[relative-path|title]] — description`
+- Sessions section: last 5 sessions only
+
+---
+
+## Wiki backend
+
+### Reconcile folder structure
+
+The canonical wiki layout is:
+
+```
+<vault-root>/knowledge/
+├── .obsidianignore
+├── raw/                    # immutable source archive
+└── wiki/
+    ├── index.md
+    ├── log.md
+    ├── sources/
+    ├── concepts/
+    ├── entities/
+    ├── synthesis/
+    └── sessions/
+```
+
+Reconciliation rules:
+- Create any missing folders: `raw/`, `wiki/`, and all page type folders (`sources/`, `concepts/`, `entities/`, `synthesis/`, `sessions/`)
+- If `.obsidianignore` is missing, create it with content: `raw/`
+- If `wiki/index.md` is missing, create it with the standard header
+- If `wiki/log.md` is missing, create it empty
+
+### Reconcile wiki page frontmatter
+
+Every `.md` file inside `wiki/sources/`, `wiki/concepts/`, `wiki/entities/`, `wiki/synthesis/`, and `wiki/sessions/` must have this frontmatter:
+
+```yaml
+---
+created_at: <ISO 8601 UTC, "Z" suffix>
+updated_at: <ISO 8601 UTC, "Z" suffix>
+type: <sources|concepts|entities|synthesis|sessions>
+tags: ["tag1", "tag2"]         # optional
+aliases: ["alias1"]            # optional
+sources: ["raw/source-file.md"] # optional
+agent: <agent-name>            # optional
+project: <project-name>        # optional
+confidence: "<high|medium|low>" # optional
+---
+```
+
+Reconciliation rules:
+- `created_at` — if missing, use file modification time in ISO 8601 UTC
+- `updated_at` — if missing, set equal to `created_at`
+- `type` — if missing, derive from parent folder name. `concepts/` → `concepts`, etc.
+- `tags`, `aliases`, `sources`, `agent`, `project`, `confidence` — leave as-is if present; do not add if absent
+- Do NOT remove extra frontmatter fields — only add/fix the required ones
+
+### Reconcile wiki filenames
+
+Canonical filename: `<kebab-case-slug>.md` (no date prefix for wiki pages)
+- Slug derived from the H1 heading or title
+- Report any non-compliant filenames
+
+### Regenerate wiki/index.md
+
+After all pages are reconciled, regenerate `wiki/index.md`:
+- Group by page type in this order: Sources, Concepts, Entities, Synthesis, Sessions
+- Each section as a markdown table: `| Page | Tags | Updated |`
+- Each row: `| [[slug]] — description | #tag1 #tag2 | YYYY-MM-DD |`
+- Description: first sentence of body content, capped at 80 characters
+
+---
+
+## Report
+
+Print a summary of changes made:
+- Backend: obsidian or wiki
+- Folders: created / renamed / merged / removed
+- Notes with updated frontmatter (count)
+- Notes already compliant (count)
+- Filenames: all OK or list non-compliant
+- Index regenerated: yes/no
+
+## Constraints
+
+- Never delete individual notes. Only add/fix metadata, rename, and merge folders.
+- Preserve note body content exactly — only touch frontmatter and filenames.
+- When merging folders, skip files that already exist at the destination (do not overwrite).

{agent_notes-2.23.0 → agent_notes-2.24.0}/agent_notes/data/skills/obsidian-memory/SKILL.md

@@ -107,7 +107,7 @@ agent-notes memory vault             # confirm storage and path
 
 The vault is structured as:
 ```
-vault/agent-notes/notes/
+vault/agent-notes/projects/
 ├── <project-name>/
 │   ├── Patterns/     — reusable solutions        YYYY-MM-DD_<slug>.md
 │   ├── Decisions/    — architectural choices     YYYY-MM-DD_<slug>.md

agent_notes-2.24.0/agent_notes/data/skills/prototype/LOGIC.md

@@ -0,0 +1,47 @@
+# Logic Prototype
+
+A tiny interactive terminal app to drive a state model by hand. Use when the question is about business logic, state transitions, or data shape.
+
+## When this is the right shape
+
+- "Does this state machine handle the edge case where X then Y?"
+- "Does this data model let me represent the case where...?"
+- "I want to feel out what the API should look like before writing it."
+
+If the question is visual → use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+Write down the state model and question being prototyped. One paragraph at the top of the file.
+
+### 2. Pick the language
+Use the host project's language. Match existing tooling conventions.
+
+### 3. Isolate logic in a portable module
+Put logic behind a small, pure interface that could be lifted into the real codebase:
+- **Pure reducer** — `(state, action) => state` for discrete events
+- **State machine** — explicit states and transitions
+- **Pure functions** over a plain data type
+- **Class/module** with clear method surface for genuine ongoing state
+
+Keep it pure: no I/O, no terminal code. The TUI imports it; nothing flows back.
+
+### 4. Build the smallest TUI
+On every tick, clear screen and re-render:
+1. **Current state** — pretty-printed, bold field names, dim less important context
+2. **Keyboard shortcuts** — listed at bottom: `[a] add user  [d] delete user  [q] quit`
+
+Loop: initialize → read keystroke → dispatch → re-render → repeat until quit.
+
+### 5. One command to run
+Add a script to the project's task runner.
+
+### 6. Capture the answer
+When done, record what it taught in NOTES.md, commit message, or ADR. The logic module is worth keeping; the TUI shell gets deleted.
+
+## Anti-patterns
+- Don't add tests — a prototype that needs tests is no longer a prototype
+- Don't wire to the real database — use in-memory
+- Don't generalise — answer one question
+- Don't blur logic and TUI — keep the TUI as a thin shell over a pure module

agent_notes-2.24.0/agent_notes/data/skills/prototype/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: prototype
+description: "Build a throwaway prototype to answer a design question. Routes between a terminal app for logic/state questions or multiple UI variations for visual questions. Use when user wants to prototype, sanity-check a data model, mock up UI, or says 'prototype this'."
+group: process
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app.
+- **"What should this look like?"** → [UI.md](UI.md). Generate radically different UI variations switchable via URL param.
+
+If ambiguous, default to whichever matches the surrounding code (backend module → logic; page/component → UI).
+
+## Rules for both branches
+
+1. **Throwaway and clearly marked.** Locate near where it will be used but name it obviously.
+2. **One command to run.** Use the project's existing task runner.
+3. **No persistence by default.** State lives in memory.
+4. **Skip the polish.** No tests, no error handling beyond runnable, no abstractions.
+5. **Surface the state.** After every action, print or render the full relevant state.
+6. **Delete or absorb when done.** Either delete or fold the validated decision into real code.
+
+## When done
+
+Capture the answer somewhere durable (commit message, ADR, issue, or NOTES.md next to the prototype). The answer is the only thing worth keeping.