diff --git a/.gitignore b/.gitignore index d8031bfe..9792b3d4 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,10 @@ __pycache__/ # Secrets .env +# Plans (managed by flow, local to each installation) +FPLAN-*.md +DPLAN-*.md + # AIPass runtime state (local to each installation) AIPASS_REGISTRY.json .trinity/ diff --git a/FPLAN-0003_framework_memory_bank_port_to_aipass_rep_2026-03-06.md b/FPLAN-0003_framework_memory_bank_port_to_aipass_rep_2026-03-06.md deleted file mode 100644 index d065fdbd..00000000 --- a/FPLAN-0003_framework_memory_bank_port_to_aipass_rep_2026-03-06.md +++ /dev/null @@ -1,308 +0,0 @@ -# FPLAN-0003 - [framework] Memory Bank — port to AIPass repo - -**Created**: 2026-03-06 -**Branch**: /home/aipass/aipass_business/AIPass -**Status**: Active -**Type**: Standard Plan - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building features or modules -- Single focused construction tasks -- Sub-plans within a master plan - ---- - -## When to Use This vs Master Plan - -| This (Default) | Master Plan | -|----------------|-------------| -| Single focused task | 3+ phases, complex build | -| Self-contained | Roadmap + multiple sub-plans | -| Quick build | Multi-session project | -| One phase of a master | Entire branch/system build | - -**Need a master plan?** `drone @flow create "subject" master` - ---- - -## Branch Directory Structure - -Use dedicated directories - don't scatter files: - -| Directory | Purpose | -|-----------|---------| -| `apps/` | Code (modules/, handlers/) | -| `tests/` | All test files | -| `tools/` | Utility scripts | -| `artifacts/` | Agent outputs | -| `docs/` | Documentation | - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans | Write code | -| Give instructions | Run tests | -| Review output | Read/modify files | -| Course correct | Research/exploration | -| Update memories | Heavy lifting | -| Send status emails | Single-task execution | - -**Pattern:** Instruct agent → Wait for completion → Review output → Next step - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seed for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so Patrick can glance without asking -- **Questions for Patrick** - Non-urgent questions that can wait for his next visit -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. Patrick checks it when he wants to, skips it when he's busy. - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "subject" # Create plan (. = current dir) -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow --help # Full help - -# Seed - Quality gates -drone @seed checklist # 10-point check on file -drone @seed audit @branch # Full branch audit -drone @seed --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @dev_central "Subject" "Message" -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## Planning Phase - -### Goal -Port the internal Memory Bank system into `src/aipass/memory/` as a fully functional module. Every spawned branch should have working memory rollover, JSONL archival, and searchable archives out of the box. Vector storage (ChromaDB + sentence-transformers) as optional pip extra. - -### What We're Porting -Source: `/home/aipass/MEMORY_BANK/` (~1,800 lines, 75+ files) - -**Core (zero new deps — must ship):** -- `detector.py` — threshold detection via AIPASS_REGISTRY.json (600-line default) -- `extractor.py` — FIFO extraction of oldest sessions, backup-before-extract -- `line_counter.py` — metadata `current_lines` updates -- `json_handler.py` — atomic JSON read/write (temp file + rename) -- `archiver.py` — JSONL archive write + keyword search -- `rollover.py` module — orchestrates detect → extract → archive → update -- `search.py` module — keyword search over JSONL archives - -**Optional (`pip install aipass[vectors]`):** -- `embedder.py` — sentence-transformers wrapper (all-MiniLM-L6-v2, 384-dim) -- `vector_store.py` — ChromaDB persistence, per-branch `.chroma/` dirs -- `vector_search.py` — semantic search with metadata filtering -- Graceful fallback to keyword search if deps not installed - -**Not v1 (later):** -- Symbolic/fragmented memory (experimental, v0.3) -- Living template push system -- Dashboard integration (needs DevPulse) -- Central writer (needs AI_CENTRAL concept) -- Memory pool intake processing - -### Key Decisions -- **passport.json** is the identity file name (not id.json) -- **`.trinity/`** stays as the memory directory name -- **AIPASS_REGISTRY.json** is used for branch discovery (same as internal BRANCH_REGISTRY.json) -- **No daemon** — auto-check on command execution or manual `drone @memory rollover` -- **3-layer architecture** — apps/memory.py → modules/ → handlers/ -- **JSONL for base archive** — keyword search good enough for most users -- **ChromaDB optional** — subprocess isolation if Python version issues arise - -### Spawn Template Updates -- Welcome session (session 0) in local.json on branch creation -- `.trinity/archive/` directory pre-created and empty -- Memory self-managing — agent updates files, rollover handles overflow - -### Integration Points -- Drone: `drone @memory status|rollover|search` commands -- Spawn: post-spawn welcome memory -- Registry: reads AIPASS_REGISTRY.json for branch discovery -- Hooks: PreCompact already references memory context - -### Reference Documents -- Internal Memory Bank: `/home/aipass/MEMORY_BANK/apps/` (source code) -- Internal rollover module: `/home/aipass/MEMORY_BANK/apps/modules/rollover.py` (676 lines) -- Internal detector: `/home/aipass/MEMORY_BANK/apps/handlers/monitor/detector.py` -- Internal extractor: `/home/aipass/MEMORY_BANK/apps/handlers/rollover/extractor.py` -- Spawn templates: `src/aipass/spawn/templates/agent.template/.trinity/` -- AIPass architecture: 3-layer pattern (apps → modules → handlers) - ---- - -## Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - ---- - -## Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seed standards (3-layer architecture) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by DEV_CENTRAL -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Execution Log - -### 2026-03-06 -- [ ] Created FPLAN-0003 -- [ ] Agent deployed for: [task] -- [ ] Agent completed: [outcome] -- [ ] Seed checklist passed: [file] -- [ ] Memories updated - -**Log Pattern:** Task → Agent → Outcome → Quality check → Next - -**If production stops (critical blocker):** -```bash -drone @ai_mail send @dev_central "PRODUCTION STOPPED: FPLAN-0003" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - ---- - -## Notes - -[Working notes, issues encountered, decisions made] - ---- - -## Completion Checklist - -### Before Closing - -- [ ] All goals achieved -- [ ] Agent output reviewed and verified -- [ ] Seed checklist on new code: `drone @seed checklist ` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - session/work log - - [ ] `BRANCH.observations.json` - patterns learned (if any) -- [ ] README.md updated (if build changed status/capabilities) -- [ ] Status email sent to DEV_CENTRAL: - ```bash - drone @ai_mail send @dev_central "FPLAN-0003 Complete" "Summary of what was done, any issues, outcomes" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -### Definition of Done -- `src/aipass/memory/` module exists with 3-layer architecture -- `drone @memory status` shows all branches and their memory file line counts -- `drone @memory rollover` detects and processes oversized files -- `drone @memory search "query"` returns keyword matches from JSONL archives -- Spawn creates branches with welcome session and empty archive dir -- All 13+ existing tests still pass -- New tests for memory module (detector, extractor, archiver, search) -- `pip install aipass[vectors]` adds ChromaDB + semantic search capability -- Memory module registered in AIPASS_REGISTRY.json - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0003 -``` diff --git a/FPLAN-0004_framework_backup_system_port_to_aipass_r_2026-03-06.md b/FPLAN-0004_framework_backup_system_port_to_aipass_r_2026-03-06.md deleted file mode 100644 index b7a0ec8a..00000000 --- a/FPLAN-0004_framework_backup_system_port_to_aipass_r_2026-03-06.md +++ /dev/null @@ -1,274 +0,0 @@ -# FPLAN-0004 - [framework] Backup System — port to AIPass repo - -**Created**: 2026-03-06 -**Branch**: /home/aipass/aipass_business/AIPass -**Status**: Active -**Type**: Standard Plan - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building features or modules -- Single focused construction tasks -- Sub-plans within a master plan - ---- - -## When to Use This vs Master Plan - -| This (Default) | Master Plan | -|----------------|-------------| -| Single focused task | 3+ phases, complex build | -| Self-contained | Roadmap + multiple sub-plans | -| Quick build | Multi-session project | -| One phase of a master | Entire branch/system build | - -**Need a master plan?** `drone @flow create "subject" master` - ---- - -## Branch Directory Structure - -Use dedicated directories - don't scatter files: - -| Directory | Purpose | -|-----------|---------| -| `apps/` | Code (modules/, handlers/) | -| `tests/` | All test files | -| `tools/` | Utility scripts | -| `artifacts/` | Agent outputs | -| `docs/` | Documentation | - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans | Write code | -| Give instructions | Run tests | -| Review output | Read/modify files | -| Course correct | Research/exploration | -| Update memories | Heavy lifting | -| Send status emails | Single-task execution | - -**Pattern:** Instruct agent → Wait for completion → Review output → Next step - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seed for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so Patrick can glance without asking -- **Questions for Patrick** - Non-urgent questions that can wait for his next visit -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. Patrick checks it when he wants to, skips it when he's busy. - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "subject" # Create plan (. = current dir) -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow --help # Full help - -# Seed - Quality gates -drone @seed checklist # 10-point check on file -drone @seed audit @branch # Full branch audit -drone @seed --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @dev_central "Subject" "Message" -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## Planning Phase - -### Goal -Port the internal Backup System (`/home/aipass/aipass_core/backup_system/`) into the AIPass public repo at `src/aipass/backup/`. Working backup with snapshot mode, versioned mode, Google Drive sync (optional), dry-run support, and 90+ ignore patterns. Same approach as FPLAN-0003 (Memory Bank) — rewire, don't rebuild. - -### Approach -1. Copy all source files from internal backup_system/apps/ into src/aipass/backup/apps/ -2. Deploy parallel agents to adapt imports (remove prax/cli/sys.path, use relative imports, make Google Drive optional) -3. Fix hardcoded paths to use `Path(__file__).resolve().parents[N]` -4. Verify no internal references remain - -### Reference Documents -- Source: `/home/aipass/aipass_core/backup_system/apps/` (entry point + 4 modules + ~20 handlers) -- Pattern: FPLAN-0003 (Memory Bank port) — identical approach -- Architecture: 3-layer (apps/backup.py → modules/ → handlers/) - ---- - -## Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - ---- - -## Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seed standards (3-layer architecture) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by DEV_CENTRAL -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Execution Log - -### 2026-03-06 -- [x] Created FPLAN-0004 -- [x] Agent deployed for: investigate backup_system structure (returned full report) -- [x] Created directory structure: src/aipass/backup/apps/{modules,handlers/{config,models,operations,utils,json,diff,reporting},json_templates/default,extensions,plugins} -- [x] Copied 42 files from internal backup_system -- [x] Agent 1 deployed: adapt 5 modules + entry point (completed — all imports fixed) -- [x] Agent 2 deployed: adapt 20 handler files (completed — all imports fixed) -- [x] Manual fix: handlers/__init__.py cross-branch guard removed (incompatible with public repo paths) -- [x] Manual fix: removed unused imports in backup_core.py (load_json, save_json, temporarily_writable, module-level logger.info) -- [x] Verified: zero remaining internal imports (prax, cli, sys.path, aipass_core, backup_system.apps) -- [ ] Memories updated - -**Log Pattern:** Task → Agent → Outcome → Quality check → Next - -**If production stops (critical blocker):** -```bash -drone @ai_mail send @dev_central "PRODUCTION STOPPED: FPLAN-0004" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - ---- - -## Notes - -- Same port-by-rewiring pattern as Memory Bank (FPLAN-0003): copy files, adapt imports, verify -- Google Drive deps (google-api-python-client, google-auth-oauthlib) made optional via try/except -- drive_sync_client.py already had Google API imports wrapped — just fixed internal path refs -- handlers/__init__.py had cross-branch security guard that checked for `/backup_system/` in caller path — incompatible with new `/backup/` path, replaced with simple package init -- JSON runtime data dir changed from `backup_system_json/` to `backup_json/` (relative to backup root) -- Timestamps file moved to `backup_data/backup_timestamps.json` -- Entry point renamed from `backup_system.py` to `backup.py` -- All `header()` calls from cli module replaced with local `_header()` helpers - ---- - -## Completion Checklist - -### Before Closing - -- [ ] All goals achieved -- [ ] Agent output reviewed and verified -- [ ] Seed checklist on new code: `drone @seed checklist ` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - session/work log - - [ ] `BRANCH.observations.json` - patterns learned (if any) -- [ ] README.md updated (if build changed status/capabilities) -- [ ] Status email sent to DEV_CENTRAL: - ```bash - drone @ai_mail send @dev_central "FPLAN-0004 Complete" "Summary of what was done, any issues, outcomes" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -### Definition of Done -- All backup_system files ported to src/aipass/backup/ with working imports -- Zero references to internal paths (prax, cli, aipass_core, sys.path hacks) -- Google Drive integration optional (graceful degradation when deps missing) -- JSON templates preserved for module initialization -- Entry point (backup.py) routes commands to all 4 modules - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0004 -``` diff --git a/FPLAN-0005_framework_daemon_port_to_aipass_repo_2026-03-07.md b/FPLAN-0005_framework_daemon_port_to_aipass_repo_2026-03-07.md deleted file mode 100644 index 1191579a..00000000 --- a/FPLAN-0005_framework_daemon_port_to_aipass_repo_2026-03-07.md +++ /dev/null @@ -1,106 +0,0 @@ -# FPLAN-0005 - [framework] Daemon (assistant) — port to AIPass repo - -**Created**: 2026-03-07 -**Branch**: /home/aipass/aipass_business/AIPass -**Status**: Active -**Type**: Standard Plan - ---- - -## Planning Phase - -### Goal -Port the internal Assistant system (`/home/aipass/aipass_os/dev_central/assistant/`) into the AIPass public repo at `src/aipass/daemon/`. Rename from "assistant" to "daemon". Working scheduler with plugin system, scheduled tasks, activity monitoring, and cron-driven execution. Telegram integration optional. Same approach as FPLAN-0003/0004 — rewire, don't rebuild. - -### Approach -1. Copy all source files from internal assistant/apps/ into src/aipass/daemon/apps/ -2. Rename entry point from assistant.py to daemon.py -3. Deploy parallel agents to adapt imports (remove prax/cli/sys.path, use relative imports) -4. Make Telegram, ai_mail dispatch, and BRANCH_REGISTRY deps optional via try/except -5. Fix hardcoded paths to use `Path(__file__).resolve().parents[N]` -6. Verify no internal references remain - -### Key Decisions -- **Rename**: assistant → daemon (Patrick approved) -- **Telegram**: Optional — wrap in try/except, graceful skip when unconfigured -- **ai_mail dispatch**: Optional — wake.py spawning won't work outside Dev-Pass, needs abstraction -- **BRANCH_REGISTRY**: Activity monitoring reads this — make it configurable, graceful fallback -- **Plugins**: Port all 5 plugins as examples, but they're Dev-Pass-specific — document as templates -- **filelock**: Only external dep (already lightweight) - -### Reference Documents -- Source: `/home/aipass/aipass_os/dev_central/assistant/apps/` (entry point + 2 cron scripts + 4 modules + ~10 handlers + 5 plugins) -- Pattern: FPLAN-0003 (Memory Bank) and FPLAN-0004 (Backup System) — identical approach -- Architecture: 3-layer (apps/daemon.py → modules/ → handlers/) - -### Investigation Summary -- **4 modules**: update, schedule, activity_report, actions -- **10 handlers** across 6 subdirs: actions/, json/, monitoring/ (3 files), schedule/ (3 files), telegram/, update/ -- **5 plugins**: heartbeat, daily_audit, community_rotation, botfather_reminder, dev_central_monitor -- **2 cron scripts**: scheduler_cron.py, assistant_wakeup.py (renamed to daemon_wakeup.py) -- **External deps**: filelock only -- **Internal deps**: prax logger, cli console/header, ai_mail send_email_direct, api telegram_chat, BRANCH_REGISTRY.json -- **Tests**: 1 test file (test_actions_registry.py) with pytest - ---- - -## Execution Log - -### 2026-03-07 -- [x] Created FPLAN-0005 -- [x] Agent deployed for: investigate assistant structure (returned full report) -- [x] Created directory structure: src/aipass/daemon/apps/{modules,handlers/{actions,json,monitoring,schedule,telegram,update},plugins,extensions,json_templates/default} -- [x] Copied 41 files from internal assistant system (renamed assistant→daemon) -- [x] Agent 1 deployed: adapt 13 files (3 entry points + 4 modules + 5 plugins + plugin init) — completed -- [x] Agent 2 deployed: adapt 10 handler files — completed -- [x] Fixed standalone scripts (scheduler_cron.py, daemon_wakeup.py): changed relative imports to absolute package imports (standalone scripts can't use relative imports) -- [x] Fixed test file: removed sys.path manipulation, uses package imports -- [x] Fixed actions_registry.py: removed sys.path.insert in migrate_plugins, uses absolute package import -- [x] Fixed memory_health.py: removed hardcoded /home/aipass test path -- [x] Removed 3 remaining shebangs from conftest.py and handler __init__.py files -- [x] Cleaned unused imports (Path, sys, os, timedelta, Optional, Tuple) across modules -- [x] Verified: zero remaining internal imports (prax, cli, sys.path, aipass_core, aipass_os, assistant_json, ASSISTANT_ROOT) -- [ ] Memories updated - ---- - -## Notes - -- Same port-by-rewiring pattern as Memory Bank (FPLAN-0003) and Backup System (FPLAN-0004) -- Renamed assistant → daemon (Patrick approved the name) -- Standalone cron scripts (scheduler_cron.py, daemon_wakeup.py) can't use relative imports — fixed to use absolute package imports (aipass.daemon.apps.handlers.xxx) -- Telegram integration made optional via try/except + TELEGRAM_AVAILABLE flag -- ai_mail dispatch made optional via try/except + AI_MAIL_AVAILABLE flag -- Wake script path configurable via AIPASS_WAKE_SCRIPT env var -- BRANCH_REGISTRY path configurable via AIPASS_REGISTRY env var -- Daemon config path configurable via AIPASS_DAEMON_CONFIG env var -- filelock made optional (try/except, falls back to fcntl) -- handlers/__init__.py cross-branch guard removed (incompatible with public repo) -- JSON runtime data dir changed from assistant_json/ to daemon_json/ -- Entry point renamed from assistant.py to daemon.py -- Wakeup script renamed from assistant_wakeup.py to daemon_wakeup.py -- All ASSISTANT.local.json refs changed to DAEMON.local.json -- Plugin system preserved — 5 example plugins ported as templates - ---- - -## Completion Checklist - -### Definition of Done -- All assistant files ported to src/aipass/daemon/ with working imports -- Entry point renamed from assistant.py to daemon.py -- Zero references to internal paths (prax, cli, aipass_core, aipass_os, sys.path hacks) -- Telegram integration optional (graceful degradation) -- ai_mail dispatch optional (abstracted for external use) -- Plugin system preserved with example plugins -- JSON templates preserved for module initialization -- Tests ported and passing - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0005 -``` diff --git a/FPLAN-0006_framework_skills_system_2026-03-07.md b/FPLAN-0006_framework_skills_system_2026-03-07.md deleted file mode 100644 index 8c6cbe01..00000000 --- a/FPLAN-0006_framework_skills_system_2026-03-07.md +++ /dev/null @@ -1,116 +0,0 @@ -# FPLAN-0006 - [framework] Skills System Build - -**Created**: 2026-03-07 -**Branch**: /home/aipass/aipass_business/AIPass -**Status**: Complete -**Type**: Master Plan - ---- - -## Planning Phase - -### Goal -Build the Skills system for AIPass framework. Skills are documented capabilities that any AI can use — from simple markdown SOPs to full 3-layer code implementations. Lives at `src/skills/` (peer to `src/aipass/`, not inside it — skills are separate from infrastructure). - -### Approach -Three-tier skill architecture: -- **Tier 1 (Markdown):** SKILL.md only — instructions an LLM reads and follows -- **Tier 2 (Markdown + Handler):** SKILL.md + handler.py — code does the work -- **Tier 3 (Full 3-layer):** SKILL.md + apps/modules/handlers — complete implementation - -Follows seedgo's pack pattern: auto-discovery via SKILL.md manifests, drone-routable via `handle_command()`. - -OpenClaw SKILL.md format compatibility: their 52 skills (MIT license) can be adapted with minor metadata changes. - -### Key Decisions -- **Location**: `src/skills/` — outside `src/aipass/` (skills are capabilities, not infrastructure) -- **Format**: SKILL.md with YAML frontmatter (compatible with OpenClaw format) -- **Discovery**: Glob + importlib + duck typing (same pattern as Nexus skills, seedgo packs) -- **Drone integration**: `drone @skills list|info|run|create|validate` -- **Handler contract**: `run(action, args, config) -> {"success": bool, "output": str, "error": str|None}` -- **No branch manager build** — directory structure only (like FPLAN-0003/0004/0005 pattern) - -### Reference Documents -- Design: `vera/projects/framework/skills_system_design.md` -- Research: `vera/projects/framework/nexus_and_skills_design.md` -- Seedgo pattern: `src/aipass/seedgo/apps/standards/aipass/` (pack architecture) -- Telegram reference: `/home/aipass/aipass_core/api/apps/handlers/telegram/` (complex skill example) -- OpenClaw skills: `/home/aipass/external_repos/openclaw/skills/` (SKILL.md format reference) -- Architecture: `vera/projects/framework/architecture_reference.md` - ---- - -## Execution Log - -### Phase 1: Foundation — Directory Structure + Core -- [x] Create `src/skills/` directory structure (3-layer: apps/skills.py → modules/ → handlers/) -- [x] Create entry point: `apps/skills.py` with `handle_command()` for drone routing -- [x] Create discovery module: `apps/modules/discovery.py` (scan search paths, parse SKILL.md frontmatter) -- [x] Create loader module: `apps/modules/loader.py` (load full SKILL.md, import handler if present) -- [x] Create runner module: `apps/modules/runner.py` (execute handler or display instructions) -- [x] Create creator module: `apps/modules/creator.py` (scaffold new skills from templates) -- [x] Create registry handler: `apps/handlers/registry.py` (skill registry management) -- [x] Create validator handler: `apps/handlers/validator.py` (check requirements — bins, pip, config) -- [x] Create template handler: `apps/handlers/template.py` (skill templates for scaffolding) -- [x] Create Trinity files: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json` -- [x] Create `__init__.py` files at all levels -- [x] Create README.md - -### Phase 2: Templates -- [x] Markdown-only skill template (`templates/markdown_only/SKILL.md`) -- [x] Markdown + handler skill template (`templates/with_handler/SKILL.md` + `handler.py`) -- [x] Full 3-layer skill template (`templates/full/SKILL.md` + `apps/` structure) - -### Phase 3: Test Skills (One Per Tier) -- [x] Tier 1: Adapt OpenClaw GitHub skill → `catalog/github/SKILL.md` -- [x] Tier 2: Build system_status skill → `catalog/system_status/SKILL.md` + `handler.py` -- [x] Tier 3: Create drone_commands skill skeleton → `catalog/drone_commands/` with apps structure - -### Phase 4: Seedgo Skills Standard -- [x] Create skills standard pack: `src/aipass/seedgo/apps/standards/skills/` -- [x] Create `pack.json` manifest -- [x] Create `pack_entry.py` entry point -- [x] Create standard modules (skill_format, skill_structure, skill_handler) -- [x] Create standard handlers (content + check pairs) - -### Phase 5: Testing -- [x] Unit tests for discovery engine (32 tests) -- [x] Unit tests for loader (7 tests) -- [x] Unit tests for runner (11 tests) -- [x] Unit tests for validator (10 tests) -- [x] Integration test: full skill lifecycle create → discover → load → run (14 tests) -- [x] Test OpenClaw skill adaptation works (github skill loads and runs correctly) - ---- - -## Notes - -- Same citizen-branch pattern as drone, ai_mail, prax — but directory structure only, no branch manager -- Skills are separate from aipass infrastructure (sit at `src/skills/`, not `src/aipass/skills/`) -- Patrick wants all three tiers supported: markdown SOPs, markdown+handler, full 3-layer -- Code skills cost zero tokens to run — markdown skills cost tokens every time. Both have a place. -- OpenClaw SKILL.md compatibility lets users adapt 52 existing MIT-licensed skills -- Seedgo standard for skills ensures all skills meet quality bar - ---- - -## Completion Checklist - -### Definition of Done -- Skills branch exists at `src/skills/` with full 3-layer architecture -- `drone @skills list|info|run|create|validate` commands work -- All three skill tiers supported (markdown, markdown+handler, full 3-layer) -- At least one test skill per tier working -- OpenClaw GitHub skill successfully adapted -- Seedgo skills standard created with at least 3 checks -- Tests passing -- Trinity files in place - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0006 -``` diff --git a/FPLAN-0411_framework_the_commons_port_to_aipass_fra_2026-03-07.md b/FPLAN-0411_framework_the_commons_port_to_aipass_fra_2026-03-07.md deleted file mode 100644 index 2cddcf24..00000000 --- a/FPLAN-0411_framework_the_commons_port_to_aipass_fra_2026-03-07.md +++ /dev/null @@ -1,679 +0,0 @@ -# FPLAN-0411 - [framework] The Commons — Port to AIPass Framework (MASTER PLAN) - -**Created**: 2026-03-07 -**Branch**: /home/aipass/aipass_business/AIPass -**Status**: COMPLETE -**Type**: Master Plan (Multi-Phase) - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. They're the structured way to execute work without constant human oversight. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building new branches/modules -- Implementing features -- Multi-phase construction projects -- Autonomous execution - ---- - -## Master Plan vs Default Plan - -| | Master Plan | Default Plan | -|---|-------------|--------------| -| **Use when** | 3+ phases, complex build | Single focused task | -| **Structure** | Roadmap + sub-plans | Self-contained | -| **Phases** | Multiple, sequential | One | -| **Sub-plans** | Yes, one per phase | No | -| **Typical use** | Build entire branch | One phase of master | - -**Pattern:** -``` -Master Plan (roadmap) -├── Sub-plan Phase 1 (default template) -├── Sub-plan Phase 2 (default template) -├── Sub-plan Phase 3 (default template) -└── Sub-plan Phase 4 (default template) -``` - -**How to start:** -1. DEV_CENTRAL provides planning doc or instructions -2. Branch manager reads and understands scope -3. Branch manager creates master plan: `drone @flow create . "Build X" master` -4. Branch manager fills in phases, then executes autonomously - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans & sub-plans | Write code | -| Define phases | Run tests | -| Give agent instructions | Read/modify files | -| Review agent output | Research/exploration | -| Course correct | Heavy lifting | -| Update memories | Single-task execution | -| Send status emails | Build deliverables | -| Track phase progress | Quality checks on code | - -**Master Plan Pattern:** Define all phases → Create sub-plan for Phase 1 → Deploy agent → Review → Close sub-plan → Email update → Next phase - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seed for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. For master plans spanning multiple domains, identify which branches to consult during phase definitions. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so Patrick can glance without asking -- **Questions for Patrick** - Non-urgent questions that can wait for his next visit -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. Patrick checks it when he wants to, skips it when he's busy. Low friction both ways. - -```bash -# Create it at plan start -echo "# Notepad - FPLAN-0411" > notepad.md -``` - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "Phase X: subject" # Create sub-plan (. = current dir) -drone @flow create . "subject" master # Create master plan -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow status # Plan status -drone @flow --help # Full help - -# Seed - Quality gates -drone @seed checklist # 10-point check on file -drone @seed audit @branch # Full branch audit (before master close) -drone @seed --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @vera "Subject" "Message" -drone @ai_mail inbox # Check your inbox -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## What is a Master Plan? - -Master Plans are for **complex multi-phase projects**. You define all phases upfront, then create focused sub-plans for each phase. - -**When to use:** -- 3+ distinct sequential phases -- Work spanning multiple sessions -- Need clear phase completion milestones -- Complex builds requiring sustained focus - -**Pattern:** Master Plan = Roadmap | Sub-Plans = Focused Execution - ---- - -## Project Overview - -### Goal -Port The Commons — AIPass's social network for branches — from the dev system (`/home/aipass/The_Commons/`) to the public AIPass framework at `src/commons/`. This is a complete social platform: 12,649 lines, 85 Python files, SQLite database with 16 tables, 50+ commands, 22 modules, 60 handler files. - -The Commons sits at `src/commons/` — peer to `src/aipass/` (infrastructure) and `src/skills/` (capabilities). It's a social application, not infrastructure. - -### Reference Documentation -- **Source code:** `/home/aipass/The_Commons/` (dev system — the authoritative implementation) -- **Entry point:** `/home/aipass/The_Commons/apps/the_commons.py` (442 lines) -- **Schema:** `/home/aipass/The_Commons/apps/handlers/database/schema.sql` -- **Database manager:** `/home/aipass/The_Commons/apps/handlers/database/db.py` (527 lines) -- **Identity:** `/home/aipass/The_Commons/THE_COMMONS.id.json` -- **Architecture reference:** `vera/projects/framework/architecture_reference.md` -- **Skills port (pattern reference):** FPLAN-0006 (just completed — same port-by-copy approach) -- **Branch manager:** The Commons has its own branch manager at `/home/aipass/The_Commons/` - -### Success Criteria -- `src/commons/` exists with full 3-layer architecture -- `drone @commons` commands route correctly (list, post, feed, thread, comment, vote, room, etc.) -- SQLite database initializes and works (all 16 tables, FTS5 search) -- All 50+ commands functional -- Tests passing (baseline: port the 72 existing tests) -- Trinity files in place -- Cross-branch integrations abstracted (ai_mail, prax, cli, devpulse — lazy-imported, graceful fallback) - -### Architecture Decisions -- **Location:** `src/commons/` (social layer, separate from infrastructure) -- **Imports:** Replace dev-system absolute imports with relative package imports -- **Cross-branch deps:** Lazy-import with graceful fallback (system works without prax/ai_mail/cli) -- **Database:** Ships with schema, creates `commons.db` in user's `.aipass/` directory (not in package) -- **Rich dependency:** Required — The Commons uses Rich extensively for CLI output -- **No branch manager build** — just the code package (same pattern as skills, FPLAN-0006) - -### Branch Expertise to Leverage -| Branch | Consultation Topic | -|--------|-------------------| -| @the_commons | Architecture decisions, why certain patterns exist, migration history | -| @ai_mail | Notification integration — how send_email_direct works, what to abstract | -| @prax | Logger integration — system_logger API, what to stub for standalone use | -| @memory_bank | SQLite patterns — they use vectors/ChromaDB, may have connection pool insights | -| @drone | Routing registration — how to add `commons` as a routable module | -| @seed | Standards compliance — what the 3-layer audit expects for this size module | - ---- - -## Branch Directory Structure - -Every branch has dedicated directories. Use them correctly: - -``` -branch/ -├── apps/ # Code (modules/, handlers/) -├── tests/ # All test files go here -├── tools/ # Utility scripts, helpers -├── artifacts/ # Agent outputs (reports, logs) -├── docs/ # Documentation -└── logs/ # Execution logs -``` - -**Rules:** -- Tests → `tests/` (not root, not random locations) -- Tools/scripts → `tools/` -- Agent artifacts → `artifacts/` -- Create subdirs if needed: `mkdir -p artifacts/reports artifacts/logs` -- **Never delete** - DEV_CENTRAL manages cleanup -- Future: artifacts auto-roll to Memory Bank - ---- - -## Phase Definitions - -Define ALL phases before starting work: - -### Phase 1: Foundation — Directory Structure, Database, Entry Point -**Goal:** Create `src/commons/` skeleton and port the database layer + entry point. This is the foundation everything else builds on. Without the DB, nothing works. -**Agent Task:** -- Create `src/commons/` directory tree (apps/, apps/modules/, apps/handlers/ with all subdirs) -- Port `apps/the_commons.py` entry point (adapt imports to relative) -- Port `apps/handlers/database/` (schema.sql, db.py, migrations.py) — the entire DB layer -- Port `apps/modules/commons_identity.py` (identity detection) -- Port `apps/handlers/identity/` (identity ops — branch detection from CWD) -- Create all `__init__.py` files -- Create `.trinity/` files (passport.json, local.json, observations.json) -- Abstract cross-branch imports: prax logger → stdlib logging fallback, cli console → Rich direct -- Database path: `{AIPASS_ROOT}/.aipass/commons.db` (not in package) -**Deliverables:** -- `src/commons/apps/the_commons.py` -- `src/commons/apps/handlers/database/schema.sql` -- `src/commons/apps/handlers/database/db.py` -- `src/commons/apps/handlers/database/migrations.py` -- `src/commons/apps/modules/commons_identity.py` -- `src/commons/apps/handlers/identity/identity_ops.py` -- All `__init__.py` files (15+) -- `.trinity/` files -- `README.md` -**Consult:** @the_commons (migration history), @prax (logger stub pattern), @memory_bank (SQLite best practices) - -### Phase 2: Core Social — Posts, Comments, Votes, Feed, Rooms -**Goal:** Port the core social functionality — the fundamental CRUD operations that everything else builds on. After this phase, you can post, comment, vote, browse feeds, and manage rooms. -**Agent Task:** -- Port `apps/modules/post_module.py` + `apps/handlers/posts/post_ops.py` -- Port `apps/modules/comment_module.py` + `apps/handlers/comments/comment_ops.py` -- Port `apps/modules/feed_module.py` + `apps/handlers/feed/feed_ops.py` -- Port `apps/modules/room_module.py` + `apps/handlers/rooms/room_ops.py` -- Port vote handling (in comment_module or post_module — verify source) -- Adapt all imports (prax logger → fallback, cli console → Rich direct, cross-handler refs → relative) -- Wire module discovery in entry point -**Deliverables:** -- 4 modules, 4+ handler files -- All CRUD operations working: create/read/delete posts, add/read comments, vote up/down, feed sorting (hot/new/top/activity), room create/list/join -**Consult:** @the_commons (feed sorting algorithm, vote score calculation) - -### Phase 3: Discovery & Social Features — Search, Catchup, Activity, Profiles, Welcome -**Goal:** Port the discovery and social enrichment features that make The Commons useful beyond basic CRUD. -**Agent Task:** -- Port `search_module.py` + `apps/handlers/search/` (FTS5 full-text search, log export) -- Port `catchup_module.py` + `apps/handlers/catchup/` (what you missed) -- Port `activity_module.py` + `apps/handlers/activity/` (cross-thread activity feed) -- Port `profile_module.py` + `apps/handlers/profiles/` (view/edit profiles) -- Port `welcome_module.py` + `apps/handlers/welcome/` (welcome new branches) -- Port `digest_module.py` + `apps/handlers/digest/` (24h digest) -**Deliverables:** -- 6 modules, 8+ handler files -- FTS5 search working, catchup/activity feeds functional - -### Phase 4: Engagement — Reactions, Notifications, Pins, Trending, Leaderboards -**Goal:** Port the engagement layer — reactions, curation, notifications, gamification. -**Agent Task:** -- Port `reaction_module.py` + `apps/handlers/curation/` (react, pin, pinned, trending) -- Port `notification_module.py` + `apps/handlers/notifications/` (watch, mute, track, preferences) -- Port `leaderboard_module.py` + `apps/handlers/social/` (rankings) -- Port `engagement_module.py` + `apps/handlers/engagement/` (prompts, events) -- Abstract ai_mail notification integration (lazy import with graceful "notifications disabled" fallback) -**Deliverables:** -- 4 modules, 10+ handler files -- Notification preferences working, reactions functional, leaderboards calculating -**Consult:** @ai_mail (send_email_direct API for notification abstraction) - -### Phase 5: Extended Features — Spatial, Artifacts, Trading, Capsules, Exploration -**Goal:** Port the extended/fun features — spatial mechanics, artifact crafting, trading, time capsules, secret rooms. -**Agent Task:** -- Port `space_module.py` + `apps/handlers/rooms/spatial_ops.py` (enter, look, decorate, visitors) -- Port `artifact_module.py` + `apps/handlers/artifacts/` (craft, list, inspect, rewards) -- Port `trade_module.py` + `apps/handlers/artifacts/trade_ops.py` (gift, trade, drop, find, mint) -- Port `capsule_module.py` + `apps/handlers/artifacts/capsule_ops.py` (time capsules) -- Port `explore_module.py` + `apps/handlers/rooms/exploration_ops.py` (secret rooms) -**Deliverables:** -- 5 modules, 6+ handler files -- Spatial mechanics working, artifacts craftable, trading functional - -### Phase 6: Integration & Output — Central, Dashboard, JSON Templates -**Goal:** Port the integration layer that connects Commons to the broader ecosystem (AI_CENTRAL stats, dashboard updates, JSON output). -**Agent Task:** -- Port `central_module.py` + `apps/handlers/central/` (push stats to AI_CENTRAL) -- Port `apps/handlers/dashboard/` (dashboard write-through to branch DASHBOARD files) -- Port `apps/handlers/json/` (JSON template rendering) -- Abstract devpulse write_section import (lazy + graceful fallback) -- All cross-branch integrations use lazy import pattern with disabled-mode fallback -**Deliverables:** -- 1 module, 4+ handler files -- Central stats generation working (even if push target doesn't exist) -**Consult:** @devpulse (write_section API), @the_commons (central JSON format) - -### Phase 7: Testing & Verification -**Goal:** Port existing tests, write additional coverage, run end-to-end verification. -**Agent Task:** -- Port `/home/aipass/The_Commons/tests/test_commons.py` (72 tests) into `src/commons/tests/` -- Adapt test imports for package structure -- Add integration tests: full lifecycle (init DB → create room → post → comment → vote → feed → search) -- Verify all 50+ commands work via entry point -- Run full test suite -- Syntax check all files -**Deliverables:** -- `src/commons/tests/test_commons.py` (ported 72 tests) -- `src/commons/tests/test_lifecycle.py` (new integration tests) -- All tests passing -- End-to-end command verification report - ---- - -## Execution Philosophy - -### Autonomous Power-Through - -Master plans are for **autonomous execution**. Don't halt production every phase waiting for DEV_CENTRAL review. - -**The Pattern:** -- Power through all phases -- Accumulate issues as you go -- Deal with issues at the end -- DEV_CENTRAL reviews final result, not every step - -**Why this works:** -- Context is precious - don't burn it chasing bugs -- Complete picture reveals which issues actually matter -- Many "bugs" resolve themselves when later phases complete -- DEV_CENTRAL time is for decisions, not babysitting - -### The 2-Attempt Rule - -When agent encounters an issue: - -``` -Attempt 1 → Failed? - ↓ -Attempt 2 → Failed? - ↓ -STOP. Mark as issue. Move on. -``` - -**Do NOT:** -- Try 5 different approaches -- Go down rabbit holes -- Burn context debugging -- Stop production for every error - -**DO:** -- Note the issue clearly -- Note what was tried -- Move to next task -- Let branch manager decide priority - -### Critical vs Non-Critical Issues - -When you see an issue, decide: - -| Question | If YES → | If NO → | -|----------|----------|---------| -| Does this block ALL future phases? | STOP. Investigate. | Continue. | -| Can the system work around this? | Continue. | STOP. Investigate. | -| Is this a syntax/import error? | Quick fix, continue. | - | -| Is this a logic/design problem? | Note it. Continue. | - | - -**Critical (stop production):** -- Core module won't import at all -- Database/file system inaccessible -- Fundamental architecture wrong - -**Non-critical (note and continue):** -- One command throws error but others work -- Registry not updating properly -- Edge case not handled -- Test failing but code runs - -**Pattern:** Note issue → Continue building → Fix at end with complete picture - -### False Positives Awareness - -Seed audits are helpful but not infallible. - -**When Seed flags something:** -1. Check if the code is actually correct from your understanding -2. If you're confident it's right → mark as false positive, move on -3. If you're unsure → note it, continue, review later - -**Don't stop production for:** -- Style preferences (comments, spacing) -- Patterns that differ from Seed's but still work -- Checks that don't apply to your context - -### Forward Momentum Summary -- **Don't stop to fix bugs during phases** - Note them, keep moving -- **Get complete picture first** - All phases done, THEN systematic fixes -- **Prevents:** Bug-fixing rabbit holes, premature optimization, scope creep -- **DEV_CENTRAL reviews at END** - not every phase - -### Production Stop Protocol - -If something causes production to STOP (critical blocker), **immediately email DEV_CENTRAL**: - -```bash -drone @ai_mail send @vera "PRODUCTION STOPPED: FPLAN-0411" "Phase X halted. Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - -**Never leave a branch stopped without reporting.** VERA (not DEV_CENTRAL) is the main contact for this build. - -### Monitoring Resources - -For quick status checks and debugging, these resources are available: - -| Resource | Location | Purpose | -|----------|----------|---------| -| Branch logs | `logs/` directory | Local execution logs | -| JSON tree | `apps/json_templates/` | Module firing status | -| Prax monitor | `drone @prax monitor` | Real-time system events | -| Seed audit | `drone @seed audit @branch` | Code quality check | - -Use these when you need to confirm status or investigate issues. - -### Branch Dispatch Per Phase -Each phase = dispatch to the domain-expert branch: -1. Identify which branch(es) own this phase's domain -2. Send dispatch email with clear task + context + deliverables -3. Wake the branch (`drone wake @branch`) -4. Monitor progress (check inbox for replies, check files for output) -5. Review deliverables when branch replies -6. Run seedgo checklist on new code -7. Course-correct if needed, then dispatch next phase - -**Branch Ownership:** -| Phase | Primary Branch | Support | -|-------|---------------|---------| -| Phase 1 (Foundation) | Vera sub-agent (DONE) | @prax (logger), @memory_bank (SQLite) | -| Phase 2 (Core Social) | @the_commons | — | -| Phase 3 (Discovery) | @the_commons | — | -| Phase 4 (Engagement) | @the_commons | @ai_mail (notification integration) | -| Phase 5 (Extended) | @the_commons | — | -| Phase 6 (Integration) | @the_commons | @devpulse (dashboard API) | -| Phase 7 (Testing) | @the_commons | @seed (compliance) | - -**Key Principle:** The Commons branch manager knows their own code better than any generic sub-agent. They port their own modules. Vera orchestrates and monitors. - -### Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - -### Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task for this phase] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seed standards (3-layer architecture: apps/modules/handlers) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by @vera -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -SEEDGO COMPLIANCE: -- After building, run seedgo checklist on key files: - cd /home/aipass/aipass_business/AIPass/src/aipass/seedgo && python3 apps/seedgo.py checklist aipass -- Run seedgo audit for full branch check: - cd /home/aipass/aipass_business/AIPass/src/aipass/seedgo && python3 apps/seedgo.py audit aipass -- Target: 80%+ compliance score -- Key standards to hit: - - architecture: 3-layer pattern (apps/entry.py -> modules/ -> handlers/) - - handlers: return dicts, NEVER print - - modules: handle_command(command, args) -> bool, can print - - imports: no sys.path hacking, no AIPASS_ROOT, proper aipass.* namespace - - naming: snake_case files and functions - - meta: AIPass metadata headers on all .py files - -WHEN COMPLETE: -- Verify code runs without syntax errors -- Run seedgo checklist on entry point and 2-3 key handlers -- List files created/modified -- Note any issues encountered (with what was attempted) -- Report score from seedgo -``` - ---- - -## Phase Tracking - -### Phase 1: Foundation — Directory Structure, Database, Entry Point -- [x] Built by Vera sub-agent (initial scaffolding) -- [x] Output reviewed and verified -- [ ] Seedgo checklist passed (80%+) -- **Status:** COMPLETE -- **Owner:** Vera sub-agent -- **Notes:** 18 files created. Entry point, flattened schema (16 tables), db.py, identity detection, Trinity files. Quality verified. - -### Phase 2: Core Social — Posts, Comments, Votes, Feed, Rooms -- [x] Dispatched to @the_commons -- [x] @the_commons replied with completion -- [x] Output reviewed — clean 3-layer separation, proper dict-return handlers, Rich display -- [ ] Seedgo checklist passed (80%+) -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** 8 files: post_ops, comment_ops (dedup + vote toggle), feed_ops (hot/new/top/activity + format_time_ago), room_ops + 4 matching modules. Stripped dev-pass integrations (FTS sync, dashboard, reward drops, profile counts). - -### Phase 3: Discovery & Social Features — Search, Catchup, Activity, Profiles, Welcome -- [x] Dispatched to @the_commons -- [x] @the_commons replied with completion -- [x] Output reviewed — 6 modules + 11 handler files. Seedgo: 91%, 86%, 94%. -- [x] Seedgo checklist passed (80%+) — All scores above 80% -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** search (FTS5), catchup (what-you-missed), activity (cross-thread), profile (view/edit/who), welcome (scan/welcome), digest (24h). Stripped dashboard pipeline for later phase. - -### Phase 4: Engagement — Reactions, Notifications, Pins, Trending, Leaderboards -- [x] Dispatched to @the_commons (primary) + @ai_mail (notification patterns — received) -- [x] @the_commons replied with completion -- [x] Output reviewed — 4 modules + 8 handlers. Seedgo: 95%, 91%, 90%. -- [x] Seedgo checklist passed (80%+) -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** curation_ops (7 commands), notification_ops, leaderboard_ops (5 categories), engagement_ops (prompts + events). Pure DB helpers: reaction_queries, pin_queries, trending_queries, preferences. ai_mail notification not yet wired (Phase 6). - -### Phase 5: Extended Features — Spatial, Artifacts, Trading, Capsules, Exploration -- [x] Dispatched to @the_commons -- [x] @the_commons replied with completion -- [x] Output reviewed — 5 modules + 8 handler files. Seedgo: 100%, 91%, 85%. -- [x] Seedgo checklist passed (80%+) -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** space_ops (enter/look/decorate/visitors), room_state_ops, explore_ops (secret rooms), artifact_ops (craft/inspect/list/collab/sign with provenance), trade_ops (gift/trade/drop/find/mint with sweep-on-access), capsule_ops (seal/list/open). Stripped physical artifact file operations. - -### Phase 6: Integration & Output — Central, Dashboard, JSON Templates -- [x] Dispatched to @the_commons -- [x] @the_commons replied with completion -- [x] Output reviewed — 1 module + 4 handlers + 3 JSON templates. Seedgo: 90%, 84%, 81%, 81%, 80%. -- [x] Seedgo checklist passed (80%+) — All files at or above 80% -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** central_writer (aggregate stats, atomic write), dashboard_writer (write-through via lazy devpulse), dashboard_pipeline (event-driven, tiered), json_handler (template-based auto-create), central_module (push-central cmd). JSON templates copied. - -### Phase 7: Testing & Verification -- [x] Dispatched to @the_commons -- [x] @the_commons replied with completion -- [x] Output reviewed — 72 ported tests + 10 integration tests = 82/82 passing. Syntax clean. -- [x] All tests passing — Verified: `pytest src/commons/tests/ -v` → 82 passed in 5.64s -- **Status:** COMPLETE -- **Owner:** @the_commons -- **Notes:** test_commons.py (72 tests, 11 classes — adapted imports, fixed room name collisions). test_lifecycle.py (10 integration tests: room→post→comment→vote→feed→search→thread→cascade delete→room filter→mentions). 83 .py files syntax checked — zero failures. - ---- - -## Issues Log - -Track issues here as you encounter them. Don't fix during build - log and continue. - -| Phase | Issue | Severity | Attempted | Status | -|-------|-------|----------|-----------|--------| -| 1 | [description] | Low/Med/High | [what was tried] | Open/Resolved | -| 2 | [description] | Low/Med/High | [what was tried] | Open/Resolved | - -**Severity Guide:** -- **High:** Blocks future phases, must fix before continuing -- **Med:** Affects functionality but can work around -- **Low:** Cosmetic, edge case, or false positive - -**End of Build:** Review this log. Tackle High→Med→Low. Some Low issues may not need fixing. - ---- - -## Master Plan Notes - -**Cross-Phase Patterns:** -[Patterns discovered that span multiple phases] - -**Blockers & Resolutions:** -[Significant blockers and how resolved] - -**Adjustments:** -[Changes to planned phases - scope changes, phases added/merged] - ---- - -## Final Completion Checklist - -### Before Closing Master Plan - -- [ ] All phases complete -- [ ] All sub-plans closed -- [ ] Issues Log reviewed - High/Med issues addressed -- [ ] Full seedgo audit: `cd /home/aipass/aipass_business/AIPass/src/aipass/seedgo && python3 apps/seedgo.py audit aipass` (80%+) -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - full session log - - [ ] `BRANCH.observations.json` - patterns learned -- [ ] README.md updated (status, architecture, API - if build changed capabilities) -- [ ] Artifacts reviewed -- [ ] Final status to @vera (main contact for this build): - ```bash - drone @ai_mail send @vera "FPLAN-0411 MASTER COMPLETE" "Full build summary: phases completed, seedgo score, deliverables, remaining issues (if any)" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -**Note:** DEV_CENTRAL will perform their own Seed audit for visibility into the work. - -### Definition of Done -- `src/commons/` exists at `/home/aipass/aipass_business/AIPass/src/commons/` with full 3-layer architecture -- Entry point (`apps/the_commons.py`) routes all 50+ commands -- SQLite database initializes correctly (16 tables, 22 indexes, FTS5 virtual tables) -- All 22 modules ported and discoverable -- All 60 handler files ported with adapted imports -- Cross-branch integrations abstracted (lazy import + graceful fallback for prax, ai_mail, cli, devpulse) -- Database stored at `{AIPASS_ROOT}/.aipass/commons.db` (not in package) -- 72+ tests passing -- Trinity files in place -- README.md accurate -- No hardcoded dev-system paths - ---- - -## Close Command - -When ALL phases complete and checklist done: -```bash -drone @flow close FPLAN-0411 -``` diff --git a/src/aipass/devpulse/docs/DPLAN-0001_system_bootstrap.md b/src/aipass/devpulse/docs/DPLAN-0001_system_bootstrap.md deleted file mode 100644 index f27436c9..00000000 --- a/src/aipass/devpulse/docs/DPLAN-0001_system_bootstrap.md +++ /dev/null @@ -1,92 +0,0 @@ -# DPLAN-0001: System Bootstrap - -Tag: bootstrap - -> Get all 15 modules operational with citizenship, comms, and branch awareness. - -## Vision -Every module has citizenship (.trinity/), can receive email, and can be woken via dispatch. DevPulse has full visibility. The system runs as a coordinated multi-agent team. - -## Current State -- All 15 branches registered, discoverable, and fully scaffolded -- All citizens are builder class (except devpulse = manager) -- 13/15 respond to `drone @branch --help` (devpulse has no apps/ by design, commons DB init fails) -- Import fixes complete: backup (16 files), daemon (8 files), skills (5 files) -- Commons entry point renamed (the_commons.py → commons.py) -- Wake + round-trip comms verified on @memory and @backup -- Seedgo audit: all branches passing (77-98%) -- gh CLI installed and authed for PR workflow -- 3 PRs merged: #17 (bootstrap), #18 (builder scaffold), #19 (commons/skills scaffold) - -## What Needs Building - -### Phase 1: Test Spawn Safety -- [x] Create mock test branch with apps/ to verify spawn passport doesn't clobber existing code -- [x] Verify birthright grants .trinity/ without touching apps/ -- [x] Clean up test branch after verification - -### Phase 2: Grant Citizenship -- [x] Grant birthright to backup (has apps/, is builder — but existing code, use passport) -- [x] Grant birthright to daemon (has apps/, same situation) -- [x] Grant birthright to memory (has apps/, same situation) -- [x] Grant birthright to skills (src/skills/, external) -- [x] Grant birthright to commons (src/commons/, external) -- [x] Clean stale test entries from registry (sync-registry --fix removed 6 stale) - -### Phase 3: Drone Discovery -- [x] Verify `drone systems` shows all 15 branches -- [x] Test `drone @backup --help` — FIXED: agent converted 16 files relative→absolute imports -- [x] Test `drone @daemon --help` — FIXED: agent converted 8 files relative→absolute imports -- [x] Test `drone @memory --help` — WORKS -- [x] Test `drone @skills --help` — FIXED: added __main__ block + converted relative→absolute imports -- [x] Test `drone @commons --help` — FIXED: renamed the_commons.py → commons.py (DB init still fails, separate issue) -- [ ] Fix commons DB initialization (ported code, SQLite path issue) - -### Phase 4: Wake & Comms -- [x] Send test email to each new citizen (all 5 delivered) -- [x] Verify inboxes receive messages (confirmed all 5) -- [x] Test wake on @memory — agent spawned successfully via dispatch -- [x] Confirm round-trip communication — memory replied to both emails, replies in devpulse inbox.json -- [ ] Fix `drone @ai_mail inbox` display — shows stale cached message, doesn't reflect actual inbox.json content - -### Phase 5: Branch Prompts -- [x] Update devpulse local prompt (fixed paths, added all 15 modules with descriptions) -- [x] Fix devpulse passport (builder → manager) -- [ ] Build local prompts for new citizens (backup, daemon, memory, skills, commons) -- [x] Update global prompt branch count (10 → 15) -- [x] Disabled stale aipass_local_prompt.md - -## Design Decisions - -| Decision | Options | Leaning | Notes | -|----------|---------|---------|-------| -| commons/skills location | Move to src/aipass/ vs keep outside | Keep outside | They're not aipass system apps, they're external projects with their own namespace | -| Citizenship for existing code | spawn create vs spawn passport | passport | Passport adds .trinity/ without touching apps/ | -| Registry cleanup | Manual vs sync-registry --fix | sync-registry --fix | Let spawn's built-in tool handle it | -| Citizen class for ported code | birthright vs builder | builder | All branches with apps/ should be builder — birthright is for identity-only | -| External project scaffolding | spawn update vs manual | manual | spawn update can't reach outside src/aipass/, copy template files manually | - -## Relationships -- **Related DPLANs:** None yet -- **Related FPLANs:** None yet -- **Owner branches:** devpulse (coordination), spawn (execution) - -## Status -- [x] Planning -- [x] In Progress -- [ ] Ready for Execution -- [ ] Complete -- [ ] Abandoned - -## Notes -Session 11. First DPLAN in AIPass. Patrick confirmed: commons and skills are NOT aipass system apps — they live outside src/aipass/ intentionally. Use spawn passport for existing directories to avoid clobbering code. - -**Progress:** Phases 1-4 substantially complete. All 15 branches scaffolded as builder class. Wake + round-trip comms verified on @memory and @backup. Phase 5 partial — prompts need building for new citizens. - -**Session 12:** Fixed skills (added __main__ + absolute imports), fixed commons routing (renamed entry point), cleaned registry stale entries manually, tested wake dispatch on @memory and @backup — both replied autonomously. Discovered passport was setting birthright instead of builder — fixed all 5, ran spawn update on backup/daemon/memory, manually scaffolded commons/skills. Installed gh CLI. PRs #17, #18, #19 merged. - -**Remaining:** Commons DB init fix, ai_mail inbox display bug, branch prompts for new citizens, test registry isolation. - ---- -*Created: 2026-03-07* -*Updated: 2026-03-07* diff --git a/src/aipass/devpulse/docs/DPLAN-0002_prompt_architecture.md b/src/aipass/devpulse/docs/DPLAN-0002_prompt_architecture.md deleted file mode 100644 index 339137c5..00000000 --- a/src/aipass/devpulse/docs/DPLAN-0002_prompt_architecture.md +++ /dev/null @@ -1,129 +0,0 @@ -# DPLAN-0002: Prompt Architecture & Standards - -Tag: infrastructure - -> Design the prompt system so every branch has exactly what it needs — no more, no less — and seedgo can enforce it. - -## Vision - -Every branch gets a local prompt that orients it instantly. The system prompt (CLAUDE.md) + hook-injected global prompt + branch local prompt work together without duplication. Seedgo has a standard to audit prompt quality. New branches get a prompt template from spawn. - -## Current State - -- **CLAUDE.md** — lean system prompt (startup, hard rules, navigation, memory, docker). ~30 lines. Good. -- **Hook-injected global prompt** — identity_injector.py injects AIPass system context every turn. Contains terminology, branch structure template, commands, dispatch syntax, hard rules, memories. ~80 lines. Heavy — overlaps with CLAUDE.md. -- **Devpulse local prompt** — rewritten session 14. Lean, operational. Has branch list (needed for orchestrator role). ~55 lines. -- **Other branch prompts** — vary wildly. Some copied from devpulse template, some minimal, some empty. No standard. -- **No seedgo standard** for prompt quality. -- **No spawn template** for local prompts — spawn scaffolds branches but doesn't generate a prompt. - -### Key Insight: Three Prompt Layers - -| Layer | File | Injected | Purpose | -|-------|------|----------|---------| -| System | `CLAUDE.md` | Every turn (by Claude Code) | Hard rules, startup, navigation | -| Global | Hook output (`identity_injector.py`) | Every turn (by hook) | AIPass context, terminology, commands | -| Local | `.aipass/aipass_local_prompt.md` | Every turn (by hook) | Branch identity, role-specific guidance | - -**Problem:** System + Global overlap significantly. Both have commands, rules, structure. That's ~110 lines injected every turn with duplication. - -## What Needs Building - -### Phase 1: Prompt Templates -- [ ] Define what goes in each layer (system vs global vs local) — no overlap -- [ ] Create local prompt template for **worker branches** (most branches) -- [ ] Create local prompt template for **orchestrator** (devpulse only) -- [ ] Create local prompt template for **infrastructure** branches (drone, prax, seedgo — they serve others) -- [ ] Add template to spawn's scaffold so new branches get a prompt automatically - -### Phase 2: Consolidate System + Global -- [ ] Audit overlap between CLAUDE.md and hook-injected global prompt -- [ ] Decide: merge into one, or split responsibilities cleanly -- [ ] Option A: CLAUDE.md has rules + startup, hook has AIPass context (no rules) -- [ ] Option B: Kill CLAUDE.md, put everything in hook (single source) -- [ ] Option C: Kill hook injection, put everything in CLAUDE.md (simpler) -- [ ] Reduce total injected tokens - -### Phase 3: Seedgo Standard -- [ ] Add prompt standard to seedgo audit pack (e.g. `prompt_quality`) -- [ ] Checks: file exists, not empty, has Identity section, has Current Context, under max lines -- [ ] Checks: no directory structures (belong in README), no duplicated rules (belong in system prompt) -- [ ] Checks: has @branch address references where needed (orchestrator only) - -### Phase 4: Migrate All Branches -- [ ] Audit all 15 branch prompts against the template -- [ ] Rewrite each to match template -- [ ] Run seedgo prompt_quality checker on all - -## Design Decisions - -| Decision | Options | Leaning | Notes | -|----------|---------|---------|-------| -| System + Global merge | A: split clean / B: merge to CLAUDE.md / C: merge to hook | A | Hook gives dynamic injection, CLAUDE.md is static. Both have value. | -| Branch list in prompts | Devpulse only / All branches / None | Devpulse only | Orchestrator needs awareness. Workers get instructions, don't need full map. | -| Prompt max lines | 30 / 50 / 80 | 50 | Worker branches ~30, orchestrator ~55, infra ~40. Ceiling at 80. | -| Seedgo enforcement | Advisory / Blocking | Advisory first | Start with checklist, not gate. Tighten later. | -| Local prompt sections | Fixed template / Flexible | Fixed core + flexible extras | Identity + How You Work + Current Context required. Rest optional per role. | - -### What Goes Where - -| Content | Layer | Why | -|---------|-------|-----| -| Startup protocol | System (CLAUDE.md) | Universal, rarely changes | -| Hard rules (imports, paths) | System (CLAUDE.md) | Universal, authoritative | -| Memory update guidance | System (CLAUDE.md) | Universal behavior | -| AIPass terminology | Global (hook) | Context, not rules | -| Branch structure template | Global (hook) | Shows what a branch looks like | -| Command reference | Global (hook) | Available to all, operational | -| Dispatch syntax | Global (hook) | Operational pattern | -| Branch identity/role | Local | Unique per branch | -| Branch-specific commands | Local | What THIS branch does | -| Branch list (15) | Local (devpulse only) | Orchestrator needs it | -| Current context/session | Local | Unique per branch | - -### Worker Branch Template (draft) - -``` -# {BRANCH} — Branch Prompt - -## Identity -You are {BRANCH} — {one-line role}. {What you do, what you don't do.} - -## Your Commands -{Branch-specific commands from --help, just the key ones} - -## How You Work -{Role-specific operational guidance — 3-5 bullets} - -## Current Context (Session N) -**Date:** YYYY-MM-DD -{Active work, blockers, recent changes} -``` - -## Ideas - -- Could generate prompt health report: `drone @seedgo prompt-audit` showing all branches, line counts, missing sections -- Prompt version tracking — when template changes, detect stale prompts across branches -- "Prompt diff" tool — compare branch prompt against template, show gaps -- Dynamic section injection — hook could inject inbox count, active plans, etc. (already does email count) - -## Relationships -- **Related DPLANs:** DPLAN-0001 (system bootstrap — prompts are part of bootstrap) -- **Related FPLANs:** Will spawn FPLANs for Phase 2 (consolidation) and Phase 4 (migration) -- **Owner branches:** @devpulse (design), @seedgo (standard), @spawn (template) - -## Status -- [x] Planning -- [ ] In Progress -- [ ] Ready for Execution -- [ ] Complete -- [ ] Abandoned - -## Notes -- Session 14: Discovered prompt vs memory distinction through Patrick's feedback. "Prompts are signposts, memories are knowledge." Every-turn injection must be minimal. -- The hook-injected global prompt is the biggest opportunity — it's ~80 lines injected every single turn across every branch. Reducing that by even 30% saves significant tokens per session. -- Patrick's key insight: "branches take instructions from devpulse — they don't need the full map, just their own commands and identity." - ---- -*Created: 2026-03-08* -*Updated: 2026-03-08* diff --git a/src/aipass/devpulse/docs/FPLAN-001_path_rewire_portability_2026-03-06.md b/src/aipass/devpulse/docs/FPLAN-001_path_rewire_portability_2026-03-06.md deleted file mode 100644 index 5d224e43..00000000 --- a/src/aipass/devpulse/docs/FPLAN-001_path_rewire_portability_2026-03-06.md +++ /dev/null @@ -1,194 +0,0 @@ -# FPLAN-001 - AIPass Path Rewire & Portability Fix (MASTER PLAN) - -**Created**: 2026-03-06 -**Branch**: src/aipass/devpulse -**Status**: Phase 5 (Final Verification) -**Type**: Master Plan (Multi-Phase) -**Reference**: DPLAN-047 (Path.home() Purge) - ---- - -## Project Overview - -### Goal -All 10 AIPass modules import cleanly on ANY system. Zero filesystem assumptions. Code runs after `pip install -e .` on Mac, Linux, CI runners, Docker — anywhere. - -### CRITICAL: This is a Public Pip Package -AIPass is a PUBLIC pip package installable on ANY machine. There is NO `/home/aipass`. There is NO `aipass_core` directory. There is NO `.venv` at a known location. None of that exists outside Dev-Pass (the private source repo). - -**Dev-Pass vs AIPass confusion is the #1 risk.** Code was ported from Dev-Pass where `/home/aipass` and `aipass_core` are real paths. Here, they are ghosts that crash on import. - -### Only Valid Path Patterns -```python -# 1. Package-relative (where the code lives) -Path(__file__).resolve().parents[N] - -# 2. Walk-up to repo root (finds AIPASS_REGISTRY.json) -def _find_repo_root() -> Path: - current = Path(__file__).resolve().parent - for parent in [current] + list(current.parents): - if (parent / "AIPASS_REGISTRY.json").exists(): - return parent - return Path.cwd() - -# 3. User's working directory -Path.cwd() -``` - -**Everything else is Dev-Pass baggage and MUST be removed or rewired.** - -### Seedgo Standards Adjustment -Seedgo standards were built for Dev-Pass. Standards that don't align with public pip package reality MUST be adjusted: -- Shebang requirements: REMOVED (irrelevant for pip packages) -- `/home/aipass` reference paths in standards content: must be updated -- Any standard assuming filesystem structure beyond the package itself - -### Reference Documentation -- `DPLAN-047_path_home_purge_portability_2026-03-06.md` (repo root) -- `docs/sub_agent_drops/path_home_audit.md` (full audit from session 1) -- `spawn/templates/agent.template/` (reference for correct patterns) - -### Success Criteria -1. `pip install -e .` clean -2. All module top-level imports work (`from aipass.{module} import ...`) -3. `drone systems` shows 10 branches -4. `drone @seedgo verify` passes -5. `drone @seedgo audit aipass` runs without import crashes -6. Zero `Path.home()` or `/home/aipass` in functional code (comments/docstrings updated too) -7. Zero `aipass_core` references in functional code - ---- - -## What We're Cleaning Up - -This is a cleanup of Dev-Pass baggage. The code was ported from a private system that assumes `/home/aipass/aipass_core/` exists. We're making it universal. - -### Fix Categories -1. **FUNCTIONAL** — `Path.home()`, `Path("/home/aipass/...")`, `aipass_core` in actual code logic → MUST fix or code crashes -2. **COMMENTS/DOCSTRINGS** — References to `/home/aipass` in documentation strings → Update to reflect package-relative reality -3. **STRING COMPARISONS** — Code checking for `aipass_core` in path parts → Adapt to new structure (`src/aipass/`) - -### Fix Pattern - -```python -# WRONG — Dev-Pass patterns (CRASH on any other system) -AIPASS_ROOT = Path.home() / "aipass_core" -ECOSYSTEM_ROOT = Path("/home/aipass") -SYSTEM_LOGS_DIR = Path("/home/aipass/system_logs") - -# RIGHT — Package-relative -MODULE_ROOT = Path(__file__).resolve().parents[N] # N = depth to module root - -# RIGHT — Walk-up finder (proven in drone/seedgo) -def _find_repo_root() -> Path: - current = Path(__file__).resolve().parent - for parent in [current] + list(current.parents): - if (parent / "AIPASS_REGISTRY.json").exists(): - return parent - return Path.cwd() - -# RIGHT — Logs go in package-relative location -LOGS_DIR = Path(__file__).resolve().parents[3] / "logs" -``` - ---- - -## Phase Definitions - -### Phase 1: Safe Modules (drone, cli, spawn, devpulse) — COMPLETE -**Goal:** Fix LOW severity modules -**Result:** drone (2 files), cli (12 files), spawn (4 files) — all verified clean -**Remaining:** drone/config.py has 1 Path.home() for registry (quick fix), cli/__init__.py has 1 string comparison (cosmetic) - -### Phase 2: Prax — COMPLETE -**Goal:** `from aipass.prax import logger` works AND deeper handler imports don't crash -**Scope:** ~47 hits across functional code, comments, and string comparisons. Key files: introspection.py (14), branch_detector.py (8), monitor_module.py (6), setup.py (5), log_watcher.py (4) -**Result:** 16 files functional fixes + 17 files comments/docstrings updated. All imports verified. -**Critical:** Unblocks all other modules since they import prax - -### Phase 3: Trigger + Flow — COMPLETE -**Goal:** Fix CRITICAL import-time crashes + all Dev-Pass path references -**Scope:** trigger (~50 hits), flow (~70 hits). CRITICAL: plan_file.py ECOSYSTEM_ROOT, registry_monitor.py ECOSYSTEM_ROOT -**Result:** Trigger 23 files fixed, flow 37 files fixed. All CRITICAL crashes resolved. -**Parallel:** Yes, 2 agents - -### Phase 4: AI Mail + API — COMPLETE -**Goal:** Fix the heaviest modules -**Scope:** ai_mail (~80 hits), api (~70 hits). CRITICAL: ai_mail/registry/read.py, api/log_streamer.py -**Result:** ai_mail 37 files fixed, api 35 files fixed. All CRITICAL crashes resolved. -**Parallel:** Yes, 2 agents - -### Phase 5: Seedgo Standards + Verification — IN PROGRESS -**Goal:** Fix seedgo's own Dev-Pass references + full system test -**Scope:** ~60 hits in seedgo standards content (reference strings pointing to /home/aipass/standards/). Remove shebang standard. Update all reference paths. Run full import + drone verification. -**Critical:** Seedgo standards must reflect the public pip package reality -**Progress:** -- Seedgo standards: 30 files updated (Dev-Pass reference paths) -- Shebang standard: CREATED (new SHEBANG check that fails files with shebangs) -- Shebangs stripped: 205 files cleaned codebase-wide -- Meta docs: aligned to match checker format -- 4 bare import violations: FIXED -- Full verification: All 10 modules import clean, `drone systems` works -- Remaining: Running `seedgo audit` for final violations - ---- - -## Phase Tracking - -### Phase 1: Safe Modules -- **Status:** COMPLETE -- **Agents:** 4 (drone, cli, spawn, devpulse) -- **Result:** All verified clean. Minor residual hits (drone config.py, cli __init__.py) - -### Phase 2: Prax -- **Status:** COMPLETE -- **Agents:** 1 -- **Result:** 16 files functional fixes, 17 files comments/docstrings. All imports verified. - -### Phase 3: Trigger + Flow -- **Status:** COMPLETE -- **Agents:** 2 -- **Result:** Trigger 23 files, flow 37 files. All CRITICAL import crashes fixed. - -### Phase 4: AI Mail + API -- **Status:** COMPLETE -- **Agents:** 2 -- **Result:** ai_mail 37 files, api 35 files. All CRITICAL import crashes fixed. - -### Phase 5: Seedgo Standards + Verification -- **Status:** IN PROGRESS -- **Agents:** 2 (1 for seedgo cleanup, 1 for final verification) -- **Progress:** 30 seedgo files updated, shebang standard created, 205 shebangs stripped, 4 bare imports fixed. All 10 modules import clean. Remaining: final seedgo audit pass. - ---- - -## Issues Log - -| Phase | Issue | Severity | Attempted | Status | -|-------|-------|----------|-----------|--------| -| 2 | Prax agent lost during session compaction | LOW | Retry deployed | RESOLVED | -| 3 | trigger/plan_file.py ECOSYSTEM_ROOT crash | CRITICAL | Phase 3 | RESOLVED | -| 3 | flow/registry_monitor.py ECOSYSTEM_ROOT crash | CRITICAL | Phase 3 | RESOLVED | -| 4 | ai_mail/registry/read.py import crash | CRITICAL | Phase 4 | RESOLVED | -| 4 | api/log_streamer.py import crash | CRITICAL | Phase 4 | RESOLVED | -| 5 | 4 bare import violations (missing aipass. prefix) | HIGH | Phase 5 | RESOLVED | -| 5 | 205 files with shebangs (irrelevant for pip pkg) | MEDIUM | Phase 5 | RESOLVED | -| 5 | Seedgo standards referencing Dev-Pass paths | HIGH | Phase 5 | RESOLVED | -| 5 | Final seedgo audit for remaining violations | MEDIUM | In progress | OPEN | - ---- - -## Notes - -- **PUBLIC PIP PACKAGE** — This is the core principle. Zero filesystem assumptions. Works on any machine. -- **Dev-Pass confusion is the #1 risk** — All code was ported from a system where /home/aipass exists. Be vigilant. -- Seedgo standards built for Dev-Pass MUST be adjusted: shebang standard removed, reference paths updated -- Shebangs are IRRELEVANT for pip packages — don't waste time on them, focus on functional path violations -- Some modules reference Dev-Pass infrastructure (AI_CENTRAL, MEMORY_BANK, telegram) — guard or remove -- 2-attempt rule: if a fix breaks something, note it and move on -- Comments/docstrings referencing /home/aipass should be updated too — clean break from Dev-Pass - ---- - -## Definition of Done -All 5 success criteria pass in Docker container. diff --git a/src/aipass/flow/FPLAN-0005_spawn_branch_scaffold_audit_2026-03-07.md b/src/aipass/flow/FPLAN-0005_spawn_branch_scaffold_audit_2026-03-07.md deleted file mode 100644 index 468292fe..00000000 --- a/src/aipass/flow/FPLAN-0005_spawn_branch_scaffold_audit_2026-03-07.md +++ /dev/null @@ -1,279 +0,0 @@ -# FPLAN-0005 - Spawn Branch Scaffold Audit - -**Created**: 2026-03-07 -**Branch**: flow -**Status**: Active -**Type**: Standard Plan - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building features or modules -- Single focused construction tasks -- Sub-plans within a master plan - ---- - -## When to Use This vs Master Plan - -| This (Default) | Master Plan | -|----------------|-------------| -| Single focused task | 3+ phases, complex build | -| Self-contained | Roadmap + multiple sub-plans | -| Quick build | Multi-session project | -| One phase of a master | Entire branch/system build | - -**Need a master plan?** `drone @flow create "subject" master` - ---- - -## Branch Directory Structure - -Use dedicated directories - don't scatter files: - -| Directory | Purpose | -|-----------|---------| -| `apps/` | Code (modules/, handlers/) | -| `tests/` | All test files | -| `tools/` | Utility scripts | -| `artifacts/` | Agent outputs | -| `docs/` | Documentation | - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans | Write code | -| Give instructions | Run tests | -| Review output | Read/modify files | -| Course correct | Research/exploration | -| Update memories | Heavy lifting | -| Send status emails | Single-task execution | - -**Pattern:** Instruct agent → Wait for completion → Review output → Next step - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "subject" # Create plan (. = current dir) -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## Planning Phase - -### Goal -All 10 branches are fully scaffolded citizens — each has `.trinity/` identity, `.aipass/` prompt, `.ai_mail.local/` mailbox, and all standard dirs from the spawn template. No code is overwritten — only missing pieces are added. - -### Current State (Audit) - -| Branch | .trinity/ | .aipass/ | .ai_mail.local/ | logs/ | Status | -|--------|:---------:|:--------:|:---------------:|:-----:|--------| -| **spawn** | YES | YES | YES | YES | COMPLETE | -| **devpulse** | YES | YES | YES | YES | COMPLETE | -| **ai_mail** | YES | MISSING | MISSING | YES | PARTIAL | -| **flow** | MISSING | MISSING | MISSING | YES | NEEDS SCAFFOLD | -| **prax** | MISSING | MISSING | MISSING | YES | NEEDS SCAFFOLD | -| **seedgo** | MISSING | MISSING | MISSING | YES | NEEDS SCAFFOLD | -| **trigger** | MISSING | MISSING | MISSING | YES | NEEDS SCAFFOLD | -| **api** | MISSING | MISSING | MISSING | MISSING | NEEDS SCAFFOLD | -| **cli** | MISSING | MISSING | MISSING | MISSING | NEEDS SCAFFOLD | -| **drone** | MISSING | MISSING | MISSING | MISSING | NEEDS SCAFFOLD | - -### Approach -Deploy agents (one or more per branch) to add missing scaffold. Each agent: -1. Reads spawn's template (`src/aipass/spawn/templates/agent.template/`) to understand the standard -2. Reads the target branch to see what already exists -3. Adds ONLY what's missing — never overwrites existing files -4. Fills `.trinity/passport.json` with correct branch name, role, email (@name) -5. Creates stub `.aipass/branch_system_prompt.md` with branch-specific context -6. Sets up `.ai_mail.local/` mailbox structure - -**Critical:** Existing code in `apps/`, `README.md`, etc. must NOT be touched. This is additive only. - -### Reference Documents -- Template source: `src/aipass/spawn/templates/agent.template/` -- Mock example: `src/aipass/spawn/templates/agent_mock_branch/` -- Registry: `AIPASS_REGISTRY.json` (branch emails, paths, roles) -- Completed examples: `src/aipass/spawn/` and `src/aipass/devpulse/` (reference citizens) - ---- - -## Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - ---- - -## Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Execution Log - -### 2026-03-07 -- [ ] Created FPLAN-0005 -- [ ] Agent deployed for: [task] -- [ ] Agent completed: [outcome] -- [ ] Seedgo checklist passed: [file] -- [ ] Memories updated - -**Log Pattern:** Task → Agent → Outcome → Quality check → Next - -**If production stops (critical blocker):** -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0005" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - ---- - -## Notes - -[Working notes, issues encountered, decisions made] - ---- - -## Completion Checklist - -### Before Closing - -- [ ] All goals achieved -- [ ] Agent output reviewed and verified -- [ ] Seedgo checklist on new code: `drone @seedgo checklist ` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - session/work log - - [ ] `BRANCH.observations.json` - patterns learned (if any) -- [ ] README.md updated (if build changed status/capabilities) -- [ ] Status email sent to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0005 Complete" "Summary of what was done, any issues, outcomes" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -### Definition of Done -All 10 branches have: `.trinity/passport.json`, `.trinity/local.json`, `.trinity/observations.json`, `.aipass/branch_system_prompt.md`, `.ai_mail.local/inbox.json`, `logs/` directory. No existing code was overwritten. `drone @seedgo audit aipass` shows improvement across the board. - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0005 -``` diff --git a/src/aipass/flow/FPLAN-0007_seedgo_architecture_checker_activation_2026-03-07.md b/src/aipass/flow/FPLAN-0007_seedgo_architecture_checker_activation_2026-03-07.md deleted file mode 100644 index 740558e9..00000000 --- a/src/aipass/flow/FPLAN-0007_seedgo_architecture_checker_activation_2026-03-07.md +++ /dev/null @@ -1,253 +0,0 @@ -# FPLAN-0007 - Seedgo Architecture Checker Activation - -**Created**: 2026-03-07 -**Branch**: flow -**Status**: Active -**Type**: Standard Plan - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building features or modules -- Single focused construction tasks -- Sub-plans within a master plan - ---- - -## When to Use This vs Master Plan - -| This (Default) | Master Plan | -|----------------|-------------| -| Single focused task | 3+ phases, complex build | -| Self-contained | Roadmap + multiple sub-plans | -| Quick build | Multi-session project | -| One phase of a master | Entire branch/system build | - -**Need a master plan?** `drone @flow create "subject" master` - ---- - -## Branch Directory Structure - -Use dedicated directories - don't scatter files: - -| Directory | Purpose | -|-----------|---------| -| `apps/` | Code (modules/, handlers/) | -| `tests/` | All test files | -| `tools/` | Utility scripts | -| `artifacts/` | Agent outputs | -| `docs/` | Documentation | - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans | Write code | -| Give instructions | Run tests | -| Review output | Read/modify files | -| Course correct | Research/exploration | -| Update memories | Heavy lifting | -| Send status emails | Single-task execution | - -**Pattern:** Instruct agent → Wait for completion → Review output → Next step - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "subject" # Create plan (. = current dir) -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## Planning Phase - -### Goal -[What do you want to achieve? Specific end state.] - -### Approach -[How will agents tackle this? What instructions will they need?] - -### Reference Documents -[List any planning docs, specs, or examples to reference] - ---- - -## Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - ---- - -## Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Execution Log - -### 2026-03-07 -- [ ] Created FPLAN-0007 -- [ ] Agent deployed for: [task] -- [ ] Agent completed: [outcome] -- [ ] Seedgo checklist passed: [file] -- [ ] Memories updated - -**Log Pattern:** Task → Agent → Outcome → Quality check → Next - -**If production stops (critical blocker):** -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0007" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - ---- - -## Notes - -[Working notes, issues encountered, decisions made] - ---- - -## Completion Checklist - -### Before Closing - -- [ ] All goals achieved -- [ ] Agent output reviewed and verified -- [ ] Seedgo checklist on new code: `drone @seedgo checklist ` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - session/work log - - [ ] `BRANCH.observations.json` - patterns learned (if any) -- [ ] README.md updated (if build changed status/capabilities) -- [ ] Status email sent to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0007 Complete" "Summary of what was done, any issues, outcomes" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -### Definition of Done -[What specifically defines complete for this plan?] - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0007 -``` diff --git a/src/aipass/flow/FPLAN-0008_spawn_rebuild_full_branch_lifecycle_mana_2026-03-07.md b/src/aipass/flow/FPLAN-0008_spawn_rebuild_full_branch_lifecycle_mana_2026-03-07.md deleted file mode 100644 index 95b2a865..00000000 --- a/src/aipass/flow/FPLAN-0008_spawn_rebuild_full_branch_lifecycle_mana_2026-03-07.md +++ /dev/null @@ -1,635 +0,0 @@ -# FPLAN-0008 - Spawn Rebuild — Full Branch Lifecycle Manager (MASTER PLAN) - -**Created**: 2026-03-07 -**Branch**: flow -**Status**: Active -**Type**: Master Plan (Multi-Phase) - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. They're the structured way to execute work without constant human oversight. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building new branches/modules -- Implementing features -- Multi-phase construction projects -- Autonomous execution - ---- - -## Master Plan vs Default Plan - -| | Master Plan | Default Plan | -|---|-------------|--------------| -| **Use when** | 3+ phases, complex build | Single focused task | -| **Structure** | Roadmap + sub-plans | Self-contained | -| **Phases** | Multiple, sequential | One | -| **Sub-plans** | Yes, one per phase | No | -| **Typical use** | Build entire branch | One phase of master | - -**Pattern:** -``` -Master Plan (roadmap) -├── Sub-plan Phase 1 (default template) -├── Sub-plan Phase 2 (default template) -├── Sub-plan Phase 3 (default template) -└── Sub-plan Phase 4 (default template) -``` - -**How to start:** -1. The user provides planning doc or instructions (coordinate with @devpulse) -2. Branch manager reads and understands scope -3. Branch manager creates master plan: `drone @flow create . "Build X" master` -4. Branch manager fills in phases, then executes autonomously - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans & sub-plans | Write code | -| Define phases | Run tests | -| Give agent instructions | Read/modify files | -| Review agent output | Research/exploration | -| Course correct | Heavy lifting | -| Update memories | Single-task execution | -| Send status emails | Build deliverables | -| Track phase progress | Quality checks on code | - -**Master Plan Pattern:** Define all phases → Create sub-plan for Phase 1 → Deploy agent → Review → Close sub-plan → Email update → Next phase - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. For master plans spanning multiple domains, identify which branches to consult during phase definitions. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. Low friction both ways. - -```bash -# Create it at plan start -echo "# Notepad - FPLAN-0008" > notepad.md -``` - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "Phase X: subject" # Create sub-plan (. = current dir) -drone @flow create . "subject" master # Create master plan -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow status # Plan status -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit (before master close) -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail inbox # Check your inbox -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## What is a Master Plan? - -Master Plans are for **complex multi-phase projects**. You define all phases upfront, then create focused sub-plans for each phase. - -**When to use:** -- 3+ distinct sequential phases -- Work spanning multiple sessions -- Need clear phase completion milestones -- Complex builds requiring sustained focus - -**Pattern:** Master Plan = Roadmap | Sub-Plans = Focused Execution - ---- - -## Project Overview - -### Goal -Rebuild spawn from a create-only tool into a **full branch lifecycle manager** — matching and exceeding Dev-Pass cortex capabilities. When complete, spawn can create, update, delete, and sync branches. Template changes propagate system-wide with a single command. 100% seedgo audit compliance. - -### Reference Documentation -- **Dev-Pass cortex** (reference, not source): `/home/coder/share/cortex/` - - `apps/modules/update_branch.py` — 965-line update system (the crown jewel) - - `apps/handlers/branch/change_detection.py` — ID-based rename detection - - `apps/handlers/branch/reconcile.py` — pre/post-flight verification - - `apps/handlers/json/ops.py` — deep merge + migrations - - `apps/handlers/registry/meta_ops.py` — template registry + branch metadata ops - - `apps/handlers/templates/sync.py` — managed file sync from source branches -- **Our spawn** (current state): `/home/coder/workspace/AIPass/src/aipass/spawn/` -- **Template**: `spawn/templates/agent.template/` -- **Existing tracking**: `.spawn/` dir per branch (template_registry, migrations stub, ignore files) -- **Registry**: `AIPASS_REGISTRY.json` at repo root - -### Success Criteria -1. `drone @spawn create @newbranch` — creates branch from template (already works, wire through drone) -2. `drone @spawn update @branch` — fills missing scaffold, deep merges JSON, preserves code -3. `drone @spawn update --all` — batch update all branches -4. `drone @spawn sync-registry` — repair registry against filesystem -5. `drone @spawn delete @branch` — archive + deregister (with confirmation) -6. `.spawn/.branch_meta.json` tracks files by ID + hash per branch -7. `.spawn/.migrations.json` executes structural JSON transforms -8. Python files (.py) NEVER auto-overwritten — user code protected -9. Dry-run mode (`--dry-run`) for preview without execution -10. `drone @seedgo audit aipass` — spawn branch passes at highest possible score - ---- - -## Branch Directory Structure - -Every branch has dedicated directories. Use them correctly: - -``` -branch/ -├── apps/ # Code (modules/, handlers/) -├── tests/ # All test files go here -├── tools/ # Utility scripts, helpers -├── artifacts/ # Agent outputs (reports, logs) -├── docs/ # Documentation -└── logs/ # Execution logs -``` - -**Rules:** -- Tests → `tests/` (not root, not random locations) -- Tools/scripts → `tools/` -- Agent artifacts → `artifacts/` -- Create subdirs if needed: `mkdir -p artifacts/reports artifacts/logs` -- **Never delete** - devpulse manages cleanup -- Future: artifacts auto-roll to Memory Bank - ---- - -## Phase Definitions - -Define ALL phases before starting work: - -### Phase 1: Drone Adapter + CLI Wiring -**Goal:** Make spawn routable via `drone @spawn` — currently spawn is only callable directly, not through drone routing. -**Agent Task:** -- Create `spawn/apps/handlers/drone_adapter.py` following the pattern from other branches (e.g., `drone/apps/handlers/module_registry.py`) -- Register spawn in drone's module registry so `drone @spawn` resolves -- Wire existing `create` command through adapter -- Add `--help` output listing all commands (create, update, delete, sync-registry) -- Stub command routing for future commands (update, delete, sync-registry) — they can return "not yet implemented" -**Deliverables:** -- `spawn/apps/handlers/drone_adapter.py` -- Updated module registry entry -- `drone @spawn --help` works -- `drone @spawn create` routes to existing create logic -- Tests in `spawn/tests/` - -### Phase 2: Branch Metadata + Reconciliation Handlers -**Goal:** Build the tracking infrastructure that update depends on. Each branch needs `.spawn/.branch_meta.json` (ID-based file tracking with hashes). Need handlers for: loading/saving metadata, reconciling tracked state vs filesystem, and change detection. -**Agent Task:** -- Create `spawn/apps/handlers/meta_ops.py` — load/save `.branch_meta.json`, generate metadata for existing branches (scan filesystem, assign IDs, compute hashes) -- Create `spawn/apps/handlers/reconcile.py` — compare `.branch_meta.json` vs actual filesystem (missing files, untracked files, hash mismatches) -- Create `spawn/apps/handlers/change_detection.py` — compare template registry vs branch metadata: detect renames (by ID), additions, content updates (by hash), pruned files -- Create `spawn/apps/handlers/json_ops.py` — deep merge (template structure + existing values), load/apply migrations from `.migrations.json` -- Reference cortex handlers for logic patterns but use AIPass conventions (imports, prax logging, Path resolution) -**Deliverables:** -- `spawn/apps/handlers/meta_ops.py` -- `spawn/apps/handlers/reconcile.py` -- `spawn/apps/handlers/change_detection.py` -- `spawn/apps/handlers/json_ops.py` -- Tests in `spawn/tests/` - -### Phase 3: Update Command -**Goal:** Build `drone @spawn update @branch` — the core feature. Uses Phase 2 handlers to: load tracking, detect changes, backup, apply changes (add missing files, deep merge JSON, archive pruned), update tracking. -**Agent Task:** -- Create `spawn/apps/modules/update.py` — orchestrator for the update workflow: - 1. Resolve branch path from registry - 2. Load `.spawn/.template_registry.json` + `.spawn/.branch_meta.json` - 3. If no branch_meta → generate from filesystem scan (first-time adoption) - 4. Pre-flight reconciliation (reconcile.py) - 5. Change detection (change_detection.py) - 6. If `--dry-run` → print what would change, exit - 7. Create backup of branch state - 8. Execute: renames → additions → JSON deep merges → archive pruned - 9. NEVER overwrite .py files — log as "manual review needed" - 10. Update `.spawn/.branch_meta.json` with new state - 11. Post-flight reconciliation to verify -- Wire `update` command into drone_adapter.py -- Support `--dry-run`, `--all` (batch), `--trace` (verbose logging) -**Deliverables:** -- `spawn/apps/modules/update.py` -- Updated `drone_adapter.py` with `update` routing -- `drone @spawn update @branch` works end-to-end -- `drone @spawn update --all` iterates all registered branches -- `drone @spawn update --dry-run @branch` previews without executing -- Tests in `spawn/tests/` - -### Phase 4: Delete + Sync-Registry + Template Sync -**Goal:** Complete the lifecycle with delete (archive + deregister), registry repair, and managed file sync. -**Agent Task:** -- Create `spawn/apps/modules/delete.py`: - - Move branch to `.archive/deleted_branches/{name}_{timestamp}/` - - Remove from AIPASS_REGISTRY.json - - Require `--yes` flag to skip confirmation (default: confirm) - - Fire `branch_deleted` trigger event -- Create `spawn/apps/modules/sync_registry.py`: - - Scan `src/aipass/` for branches with `.trinity/passport.json` - - Compare against AIPASS_REGISTRY.json - - Report stale entries (registered but missing) and unregistered branches - - `--fix` flag to auto-repair -- Create `spawn/apps/modules/sync_templates.py`: - - Define `template_owners.json` — maps template files to authoritative source branches - - Pull latest versions of managed files from source branches into template - - Example: if devpulse owns DASHBOARD.local.json schema → sync latest into template -- Wire all commands into drone_adapter.py -- Add `drone @spawn --help` showing complete command list -**Deliverables:** -- `spawn/apps/modules/delete.py` -- `spawn/apps/modules/sync_registry.py` -- `spawn/apps/modules/sync_templates.py` -- `spawn/apps/handlers/templates/template_owners.json` -- Updated `drone_adapter.py` -- Tests in `spawn/tests/` - -### Phase 5: Seedgo Compliance + Integration Testing -**Goal:** Get spawn to highest possible seedgo audit score. End-to-end integration tests. Verify the full lifecycle: create → update → re-update after template change → delete. -**Agent Task:** -- Run `drone @seedgo audit aipass` and focus on spawn branch violations -- Fix all fixable violations (imports, structure, docstrings, logging) -- Create integration test suite: - - Test create → verify scaffold complete - - Test update on fresh branch → verify metadata generated - - Test update after template change → verify additions detected - - Test update --dry-run → verify no filesystem changes - - Test JSON deep merge → verify values preserved, structure updated - - Test .py file protection → verify Python never overwritten - - Test delete → verify archive created + registry cleaned - - Test sync-registry → verify stale/missing detection -- Update spawn README.md with complete API documentation -- Update spawn's `.trinity/` identity files -**Deliverables:** -- All seedgo violations fixed -- `spawn/tests/test_lifecycle.py` — integration test suite -- Updated `spawn/README.md` -- Updated `.trinity/passport.json` reflecting new capabilities -- Final `drone @seedgo audit aipass` report showing spawn score - ---- - -## Execution Philosophy - -### Autonomous Power-Through - -Master plans are for **autonomous execution**. Don't halt production every phase waiting for review. - -**The Pattern:** -- Power through all phases -- Accumulate issues as you go -- Deal with issues at the end -- The user reviews the final result, not every step - -**Why this works:** -- Context is precious - don't burn it chasing bugs -- Complete picture reveals which issues actually matter -- Many "bugs" resolve themselves when later phases complete -- Coordination time is for decisions, not babysitting - -### The 2-Attempt Rule - -When agent encounters an issue: - -``` -Attempt 1 → Failed? - ↓ -Attempt 2 → Failed? - ↓ -STOP. Mark as issue. Move on. -``` - -**Do NOT:** -- Try 5 different approaches -- Go down rabbit holes -- Burn context debugging -- Stop production for every error - -**DO:** -- Note the issue clearly -- Note what was tried -- Move to next task -- Let branch manager decide priority - -### Critical vs Non-Critical Issues - -When you see an issue, decide: - -| Question | If YES → | If NO → | -|----------|----------|---------| -| Does this block ALL future phases? | STOP. Investigate. | Continue. | -| Can the system work around this? | Continue. | STOP. Investigate. | -| Is this a syntax/import error? | Quick fix, continue. | - | -| Is this a logic/design problem? | Note it. Continue. | - | - -**Critical (stop production):** -- Core module won't import at all -- Database/file system inaccessible -- Fundamental architecture wrong - -**Non-critical (note and continue):** -- One command throws error but others work -- Registry not updating properly -- Edge case not handled -- Test failing but code runs - -**Pattern:** Note issue → Continue building → Fix at end with complete picture - -### False Positives Awareness - -Seedgo audits are helpful but not infallible. - -**When Seedgo flags something:** -1. Check if the code is actually correct from your understanding -2. If you're confident it's right → mark as false positive, move on -3. If you're unsure → note it, continue, review later - -**Don't stop production for:** -- Style preferences (comments, spacing) -- Patterns that differ from Seedgo's but still work -- Checks that don't apply to your context - -### Forward Momentum Summary -- **Don't stop to fix bugs during phases** - Note them, keep moving -- **Get complete picture first** - All phases done, THEN systematic fixes -- **Prevents:** Bug-fixing rabbit holes, premature optimization, scope creep -- **Review happens at END** - not every phase - -### Production Stop Protocol - -If something causes production to STOP (critical blocker), **immediately email @devpulse**: - -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0008" "Phase X halted. Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - -**Never leave a branch stopped without reporting.** The orchestration hub needs visibility into all work. - -### Monitoring Resources - -For quick status checks and debugging, these resources are available: - -| Resource | Location | Purpose | -|----------|----------|---------| -| Branch logs | `logs/` directory | Local execution logs | -| JSON tree | `apps/json_templates/` | Module firing status | -| Prax monitor | `drone @prax monitor` | Real-time system events | -| Seedgo audit | `drone @seedgo audit @branch` | Code quality check | - -Use these when you need to confirm status or investigate issues. - -### Agent Deployment Per Phase -Each phase = focused agent deployment: -1. Create sub-plan: `drone @flow create . "Phase X: [name]"` -2. Write agent instructions in sub-plan -3. Deploy agent with single-task focus -4. Review agent output (don't rebuild yourself) -5. Seedgo checklist on new code -6. Close sub-plan -7. Update memories -8. Email status to @devpulse -9. Next phase - -### Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - -### Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task for this phase] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture: apps/modules/handlers) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user in the planning doc -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Phase Tracking - -### Phase 1: Drone Adapter + CLI Wiring -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 2: Branch Metadata + Reconciliation Handlers -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 3: Update Command -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 4: Delete + Sync-Registry + Template Sync -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 5: Seedgo Compliance + Integration Testing -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - ---- - -## Issues Log - -Track issues here as you encounter them. Don't fix during build - log and continue. - -| Phase | Issue | Severity | Attempted | Status | -|-------|-------|----------|-----------|--------| -| 1 | [description] | Low/Med/High | [what was tried] | Open/Resolved | -| 2 | [description] | Low/Med/High | [what was tried] | Open/Resolved | - -**Severity Guide:** -- **High:** Blocks future phases, must fix before continuing -- **Med:** Affects functionality but can work around -- **Low:** Cosmetic, edge case, or false positive - -**End of Build:** Review this log. Tackle High→Med→Low. Some Low issues may not need fixing. - ---- - -## Master Plan Notes - -**Cross-Phase Patterns:** -[Patterns discovered that span multiple phases] - -**Blockers & Resolutions:** -[Significant blockers and how resolved] - -**Adjustments:** -[Changes to planned phases - scope changes, phases added/merged] - ---- - -## Final Completion Checklist - -### Before Closing Master Plan - -- [ ] All phases complete -- [ ] All sub-plans closed -- [ ] Issues Log reviewed - High/Med issues addressed -- [ ] Full branch audit: `drone @seedgo audit @branch` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - full session log - - [ ] `BRANCH.observations.json` - patterns learned -- [ ] README.md updated (status, architecture, API - if build changed capabilities) -- [ ] Artifacts reviewed (devpulse manages cleanup) -- [ ] Final email to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0008 MASTER COMPLETE" "Full build summary: phases completed, deliverables, remaining issues (if any)" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -**Note:** Devpulse will perform its own Seedgo audit for visibility into the work. - -### Definition of Done -1. All 5 commands work via drone: `create`, `update`, `delete`, `sync-registry`, `sync-templates` -2. `drone @spawn update --all` successfully updates all 10 branches from template -3. `.spawn/.branch_meta.json` exists in every branch with ID-based tracking -4. JSON deep merge preserves existing values while adopting template structure changes -5. Python files are never auto-overwritten during updates -6. `--dry-run` mode works for update and delete -7. Integration tests pass for full lifecycle (create → update → delete) -8. `drone @seedgo audit aipass` — spawn scores highest possible -9. spawn README.md documents complete API -10. spawn `.trinity/` identity reflects lifecycle manager role - ---- - -## Close Command - -When ALL phases complete and checklist done: -```bash -drone @flow close FPLAN-0008 -``` diff --git a/src/aipass/flow/FPLAN-0009_citizen_classes_template_system_passport_2026-03-07.md b/src/aipass/flow/FPLAN-0009_citizen_classes_template_system_passport_2026-03-07.md deleted file mode 100644 index a810370c..00000000 --- a/src/aipass/flow/FPLAN-0009_citizen_classes_template_system_passport_2026-03-07.md +++ /dev/null @@ -1,609 +0,0 @@ -# FPLAN-0009 - Citizen Classes — Template System + Passport Command (MASTER PLAN) - -**Created**: 2026-03-07 -**Branch**: flow -**Status**: Active -**Type**: Master Plan (Multi-Phase) - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. They're the structured way to execute work without constant human oversight. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building new branches/modules -- Implementing features -- Multi-phase construction projects -- Autonomous execution - ---- - -## Master Plan vs Default Plan - -| | Master Plan | Default Plan | -|---|-------------|--------------| -| **Use when** | 3+ phases, complex build | Single focused task | -| **Structure** | Roadmap + sub-plans | Self-contained | -| **Phases** | Multiple, sequential | One | -| **Sub-plans** | Yes, one per phase | No | -| **Typical use** | Build entire branch | One phase of master | - -**Pattern:** -``` -Master Plan (roadmap) -├── Sub-plan Phase 1 (default template) -├── Sub-plan Phase 2 (default template) -├── Sub-plan Phase 3 (default template) -└── Sub-plan Phase 4 (default template) -``` - -**How to start:** -1. The user provides planning doc or instructions (coordinate with @devpulse) -2. Branch manager reads and understands scope -3. Branch manager creates master plan: `drone @flow create . "Build X" master` -4. Branch manager fills in phases, then executes autonomously - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans & sub-plans | Write code | -| Define phases | Run tests | -| Give agent instructions | Read/modify files | -| Review agent output | Research/exploration | -| Course correct | Heavy lifting | -| Update memories | Single-task execution | -| Send status emails | Build deliverables | -| Track phase progress | Quality checks on code | - -**Master Plan Pattern:** Define all phases → Create sub-plan for Phase 1 → Deploy agent → Review → Close sub-plan → Email update → Next phase - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. For master plans spanning multiple domains, identify which branches to consult during phase definitions. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. Low friction both ways. - -```bash -# Create it at plan start -echo "# Notepad - FPLAN-0009" > notepad.md -``` - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "Phase X: subject" # Create sub-plan (. = current dir) -drone @flow create . "subject" master # Create master plan -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow status # Plan status -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit (before master close) -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail inbox # Check your inbox -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## What is a Master Plan? - -Master Plans are for **complex multi-phase projects**. You define all phases upfront, then create focused sub-plans for each phase. - -**When to use:** -- 3+ distinct sequential phases -- Work spanning multiple sessions -- Need clear phase completion milestones -- Complex builds requiring sustained focus - -**Pattern:** Master Plan = Roadmap | Sub-Plans = Focused Execution - ---- - -## Project Overview - -### Goal -Evolve spawn from a single-template system into a **class-based template system** where citizens have different types (builder, manager, researcher, birthright). Each class has its own template. Commands become class-aware. `update --all` scopes by class. A new `passport` command grants lightweight citizenship without full scaffold. - -### Reference Documentation -- **Current spawn**: `/home/coder/workspace/AIPass/src/aipass/spawn/` -- **Current template**: `spawn/templates/agent.template/` (becomes `builder` template) -- **FPLAN-0008**: Spawn rebuild plan (completed — lifecycle commands working) -- **Session 7 design discussion**: citizen_classes key in local.json + MEMORY.md -- **Dev-Pass cortex templates**: `/home/coder/share/cortex/templates/` (had branch, business_branch, team — same concept, different naming) -- **daemon branch**: `/home/coder/workspace/AIPass/src/aipass/daemon/` — the real-world case that drove this design (needs citizenship without apps/) - -### Success Criteria -1. `drone @spawn create builder @newbranch` — creates full 3-layer branch (current behavior, new syntax) -2. `drone @spawn create manager @ops` — creates manager-class citizen (lighter template) -3. `drone @spawn passport @daemon` — grants birthright only (.trinity/ + .aipass/ + registry) -4. `drone @spawn update builder --all` — updates only builder-class branches -5. `drone @spawn update --all` — BLOCKED with "specify a class" message -6. Passport stores `citizen_class` field — spawn reads it for routing -7. `agent.template/` renamed to `builder/` in templates dir -8. At least 2 templates: `builder` (full) and `birthright` (minimal) -9. All existing branches get `citizen_class: "builder"` in passport -10. 84+ tests still passing, new tests for class-based features - ---- - -## Branch Directory Structure - -Every branch has dedicated directories. Use them correctly: - -``` -branch/ -├── apps/ # Code (modules/, handlers/) -├── tests/ # All test files go here -├── tools/ # Utility scripts, helpers -├── artifacts/ # Agent outputs (reports, logs) -├── docs/ # Documentation -└── logs/ # Execution logs -``` - -**Rules:** -- Tests → `tests/` (not root, not random locations) -- Tools/scripts → `tools/` -- Agent artifacts → `artifacts/` -- Create subdirs if needed: `mkdir -p artifacts/reports artifacts/logs` -- **Never delete** - devpulse manages cleanup -- Future: artifacts auto-roll to Memory Bank - ---- - -## Phase Definitions - -Define ALL phases before starting work: - -### Phase 1: Template Restructure + Class Registry -**Goal:** Reorganize templates directory from single template to class-based structure. Create a class registry that maps class names to template dirs. Rename `agent.template/` to `builder/`. -**Agent Task:** -- Rename `spawn/templates/agent.template/` to `spawn/templates/builder/` -- Create `spawn/templates/birthright/` with minimal template: - - `.trinity/passport.json` (with `citizen_class: "birthright"`) - - `.trinity/local.json` (empty session template) - - `.trinity/observations.json` (empty observations template) - - `.aipass/branch_system_prompt.md` (placeholder prompt) - - `README.md` (minimal) - - `.spawn/.template_registry.json` (generated) -- Create `spawn/apps/handlers/class_registry.py`: - - `CITIZEN_CLASSES` dict mapping class name → template dir - - `get_template_dir(citizen_class)` → returns Path to template - - `get_available_classes()` → returns list of class names - - `validate_class(name)` → bool -- Update `spawn/apps/handlers/meta_ops.py` → `get_template_dir()` now accepts optional `citizen_class` param (default: "builder") -- Update all references to `agent.template` across spawn code -- Update `spawn/templates/agent_mock_branch/` references if needed -- Generate `.template_registry.json` for both builder and birthright templates -**Deliverables:** -- `spawn/templates/builder/` (renamed from agent.template) -- `spawn/templates/birthright/` (new minimal template) -- `spawn/apps/handlers/class_registry.py` -- Updated meta_ops.py -- All existing tests still pass - -### Phase 2: Passport Command + Class-Aware Create -**Goal:** Build the `passport` command for lightweight citizenship. Make `create` class-aware with new syntax. -**Agent Task:** -- Create `spawn/apps/modules/passport.py` (thin module) + `spawn/apps/handlers/passport_ops.py` (implementation): - - `drone @spawn passport @dirname` — grants birthright to existing directory - - Creates .trinity/ with passport (citizen_class: "birthright"), local.json, observations.json - - Creates .aipass/ with branch_system_prompt.md - - Registers in AIPASS_REGISTRY.json - - Accepts `--role`, `--purpose` flags for passport fields - - If directory doesn't exist, creates it - - If .trinity/ already exists, error: "already a citizen" -- Update `spawn/apps/spawn.py` to route `passport` command -- Update `create` command to accept class as first arg: - - `drone @spawn create builder @path` (explicit class) - - `drone @spawn create @path` (default: builder, backward compatible) -- Wire class through to `_spawn_agent()` in core.py → passes class to template selection -- Add `citizen_class` field to passport.json template and create logic -**Deliverables:** -- `spawn/apps/modules/passport.py` -- `spawn/apps/handlers/passport_ops.py` -- Updated `spawn/apps/spawn.py` with passport + class-aware create -- Updated `spawn/apps/modules/core.py` with class routing -- Tests for passport command - -### Phase 3: Class-Aware Update + Profile Check -**Goal:** Make update class-aware. `update --all` requires class. Update checks passport's citizen_class to know which template applies. Light citizens don't get builder scaffold forced on them. -**Agent Task:** -- Update `spawn/apps/handlers/update_ops.py`: - - `update_branch()` reads passport.json → gets `citizen_class` → selects correct template - - If no citizen_class in passport → default to "builder" (backward compat for existing branches) - - Template comparison uses class-appropriate template dir -- Update `update_all()`: - - REQUIRE class arg: `update_all(citizen_class, dry_run, trace)` - - `drone @spawn update --all` without class → error message: "Specify a class: drone @spawn update builder --all" - - `drone @spawn update builder --all` → only updates branches with citizen_class="builder" - - `drone @spawn update birthright --all` → only updates birthright branches -- Update CLI parsing in `spawn/apps/modules/update.py`: - - `["builder", "--all"]` → update all builders - - `["builder", "@branch"]` → update specific branch as builder - - `["@branch"]` → update using branch's own citizen_class from passport - - `["--all"]` → blocked -- Backfill: add `citizen_class: "builder"` to all 10 existing branch passports -**Deliverables:** -- Updated `spawn/apps/handlers/update_ops.py` -- Updated `spawn/apps/modules/update.py` -- All 10 existing passports updated with citizen_class -- Tests for class-scoped update - -### Phase 4: Integration Testing + Seedgo Compliance -**Goal:** End-to-end testing of the full class system. Verify seedgo compliance. -**Agent Task:** -- Create integration tests: - - `passport @dirname` → verify birthright files created, registered - - `create builder @path` → verify full scaffold - - `create @path` → verify backward compat (defaults to builder) - - `update builder --all` → only touches builders, skips birthright - - `update --all` → blocked with clear error - - `update @birthright_branch` → uses birthright template, doesn't add apps/ - - `passport` on existing citizen → error - - `delete @birthright_branch` → archive works for light citizens too -- Run `drone @seedgo audit aipass` → fix any new violations -- Update spawn README.md with new command syntax -- Update spawn --help text -**Deliverables:** -- `spawn/tests/test_citizen_classes.py` -- Updated README.md -- Seedgo compliance maintained -- All tests passing - ---- - -## Execution Philosophy - -### Autonomous Power-Through - -Master plans are for **autonomous execution**. Don't halt production every phase waiting for review. - -**The Pattern:** -- Power through all phases -- Accumulate issues as you go -- Deal with issues at the end -- The user reviews the final result, not every step - -**Why this works:** -- Context is precious - don't burn it chasing bugs -- Complete picture reveals which issues actually matter -- Many "bugs" resolve themselves when later phases complete -- Coordination time is for decisions, not babysitting - -### The 2-Attempt Rule - -When agent encounters an issue: - -``` -Attempt 1 → Failed? - ↓ -Attempt 2 → Failed? - ↓ -STOP. Mark as issue. Move on. -``` - -**Do NOT:** -- Try 5 different approaches -- Go down rabbit holes -- Burn context debugging -- Stop production for every error - -**DO:** -- Note the issue clearly -- Note what was tried -- Move to next task -- Let branch manager decide priority - -### Critical vs Non-Critical Issues - -When you see an issue, decide: - -| Question | If YES → | If NO → | -|----------|----------|---------| -| Does this block ALL future phases? | STOP. Investigate. | Continue. | -| Can the system work around this? | Continue. | STOP. Investigate. | -| Is this a syntax/import error? | Quick fix, continue. | - | -| Is this a logic/design problem? | Note it. Continue. | - | - -**Critical (stop production):** -- Core module won't import at all -- Database/file system inaccessible -- Fundamental architecture wrong - -**Non-critical (note and continue):** -- One command throws error but others work -- Registry not updating properly -- Edge case not handled -- Test failing but code runs - -**Pattern:** Note issue → Continue building → Fix at end with complete picture - -### False Positives Awareness - -Seedgo audits are helpful but not infallible. - -**When Seedgo flags something:** -1. Check if the code is actually correct from your understanding -2. If you're confident it's right → mark as false positive, move on -3. If you're unsure → note it, continue, review later - -**Don't stop production for:** -- Style preferences (comments, spacing) -- Patterns that differ from Seedgo's but still work -- Checks that don't apply to your context - -### Forward Momentum Summary -- **Don't stop to fix bugs during phases** - Note them, keep moving -- **Get complete picture first** - All phases done, THEN systematic fixes -- **Prevents:** Bug-fixing rabbit holes, premature optimization, scope creep -- **Review happens at END** - not every phase - -### Production Stop Protocol - -If something causes production to STOP (critical blocker), **immediately email @devpulse**: - -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0009" "Phase X halted. Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - -**Never leave a branch stopped without reporting.** The orchestration hub needs visibility into all work. - -### Monitoring Resources - -For quick status checks and debugging, these resources are available: - -| Resource | Location | Purpose | -|----------|----------|---------| -| Branch logs | `logs/` directory | Local execution logs | -| JSON tree | `apps/json_templates/` | Module firing status | -| Prax monitor | `drone @prax monitor` | Real-time system events | -| Seedgo audit | `drone @seedgo audit @branch` | Code quality check | - -Use these when you need to confirm status or investigate issues. - -### Agent Deployment Per Phase -Each phase = focused agent deployment: -1. Create sub-plan: `drone @flow create . "Phase X: [name]"` -2. Write agent instructions in sub-plan -3. Deploy agent with single-task focus -4. Review agent output (don't rebuild yourself) -5. Seedgo checklist on new code -6. Close sub-plan -7. Update memories -8. Email status to @devpulse -9. Next phase - -### Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - -### Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task for this phase] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture: apps/modules/handlers) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user in the planning doc -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Phase Tracking - -### Phase 1: Template Restructure + Class Registry -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 2: Passport Command + Class-Aware Create -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 3: Class-Aware Update + Profile Check -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - -### Phase 4: Integration Testing + Seedgo Compliance -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending -- **Notes:** - ---- - -## Issues Log - -Track issues here as you encounter them. Don't fix during build - log and continue. - -| Phase | Issue | Severity | Attempted | Status | -|-------|-------|----------|-----------|--------| -| 1 | [description] | Low/Med/High | [what was tried] | Open/Resolved | -| 2 | [description] | Low/Med/High | [what was tried] | Open/Resolved | - -**Severity Guide:** -- **High:** Blocks future phases, must fix before continuing -- **Med:** Affects functionality but can work around -- **Low:** Cosmetic, edge case, or false positive - -**End of Build:** Review this log. Tackle High→Med→Low. Some Low issues may not need fixing. - ---- - -## Master Plan Notes - -**Cross-Phase Patterns:** -[Patterns discovered that span multiple phases] - -**Blockers & Resolutions:** -[Significant blockers and how resolved] - -**Adjustments:** -[Changes to planned phases - scope changes, phases added/merged] - ---- - -## Final Completion Checklist - -### Before Closing Master Plan - -- [ ] All phases complete -- [ ] All sub-plans closed -- [ ] Issues Log reviewed - High/Med issues addressed -- [ ] Full branch audit: `drone @seedgo audit @branch` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - full session log - - [ ] `BRANCH.observations.json` - patterns learned -- [ ] README.md updated (status, architecture, API - if build changed capabilities) -- [ ] Artifacts reviewed (devpulse manages cleanup) -- [ ] Final email to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0009 MASTER COMPLETE" "Full build summary: phases completed, deliverables, remaining issues (if any)" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -**Note:** Devpulse will perform its own Seedgo audit for visibility into the work. - -### Definition of Done -1. `templates/` has `builder/` and `birthright/` (no more `agent.template/`) -2. `drone @spawn passport @daemon` creates .trinity/ + .aipass/ + registry entry -3. `drone @spawn create builder @path` creates full scaffold -4. `drone @spawn create @path` defaults to builder (backward compat) -5. `drone @spawn update builder --all` only touches builders -6. `drone @spawn update --all` blocked with clear error -7. All 10 existing passports have `citizen_class: "builder"` -8. daemon has `citizen_class: "birthright"` after passport command -9. All tests passing (84+ existing + new class tests) -10. Seedgo audit score maintained - ---- - -## Close Command - -When ALL phases complete and checklist done: -```bash -drone @flow close FPLAN-0009 -``` diff --git a/src/aipass/flow/FPLAN-0010_fix_seedgo_standards_3_checker_bugs_doc__2026-03-08.md b/src/aipass/flow/FPLAN-0010_fix_seedgo_standards_3_checker_bugs_doc__2026-03-08.md deleted file mode 100644 index ed4d6b62..00000000 --- a/src/aipass/flow/FPLAN-0010_fix_seedgo_standards_3_checker_bugs_doc__2026-03-08.md +++ /dev/null @@ -1,514 +0,0 @@ -# FPLAN-0010 - Fix seedgo standards: 3 checker bugs, doc paths, header regex (MASTER PLAN) - -**Created**: 2026-03-08 -**Branch**: flow -**Status**: Active -**Type**: Master Plan (Multi-Phase) - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. They're the structured way to execute work without constant human oversight. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building new branches/modules -- Implementing features -- Multi-phase construction projects -- Autonomous execution - ---- - -## Master Plan vs Default Plan - -| | Master Plan | Default Plan | -|---|-------------|--------------| -| **Use when** | 3+ phases, complex build | Single focused task | -| **Structure** | Roadmap + sub-plans | Self-contained | -| **Phases** | Multiple, sequential | One | -| **Sub-plans** | Yes, one per phase | No | -| **Typical use** | Build entire branch | One phase of master | - -**Pattern:** -``` -Master Plan (roadmap) -├── Sub-plan Phase 1 (default template) -├── Sub-plan Phase 2 (default template) -├── Sub-plan Phase 3 (default template) -└── Sub-plan Phase 4 (default template) -``` - -**How to start:** -1. The user provides planning doc or instructions (coordinate with @devpulse) -2. Branch manager reads and understands scope -3. Branch manager creates master plan: `drone @flow create . "Build X" master` -4. Branch manager fills in phases, then executes autonomously - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans & sub-plans | Write code | -| Define phases | Run tests | -| Give agent instructions | Read/modify files | -| Review agent output | Research/exploration | -| Course correct | Heavy lifting | -| Update memories | Single-task execution | -| Send status emails | Build deliverables | -| Track phase progress | Quality checks on code | - -**Master Plan Pattern:** Define all phases → Create sub-plan for Phase 1 → Deploy agent → Review → Close sub-plan → Email update → Next phase - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. For master plans spanning multiple domains, identify which branches to consult during phase definitions. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. Low friction both ways. - -```bash -# Create it at plan start -echo "# Notepad - FPLAN-0010" > notepad.md -``` - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "Phase X: subject" # Create sub-plan (. = current dir) -drone @flow create . "subject" master # Create master plan -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow status # Plan status -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit (before master close) -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail inbox # Check your inbox -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## What is a Master Plan? - -Master Plans are for **complex multi-phase projects**. You define all phases upfront, then create focused sub-plans for each phase. - -**When to use:** -- 3+ distinct sequential phases -- Work spanning multiple sessions -- Need clear phase completion milestones -- Complex builds requiring sustained focus - -**Pattern:** Master Plan = Roadmap | Sub-Plans = Focused Execution - ---- - -## Project Overview - -### Goal -[What is the end state when ALL phases complete?] - -### Reference Documentation -[List planning docs, specs, existing code to reference] - -### Success Criteria -[What defines DONE for the entire project?] - ---- - -## Branch Directory Structure - -Every branch has dedicated directories. Use them correctly: - -``` -branch/ -├── apps/ # Code (modules/, handlers/) -├── tests/ # All test files go here -├── tools/ # Utility scripts, helpers -├── artifacts/ # Agent outputs (reports, logs) -├── docs/ # Documentation -└── logs/ # Execution logs -``` - -**Rules:** -- Tests → `tests/` (not root, not random locations) -- Tools/scripts → `tools/` -- Agent artifacts → `artifacts/` -- Create subdirs if needed: `mkdir -p artifacts/reports artifacts/logs` -- **Never delete** - devpulse manages cleanup -- Future: artifacts auto-roll to Memory Bank - ---- - -## Phase Definitions - -Define ALL phases before starting work: - -### Phase 1: [Name] -**Goal:** [What this phase accomplishes] -**Agent Task:** [What the agent will build] -**Deliverables:** [Files/outputs expected] - -### Phase 2: [Name] -**Goal:** [What this phase accomplishes] -**Agent Task:** [What the agent will build] -**Deliverables:** [Files/outputs expected] - -### Phase 3: [Name] -**Goal:** [What this phase accomplishes] -**Agent Task:** [What the agent will build] -**Deliverables:** [Files/outputs expected] - -### Phase 4: [Name] -**Goal:** [What this phase accomplishes] -**Agent Task:** [What the agent will build] -**Deliverables:** [Files/outputs expected] - -[Add more phases as needed] - ---- - -## Execution Philosophy - -### Autonomous Power-Through - -Master plans are for **autonomous execution**. Don't halt production every phase waiting for review. - -**The Pattern:** -- Power through all phases -- Accumulate issues as you go -- Deal with issues at the end -- The user reviews the final result, not every step - -**Why this works:** -- Context is precious - don't burn it chasing bugs -- Complete picture reveals which issues actually matter -- Many "bugs" resolve themselves when later phases complete -- Coordination time is for decisions, not babysitting - -### The 2-Attempt Rule - -When agent encounters an issue: - -``` -Attempt 1 → Failed? - ↓ -Attempt 2 → Failed? - ↓ -STOP. Mark as issue. Move on. -``` - -**Do NOT:** -- Try 5 different approaches -- Go down rabbit holes -- Burn context debugging -- Stop production for every error - -**DO:** -- Note the issue clearly -- Note what was tried -- Move to next task -- Let branch manager decide priority - -### Critical vs Non-Critical Issues - -When you see an issue, decide: - -| Question | If YES → | If NO → | -|----------|----------|---------| -| Does this block ALL future phases? | STOP. Investigate. | Continue. | -| Can the system work around this? | Continue. | STOP. Investigate. | -| Is this a syntax/import error? | Quick fix, continue. | - | -| Is this a logic/design problem? | Note it. Continue. | - | - -**Critical (stop production):** -- Core module won't import at all -- Database/file system inaccessible -- Fundamental architecture wrong - -**Non-critical (note and continue):** -- One command throws error but others work -- Registry not updating properly -- Edge case not handled -- Test failing but code runs - -**Pattern:** Note issue → Continue building → Fix at end with complete picture - -### False Positives Awareness - -Seedgo audits are helpful but not infallible. - -**When Seedgo flags something:** -1. Check if the code is actually correct from your understanding -2. If you're confident it's right → mark as false positive, move on -3. If you're unsure → note it, continue, review later - -**Don't stop production for:** -- Style preferences (comments, spacing) -- Patterns that differ from Seedgo's but still work -- Checks that don't apply to your context - -### Forward Momentum Summary -- **Don't stop to fix bugs during phases** - Note them, keep moving -- **Get complete picture first** - All phases done, THEN systematic fixes -- **Prevents:** Bug-fixing rabbit holes, premature optimization, scope creep -- **Review happens at END** - not every phase - -### Production Stop Protocol - -If something causes production to STOP (critical blocker), **immediately email @devpulse**: - -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0010" "Phase X halted. Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - -**Never leave a branch stopped without reporting.** The orchestration hub needs visibility into all work. - -### Monitoring Resources - -For quick status checks and debugging, these resources are available: - -| Resource | Location | Purpose | -|----------|----------|---------| -| Branch logs | `logs/` directory | Local execution logs | -| JSON tree | `apps/json_templates/` | Module firing status | -| Prax monitor | `drone @prax monitor` | Real-time system events | -| Seedgo audit | `drone @seedgo audit @branch` | Code quality check | - -Use these when you need to confirm status or investigate issues. - -### Agent Deployment Per Phase -Each phase = focused agent deployment: -1. Create sub-plan: `drone @flow create . "Phase X: [name]"` -2. Write agent instructions in sub-plan -3. Deploy agent with single-task focus -4. Review agent output (don't rebuild yourself) -5. Seedgo checklist on new code -6. Close sub-plan -7. Update memories -8. Email status to @devpulse -9. Next phase - -### Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - -### Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task for this phase] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture: apps/modules/handlers) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user in the planning doc -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Phase Tracking - -### Phase 1: [Name] -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending / In Progress / Complete -- **Notes:** [Outcomes, issues, adjustments] - -### Phase 2: [Name] -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending / In Progress / Complete -- **Notes:** [Outcomes, issues, adjustments] - -### Phase 3: [Name] -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending / In Progress / Complete -- **Notes:** [Outcomes, issues, adjustments] - -### Phase 4: [Name] -- [ ] Sub-plan created: FPLAN-____ -- [ ] Agent deployed -- [ ] Agent completed -- [ ] Output reviewed -- [ ] Seedgo checklist passed -- [ ] Sub-plan closed -- [ ] Memories updated -- [ ] Email sent to @devpulse -- **Status:** Pending / In Progress / Complete -- **Notes:** [Outcomes, issues, adjustments] - -[Copy template for additional phases] - ---- - -## Issues Log - -Track issues here as you encounter them. Don't fix during build - log and continue. - -| Phase | Issue | Severity | Attempted | Status | -|-------|-------|----------|-----------|--------| -| 1 | [description] | Low/Med/High | [what was tried] | Open/Resolved | -| 2 | [description] | Low/Med/High | [what was tried] | Open/Resolved | - -**Severity Guide:** -- **High:** Blocks future phases, must fix before continuing -- **Med:** Affects functionality but can work around -- **Low:** Cosmetic, edge case, or false positive - -**End of Build:** Review this log. Tackle High→Med→Low. Some Low issues may not need fixing. - ---- - -## Master Plan Notes - -**Cross-Phase Patterns:** -[Patterns discovered that span multiple phases] - -**Blockers & Resolutions:** -[Significant blockers and how resolved] - -**Adjustments:** -[Changes to planned phases - scope changes, phases added/merged] - ---- - -## Final Completion Checklist - -### Before Closing Master Plan - -- [ ] All phases complete -- [ ] All sub-plans closed -- [ ] Issues Log reviewed - High/Med issues addressed -- [ ] Full branch audit: `drone @seedgo audit @branch` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - full session log - - [ ] `BRANCH.observations.json` - patterns learned -- [ ] README.md updated (status, architecture, API - if build changed capabilities) -- [ ] Artifacts reviewed (devpulse manages cleanup) -- [ ] Final email to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0010 MASTER COMPLETE" "Full build summary: phases completed, deliverables, remaining issues (if any)" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -**Note:** Devpulse will perform its own Seedgo audit for visibility into the work. - -### Definition of Done -[What specifically defines the project complete?] - ---- - -## Close Command - -When ALL phases complete and checklist done: -```bash -drone @flow close FPLAN-0010 -``` diff --git a/src/aipass/flow/FPLAN-0011_fix_ai_mail_caller_identity_detection_fo_2026-03-08.md b/src/aipass/flow/FPLAN-0011_fix_ai_mail_caller_identity_detection_fo_2026-03-08.md deleted file mode 100644 index c7c4ca16..00000000 --- a/src/aipass/flow/FPLAN-0011_fix_ai_mail_caller_identity_detection_fo_2026-03-08.md +++ /dev/null @@ -1,281 +0,0 @@ -# FPLAN-0011 - Fix ai_mail caller identity detection for Docker and local - -**Created**: 2026-03-08 -**Branch**: flow -**Status**: Active -**Type**: Standard Plan - ---- - -## What Are Flow Plans? - -Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. - -**This is NOT for:** -- Research or exploration (use agents directly) -- Quick fixes (just do it) -- Discussion or planning (that happens before creating the FPLAN) - -**This IS for:** -- Building features or modules -- Single focused construction tasks -- Sub-plans within a master plan - ---- - -## When to Use This vs Master Plan - -| This (Default) | Master Plan | -|----------------|-------------| -| Single focused task | 3+ phases, complex build | -| Self-contained | Roadmap + multiple sub-plans | -| Quick build | Multi-session project | -| One phase of a master | Entire branch/system build | - -**Need a master plan?** `drone @flow create "subject" master` - ---- - -## Branch Directory Structure - -Use dedicated directories - don't scatter files: - -| Directory | Purpose | -|-----------|---------| -| `apps/` | Code (modules/, handlers/) | -| `tests/` | All test files | -| `tools/` | Utility scripts | -| `artifacts/` | Agent outputs | -| `docs/` | Documentation | - ---- - -## Critical: Branch Manager Role - -**You are the ORCHESTRATOR, not the builder.** - -Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. - -| You Do (Orchestrator) | Agents Do (Builders) | -|-----------------------|----------------------| -| Create plans | Write code | -| Give instructions | Run tests | -| Review output | Read/modify files | -| Course correct | Research/exploration | -| Update memories | Heavy lifting | -| Send status emails | Single-task execution | - -**Pattern:** Instruct agent → Wait for completion → Review output → Next step - ---- - -## Seek Branch Expertise - -Don't figure everything out alone. Other branches are domain experts - ask them first. - -**Before building anything that touches another branch's domain:** -```bash -ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" -``` - -**Common examples:** -- Building something with email? Ask @ai_mail how delivery works -- Need routing or @ resolution? Ask @drone -- Unsure about standards? Ask @seedgo for reference code -- Need persistent storage or search? Ask @memory_bank -- Event-driven behavior? Ask @trigger about their event system -- Dashboard integration? Ask @devpulse about update_section() - -They have deep memory on their systems. A 1-email question saves you hours of guessing. - ---- - -## Notepad - -Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: -- **Status updates** - Quick progress lines so the user can glance without asking -- **Questions for the user** - Non-urgent questions that can wait for the next check-in -- **Notes to self** - Decisions made, things to revisit, gotchas discovered - -Update it as you work - lightweight, not formal. The user checks it when they want to, skips it when busy. - ---- - -## Command Reference - -When unsure about syntax, use `--help`: - -```bash -# Flow - Plan management -drone @flow create . "subject" # Create plan (. = current dir) -drone @flow close FPLAN-XXXX # Close plan -drone @flow list # List active plans -drone @flow --help # Full help - -# Seedgo - Quality gates -drone @seedgo checklist # 10-point check on file -drone @seedgo audit @branch # Full branch audit -drone @seedgo --help # Full help - -# AI_Mail - Status updates -drone @ai_mail send @devpulse "Subject" "Message" -drone @ai_mail --help # Full help - -# Discovery -drone systems # All available modules -drone list @branch # Commands for branch -``` - ---- - -## Planning Phase - -### Goal -ai_mail caller identity detection works in both Docker containers and local environments. When devpulse sends an email via `drone @ai_mail send @spawn "Subject" "Body"`, ai_mail correctly identifies devpulse as the sender — regardless of mount paths. - -### Problem -Drone routes commands to ai_mail via subprocess with `cwd=ai_mail_dir`. Drone passes `AIPASS_CALLER_CWD` env var with the original caller's directory. ai_mail's `branch_detection.py` reads this CWD and walks up looking for `.trinity/passport.json`, then matches against the registry. - -In Docker: registry paths use container paths (`/home/coder/workspace/AIPass/...`) which are generated fresh. The CWD-to-registry path resolution fails when paths don't match exactly. - -### Approach -Two-branch fix — drone and ai_mail cooperate: - -**Phase 1 — Drone side** (`src/aipass/drone/apps/modules/router.py`): -- Detect caller branch name from CWD (walk up to find `.trinity/passport.json`, read `identity.name`) -- Pass as `AIPASS_CALLER_BRANCH` env var alongside existing `AIPASS_CALLER_CWD` -- Keep CWD — other branches may need it for different purposes - -**Phase 2 — ai_mail side** (`src/aipass/ai_mail/apps/handlers/users/branch_detection.py`): -- Check `AIPASS_CALLER_BRANCH` first — direct name lookup in registry (path-independent) -- Fall back to `AIPASS_CALLER_CWD` path resolution (existing behavior) -- Fall back to `Path.cwd()` (original behavior) - -**Phase 3 — Test in Docker**: -- Copy fixed files into `aipass-fresh-test` container -- Run `cd src/aipass/devpulse && drone @ai_mail send @spawn "Test" "Test body"` -- Verify email lands in spawn's inbox -- Verify sender is "@devpulse" - -**Phase 4 — Test locally**: -- Run same command from local devpulse -- Verify existing ai_mail functionality still works - -### Reference Documents -- `src/aipass/drone/apps/modules/router.py` — lines 57-66, AIPASS_CALLER_CWD -- `src/aipass/drone/apps/handlers/executor.py` — lines 46-50, env merge -- `src/aipass/ai_mail/apps/handlers/users/branch_detection.py` — lines 51-87, detect_branch_from_pwd() -- `src/aipass/ai_mail/apps/handlers/users/user.py` — lines 37-97, get_current_user() - ---- - -## Agent Preparation (Before Deploying) - -Agents can't work blind. They need context before they build. - -**Your Prep Work (as orchestrator):** -1. [ ] Know where agent will work (branch path, key directories) -2. [ ] Identify files agent needs to reference or modify -3. [ ] Gather any specs, planning docs, or examples to include -4. [ ] Prepare COMPLETE instructions (agents are stateless) - -**Agent's First Task (context building):** -- Agent should explore/read relevant files BEFORE writing code -- "First, read X and Y to understand the current structure" -- "Look at Z for the pattern to follow" -- Context-first, build-second - -**What Agents DON'T Have:** -- No prior conversation history -- No memory files loaded automatically -- No knowledge of other branches -- Only what you put in their instructions - -**Your instructions determine success - be thorough and specific.** - ---- - -## Agent Instructions Template -``` -You are working at [BRANCH_PATH]. - -TASK: [Specific single task] - -CONTEXT: -- [What they need to know] -- Reference: [planning docs, existing code to study] -- First, READ the relevant files to understand current structure - -DELIVERABLES: -- [Specific file or output expected] -- Tests → tests/ -- Reports/logs → artifacts/reports/ or artifacts/logs/ - -CONSTRAINTS: -- Follow Seedgo standards (3-layer architecture) -- Do NOT modify files outside your task scope -- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by the user -- 2-ATTEMPT RULE: If something fails twice, note the issue and move on -- Do NOT go down rabbit holes debugging - -WHEN COMPLETE: -- Verify code runs without syntax errors -- List files created/modified -- Note any issues encountered (with what was attempted) -``` - ---- - -## Execution Log - -### 2026-03-08 -- [ ] Created FPLAN-0011 -- [ ] Agent deployed for: [task] -- [ ] Agent completed: [outcome] -- [ ] Seedgo checklist passed: [file] -- [ ] Memories updated - -**Log Pattern:** Task → Agent → Outcome → Quality check → Next - -**If production stops (critical blocker):** -```bash -drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0011" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." -``` - ---- - -## Notes - -[Working notes, issues encountered, decisions made] - ---- - -## Completion Checklist - -### Before Closing - -- [ ] All goals achieved -- [ ] Agent output reviewed and verified -- [ ] Seedgo checklist on new code: `drone @seedgo checklist ` -- [ ] Branch memories updated: - - [ ] `BRANCH.local.json` - session/work log - - [ ] `BRANCH.observations.json` - patterns learned (if any) -- [ ] README.md updated (if build changed status/capabilities) -- [ ] Status email sent to @devpulse: - ```bash - drone @ai_mail send @devpulse "FPLAN-0011 Complete" "Summary of what was done, any issues, outcomes" - ``` - -**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) - -### Definition of Done -[What specifically defines complete for this plan?] - ---- - -## Close Command - -When all boxes checked: -```bash -drone @flow close FPLAN-0011 -```