agent-notes 2.0.4__tar.gz

agent_notes-2.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rubakas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_notes-2.0.4/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: agent-notes
+Version: 2.0.4
+Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
+Author: Eugene Naumov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rubakas/agent-notes
+Project-URL: Repository, https://github.com/rubakas/agent-notes
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file

agent_notes-2.0.4/README.md

@@ -0,0 +1,493 @@
+# agent-notes
+
+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 plans and reasons, Sonnet executes, and Haiku explores.
+
+## Quick Start
+
+```bash
+pip install agent-notes
+agent-notes install    # interactive wizard guides you through setup
+agent-notes doctor
+```
+
+Update anytime with `pip install --upgrade agent-notes && agent-notes install`.
+
+## What's Included
+
+| Component | Description |
+|-----------|-------------|
+| **Skills** | 35 on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
+| **Agents** | 18 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 |
+
+## CLI Reference
+
+```
+agent-notes <command> [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `install [--local] [--copy]` | Interactive wizard or direct install |
+| `uninstall [--local]` | Remove installed components |
+| `update` | Pull latest, rebuild, reinstall |
+| `doctor [--local] [--fix]` | Check installation health |
+| `info` | Show status and component counts |
+| `list [clis\|models\|roles\|agents\|skills\|rules\|all]` | List engine components or installed |
+| `set role <role> <model> [--cli <cli>]` | Change model for a role (Phase 10+) |
+| `regenerate [--cli <cli>]` | Rebuild files from state.json (Phase 10+) |
+| `validate` | Lint source configuration files |
+| `memory [list\|size\|show\|reset\|export\|import] [name]` | Manage agent memory |
+
+### Supported platforms
+
+| Platform | Install target | Config format |
+|----------|---------------|---------------|
+| **Claude Code** | `~/.claude/` | YAML frontmatter + Markdown prompts |
+| **OpenCode** | `~/.config/opencode/` | YAML frontmatter + Markdown prompts |
+| **GitHub Copilot** | `~/.github/` | `copilot-instructions.md` |
+
+### Examples
+
+```bash
+# Interactive install (recommended)
+agent-notes install
+
+# Example wizard session:
+#
+#   Which CLI do you use?
+#     1) [*] Claude Code
+#     2) [*] OpenCode
+#   Enter numbers to toggle (comma-separated), or press enter for defaults.
+#   Choice:                          ← press enter to keep both
+#
+#   Step 2/7: Configure model roles
+#   Which models should each role use?  (claude)
+#
+#     orchestrator  [claude-opus-4-7]    Plans, delegates, synthesizes
+#     reasoner      [claude-opus-4-7]    Complex reasoning, architecture
+#     worker        [claude-sonnet-4-6]  Implements, writes, edits
+#     scout         [claude-haiku-4-5]   Fast search and exploration
+#
+#   Enter role=model pairs to change, or press enter to keep defaults.
+#   Choice:                          ← press enter to keep defaults
+#
+#   Where to install?
+#     1) * Global (~/.claude, ~/.config/opencode)
+#     2)   Local (current project)
+#   Choice [1]:                      ← press enter for global
+#
+#   How to install?
+#     1) * Symlink (auto-updates when source changes)
+#     2)   Copy (standalone, allows local customization)
+#   Choice [1]:                      ← press enter for symlink
+#
+#   Which skills to include?
+#     1) [*] Rails — models, controllers, views, routes, testing (24 skills)
+#     2) [*] Docker — Dockerfile, Compose patterns (4 skills)
+#     3) [*] Kamal — deployment with Kamal (1 skill)
+#     4) [*] Git — commit workflow, conventional commits (1 skill)
+#     5) [*] Process — TDD, refactoring, debugging, planning (5 skills)
+#   Choice:                          ← press enter for all
+#
+#   Ready to install:
+#     CLI:      Claude Code + OpenCode
+#     Scope:    Global (~/.claude, ~/.config/opencode)
+#     Mode:     Symlink
+#     Skills:   Rails (24), Docker (4), Kamal (1), Git (1), Process (5)
+#     Agents:   18 (Claude Code) + 19 (OpenCode)
+#     Config:   CLAUDE.md, AGENTS.md
+#     Rules:    2
+#   Proceed? [Y/n]: Y
+
+# Direct install (scripted, no wizard)
+agent-notes install --local
+agent-notes install --local --copy
+
+# Check health and fix issues
+agent-notes doctor --fix
+
+# Manage agent memory
+agent-notes memory list
+agent-notes memory vault          # show current backend and path
+agent-notes memory index          # regenerate Index.md
+agent-notes memory add "Rails enum prefix" \
+  "Always use _prefix: true to avoid method name collisions" \
+  pattern coder
+```
+
+## Agent Team
+
+Specialized subagents with hierarchical model strategy: **Opus 4.7 decides, Sonnet 4 executes, Haiku 4.5 explores.**
+
+### Agent roster
+
+| Agent | Model | Role |
+|-------|-------|------|
+| **lead** | Opus 4.7 | Plans, delegates, reviews. Orchestrator. |
+| **architect** | Opus 4.7 | System architecture, module boundaries, domain models. Read-only. |
+| **debugger** | Opus 4.7 | Bug investigation: reproduces, isolates, identifies root cause. Read-only. |
+| **coder** | Sonnet 4 | Implements features, fixes bugs, edits files. |
+| **reviewer** | Sonnet 4 | Code quality review. Read-only. |
+| **security-auditor** | Sonnet 4 | Security vulnerability analysis. Read-only. |
+| **test-writer** | Sonnet 4 | Writes tests for any framework. |
+| **test-runner** | Sonnet 4 | Diagnoses and fixes failing tests. |
+| **system-auditor** | Sonnet 4 | Codebase health: duplication, N+1, coupling. Read-only. |
+| **database-specialist** | Sonnet 4 | Schema design, indexes, query performance, migrations. Read-only. |
+| **performance-profiler** | Sonnet 4 | Response times, memory, caching, bundle size. Read-only. |
+| **devops** | Sonnet 4 | Docker, CI/CD, deployment configs. |
+| **devil** | Sonnet 4 | Challenges plans to surface hidden risks. Read-only. |
+| **integrations** | Sonnet 4 | Third-party integrations: OAuth, webhooks, payments. |
+| **refactorer** | Sonnet 4 | 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. |
+
+### 4-phase lead workflow
+
+```
+1. ANALYZE — Lead reviews requirements, explores codebase
+2. EXECUTE — Delegates to specialized agents (parallel execution)
+3. REVIEW — Quality check by reviewer agents
+4. VERIFY — Final validation and integration
+```
+
+### Team diagram
+
+```
+You (human)
+  |
+  +-- Simple task ------> Main session (direct work)
+  |
+  +-- Complex task -----> Lead (Opus 4.7)
+                           +-- Explorer (Haiku 4.5)          quick lookups
+                           +-- Analyst (Haiku 4.5)           requirements analysis
+                           +-- Architect (Opus 4.7)          system design
+                           +-- Coder (Sonnet 4)              implementation
+                           +-- Refactorer (Sonnet 4)         code restructuring
+                           +-- Reviewer (Sonnet 4)           code review
+                           +-- Security (Sonnet 4)           security audit
+                           +-- Devil (Sonnet 4)              risk challenge
+                           +-- Debugger (Opus 4.7)           bug investigation
+                           +-- Test Writer (Sonnet 4)        tests
+                           +-- Test Runner (Sonnet 4)        fix tests
+                           +-- Auditor (Sonnet 4)            codebase health
+                           +-- DB Specialist (Sonnet 4)      schema & queries
+                           +-- Perf Profiler (Sonnet 4)      performance
+                           +-- API Reviewer (Haiku 4.5)      API design
+                           +-- Integrations (Sonnet 4)       third-party APIs
+                           +-- Tech Writer (Haiku 4.5)       documentation
+                           +-- DevOps (Sonnet 4)             infrastructure
+```
+
+## Architecture: YAML-Driven Extensibility
+
+Agent-notes is a **4-layer bounded-context engine** (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full details):
+
+| Layer | Purpose | Example |
+|-------|---------|---------|
+| **Domain** | Pure dataclasses (Agent, Model, Role, State) | `agent_notes/domain/` |
+| **Registries** | YAML loaders from `data/` → domain types | `agent_notes/registries/` |
+| **Services** | Technical concerns (I/O, rendering, state, install) | `agent_notes/services/` |
+| **Commands** | CLI orchestrators (install, doctor, list, etc.) | `agent_notes/commands/` |
+
+**Single source of truth:** `agent_notes/data/` holds all extensible content (CLI, model, role, agent, skill, rule YAMLs).
+
+**Zero Python changes to add:**
+- New CLI: drop `data/cli/cursor.yaml` 
+- New model: drop `data/models/gpt-5.yaml`
+- New role: drop `data/roles/specialist.yaml`
+
+See [docs/ADD_CLI.md](docs/ADD_CLI.md), [docs/ADD_MODEL.md](docs/ADD_MODEL.md), [docs/ADD_ROLE.md](docs/ADD_ROLE.md) for guides.
+
+
+
+## Project Structure
+
+```
+agent-notes/
+├── bin/agent-notes          # CLI wrapper (entry point)
+├── docs/
+│   ├── ADD_CLI.md           # Guide: add a new CLI backend
+│   ├── ADD_MODEL.md         # Guide: add a new AI model
+│   ├── ADD_ROLE.md          # Guide: add a new agent role
+│   ├── CLI_CAPABILITIES.md  # Source of truth for per-CLI features
+│   └── ENGINE_PLAN.md       # Refactor phases and design details
+├── agent_notes/             # Python implementation
+│   ├── __init__.py, cli.py  # Core modules
+│   ├── VERSION              # Package version
+│   ├── data/                # Single source of truth
+│   │   ├── cli/             # CLI descriptors
+│   │   │   ├── claude.yaml, opencode.yaml, copilot.yaml
+│   │   │   └── gemini.yaml  # (add your own)
+│   │   ├── models/          # Model descriptors
+│   │   │   ├── claude-opus-4-7.yaml, claude-sonnet-4.yaml, ...
+│   │   │   └── gpt-4o.yaml  # (add your own)
+│   │   ├── roles/           # Role descriptors
+│   │   │   ├── orchestrator.yaml, worker.yaml, scout.yaml, reasoner.yaml
+│   │   │   └── specialist.yaml # (add your own)
+│   │   ├── templates/frontmatter/
+│   │   │   ├── claude.py, opencode.py
+│   │   │   └── cursor.py    # (add if format differs from Claude/OpenCode)
+│   │   ├── agents/
+│   │   │   ├── agents.yaml  # Agent metadata + role declarations
+│   │   │   └── *.md         # Agent prompt files
+│   │   ├── skills/          # Skill directories
+│   │   ├── rules/           # Code quality rules
+│   │   ├── globals/         # Global config templates
+│   │   └── commands/, scripts/
+│   └── dist/                # Built artifacts (auto-generated, do not edit)
+│       ├── claude/, opencode/
+│       ├── rules/
+│       └── skills/
+├── scripts/                 # Build/utility scripts
+└── tests/                   # Test suite
+```
+
+## Install Methods
+
+### Pip install (recommended)
+
+```bash
+pip install agent-notes
+agent-notes install
+```
+
+### Git clone (for development or customization)
+
+```bash
+git clone https://github.com/rubakas/agent-notes.git ~/agent-notes
+cd ~/agent-notes && pip install -e .
+agent-notes install
+```
+
+Cloning lets you edit source files in `agent_notes/data/` and rebuild with `agent-notes build`.
+
+## Project-Level Overrides
+
+Use `--local --copy` for project-specific customizations. The wizard handles local installs too, while `--local --copy` is for scripted/CI use:
+
+```bash
+agent-notes install --local --copy
+```
+
+Then edit the copied files in `.claude/` or `.opencode/` directories.
+
+**Precedence:** Project-level configs replace global versions entirely.
+
+## Skills
+
+On-demand knowledge modules loaded mid-conversation.
+
+### Available skills
+
+**Rails (24):**
+`rails-models`, `rails-models-advanced`, `rails-controllers`, `rails-controllers-advanced`, `rails-routes`, `rails-concerns`, `rails-views`, `rails-views-advanced`, `rails-view-components`, `rails-view-components-advanced`, `rails-helpers`, `rails-javascript`, `rails-jobs`, `rails-mailers`, `rails-broadcasting`, `rails-migrations`, `rails-active-storage`, `rails-validations`, `rails-testing-controllers`, `rails-testing-models`, `rails-testing-system`, `rails-style`, `rails-initializers`, `rails-lib`
+
+**Docker (4):**
+`docker-dockerfile`, `docker-dockerfile-languages`, `docker-compose`, `docker-compose-advanced`
+
+**Kamal (1):**
+`rails-kamal`
+
+**Git (1):**
+`git` — git workflow, commit chunking, conventional commit messages
+
+**Process (5):**
+`tdd`, `refactoring-protocol`, `debugging-protocol`, `code-review`, `brainstorming`
+
+### Usage
+
+**Claude Code / OpenCode:**
+```
+Use the rails-models skill to help with this association
+Load the docker-compose skill for multi-service setup
+```
+
+## Agent Memory
+
+Agents can accumulate knowledge across sessions — patterns they discovered, decisions they made, mistakes to avoid. Three backends are available, chosen during `agent-notes install`.
+
+### Backends
+
+| Backend | Storage | Best for |
+|---------|---------|----------|
+| **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 |
+| **None** | Disabled — no files written | Stateless or shared machines |
+
+### Obsidian vault setup
+
+**Step 1 — Pick Obsidian during install**
+
+```bash
+agent-notes install
+# ...
+# Step 6/7: Memory backend
+#   How should agents store memory?
+#     1) * Local markdown files (~/.claude/agent-memory/)
+#     2)   Obsidian vault
+#     3)   None
+#   Choice [1]: 2
+#
+#   Detected Obsidian vaults:
+#     ~/Documents/Obsidian/Main
+#   Vault path [~/Documents/Obsidian/Main]: ← press enter or type your path
+#   ✓ Memory: Obsidian (~/Documents/Obsidian/Main)
+```
+
+The wizard auto-detects existing vaults (directories containing `.obsidian/`) in `~/Documents`, `~/Desktop`, and `~`. You can also point to any directory — it doesn't need to be an existing vault.
+
+**Step 2 — Initialise the vault**
+
+```bash
+agent-notes memory init
+# Obsidian vault initialised at ~/Documents/Obsidian/Main
+#   Folders: Patterns, Decisions, Mistakes, Context, Sessions
+#   Index:   ~/Documents/Obsidian/Main/Index.md
+```
+
+Then open Obsidian → "Open folder as vault" → select the same path.
+
+**Vault structure:**
+
+```
+~/your-vault/
+├── Index.md          ← entry point; auto-regenerated after every write
+├── Patterns/         ← reusable solutions and techniques
+├── Decisions/        ← architectural choices and rationale
+├── Mistakes/         ← recurring errors to avoid
+├── Context/          ← per-project background
+└── Sessions/         ← raw session extracts
+```
+
+**Step 3 — Let agents use it**
+
+The installed `CLAUDE.md` already points agents to your vault. At the start of a session Claude reads `Index.md`; at the end it can save insights:
+
+```
+Save this to memory as a pattern: always use _prefix: true with Rails enums
+```
+
+Or use the CLI directly:
+
+```bash
+agent-notes memory add "Rails enum prefix" \
+  "Always use _prefix: true to avoid method name collisions" \
+  --type pattern --agent coder --tags rails,models
+```
+
+**Regenerate the index** after adding files manually in Obsidian:
+
+```bash
+agent-notes memory index
+```
+
+### Switching backends
+
+```bash
+# See current backend
+agent-notes memory vault
+
+# Switch via reconfigure
+agent-notes install --reconfigure
+```
+
+### Memory commands
+
+```bash
+agent-notes memory init                    # create folder structure and Index.md
+agent-notes memory list                    # list all notes (by category or agent)
+agent-notes memory vault                   # show backend, path, and init status
+agent-notes memory index                   # regenerate Index.md
+agent-notes memory add <title> <body> [type] [agent] [project]   # type: pattern|decision|mistake|context|session
+agent-notes memory show <agent>            # show one agent's notes (local backend)
+agent-notes memory reset [agent]           # clear memory (confirmation required)
+agent-notes memory export                  # back up to memory-backup/
+agent-notes memory import                  # restore from memory-backup/
+```
+
+### Note format (Obsidian backend)
+
+Every note agent-notes writes has YAML frontmatter for filtering and Dataview queries:
+
+```markdown
+---
+date: 2026-04-28
+type: pattern
+agent: coder
+project: rubakas
+tags: [rails, models]
+---
+
+# Rails Enum Prefix
+
+Always use `_prefix: true` with Rails enums to avoid method name collisions with
+existing model methods.
+
+## Links
+- [[2026-04-28-switched-to-jsonb-for-settings]]
+```
+
+Files are named `YYYY-MM-DD-<slug>.md` and placed in the matching category folder. They're plain markdown — edit them freely in Obsidian.
+
+## Development
+
+### Prerequisites
+
+- Python 3.9+
+- PyYAML (`pip install pyyaml`)
+
+### Running tests
+
+```bash
+python3 -m pytest tests/
+```
+
+Tests are organized in three directories:
+
+| Directory | What it tests |
+|-----------|---------------|
+| `tests/functional/` | Unit tests: registries, build commands, CLI parsing |
+| `tests/integration/` | Real build output: dist structure, agent frontmatter, pricing embedding |
+| `tests/plugins/` | Artifact validation: every skill and agent file checked for correct metadata |
+
+### Building
+
+```bash
+python3 -m agent_notes build
+```
+
+### Validating
+
+```bash
+python3 -m agent_notes validate
+```
+
+### Project layout
+
+- `agent_notes/data/` — single source of truth (edit here)
+- `agent_notes/dist/` — generated output (do not edit)
+- `agent_notes/` — CLI implementation
+- `tests/` — test suite
+- `scripts/` — dev-only tools (release, etc.)
+
+## Contributing
+
+When adding new content:
+
+1. **Edit source files** — all changes go in `agent_notes/data/` directory
+2. **Run build** — `agent-notes build` to generate platform configs
+3. **Validate** — `agent-notes validate` before committing
+4. **Keep it generic** — remove app-specific references
+5. **Show examples** — include code samples with explanations
+6. **Stay modular** — each skill should be independently usable
+7. **Stay concise** — agent prompts under 60 lines
+
+## License
+
+MIT

agent_notes-2.0.4/agent_notes/VERSION

@@ -0,0 +1 @@
+2.0.4

agent_notes-2.0.4/agent_notes/__init__.py

@@ -0,0 +1 @@
+"""agent-notes — AI agent configuration manager."""

agent_notes-2.0.4/agent_notes/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python3 -m agent_notes"""
+from agent_notes.cli import main
+
+main()