diff --git a/docs/plans/2025-01-21-agentic-rag-design.md b/docs/plans/2025-01-21-agentic-rag-design.md new file mode 100644 index 0000000..f678e58 --- /dev/null +++ b/docs/plans/2025-01-21-agentic-rag-design.md @@ -0,0 +1,388 @@ +# Agentic RAG Design + +**Date:** 2025-01-21 +**Status:** Ready for implementation +**Category:** Agent memory / Knowledge retrieval + +## Overview + +Add semantic search to the existing Claude agent system, enabling multi-source reasoning that combines personal context (state files, memory, decisions) with external documentation. + +### Goals + +- Retrieve relevant past decisions and preferences when answering questions +- Search external docs (k0s, ArgoCD, Prometheus, etc.) for technical reference +- Cross-reference personal context with official documentation +- Support iterative query refinement (agentic behavior) + +### Non-Goals (Future Considerations) + +Deferred to `future-considerations.json`: + +- **fc-043**: Auto-sync on tool version change +- **fc-044**: Broad doc indexing (hundreds of sources) +- **fc-045**: K8s deployment +- **fc-046**: Query caching + +## Architecture + +``` +User question + │ + ▼ +Personal Assistant (existing) + │ + ├── Decides if RAG would help + │ + ▼ +rag-search skill (new) + │ + ├── Query embedding + ├── Vector similarity search + ├── Return ranked chunks with metadata + │ + ▼ +Claude reasons over results + │ + ├── Good enough? → Answer + └── Need more? → Reformulate, search again +``` + +### Two Indexes + +| Index | Contents | Update Frequency | +|-------|----------|------------------| +| **personal** | `~/.claude/state/` files, memory, decisions, preferences | Daily | +| **docs** | External documentation (k0s, ArgoCD, etc.) | Daily | + +### Why Two Indexes + +- Different update frequencies +- Different retrieval strategies (personal may weight recency) +- Can query one or both depending on the question + +## Components + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ rag-search skill │ +│ (Claude invokes this) │ +└─────────────────────┬───────────────────────────────────────────┘ + │ + ┌─────────────┴─────────────┐ + ▼ ▼ +┌───────────────────┐ ┌───────────────────┐ +│ Personal Index │ │ Docs Index │ +│ │ │ │ +│ ~/.claude/state/* │ │ External docs │ +│ memory/*.json │ │ (k0s, ArgoCD...) │ +│ kb.json │ │ │ +└────────┬──────────┘ └────────┬──────────┘ + │ │ + └──────────┬──────────────┘ + ▼ + ┌───────────────────┐ + │ Vector Store │ + │ (ChromaDB) │ + │ │ + │ Collections: │ + │ - personal │ + │ - docs │ + └────────┬──────────┘ + │ + ▼ + ┌───────────────────┐ + │ Embedding Model │ + │ (sentence- │ + │ transformers) │ + └───────────────────┘ +``` + +### Stack + +| Component | Choice | Notes | +|-----------|--------|-------| +| Vector store | ChromaDB | Pure Python, no external deps | +| Embeddings | sentence-transformers (all-MiniLM-L6-v2) | Runs on arm64, ~90MB | +| Storage | `~/.claude/data/rag-search/` | Local to workstation | + +## Skill Structure + +**Location:** `~/.claude/skills/rag-search/` + +``` +rag-search/ +├── SKILL.md # Instructions for Claude +├── scripts/ +│ ├── search.py # Main search entry point +│ ├── index_personal.py # Index state files +│ ├── index_docs.py # Index external docs +│ └── add_doc_source.py # Add new doc source +└── references/ + └── sources.json # Configured doc sources +``` + +## Skill Interface + +### Invocation + +```bash +# Basic search (both indexes) +~/.claude/skills/rag-search/scripts/search.py "how did I configure ArgoCD sync?" + +# Search specific index +~/.claude/skills/rag-search/scripts/search.py --index personal "past decisions about caching" +~/.claude/skills/rag-search/scripts/search.py --index docs "k0s node maintenance" + +# Control result count +~/.claude/skills/rag-search/scripts/search.py --top-k 10 "prometheus alerting rules" +``` + +### Output Format + +```json +{ + "query": "how did I configure ArgoCD sync?", + "results": [ + { + "rank": 1, + "score": 0.847, + "source": "personal", + "file": "memory/decisions.json", + "chunk": "Decided to use ArgoCD auto-sync with self-heal disabled...", + "metadata": {"date": "2025-01-15", "context": "k8s setup"} + }, + { + "rank": 2, + "score": 0.823, + "source": "docs", + "file": "argocd/sync-options.md", + "chunk": "Auto-sync can be configured with selfHeal and prune options...", + "metadata": {"doc_version": "2.9", "url": "https://..."} + } + ], + "searched_collections": ["personal", "docs"], + "total_chunks_searched": 1847 +} +``` + +### SKILL.md Guidance + +- Start with broad query, refine if results aren't relevant +- Cross-reference personal decisions with docs when both appear +- Cite sources in answers (file + date for personal, URL for docs) + +## External Docs Management + +### Source Registry + +**Location:** `~/.claude/skills/rag-search/references/sources.json` + +```json +{ + "sources": [ + { + "id": "k0s", + "name": "k0s Documentation", + "type": "git", + "url": "https://github.com/k0sproject/k0s.git", + "path": "docs/", + "glob": "**/*.md", + "version": "v1.30.0", + "last_indexed": "2025-01-20T10:00:00Z" + }, + { + "id": "argocd", + "name": "ArgoCD Documentation", + "type": "web", + "base_url": "https://argo-cd.readthedocs.io/en/stable/", + "pages": ["user-guide/sync-options/", "operator-manual/"], + "last_indexed": "2025-01-18T14:30:00Z" + } + ] +} +``` + +### Adding Sources + +```bash +~/.claude/skills/rag-search/scripts/add_doc_source.py \ + --id "cilium" \ + --name "Cilium Docs" \ + --type git \ + --url "https://github.com/cilium/cilium.git" \ + --path "Documentation/" \ + --glob "**/*.md" + +# Then index it +~/.claude/skills/rag-search/scripts/index_docs.py --source cilium +``` + +### Update Strategies + +| Strategy | Command | When | +|----------|---------|------| +| Manual | `index_docs.py --source ` | After version upgrade | +| All sources | `index_docs.py --all` | Periodic refresh | + +## Periodic Refresh + +Daily systemd timer on workstation. + +### Service + +**Location:** `~/.config/systemd/user/rag-index.service` + +```ini +[Unit] +Description=Refresh RAG search indexes +After=network-online.target + +[Service] +Type=oneshot +ExecStart=%h/.claude/skills/rag-search/scripts/index_docs.py --all --quiet +ExecStartPost=%h/.claude/skills/rag-search/scripts/index_personal.py --quiet +Environment=PATH=%h/.claude/skills/rag-search/venv/bin:/usr/bin + +[Install] +WantedBy=default.target +``` + +### Timer + +**Location:** `~/.config/systemd/user/rag-index.timer` + +```ini +[Unit] +Description=Daily RAG index refresh + +[Timer] +OnCalendar=daily +Persistent=true +RandomizedDelaySec=3600 + +[Install] +WantedBy=timers.target +``` + +### Enable + +```bash +systemctl --user daemon-reload +systemctl --user enable --now rag-index.timer +``` + +### Manual Trigger + +```bash +systemctl --user start rag-index.service +journalctl --user -u rag-index.service # View logs +``` + +## Resource Requirements + +**Target:** Workstation or Pi5 8GB + +| Component | RAM | Disk | Notes | +|-----------|-----|------|-------| +| Embedding model (all-MiniLM-L6-v2) | ~256MB | ~90MB | Loaded on-demand | +| ChromaDB | ~100-500MB | Varies | Scales with index size | +| Index: personal (~50 files) | — | ~5MB | Small, fast to query | +| Index: docs (10-20 sources) | — | ~100-500MB | Depends on doc volume | +| Indexing process (peak) | ~1GB | — | During embedding generation | + +**Pi3 1GB:** Not suitable for this workload. + +## Chunking Strategy + +| Index | Strategy | +|-------|----------| +| Personal | Per JSON key or logical section (decisions, preferences, facts as separate chunks) | +| Docs | ~500 tokens per chunk with overlap, preserve headers as metadata | + +## Implementation Notes + +### Recommended: Ralph Loop + +This design is suitable for Ralph loop implementation: +- Clear success criteria (tests, functional checks) +- Iterative refinement expected (tuning chunking, embeddings) +- Automatic verification possible + +### Model Delegation + +Use appropriate models for each phase: + +| Phase | Task | Model | +|-------|------|-------| +| 1 | Set up ChromaDB + embedding model | Haiku | +| 2 | Write `index_personal.py` | Sonnet | +| 3 | Write `index_docs.py` | Sonnet | +| 4 | Write `search.py` | Sonnet | +| 5 | Write SKILL.md | Haiku | +| 6 | Integration tests | Sonnet | +| 7 | End-to-end validation | Sonnet | + +### Ralph Invocation + +```bash +/ralph-loop "Implement rag-search skill per docs/plans/2025-01-21-agentic-rag-design.md. + +Delegate to appropriate models: +- Haiku: setup, docs, simple scripts +- Sonnet: implementation, tests, debugging +- Opus: only if stuck on complex reasoning + +Success criteria: +1. ChromaDB + embeddings working +2. Personal index populated from ~/.claude/state +3. At least one external doc source indexed +4. search.py returns relevant results +5. All tests pass + +Output COMPLETE when done." --max-iterations 30 --completion-promise "COMPLETE" +``` + +### When NOT to use Ralph + +- Design decisions still needed (use brainstorming first) +- Requires human judgment mid-implementation +- One-shot simple tasks + +## Workflow Integration + +``` +/superpowers:brainstorm + │ + ▼ + Design doc created + (docs/plans/YYYY-MM-DD-*-design.md) + │ + ▼ + "Ready to implement?" + │ + ┌────┴────┐ + │ │ + ▼ ▼ + Simple Complex/Iterative + │ │ + ▼ ▼ + Manual /ralph-loop + or TDD with design doc + as spec +``` + +## Summary + +| Aspect | Decision | +|--------|----------| +| **Architecture** | Extend existing Claude skill system with semantic search | +| **Indexes** | Two: personal (state files) + docs (external) | +| **Vector store** | ChromaDB (local, no deps) | +| **Embeddings** | sentence-transformers (all-MiniLM-L6-v2) | +| **Skill interface** | `rag-search` skill with `search.py` CLI | +| **Doc management** | `sources.json` registry, git/web fetching | +| **Refresh** | systemd user timer, daily | +| **Storage** | `~/.claude/data/rag-search/` | +| **Hardware** | Runs on workstation (Pi5 8GB capable if needed) | +| **Implementation** | Ralph loop with Haiku/Sonnet subagent delegation | diff --git a/state/future-considerations.json b/state/future-considerations.json index 7c01c2d..a128489 100644 --- a/state/future-considerations.json +++ b/state/future-considerations.json @@ -1 +1 @@ -{"version":"1.0.0","description":"Deferred features and decisions for future implementation","items":[{"id":"fc-001","category":"infrastructure","title":"Workstation monitoring with Prometheus","description":"Deploy node_exporter and Alertmanager for workstation metrics and alerting","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would enable proactive alerting for disk, memory, CPU issues"},{"id":"fc-002","category":"agent","title":"Network admin agent","description":"Agent for network configuration, firewall rules, VPN management","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would manage iptables/nftables, NetworkManager, WireGuard"},{"id":"fc-003","category":"agent","title":"Personal assistant agent","description":"Agent for personal tasks, reminders, scheduling","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Integration with calendar, task management"},{"id":"fc-004","category":"integration","title":"External LLM integration","description":"Support for non-Claude models in the agent system","priority":"low","status":"deferred","created":"2024-12-28","notes":"For specialized tasks or cost optimization"},{"id":"fc-005","category":"optimization","title":"Model usage logging and cost tracking","description":"Track model usage across agents for cost analysis","priority":"medium","status":"resolved","created":"2024-12-28","resolved":"2026-01-01","notes":"Implemented /usage command. Parses history/index.json for session data. Extensible for detailed metrics when session content logging is available."},{"id":"fc-006","category":"design","title":"Slash commands redesign","description":"Revisit slash command architecture and user experience","priority":"low","status":"deferred","created":"2024-12-28","notes":"Current design may need refinement"},{"id":"fc-007","category":"optimization","title":"Document structure optimization","description":"Optimize agent document format for efficiency","priority":"low","status":"deferred","created":"2024-12-28","notes":"Balance between clarity and token usage"},{"id":"fc-008","category":"infrastructure","title":"ArgoCD CLI authentication","description":"Configure argocd CLI with proper authentication","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Using 10-year API token (expires 2035-12-26). Token ID: e3980c6a-1c4e-4f1a-8459-a120a5c60cc5. Stored in ~/.config/argocd/config. No renewal automation needed."},{"id":"fc-009","category":"infrastructure","title":"Prometheus local port-forward","description":"Document Prometheus access patterns for agents","priority":"low","status":"identified","created":"2025-12-28","notes":"Prometheus not accessible on localhost:9090. Options: (1) use kubectl exec to query, (2) set up port-forward, (3) use ingress. Currently works via pod exec."},{"id":"fc-010","category":"infrastructure","title":"Clone homelab gitops repo locally","description":"Clone git@github.com:will666/homelab.git for git-operator access","priority":"low","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Cloned to ~/.claude/repos/homelab"},{"id":"fc-011","category":"k8s-health","title":"Address OutOfSync ArgoCD apps","description":"5 apps OutOfSync, 1 Degraded (porthole)","priority":"medium","status":"identified","created":"2025-12-28","notes":"OutOfSync: adopt-a-street, ai-stack, gitea, home-assistant, kubernetes-dashboard, speetest-tracker. Degraded: porthole"},{"id":"fc-012","category":"agent-memory","title":"PA knowledge base with session caching","description":"Local KB for infrastructure facts with lazy-load and in-session caching","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Implemented. KB files at state/kb.json (shared) and state/personal-assistant/kb.json (private). PA agent updated with lazy-load behavior."},{"id":"fc-013","category":"agent-memory","title":"Vector database for agent long-term memory","description":"Semantic search over agent knowledge using embeddings","priority":"low","status":"deferred","created":"2025-12-28","notes":"Would enable fuzzy matching, semantic queries, and scalable knowledge storage. Consider: ChromaDB, Qdrant, or pgvector."},{"id":"fc-014","category":"observability","title":"Grafana predefined reports","description":"Slash command like /grafana-report services to get standard metrics from known dashboards","priority":"low","status":"deferred","created":"2025-12-29","notes":"Requires comprehensive dashboard coverage first. Revisit when observability matures."},{"id":"fc-015","category":"observability","title":"Grafana integration in diagnostics","description":"Auto-pull Grafana dashboard data during /k8s:diagnose or health checks","priority":"low","status":"deferred","created":"2025-12-29","notes":"Would make Grafana the first troubleshooting tool. Depends on fc-016 and mature observability setup."},{"id":"fc-016","category":"observability","title":"Extend prometheus-analyst with Grafana API","description":"Add Grafana API query capability to existing prometheus-analyst agent","priority":"low","status":"deferred","created":"2025-12-29","notes":"Preferred approach over creating new agent/skill. Natural extension when dashboards are comprehensive. Prerequisite for fc-014 and fc-015."},{"id":"fc-017","category":"optimization","title":"Subagent spawning for skill delegation","description":"Implement Task tool or similar mechanism to spawn lower-tier models for specific operations","priority":"medium","status":"resolved","created":"2025-12-31","resolved":"2025-12-31","notes":"Implemented via Claude CLI subprocess. Helper at ~/.claude/mcp/delegation/gmail_delegate.py. Uses tiered delegation: fetch/list (no LLM), Sonnet for summarize/triage (via 'claude --print --model sonnet'). Uses subscription, no API key needed."},{"id":"fc-018","category":"gcal","title":"Custom date range query","description":"Support querying arbitrary date ranges like 'jan 2026' or 'next month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently only supports today/tomorrow/week/next. Would need new subcommand or natural language parsing."},{"id":"fc-019","category":"gcal","title":"Natural language date parsing","description":"Parse dates like 'next monday', 'jan 2026', 'next week' into calendar queries","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use dateparser library or LLM-based parsing. Would enhance hybrid command interface."},{"id":"fc-020","category":"gcal","title":"Configurable timezone","description":"Allow user to configure display timezone instead of hardcoded America/Los_Angeles","priority":"low","status":"identified","created":"2026-01-01","notes":"Could read from personal-assistant-preferences.json or detect from system."},{"id":"fc-021","category":"gcal","title":"Month subcommand","description":"Add /gcal month for current month overview","priority":"low","status":"identified","created":"2026-01-01","notes":"Would complement week view for longer-range planning."},{"id":"fc-022","category":"gcal","title":"Free/busy check","description":"Check availability like 'am I free Tuesday at 2pm?'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Useful for scheduling. Could use Google Calendar freeBusy API or query events in time range."},{"id":"fc-023","category":"gcal","title":"Write operations","description":"Create, modify, delete calendar events","priority":"low","status":"deferred","created":"2026-01-01","notes":"Would change read-only policy. Requires careful consideration of autonomy levels and confirmation flows."},{"id":"fc-024","category":"gmail","title":"Date range search","description":"Search emails by date range like 'last week', 'in December', 'past 30 days'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently uses newer_than:Nd. Could add natural language date parsing or explicit date range subcommand."},{"id":"fc-025","category":"gmail","title":"Label and folder filtering","description":"Filter by Gmail labels: starred, important, promotions, specific labels","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API supports label filtering. Would enable '/gmail starred' or '/gmail label:work'."},{"id":"fc-026","category":"gmail","title":"Thread view","description":"Show full email conversation thread instead of individual messages","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API returns threadId. Could fetch all messages in thread for context."},{"id":"fc-027","category":"gmail","title":"Attachment detection and listing","description":"List emails with attachments, show attachment names and sizes","priority":"low","status":"identified","created":"2026-01-01","notes":"Useful for finding documents. API provides attachment metadata in message payload."},{"id":"fc-028","category":"gmail","title":"Full email body view","description":"Read complete email content on demand, not just snippets","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently shows snippets. Could add '/gmail read ' or expand specific emails."},{"id":"fc-029","category":"gmail","title":"Sender statistics","description":"Show who emails you most, email volume by sender","priority":"low","status":"identified","created":"2026-01-01","notes":"Aggregate sender data over time period. Useful for identifying noise vs signal."},{"id":"fc-030","category":"gmail","title":"Natural language search","description":"Parse queries like 'emails from John about the project last month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use LLM to translate natural language to Gmail search syntax."},{"id":"fc-031","category":"gmail","title":"Configurable urgency keywords","description":"Customize what keywords/senders trigger urgent classification","priority":"low","status":"identified","created":"2026-01-01","notes":"Currently hardcoded. Could store in personal-assistant-preferences.json."},{"id":"fc-032","category":"gmail","title":"Mark as read","description":"Mark emails as read after viewing","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Would need gmail.modify scope and autonomy consideration."},{"id":"fc-033","category":"gmail","title":"Archive emails","description":"Archive emails from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.modify scope. Consider batch operations."},{"id":"fc-034","category":"gmail","title":"Reply and compose","description":"Send emails and replies from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.send scope. Significant policy change - needs careful autonomy controls."},{"id":"fc-035","category":"gmail","title":"Unsubscribe detection","description":"Identify subscription/newsletter emails, suggest unsubscribe","priority":"low","status":"identified","created":"2026-01-01","notes":"Parse List-Unsubscribe headers. Could help with inbox cleanup."},{"id":"fc-036","category":"optimization","title":"API token billing support","description":"Track actual API costs when using Anthropic API instead of subscription","priority":"low","status":"deferred","created":"2026-01-01","notes":"Currently on Pro subscription. When/if using API, add token-based cost calculation using Anthropic pricing."},{"id":"fc-037","category":"optimization","title":"Automatic usage summary","description":"PA mentions usage stats at session end or provides weekly digest","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be opt-in via preferences."},{"id":"fc-038","category":"optimization","title":"Usage dashboard file","description":"Generate Markdown/JSON usage report updated periodically","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be daily/weekly cron or on-demand generation."},{"id":"fc-039","category":"registry","title":"Registry git hook validation","description":"Pre-commit hook to run validate-registry.py automatically","priority":"low","status":"identified","created":"2026-01-01","notes":"Would prevent commits with stale or TODO registry entries."},{"id":"fc-040","category":"registry","title":"Registry trigger learning","description":"Learn new triggers from successful routing patterns","priority":"low","status":"deferred","created":"2026-01-01","notes":"Track when user rephrases after failed routing, add successful phrases as new triggers."},{"id":"fc-041","category":"morning-report","title":"Terminal output morning report","description":"Quick text output for morning report when opening first terminal","priority":"medium","status":"identified","created":"2026-01-02","notes":"Alternative to dashboard. Could be triggered by shell hook or motd-style script."},{"id":"fc-042","category":"morning-report","title":"Enhanced infrastructure dashboard detail","description":"Expand infrastructure section from traffic light to summary stats or full metrics","priority":"medium","status":"identified","created":"2026-01-02","notes":"Start with simple green/yellow/red. Options: summary stats (node count, pod health %, disk/memory), problem-focused (only show issues), or full dashboard."}]} +{"version":"1.0.0","description":"Deferred features and decisions for future implementation","items":[{"id":"fc-001","category":"infrastructure","title":"Workstation monitoring with Prometheus","description":"Deploy node_exporter and Alertmanager for workstation metrics and alerting","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would enable proactive alerting for disk, memory, CPU issues"},{"id":"fc-002","category":"agent","title":"Network admin agent","description":"Agent for network configuration, firewall rules, VPN management","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Would manage iptables/nftables, NetworkManager, WireGuard"},{"id":"fc-003","category":"agent","title":"Personal assistant agent","description":"Agent for personal tasks, reminders, scheduling","priority":"medium","status":"deferred","created":"2024-12-28","notes":"Integration with calendar, task management"},{"id":"fc-004","category":"integration","title":"External LLM integration","description":"Support for non-Claude models in the agent system","priority":"low","status":"deferred","created":"2024-12-28","notes":"For specialized tasks or cost optimization"},{"id":"fc-005","category":"optimization","title":"Model usage logging and cost tracking","description":"Track model usage across agents for cost analysis","priority":"medium","status":"resolved","created":"2024-12-28","resolved":"2026-01-01","notes":"Implemented /usage command. Parses history/index.json for session data. Extensible for detailed metrics when session content logging is available."},{"id":"fc-006","category":"design","title":"Slash commands redesign","description":"Revisit slash command architecture and user experience","priority":"low","status":"deferred","created":"2024-12-28","notes":"Current design may need refinement"},{"id":"fc-007","category":"optimization","title":"Document structure optimization","description":"Optimize agent document format for efficiency","priority":"low","status":"deferred","created":"2024-12-28","notes":"Balance between clarity and token usage"},{"id":"fc-008","category":"infrastructure","title":"ArgoCD CLI authentication","description":"Configure argocd CLI with proper authentication","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Using 10-year API token (expires 2035-12-26). Token ID: e3980c6a-1c4e-4f1a-8459-a120a5c60cc5. Stored in ~/.config/argocd/config. No renewal automation needed."},{"id":"fc-009","category":"infrastructure","title":"Prometheus local port-forward","description":"Document Prometheus access patterns for agents","priority":"low","status":"identified","created":"2025-12-28","notes":"Prometheus not accessible on localhost:9090. Options: (1) use kubectl exec to query, (2) set up port-forward, (3) use ingress. Currently works via pod exec."},{"id":"fc-010","category":"infrastructure","title":"Clone homelab gitops repo locally","description":"Clone git@github.com:will666/homelab.git for git-operator access","priority":"low","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Cloned to ~/.claude/repos/homelab"},{"id":"fc-011","category":"k8s-health","title":"Address OutOfSync ArgoCD apps","description":"5 apps OutOfSync, 1 Degraded (porthole)","priority":"medium","status":"identified","created":"2025-12-28","notes":"OutOfSync: adopt-a-street, ai-stack, gitea, home-assistant, kubernetes-dashboard, speetest-tracker. Degraded: porthole"},{"id":"fc-012","category":"agent-memory","title":"PA knowledge base with session caching","description":"Local KB for infrastructure facts with lazy-load and in-session caching","priority":"medium","status":"resolved","created":"2025-12-28","resolved":"2025-12-28","notes":"Implemented. KB files at state/kb.json (shared) and state/personal-assistant/kb.json (private). PA agent updated with lazy-load behavior."},{"id":"fc-013","category":"agent-memory","title":"Vector database for agent long-term memory","description":"Semantic search over agent knowledge using embeddings","priority":"low","status":"deferred","created":"2025-12-28","notes":"Would enable fuzzy matching, semantic queries, and scalable knowledge storage. Consider: ChromaDB, Qdrant, or pgvector."},{"id":"fc-014","category":"observability","title":"Grafana predefined reports","description":"Slash command like /grafana-report services to get standard metrics from known dashboards","priority":"low","status":"deferred","created":"2025-12-29","notes":"Requires comprehensive dashboard coverage first. Revisit when observability matures."},{"id":"fc-015","category":"observability","title":"Grafana integration in diagnostics","description":"Auto-pull Grafana dashboard data during /k8s:diagnose or health checks","priority":"low","status":"deferred","created":"2025-12-29","notes":"Would make Grafana the first troubleshooting tool. Depends on fc-016 and mature observability setup."},{"id":"fc-016","category":"observability","title":"Extend prometheus-analyst with Grafana API","description":"Add Grafana API query capability to existing prometheus-analyst agent","priority":"low","status":"deferred","created":"2025-12-29","notes":"Preferred approach over creating new agent/skill. Natural extension when dashboards are comprehensive. Prerequisite for fc-014 and fc-015."},{"id":"fc-017","category":"optimization","title":"Subagent spawning for skill delegation","description":"Implement Task tool or similar mechanism to spawn lower-tier models for specific operations","priority":"medium","status":"resolved","created":"2025-12-31","resolved":"2025-12-31","notes":"Implemented via Claude CLI subprocess. Helper at ~/.claude/mcp/delegation/gmail_delegate.py. Uses tiered delegation: fetch/list (no LLM), Sonnet for summarize/triage (via 'claude --print --model sonnet'). Uses subscription, no API key needed."},{"id":"fc-018","category":"gcal","title":"Custom date range query","description":"Support querying arbitrary date ranges like 'jan 2026' or 'next month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently only supports today/tomorrow/week/next. Would need new subcommand or natural language parsing."},{"id":"fc-019","category":"gcal","title":"Natural language date parsing","description":"Parse dates like 'next monday', 'jan 2026', 'next week' into calendar queries","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use dateparser library or LLM-based parsing. Would enhance hybrid command interface."},{"id":"fc-020","category":"gcal","title":"Configurable timezone","description":"Allow user to configure display timezone instead of hardcoded America/Los_Angeles","priority":"low","status":"identified","created":"2026-01-01","notes":"Could read from personal-assistant-preferences.json or detect from system."},{"id":"fc-021","category":"gcal","title":"Month subcommand","description":"Add /gcal month for current month overview","priority":"low","status":"identified","created":"2026-01-01","notes":"Would complement week view for longer-range planning."},{"id":"fc-022","category":"gcal","title":"Free/busy check","description":"Check availability like 'am I free Tuesday at 2pm?'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Useful for scheduling. Could use Google Calendar freeBusy API or query events in time range."},{"id":"fc-023","category":"gcal","title":"Write operations","description":"Create, modify, delete calendar events","priority":"low","status":"deferred","created":"2026-01-01","notes":"Would change read-only policy. Requires careful consideration of autonomy levels and confirmation flows."},{"id":"fc-024","category":"gmail","title":"Date range search","description":"Search emails by date range like 'last week', 'in December', 'past 30 days'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently uses newer_than:Nd. Could add natural language date parsing or explicit date range subcommand."},{"id":"fc-025","category":"gmail","title":"Label and folder filtering","description":"Filter by Gmail labels: starred, important, promotions, specific labels","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API supports label filtering. Would enable '/gmail starred' or '/gmail label:work'."},{"id":"fc-026","category":"gmail","title":"Thread view","description":"Show full email conversation thread instead of individual messages","priority":"medium","status":"identified","created":"2026-01-01","notes":"Gmail API returns threadId. Could fetch all messages in thread for context."},{"id":"fc-027","category":"gmail","title":"Attachment detection and listing","description":"List emails with attachments, show attachment names and sizes","priority":"low","status":"identified","created":"2026-01-01","notes":"Useful for finding documents. API provides attachment metadata in message payload."},{"id":"fc-028","category":"gmail","title":"Full email body view","description":"Read complete email content on demand, not just snippets","priority":"medium","status":"identified","created":"2026-01-01","notes":"Currently shows snippets. Could add '/gmail read ' or expand specific emails."},{"id":"fc-029","category":"gmail","title":"Sender statistics","description":"Show who emails you most, email volume by sender","priority":"low","status":"identified","created":"2026-01-01","notes":"Aggregate sender data over time period. Useful for identifying noise vs signal."},{"id":"fc-030","category":"gmail","title":"Natural language search","description":"Parse queries like 'emails from John about the project last month'","priority":"medium","status":"identified","created":"2026-01-01","notes":"Could use LLM to translate natural language to Gmail search syntax."},{"id":"fc-031","category":"gmail","title":"Configurable urgency keywords","description":"Customize what keywords/senders trigger urgent classification","priority":"low","status":"identified","created":"2026-01-01","notes":"Currently hardcoded. Could store in personal-assistant-preferences.json."},{"id":"fc-032","category":"gmail","title":"Mark as read","description":"Mark emails as read after viewing","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Would need gmail.modify scope and autonomy consideration."},{"id":"fc-033","category":"gmail","title":"Archive emails","description":"Archive emails from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.modify scope. Consider batch operations."},{"id":"fc-034","category":"gmail","title":"Reply and compose","description":"Send emails and replies from Claude interface","priority":"low","status":"deferred","created":"2026-01-01","notes":"Write operation. Requires gmail.send scope. Significant policy change - needs careful autonomy controls."},{"id":"fc-035","category":"gmail","title":"Unsubscribe detection","description":"Identify subscription/newsletter emails, suggest unsubscribe","priority":"low","status":"identified","created":"2026-01-01","notes":"Parse List-Unsubscribe headers. Could help with inbox cleanup."},{"id":"fc-036","category":"optimization","title":"API token billing support","description":"Track actual API costs when using Anthropic API instead of subscription","priority":"low","status":"deferred","created":"2026-01-01","notes":"Currently on Pro subscription. When/if using API, add token-based cost calculation using Anthropic pricing."},{"id":"fc-037","category":"optimization","title":"Automatic usage summary","description":"PA mentions usage stats at session end or provides weekly digest","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be opt-in via preferences."},{"id":"fc-038","category":"optimization","title":"Usage dashboard file","description":"Generate Markdown/JSON usage report updated periodically","priority":"low","status":"identified","created":"2026-01-01","notes":"Depends on fc-005 (usage logging). Could be daily/weekly cron or on-demand generation."},{"id":"fc-039","category":"registry","title":"Registry git hook validation","description":"Pre-commit hook to run validate-registry.py automatically","priority":"low","status":"identified","created":"2026-01-01","notes":"Would prevent commits with stale or TODO registry entries."},{"id":"fc-040","category":"registry","title":"Registry trigger learning","description":"Learn new triggers from successful routing patterns","priority":"low","status":"deferred","created":"2026-01-01","notes":"Track when user rephrases after failed routing, add successful phrases as new triggers."},{"id":"fc-041","category":"morning-report","title":"Terminal output morning report","description":"Quick text output for morning report when opening first terminal","priority":"medium","status":"identified","created":"2026-01-02","notes":"Alternative to dashboard. Could be triggered by shell hook or motd-style script."},{"id":"fc-042","category":"morning-report","title":"Enhanced infrastructure dashboard detail","description":"Expand infrastructure section from traffic light to summary stats or full metrics","priority":"medium","status":"identified","created":"2026-01-02","notes":"Start with simple green/yellow/red. Options: summary stats (node count, pod health %, disk/memory), problem-focused (only show issues), or full dashboard."},{"id":"fc-043","category":"rag","title":"Auto-sync on tool version change","description":"Automatically re-index external docs when upstream tool versions change","priority":"low","status":"deferred","created":"2025-01-21","notes":"Could hook into ArgoCD sync events or package update notifications. Part of Agentic RAG design."},{"id":"fc-044","category":"rag","title":"Broad doc indexing","description":"Expand from focused doc sources (10-20) to broad coverage (hundreds of sources, Stack Overflow, blogs)","priority":"low","status":"deferred","created":"2025-01-21","notes":"Option B from Agentic RAG brainstorm. Revisit once focused indexing proves value."},{"id":"fc-045","category":"rag","title":"RAG k8s deployment","description":"Deploy RAG stack (ChromaDB, embedding service) to k8s cluster instead of workstation","priority":"low","status":"deferred","created":"2025-01-21","notes":"Currently runs locally on workstation. Would enable cluster-based access but adds complexity."},{"id":"fc-046","category":"rag","title":"RAG query caching","description":"Cache frequent queries and their results to reduce embedding/search overhead","priority":"low","status":"deferred","created":"2025-01-21","notes":"Optimization for when query volume justifies it. Consider TTL and invalidation strategy."}]}