slaguru666/AIPass
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: gitignore FPLAN and DPLAN files — plans are local, not tracked (#28)

Browse Source 
Plans are runtime artifacts managed by flow. They stay on disk but don't belong in the repo.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
AIPass
2026-03-08 13:05:51 -07:00
committed by GitHub
co-authored by Claude Opus 4.6
parent 9579c27139
commit ca8b3a2912
15 changed files with 4 additions and 4469 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+4
View File
@@ -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/
FPLAN-0003_framework_memory_bank_port_to_aipass_rep_2026-03-06.md
-308
View File
@@ -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 <file> # 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 <file>`
- [ ] 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
```
FPLAN-0004_framework_backup_system_port_to_aipass_r_2026-03-06.md
-274
View File
@@ -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 <file> # 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 <file>`
- [ ] 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
```
FPLAN-0005_framework_daemon_port_to_aipass_repo_2026-03-07.md
-106
View File
@@ -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
```
FPLAN-0006_framework_skills_system_2026-03-07.md
-116
View File
@@ -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
```
FPLAN-0411_framework_the_commons_port_to_aipass_fra_2026-03-07.md
-679
View File
@@ -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 <file> # 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 <file_path>
- 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
```
src/aipass/devpulse/docs/DPLAN-0001_system_bootstrap.md
-92
View File
@@ -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*
src/aipass/devpulse/docs/DPLAN-0002_prompt_architecture.md
-129
View File
@@ -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*
src/aipass/devpulse/docs/FPLAN-001_path_rewire_portability_2026-03-06.md
-194
View File
@@ -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.
src/aipass/flow/FPLAN-0005_spawn_branch_scaffold_audit_2026-03-07.md
-279
View File
@@ -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 <file> # 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 <file>`
- [ ] 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
```
src/aipass/flow/FPLAN-0007_seedgo_architecture_checker_activation_2026-03-07.md
-253
View File
@@ -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 <file> # 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 <file>`
- [ ] 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
```
src/aipass/flow/FPLAN-0008_spawn_rebuild_full_branch_lifecycle_mana_2026-03-07.md
-635
View File
@@ -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 <file> # 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
```
src/aipass/flow/FPLAN-0009_citizen_classes_template_system_passport_2026-03-07.md
-609
View File
@@ -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 <file> # 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
```
src/aipass/flow/FPLAN-0010_fix_seedgo_standards_3_checker_bugs_doc__2026-03-08.md
-514
View File
@@ -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 <file> # 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
```
src/aipass/flow/FPLAN-0011_fix_ai_mail_caller_identity_detection_fo_2026-03-08.md
-281
View File
@@ -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 <file> # 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 <file>`
- [ ] 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
```