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

updates

Browse Source
This commit is contained in:
Input-X
2026-03-07 22:13:52 +00:00
parent fe3bca1790
commit f8b48a6bb6
104 changed files with 1275 additions and 905 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1 -1
View File
@@ -92,7 +92,7 @@ notepad.md
# Module JSON exceptions — these are source configs, must be tracked
!AIPASS_REGISTRY.json
!AI_CENTRAL/**/*.json
!.ai_central/**/*.json
!src/aipass/api/api_json/**
!src/aipass/flow/flow_json/**
!src/aipass/trigger/trigger_json/**
aipass_os/AI_CENTRAL/AI_MAIL.central.json
-50
View File
@@ -1,50 +0,0 @@
{
"service": "ai_mail",
"last_updated": "2026-03-07",
"branch_stats": {
"API": {
"unread": 0,
"total": 0
},
"TRIGGER": {
"unread": 0,
"total": 0
},
"DRONE": {
"unread": 0,
"total": 0
},
"CLI": {
"unread": 0,
"total": 0
},
"PRAX": {
"unread": 0,
"total": 0
},
"SPAWN": {
"unread": 4,
"total": 4
},
"DEVPULSE": {
"unread": 1,
"total": 1
},
"AI_MAIL": {
"unread": 0,
"total": 3
},
"FLOW": {
"unread": 0,
"total": 0
},
"SEEDGO": {
"unread": 0,
"total": 0
}
},
"system_totals": {
"total_unread": 5,
"total_messages": 8
}
}
src/aipass/ai_mail/apps/handlers/central_writer.py
+1 -1
View File
@@ -60,7 +60,7 @@ def _find_repo_root() -> Path:
_REPO_ROOT = _find_repo_root()
AI_CENTRAL_DIR = _REPO_ROOT / "aipass_os" / "AI_CENTRAL"
AI_CENTRAL_DIR = _REPO_ROOT / ".ai_central"
CENTRAL_FILE = AI_CENTRAL_DIR / "AI_MAIL.central.json"
BRANCH_REGISTRY = _REPO_ROOT / "AIPASS_REGISTRY.json"
src/aipass/devpulse/apps/handlers/__init__.py → src/aipass/cli/cli_json/.gitkeep
View File
src/aipass/devpulse/.aipass/branch_system_prompt.md
+3 -7
View File
@@ -60,13 +60,7 @@ drone @ai_mail dispatch wake --fresh @target # Fresh session (new context)
## Architecture
All branches follow 3-layer pattern:
```
apps/
{name}.py # Entry point (e.g. devpulse.py, spawn.py)
modules/ # Business logic
handlers/ # Implementation
```
Most branches follow the 3-layer pattern (`apps/{name}.py` + `modules/` + `handlers/`). DevPulse does NOT have `apps/` — it's a manager branch that coordinates via dispatch and sub-agents.
Imports use pip namespace: `from aipass.{module}.apps.modules...`
@@ -74,6 +68,8 @@ Imports use pip namespace: `from aipass.{module}.apps.modules...`
You are a **manager**, not a worker. Delegate code tasks to sub-agents — don't burn your own context reading and editing files across branches. Send agents out in parallel, collect results, report back. Your context window is precious — protect it. Only do small, quick things yourself (a single command, a quick check). Anything involving reading multiple files, auditing code, or making edits across a branch = dispatch an agent.
**Use background agents aggressively.** When multiple independent tasks exist, spawn background agents to handle them in parallel while you continue working on other items. Don't wait for one task to finish before starting the next. Keep the pipeline moving — background agents for research, audits, code generation, and file reads. Only block on an agent when you need its result for your next step.
## Critical Rules
- Imports must use `from aipass.{module}...` — never bare module imports
src/aipass/devpulse/README.md
+49 -30
View File
@@ -1,18 +1,21 @@
# DevPulse
**Purpose:** Dev notes and status tracking for AIPass projects
**Purpose:** Orchestration hub for the AIPass ecosystem
**Module:** `aipass.devpulse`
**Status:** Building
**Status:** Active
---
## Overview
DevPulse tracks development notes, plans, and project status across an AIPass ecosystem. It provides a shared notation layer where both humans and agents can log issues, todos, and progress — giving visibility into what's happening without requiring meetings or status emails.
DevPulse is the central coordination branch for AIPass. It plans, delegates, and tracks work across all 10 branches in the ecosystem. Think of it as the project manager — it doesn't build modules itself, but dispatches work to branch agents, monitors results, and maintains system-wide visibility.
### How It Works
- **Entry Point:** `apps/devpulse.py`
- **Pattern:** Auto-discovers modules in `apps/modules/` with `handle_command()` and routes commands
### What DevPulse Does
- **Cross-branch orchestration** — Dispatch tasks to branches via AI Mail + wake
- **System-wide planning** — Create and manage flow plans (FPLANs) for multi-phase work
- **Status tracking** — Dashboard, dev notes, session history
- **Architecture discussions** — Work with Patrick on design decisions
- **Agent coordination** — Deploy sub-agents in parallel for research and builds
---
@@ -20,39 +23,45 @@ DevPulse tracks development notes, plans, and project status across an AIPass ec
```
devpulse/
├── apps/
│ ├── devpulse.py # Entry point (auto-discovery + routing)
│ ├── modules/ # Business logic
│ ├── handlers/ # Implementation
│ └── plugins/ # Extensions
├── devpulse_json/ # JSON storage
├── .trinity/ # Identity + memory
│ ├── passport.json # Branch identity
│ ├── local.json # Session history + active tasks
│ └── observations.json # Collaboration patterns
├── .aipass/ # AI context
│ └── branch_system_prompt.md
├── .spawn/ # Spawn metadata
├── docs/
├── tests/
└── README.md
```
DevPulse has no `apps/` directory — it's a **manager** branch, not a builder. It coordinates via dispatch and sub-agents rather than implementing code.
---
## Commands
```bash
drone @devpulse --help # Show available commands
```
# System status
drone systems # List all registered branches
drone @seedgo verify # Verify standards packs
drone @seedgo audit aipass # Run full standards audit
*Modules are being built out — commands will appear as they ship.*
# Flow plans
drone @flow create . "Subject" # Create plan (default template)
drone @flow create . "Subject" master # Create master plan (multi-phase)
drone @flow list # List active plans
drone @flow close FPLAN-XXXX # Close a plan
---
# Dispatch work
drone @ai_mail send @target "Subject" "Body" --dispatch
drone @ai_mail dispatch wake @target # Wake branch agent
drone @ai_mail dispatch wake --fresh @target # Fresh session
## Python Usage
```python
from aipass.devpulse.apps.devpulse import discover_modules, route_command
# Discover available sub-modules
modules = discover_modules()
# Route a command
route_command("status", [], modules)
# Branch management
drone @spawn create <path> # Create new branch from template
drone @spawn update @branch # Update branch scaffold
drone @spawn delete @branch # Archive + deregister branch
```
---
@@ -60,8 +69,18 @@ route_command("status", [], modules)
## Integration Points
### Depends On
- `aipass.prax` — Logging
- `aipass.cli` — Display formatting
- `aipass.prax` — Logging (all logging goes through prax)
- `aipass.ai_mail` — Inter-branch communication + dispatch
- `aipass.flow` — Plan creation and tracking
- `aipass.drone` — Command routing to all branches
- `aipass.spawn` — Branch lifecycle management
- `aipass.seedgo` — Standards verification
### Provides To
- All modules — dev notes, plan tracking, project status
### Coordinates
- All 10 branches: drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, devpulse
---
## Role
DevPulse is a **manager** branch, not a builder. It delegates code tasks to sub-agents and branch agents. Its context window is reserved for coordination, planning, and architecture — not for reading and editing files across the codebase.
src/aipass/devpulse/apps/__init__.py
-1
View File
@@ -1 +0,0 @@
# DEVPULSE apps package
src/aipass/devpulse/apps/devpulse.py
-86
View File
@@ -1,86 +0,0 @@
"""
DEVPULSE Branch - Main Orchestrator
Auto-discovery architecture:
- Scans modules/ directory for .py files with handle_command()
- Routes commands to discovered modules automatically
- No manual imports or routing needed
"""
import sys
import importlib
from pathlib import Path
from typing import List, Any
from aipass.prax import logger
# =============================================================================
# MODULE DISCOVERY
# =============================================================================
MODULES_DIR = Path(__file__).parent / "modules"
def discover_modules() -> List[Any]:
"""Auto-discover modules in modules/ directory."""
modules = []
if not MODULES_DIR.exists():
return modules
for file_path in MODULES_DIR.glob("*.py"):
if file_path.name.startswith("_"):
continue
module_name = f"aipass.devpulse.apps.modules.{file_path.stem}"
try:
module = importlib.import_module(module_name)
if hasattr(module, "handle_command"):
modules.append(module)
except Exception as e:
logger.error(f"[DEVPULSE] Failed to load module {module_name}: {e}")
return modules
def route_command(command: str, args: List[str], modules: List[Any]) -> bool:
"""Route command to appropriate module."""
for module in modules:
try:
if module.handle_command(command, args):
return True
except Exception as e:
logger.error(f"[DEVPULSE] Module {module.__name__} error: {e}")
return False
# =============================================================================
# MAIN ENTRY POINT
# =============================================================================
def main():
"""Main entry point - routes commands or shows help."""
modules = discover_modules()
args = sys.argv[1:]
if len(args) == 0 or args[0] in ["--help", "-h", "help"]:
print(f"DEVPULSE - {len(modules)} modules discovered")
for module in modules:
name = module.__name__.split(".")[-1]
desc = (module.__doc__ or "").strip().split("\n")[0] if module.__doc__ else "No description"
print(f" {name:20} {desc}")
return 0
command = args[0]
remaining = args[1:] if len(args) > 1 else []
if route_command(command, remaining, modules):
return 0
print(f"Unknown command: {command}")
return 1
if __name__ == "__main__":
sys.exit(main())
src/aipass/devpulse/apps/extensions/__init__.py
-1
View File
@@ -1 +0,0 @@
# Extensions package - Drop-in extensions for branch functionality
src/aipass/devpulse/apps/handlers/json/__init__.py
-1
View File
@@ -1 +0,0 @@
"""JSON handler package for devpulse."""
src/aipass/devpulse/apps/handlers/json/json_handler.py
-54
View File
@@ -1,54 +0,0 @@
# ===================AIPASS====================
# META DATA HEADER
# Name: json_handler.py - JSON Handler
# Date: 2026-03-07
# Version: 1.0.0
# Category: devpulse/handlers/json
#
# CHANGELOG (Max 5 entries):
# - v1.0.0 (2026-03-07): Initial implementation
#
# CODE STANDARDS:
# - Satisfies Seed architecture standard for apps/handlers/json/ path
# =============================================
"""
JSON Handler for DevPulse
Handles JSON read/write operations for devpulse_json/ storage.
"""
import json
from pathlib import Path
from typing import Any, Optional
# Infrastructure paths (package-relative)
_DEVPULSE_ROOT = Path(__file__).resolve().parents[3] # devpulse/
DEVPULSE_JSON_DIR = _DEVPULSE_ROOT / "devpulse_json"
def load_json(file_path: Path) -> Any:
"""Load and return JSON data from file."""
with open(file_path, 'r', encoding='utf-8') as f:
return json.load(f)
def save_json(file_path: Path, data: Any, indent: int = 2) -> None:
"""Save data as JSON to file."""
file_path.parent.mkdir(parents=True, exist_ok=True)
with open(file_path, 'w', encoding='utf-8') as f:
json.dump(data, f, indent=indent, ensure_ascii=False)
f.write('\n')
def ensure_json_exists(file_path: Path, default: Optional[Any] = None) -> Path:
"""Ensure a JSON file exists, creating with default content if missing."""
if not file_path.exists():
save_json(file_path, default if default is not None else {})
return file_path
def get_json_path(filename: str) -> Path:
"""Get the path to a JSON file in devpulse_json/."""
return DEVPULSE_JSON_DIR / filename
src/aipass/devpulse/apps/json_templates/__init__.py
-1
View File
@@ -1 +0,0 @@
# JSON Templates package - Default JSON file templates
src/aipass/devpulse/apps/modules/__init__.py → src/aipass/drone/drone_json/.gitkeep
View File
src/aipass/flow/FPLAN-0005_spawn_branch_scaffold_audit_2026-03-07.md
+8 -8
View File
@@ -81,7 +81,7 @@ ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on
**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
- 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()
@@ -112,10 +112,10 @@ 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
# 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"
@@ -210,7 +210,7 @@ DELIVERABLES:
- Reports/logs → artifacts/reports/ or artifacts/logs/
CONSTRAINTS:
- Follow Seed standards (3-layer architecture)
- 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
@@ -230,7 +230,7 @@ WHEN COMPLETE:
- [ ] Created FPLAN-0005
- [ ] Agent deployed for: [task]
- [ ] Agent completed: [outcome]
- [ ] Seed checklist passed: [file]
- [ ] Seedgo checklist passed: [file]
- [ ] Memories updated
**Log Pattern:** Task → Agent → Outcome → Quality check → Next
@@ -254,7 +254,7 @@ drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0005" "Issue: [descript
- [ ] All goals achieved
- [ ] Agent output reviewed and verified
- [ ] Seed checklist on new code: `drone @seed checklist <file>`
- [ ] 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)
src/aipass/flow/FPLAN-0007_seedgo_architecture_checker_activation_2026-03-07.md
+8 -8
View File
@@ -81,7 +81,7 @@ ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on
**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
- 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()
@@ -112,10 +112,10 @@ 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
# 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"
@@ -184,7 +184,7 @@ DELIVERABLES:
- Reports/logs → artifacts/reports/ or artifacts/logs/
CONSTRAINTS:
- Follow Seed standards (3-layer architecture)
- 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
@@ -204,7 +204,7 @@ WHEN COMPLETE:
- [ ] Created FPLAN-0007
- [ ] Agent deployed for: [task]
- [ ] Agent completed: [outcome]
- [ ] Seed checklist passed: [file]
- [ ] Seedgo checklist passed: [file]
- [ ] Memories updated
**Log Pattern:** Task → Agent → Outcome → Quality check → Next
@@ -228,7 +228,7 @@ drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-0007" "Issue: [descript
- [ ] All goals achieved
- [ ] Agent output reviewed and verified
- [ ] Seed checklist on new code: `drone @seed checklist <file>`
- [ ] 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)
src/aipass/flow/FPLAN-0008_spawn_rebuild_full_branch_lifecycle_mana_2026-03-07.md
+18 -18
View File
@@ -84,7 +84,7 @@ ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on
**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
- 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()
@@ -122,10 +122,10 @@ 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
# 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"
@@ -388,16 +388,16 @@ When you see an issue, decide:
### False Positives Awareness
Seed audits are helpful but not infallible.
Seedgo audits are helpful but not infallible.
**When Seed flags something:**
**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 Seed's but still work
- Patterns that differ from Seedgo's but still work
- Checks that don't apply to your context
### Forward Momentum Summary
@@ -425,7 +425,7 @@ For quick status checks and debugging, these resources are available:
| 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 |
| Seedgo audit | `drone @seedgo audit @branch` | Code quality check |
Use these when you need to confirm status or investigate issues.
@@ -435,7 +435,7 @@ Each phase = focused agent deployment:
2. Write agent instructions in sub-plan
3. Deploy agent with single-task focus
4. Review agent output (don't rebuild yourself)
5. Seed checklist on new code
5. Seedgo checklist on new code
6. Close sub-plan
7. Update memories
8. Email status to @devpulse
@@ -482,7 +482,7 @@ DELIVERABLES:
- Reports/logs → artifacts/reports/ or artifacts/logs/
CONSTRAINTS:
- Follow Seed standards (3-layer architecture: apps/modules/handlers)
- 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
@@ -503,7 +503,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -515,7 +515,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -527,7 +527,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -539,7 +539,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -551,7 +551,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -598,7 +598,7 @@ Track issues here as you encounter them. Don't fix during build - log and contin
- [ ] All phases complete
- [ ] All sub-plans closed
- [ ] Issues Log reviewed - High/Med issues addressed
- [ ] Full branch audit: `drone @seed audit @branch`
- [ ] Full branch audit: `drone @seedgo audit @branch`
- [ ] Branch memories updated:
- [ ] `BRANCH.local.json` - full session log
- [ ] `BRANCH.observations.json` - patterns learned
@@ -611,7 +611,7 @@ Track issues here as you encounter them. Don't fix during build - log and contin
**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs)
**Note:** Devpulse will perform its own Seed audit for visibility into the work.
**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`
src/aipass/flow/FPLAN-0009_citizen_classes_template_system_passport_2026-03-07.md
+609
View File
@@ -0,0 +1,609 @@
# 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/apps/flow.py
+1 -1
View File
@@ -258,7 +258,7 @@ def print_help(modules: List[Any]):
console.print(" [dim]python3 flow.py list[/dim]")
console.print()
console.print()
console.print("[bold]NOTE:[/bold] @ syntax (e.g., @flow, @seed) only works through drone:")
console.print("[bold]NOTE:[/bold] @ syntax (e.g., @flow, @seedgo) only works through drone:")
console.print(" [dim]drone flow create @flow \"Implementation task\"[/dim]")
console.print()
console.print("─" * 70)
src/aipass/flow/apps/handlers/__init__.py
+2 -2
View File
@@ -93,7 +93,7 @@ def _guard_branch_access():
f" from {MY_BRANCH}.apps.modules.create_plan import handle_command\n"
f"\n"
f" For full standards guide:\n"
f" drone @seed handlers\n"
f" drone @seedgo handlers\n"
f"{'='*60}"
)
return # Allow if truly can't determine
@@ -123,7 +123,7 @@ def _guard_branch_access():
f" from {MY_BRANCH}.apps.modules.create_plan import handle_command\n"
f"\n"
f" For full standards guide:\n"
f" drone @seed handlers\n"
f" drone @seedgo handlers\n"
f"{'='*60}"
)
src/aipass/flow/apps/handlers/dashboard/push_central.py
+1 -1
View File
@@ -60,7 +60,7 @@ def _find_repo_root() -> Path:
_REPO_ROOT = _find_repo_root()
AI_CENTRAL_DIR = _REPO_ROOT / "AI_CENTRAL"
AI_CENTRAL_DIR = _REPO_ROOT / ".ai_central"
CENTRAL_FILE = AI_CENTRAL_DIR / "PLANS.central.json"
# =============================================
src/aipass/flow/apps/handlers/json/json_handler.py
+1 -1
View File
@@ -5,7 +5,7 @@
# Date: 2025-11-21
# Version: 2.1.0
# Category: flow/handlers/json
# Code Standards: Seed-compliant (3-tier architecture, no logger in handlers)
# Code Standards: Seedgo-compliant (3-tier architecture, no logger in handlers)
#
# CHANGELOG (Max 5 entries):
# - v2.1.0 (2025-11-29): Removed Prax logger - handlers must not log (tier 3 standard)
src/aipass/flow/apps/handlers/mbank/process.py
+1 -1
View File
@@ -162,7 +162,7 @@ def load_trl_registry() -> Dict[str, Any]:
"version": "1.0.0",
"trl_mapping": {
"types": {
"SEED": "Seed AI System",
"SEEDGO": "Seedgo AI System",
"NEXUS": "Nexus AI System",
"SKILL": "Skills Modules",
"PRAX": "Prax Infrastructure",
src/aipass/flow/apps/handlers/plan/create.py
+1 -1
View File
@@ -11,7 +11,7 @@
# - v1.0.0 (2025-11-16): Handler extraction from archive_temp
#
# CODE STANDARDS:
# - Seed v3.0 compliant (handler independence, imports, architecture)
# - Seedgo v3.0 compliant (handler independence, imports, architecture)
# ==============================================
"""
src/aipass/flow/apps/handlers/plan/validator.py
+1 -1
View File
@@ -5,7 +5,7 @@
# Date: 2025-11-30
# Version: 0.3.0
# Category: flow/handlers/plan
# CODE STANDARDS: Seed v3.0
# CODE STANDARDS: Seedgo v3.0
#
# CHANGELOG (Max 5 entries):
# - v0.3.0 (2026-01-30): Accept PLAN-XXXX and PLANXXXX prefixes (not just FPLAN-)
src/aipass/flow/apps/handlers/template/get_template.py
+1 -1
View File
@@ -5,7 +5,7 @@
# Date: 2025-11-30
# Version: 1.2.0
# Category: flow/handlers/template
# CODE STANDARDS: Seed v3.0
# CODE STANDARDS: Seedgo v3.0
#
# CHANGELOG:
# - v1.2.0 (2025-11-30): Changed TEMPLATES_DIR from .cached_templates to templates (Flow owns templates now)
src/aipass/flow/apps/modules/aggregate_central.py
+2 -2
View File
@@ -5,7 +5,7 @@
# Date: 2025-11-30
# Version: 1.2.0
# Category: flow/modules
# CODE STANDARDS: Seed v3.0
# CODE STANDARDS: Seedgo v3.0
#
# CHANGELOG:
# - v1.2.0 (2025-11-30): Comprehensive sync fix - update branch statistics, recently_closed, and global_statistics
@@ -77,7 +77,7 @@ def _find_repo_root() -> Path:
_REPO_ROOT = _find_repo_root()
AI_CENTRAL_DIR = _REPO_ROOT / "AI_CENTRAL"
AI_CENTRAL_DIR = _REPO_ROOT / ".ai_central"
CENTRAL_FILE = AI_CENTRAL_DIR / "PLANS.central.json"
# =============================================
src/aipass/flow/apps/modules/close_plan.py
+2 -2
View File
@@ -9,14 +9,14 @@
# CHANGELOG (Max 5 entries):
# - v3.4.0 (2026-02-25): FIX orphaned .md files - idempotency check now cleans up stranded files on re-close
# - v3.3.0 (2026-02-14): FIX race condition - close_all spawns ONE background process instead of N
# - v3.2.0 (2026-02-14): Auto-confirm by default, step-by-step progress, per-step error handling (Seed standards)
# - v3.2.0 (2026-02-14): Auto-confirm by default, step-by-step progress, per-step error handling (Seedgo standards)
# - v3.1.0 (2026-02-14): FIX timeout - summary/archive now truly async via subprocess (was synchronous despite comments)
# - v3.0.0 (2026-02-14): DECOUPLE close from archive - close always succeeds, archive is non-blocking
# - v2.4.0 (2026-01-30): FIX close_all EOF error - handle non-interactive stdin in bulk close
# - v2.3.0 (2025-11-25): RE-ADDED template deletion - empty templates now deleted instead of archived
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# ==============================================
"""
src/aipass/flow/apps/modules/create_plan.py
+1 -1
View File
@@ -10,7 +10,7 @@
# - v1.0.0 (2025-11-16): Refactored from archive_temp, handler-based architecture
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# ==============================================
"""
src/aipass/flow/apps/modules/list_plans.py
+1 -1
View File
@@ -10,7 +10,7 @@
# - v1.0.0 (2025-11-21): Initial implementation, handler-based architecture
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# ==============================================
"""
src/aipass/flow/apps/modules/post_close_runner.py
+1 -1
View File
@@ -11,7 +11,7 @@
# - v1.0.0 (2026-02-14): Created - runs summary generation and mbank archival in background
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# ==============================================
"""
src/aipass/flow/apps/modules/registry_monitor.py
+1 -1
View File
@@ -11,7 +11,7 @@
# - v1.0.0 (2025-11-21): Initial port from archive_temp with Python watchdog integration
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# - Module-level logging (3-tier pattern)
# - Event-driven: fires trigger events, handlers in Trigger branch
# ==============================================
src/aipass/flow/apps/modules/restore_plan.py
+1 -1
View File
@@ -14,7 +14,7 @@
# - v1.0.0 (2025-11-21): Initial creation - restore closed plans to open status
#
# CODE STANDARDS:
# - Seed v3.0 compliant (imports, architecture, error handling)
# - Seedgo v3.0 compliant (imports, architecture, error handling)
# ==============================================
"""
src/aipass/devpulse/apps/plugins/__init__.py → src/aipass/flow/flow_json/.gitkeep
View File
src/aipass/flow/templates/default.md
+8 -8
View File
@@ -81,7 +81,7 @@ ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on
**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
- 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()
@@ -112,10 +112,10 @@ 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
# 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"
@@ -184,7 +184,7 @@ DELIVERABLES:
- Reports/logs → artifacts/reports/ or artifacts/logs/
CONSTRAINTS:
- Follow Seed standards (3-layer architecture)
- 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
@@ -204,7 +204,7 @@ WHEN COMPLETE:
- [ ] Created FPLAN-{number}
- [ ] Agent deployed for: [task]
- [ ] Agent completed: [outcome]
- [ ] Seed checklist passed: [file]
- [ ] Seedgo checklist passed: [file]
- [ ] Memories updated
**Log Pattern:** Task → Agent → Outcome → Quality check → Next
@@ -228,7 +228,7 @@ drone @ai_mail send @devpulse "PRODUCTION STOPPED: FPLAN-{number}" "Issue: [desc
- [ ] All goals achieved
- [ ] Agent output reviewed and verified
- [ ] Seed checklist on new code: `drone @seed checklist <file>`
- [ ] 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)
src/aipass/flow/templates/master.md
+17 -17
View File
@@ -84,7 +84,7 @@ ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on
**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
- 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()
@@ -122,10 +122,10 @@ 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
# 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"
@@ -286,16 +286,16 @@ When you see an issue, decide:
### False Positives Awareness
Seed audits are helpful but not infallible.
Seedgo audits are helpful but not infallible.
**When Seed flags something:**
**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 Seed's but still work
- Patterns that differ from Seedgo's but still work
- Checks that don't apply to your context
### Forward Momentum Summary
@@ -323,7 +323,7 @@ For quick status checks and debugging, these resources are available:
| 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 |
| Seedgo audit | `drone @seedgo audit @branch` | Code quality check |
Use these when you need to confirm status or investigate issues.
@@ -333,7 +333,7 @@ Each phase = focused agent deployment:
2. Write agent instructions in sub-plan
3. Deploy agent with single-task focus
4. Review agent output (don't rebuild yourself)
5. Seed checklist on new code
5. Seedgo checklist on new code
6. Close sub-plan
7. Update memories
8. Email status to @devpulse
@@ -380,7 +380,7 @@ DELIVERABLES:
- Reports/logs → artifacts/reports/ or artifacts/logs/
CONSTRAINTS:
- Follow Seed standards (3-layer architecture: apps/modules/handlers)
- 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
@@ -401,7 +401,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -413,7 +413,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -425,7 +425,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -437,7 +437,7 @@ WHEN COMPLETE:
- [ ] Agent deployed
- [ ] Agent completed
- [ ] Output reviewed
- [ ] Seed checklist passed
- [ ] Seedgo checklist passed
- [ ] Sub-plan closed
- [ ] Memories updated
- [ ] Email sent to @devpulse
@@ -486,7 +486,7 @@ Track issues here as you encounter them. Don't fix during build - log and contin
- [ ] All phases complete
- [ ] All sub-plans closed
- [ ] Issues Log reviewed - High/Med issues addressed
- [ ] Full branch audit: `drone @seed audit @branch`
- [ ] Full branch audit: `drone @seedgo audit @branch`
- [ ] Branch memories updated:
- [ ] `BRANCH.local.json` - full session log
- [ ] `BRANCH.observations.json` - patterns learned
@@ -499,7 +499,7 @@ Track issues here as you encounter them. Don't fix during build - log and contin
**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs)
**Note:** Devpulse will perform its own Seed audit for visibility into the work.
**Note:** Devpulse will perform its own Seedgo audit for visibility into the work.
### Definition of Done
[What specifically defines the project complete?]
src/aipass/prax/apps/handlers/monitoring/branch_detector.py
+1 -1
View File
@@ -187,7 +187,7 @@ class BranchDetector:
# Strategy 4: AI_CENTRAL files - {BRANCH}.central.json or {BRANCH}_central.json
# Path: .../AI_CENTRAL/AI_MAIL.central.json -> AI_MAIL
if 'AI_CENTRAL' in path_str or 'ai_central' in path_str.lower():
if 'AI_CENTRAL' in path_str or '.ai_central' in path_str or 'ai_central' in path_str.lower():
name = path.name
# Extract branch from filename patterns
branch_candidate = None
src/aipass/prax/prax_json/.gitkeep
View File
src/aipass/seedgo/apps/standards/aipass/handlers/config/ignore_handler.py
+1 -1
View File
@@ -61,7 +61,7 @@ FILE_SPECIFIC_IGNORES = {
# TEMPLATE IGNORE PATTERNS
# =============================================
# Template files that exist in Cortex template but aren't required in branches
# Template files that exist in spawn template but aren't required in branches
# Used by architecture_check.py when checking template baseline
TEMPLATE_IGNORE_PATTERNS = [
'.gitkeep', # Git placeholder files - not actual requirements
src/aipass/seedgo/apps/standards/aipass/handlers/json/json_handler.py
+10 -10
View File
@@ -6,7 +6,7 @@ import sys
import inspect
PACK_ROOT = Path(__file__).resolve().parent.parent.parent # json/ -> handlers/ -> aipass/
SEED_JSON_DIR = PACK_ROOT / "aipass_json"
SEEDGO_JSON_DIR = PACK_ROOT / "aipass_json"
JSON_TEMPLATES_DIR = PACK_ROOT / "json_templates"
@@ -82,12 +82,12 @@ def validate_json_structure(data: Any, json_type: str) -> bool:
def get_json_path(module_name: str, json_type: str) -> Path:
"""Get path for module JSON file"""
filename = f"{module_name}_{json_type}.json"
return SEED_JSON_DIR / filename
return SEEDGO_JSON_DIR / filename
def ensure_json_exists(module_name: str, json_type: str) -> bool:
"""Ensure JSON file exists, create from template if missing"""
SEED_JSON_DIR.mkdir(parents=True, exist_ok=True)
SEEDGO_JSON_DIR.mkdir(parents=True, exist_ok=True)
json_path = get_json_path(module_name, json_type)
@@ -238,16 +238,16 @@ if __name__ == "__main__":
border_style="bright_blue"
))
console.print()
console.print("[yellow]TESTING:[/yellow] Creating seed JSONs...")
console.print("[yellow]TESTING:[/yellow] Creating seedgo JSONs...")
# Test auto-creation
log_operation("test_operation", {"test": "data"}, "seed")
increment_counter("seed", "test_counter", 1)
update_data_metrics("seed", test_metric="working")
log_operation("test_operation", {"test": "data"}, "seedgo")
increment_counter("seedgo", "test_counter", 1)
update_data_metrics("seedgo", test_metric="working")
console.print()
console.print("[green]Check aipass_json/ directory for created files:[/green]")
console.print(" [dim]•[/dim] seed_config.json")
console.print(" [dim]•[/dim] seed_data.json")
console.print(" [dim]•[/dim] seed_log.json")
console.print(" [dim]•[/dim] seedgo_config.json")
console.print(" [dim]•[/dim] seedgo_data.json")
console.print(" [dim]•[/dim] seedgo_log.json")
console.print()
src/aipass/seedgo/apps/standards/aipass/handlers/standards/architecture_check.py
+3 -3
View File
@@ -81,7 +81,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'architecture', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'ARCHITECTURE'
}
@@ -392,7 +392,7 @@ def _should_ignore(path: Path, template_path: Path, ignore_config: Dict) -> bool
def check_template_baseline(module_path: str, bypass_rules: list | None = None) -> List[Dict]:
"""
Verify branch structure against Cortex template registry (source of truth)
Verify branch structure against spawn template registry (source of truth)
Loads the template registry, transforms paths for the branch ({{BRANCH}}, FILE_RENAMES),
and checks if all template items exist in the branch.
@@ -456,7 +456,7 @@ def check_template_baseline(module_path: str, bypass_rules: list | None = None)
'message': f'Error reading template registry: {e} (skipped)'
}]
# FILE_RENAMES mapping (from Cortex create_branch.py)
# FILE_RENAMES mapping (from spawn create_branch.py)
# Entry point filename strips leading dots (e.g., .VSCODE -> vscode.py)
entry_point_name = branch_name.lstrip('.').lower()
FILE_RENAMES = {
src/aipass/seedgo/apps/standards/aipass/handlers/standards/architecture_content.py
+3 -3
View File
@@ -32,14 +32,14 @@ def get_architecture_standards() -> str:
" [dim]apps/handlers/[/dim] (Implement) → ALL business logic, domain-organized",
"",
"[bold cyan]TEMPLATE BASELINE COMPLIANCE:[/bold cyan]",
" All branches must match Cortex template structure",
" All branches must match spawn template structure",
"",
" [yellow]Source of Truth:[/yellow] [dim].template_registry.json[/dim] (30 files + 20 dirs = 50 checks)",
" [yellow]Transformations:[/yellow] BRANCH.ID.json → SEED.id.json, {{BRANCH}} → SEED, etc.",
" [yellow]Transformations:[/yellow] BRANCH.ID.json → .trinity/passport.json, {{BRANCH}} → SEEDGO, etc.",
" [yellow]Why:[/yellow] Template is the contract - branches that drift break during updates",
"",
" [bold]Example scores:[/bold]",
" [green]98%:[/green] BACKUP_SYSTEM, SEED [green]94%:[/green] FLOW [yellow]86%:[/yellow] API",
" [green]98%:[/green] BACKUP_SYSTEM, SEEDGO [green]94%:[/green] FLOW [yellow]86%:[/yellow] API",
"",
"[yellow]KEY RULES:[/yellow]",
"",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/cli_check.py
+1 -1
View File
@@ -70,7 +70,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'cli', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'CLI'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/cli_content.py
+3 -3
View File
@@ -26,7 +26,7 @@ def get_cli_standards() -> str:
"[yellow]POLICY:[/yellow] Rich formatting is THE standard for ALL AIPass output",
"",
"[green]✓ Approved:[/green]",
" [dim]from cli.apps.modules import console[/dim]",
" [dim]from aipass.cli.apps.modules import console[/dim]",
" [dim]console.print(\"[cyan]This is the ONLY approved way[/cyan]\")[/dim]",
"",
"[red]✗ Deprecated:[/red] Bare print() statements",
@@ -53,8 +53,8 @@ def get_cli_standards() -> str:
"[yellow]RULE:[/yellow] Build BOTH or neither",
"",
"[bold cyan]CLI SERVICE PROVIDER:[/bold cyan]",
" [dim]from cli.apps.modules import console, header, success, error[/dim]",
" [dim]from cli.apps.modules import operation_start, track_operation[/dim]",
" [dim]from aipass.cli.apps.modules import console, header, success, error[/dim]",
" [dim]from aipass.cli.apps.modules import operation_start, track_operation[/dim]",
"",
" • Consistent formatting across all branches",
" • Update CLI once → affects entire system",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/cli_flags_check.py
+1 -1
View File
@@ -69,7 +69,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'cli_flags', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'CLI_FLAGS'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/documentation_check.py
+1 -1
View File
@@ -57,7 +57,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'documentation', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'DOCUMENTATION'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/documentation_content.py
+1 -1
View File
@@ -2,7 +2,7 @@
Documentation Standards Content Handler
Condensed documentation standards verified against actual codebase.
Truth-checked 2025-11-13 against cortex and seed production code.
Truth-checked 2025-11-13 against spawn and seedgo production code.
"""
# =================== META ====================
src/aipass/seedgo/apps/standards/aipass/handlers/standards/encapsulation_check.py
+1 -1
View File
@@ -173,7 +173,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'encapsulation', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'ENCAPSULATION'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/error_handling_check.py
+1 -1
View File
@@ -69,7 +69,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'error_handling', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'ERROR_HANDLING'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/error_handling_content.py
+2 -2
View File
@@ -109,10 +109,10 @@ def get_error_handling_standards() -> str:
"[bold yellow]VALIDATION RULES:[/bold yellow]",
"",
"[dim]# All modules MUST import Prax[/dim]",
"[dim]grep -r \"from prax\" apps/modules/*.py[/dim]",
"[dim]grep -r \"from aipass.prax\" apps/modules/*.py[/dim]",
"",
"[dim]# NO handlers can import Prax[/dim]",
"[dim]grep -r \"from prax\" apps/handlers/**/*.py # Should find NOTHING[/dim]",
"[dim]grep -r \"from aipass.prax\" apps/handlers/**/*.py # Should find NOTHING[/dim]",
"",
"[dim]# NO handlers can call logger[/dim]",
"[dim]grep -r \"logger\\.\" apps/handlers/**/*.py # Should find NOTHING[/dim]",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/handlers_check.py
+5 -5
View File
@@ -70,7 +70,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'handlers', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'HANDLERS'
}
@@ -142,9 +142,9 @@ def check_handler_independence(content: str, lines: List[str], module_path: str)
Check handler independence - no cross-handler imports except defaults
Rules:
- ✅ ALLOWED: from seed.apps.handlers.json import json_handler (default handler)
- ✅ ALLOWED: from .decorators import catch_errors (same package)
- ❌ FORBIDDEN: from seed.apps.handlers.error import error_handler (cross-handler)
- ALLOWED: from aipass.seedgo.apps.handlers.json import json_handler (default handler)
- ALLOWED: from .decorators import catch_errors (same package)
- FORBIDDEN: from aipass.seedgo.apps.handlers.error import error_handler (cross-handler)
"""
forbidden_imports = []
@@ -255,7 +255,7 @@ def check_no_orchestration(content: str, lines: List[str]) -> Optional[Dict]:
Check that handler doesn't import/call modules (orchestration)
Handlers should be pure implementation, not orchestration.
❌ FORBIDDEN: from seed.apps.modules import some_module
FORBIDDEN: from aipass.seedgo.apps.modules import some_module
"""
module_imports = []
src/aipass/seedgo/apps/standards/aipass/handlers/standards/handlers_content.py
+8 -8
View File
@@ -43,12 +43,12 @@ def get_handlers_standards() -> str:
"",
"[bold]2. Independence Rules (No Circular Dependencies)[/bold]",
" [green]✓ ALLOWED[/green] - Handler imports handler (same branch):",
" [dim] # seed/apps/handlers/standards/check.py[/dim]",
" [dim] from seed.apps.handlers.json import json_handler # OK[/dim]",
" [dim] # seedgo/apps/handlers/standards/check.py[/dim]",
" [dim] from aipass.seedgo.apps.handlers.json import json_handler # OK[/dim]",
"",
" [red]✗ FORBIDDEN[/red] - Handler imports own-branch modules:",
" [dim] # seed/apps/handlers/json/json_handler.py[/dim]",
" [dim] from seed.apps.modules.create import something # NO[/dim]",
" [dim] # seedgo/apps/handlers/json/json_handler.py[/dim]",
" [dim] from aipass.seedgo.apps.modules.create import something # NO[/dim]",
"",
" [yellow]Why?[/yellow] Modules import handlers. If handlers import modules → cycle.",
"",
@@ -58,14 +58,14 @@ def get_handlers_standards() -> str:
"",
" [green]✓ Same-branch imports:[/green] ALLOWED",
" [dim] # flow/apps/handlers/plan/create.py[/dim]",
" [dim] from flow.apps.handlers.registry.load import load_registry # OK[/dim]",
" [dim] from aipass.flow.apps.handlers.registry.load import load_registry # OK[/dim]",
"",
" [red]✗ Cross-branch imports:[/red] BLOCKED (security guard)",
" [dim] # flow/apps/modules/list_plans.py[/dim]",
" [dim] from prax.apps.handlers.logging.setup import get_logger # BLOCKED[/dim]",
" [dim] from aipass.prax.apps.handlers.logging.setup import get_logger # BLOCKED[/dim]",
"",
" [green]✓ Correct pattern:[/green] Import the MODULE (public API)",
" [dim] from prax.apps.modules.logger import system_logger as logger # OK[/dim]",
" [dim] from aipass.prax.apps.modules.logger import system_logger as logger # OK[/dim]",
"",
" [yellow]Special Note - Drone Architecture:[/yellow]",
" • Drone is [red]NOT imported[/red] by branches",
@@ -107,7 +107,7 @@ def get_handlers_standards() -> str:
" • Standard across all branches",
" • [green]3-tier compliant[/green] - raises exceptions, modules log",
"",
" [dim]from seed.apps.handlers.json import json_handler[/dim]",
" [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]",
" [dim]json_handler.log_operation('operation', data)[/dim]",
"",
"[bold cyan]KEY WARNINGS:[/bold cyan]",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/imports_check.py
+2 -2
View File
@@ -57,7 +57,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'imports', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'IMPORTS'
}
@@ -377,7 +377,7 @@ def check_no_bare_imports(lines: List[str], file_path: str = "", bypass_rules: l
- from handlers.{name} import ... (bare handler import, missing namespace)
- from modules.{name} import ... (bare module import, missing namespace)
- from {module}.apps... (bare module, missing aipass. prefix)
- from seed.apps... (old Dev-Pass namespace)
- from seed.apps... (old Dev-Pass namespace, now aipass.seedgo)
- from prax.apps... (bare, should be from aipass.prax...)
VALID patterns:
src/aipass/seedgo/apps/standards/aipass/handlers/standards/imports_content.py
+8 -8
View File
@@ -32,13 +32,13 @@ def get_imports_standards() -> str:
" • json, datetime, typing, pathlib, etc.",
"",
"[bold]3. Prax logger (nearly always)[/bold]",
" • [dim]from prax.apps.modules.logger import system_logger as logger[/dim]",
" • [dim]from aipass.prax.apps.modules.logger import system_logger as logger[/dim]",
"",
"[bold]4. Services (CLI, etc.)[/bold]",
" • [dim]from cli.apps.modules import console, header, success[/dim]",
" • [dim]from aipass.cli.apps.modules import console, header, success[/dim]",
"",
"[bold]5. Internal handlers[/bold]",
" • [dim]from seed.apps.handlers.json import json_handler[/dim]",
" • [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]",
"",
"[yellow]RULE:[/yellow] Infrastructure → Stdlib → Prax → Services → Internal",
"",
@@ -50,8 +50,8 @@ def get_imports_standards() -> str:
" [dim]from datetime import datetime[/dim]",
" [dim]from typing import Dict, List, Optional[/dim]",
"",
" [dim]from prax.apps.modules.logger import system_logger as logger[/dim]",
" [dim]from cli.apps.modules import console, header[/dim]",
" [dim]from aipass.prax.apps.modules.logger import system_logger as logger[/dim]",
" [dim]from aipass.cli.apps.modules import console, header[/dim]",
" [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]",
"",
"[bold cyan]CRITICAL RULES:[/bold cyan]",
@@ -73,8 +73,8 @@ def get_imports_standards() -> str:
"",
"[bold]Context-Dependent Services (PWD detection):[/bold]",
" • [yellow]AI_MAIL[/yellow] - requires calling from branch directory",
" • Uses PWD to detect sender identity (@seed, @drone, etc.)",
" • Auto-generates config at [branch]/seed_json/user_config.json",
" • Uses PWD to detect sender identity (@seedgo, @drone, etc.)",
" • Auto-generates config at [branch]/seedgo_json/user_config.json",
"",
"[bold]Best Practice - Use Drone:[/bold]",
" [dim]subprocess.run([\"drone\", \"email\", \"send\", \"@recipient\", \"Subject\", \"Message\"])[/dim]",
@@ -85,7 +85,7 @@ def get_imports_standards() -> str:
" [dim] cwd=str(branch_dir)) # Force correct working directory[/dim]",
" • Must use cwd= parameter for PWD detection to work",
"",
"[yellow]KEY:[/yellow] AI_MAIL walks up from CWD to find *.id.json for branch identity",
"[yellow]KEY:[/yellow] AI_MAIL walks up from CWD to find .trinity/passport.json for branch identity",
"",
"[bold cyan]DEMONSTRATION:[/bold cyan]",
" [dim]src/aipass/seedgo/apps/standards/aipass/modules/ (reference modules)[/dim]",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/json_structure_check.py
+1 -1
View File
@@ -184,7 +184,7 @@ def check_json_handler_config(handler_path: Path, content: str, bypass_rules: li
# Check 1: No hardcoded absolute paths
has_path_home = bool(re.search(r'Path\.home\(\)', content))
# Only flag _ROOT constants that use Path.home() (Dev-Pass pattern)
# Only flag _ROOT constants that use Path.home() (legacy pattern)
# Allow _ROOT = Path(__file__).resolve()... (relative, pip-safe)
has_branch_root = False
for line in content.split('\n'):
src/aipass/seedgo/apps/standards/aipass/handlers/standards/json_structure_content.py
+2 -2
View File
@@ -31,7 +31,7 @@ def get_json_structure_standards() -> str:
"[yellow]RULE:[/yellow] Auto-created on first use - NEVER create manually",
"",
"[bold cyan]USAGE (AUTO-DETECTION):[/bold cyan]",
" [dim]from seed.apps.handlers.json import json_handler[/dim]",
" [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]",
"",
" [dim]# Handler auto-detects calling module name:[/dim]",
" [dim]json_handler.log_operation(\"operation_name\", {\"key\": \"value\"})[/dim]",
@@ -60,7 +60,7 @@ def get_json_structure_standards() -> str:
" • Per-module: [dim]src/aipass/{module}/{module}_json/[/dim]",
"",
"[bold red]SETUP json_handler.py (MANDATORY):[/bold red]",
" [red]✗ DO NOT copy SEED's handler without changing paths![/red]",
" [red]✗ DO NOT copy seedgo's handler without changing paths![/red]",
"",
" [green]✓ Update BRANCH_ROOT:[/green]",
" [dim]{BRANCH}_ROOT = Path(__file__).resolve().parents[N][/dim]",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_handler_check.py
+1 -1
View File
@@ -67,7 +67,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'log_handler', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'LOG_HANDLER'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_level_check.py
+1 -1
View File
@@ -67,7 +67,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'log_level', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'LOG_LEVEL'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_structure_check.py
+1 -1
View File
@@ -70,7 +70,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'log_structure', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'LOG_STRUCTURE'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_structure_content.py
+1 -1
View File
@@ -42,7 +42,7 @@ def get_log_structure_standards() -> List[str]:
" [dim] log_path = LOG_DIR / 'module_name.log'[/dim]",
"",
" [red]WRONG:[/red]",
" [dim] log_path = '/home/aipass/system_logs/module.log'[/dim]",
" [dim] log_path = '/absolute/path/system_logs/module.log'[/dim]",
" [dim] log_path = Path.home() / 'logs' / 'module.log'[/dim]",
"",
"[bold cyan]REFERENCE:[/bold cyan]",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_visibility_check.py
+2 -2
View File
@@ -69,7 +69,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'log_visibility', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'LOG_VISIBILITY'
}
@@ -168,7 +168,7 @@ def _check_prax_import(lines: List[str], content: str, file_path: str, bypass_ru
Applies to ALL files — no handler exemption.
"""
has_prax_import = bool(re.search(
r'from\s+prax\.apps\.modules\.logger\s+import',
r'from\s+aipass\.prax\.apps\.modules\.logger\s+import',
content
))
src/aipass/seedgo/apps/standards/aipass/handlers/standards/log_visibility_content.py
+2 -2
View File
@@ -18,7 +18,7 @@ from pathlib import Path
_GETLOGGER = "logging" + ".getLogger"
_FILEHANDLER = "logging" + ".FileHandler"
_PRAX_IMPORT = "from prax.apps.modules.logger import system_logger as logger"
_PRAX_IMPORT = "from aipass.prax.apps.modules.logger import system_logger as logger"
def get_log_visibility_standards() -> str:
@@ -45,7 +45,7 @@ def get_log_visibility_standards() -> str:
[bold cyan]EXEMPT[/bold cyan]
- Prax's own logging infrastructure (it IS the implementation)
- Test files (test isolation)
- Files with .seed/bypass.json exceptions
- Files with .seedgo/bypass.json exceptions
[yellow]TWO CHECKS (v3.0.0):[/yellow]
src/aipass/seedgo/apps/standards/aipass/handlers/standards/meta_check.py
+2 -2
View File
@@ -2,7 +2,7 @@
META Block Standards Checker Handler
Validates library-profile META blocks in Python files.
Library META is lighter than Dev-Pass META - focuses on identity
Library META is lighter than full META - focuses on identity
and traceability without branch-specific fields.
Required META format:
@@ -74,7 +74,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'meta', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'META'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/modules_check.py
+1 -1
View File
@@ -71,7 +71,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'modules', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'MODULES'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/modules_content.py
+3 -3
View File
@@ -63,9 +63,9 @@ def get_modules_standards() -> str:
" • 400+ lines: Consider splitting by domain",
"",
"[bold cyan]ESSENTIAL IMPORTS:[/bold cyan]",
" [dim]from prax.apps.modules.logger import system_logger as logger[/dim]",
" [dim]from cli.apps.modules import console, header, success, error[/dim]",
" [dim]from seed.apps.handlers.json import json_handler[/dim]",
" [dim]from aipass.prax.apps.modules.logger import system_logger as logger[/dim]",
" [dim]from aipass.cli.apps.modules import console, header, success, error[/dim]",
" [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]",
"",
"[bold cyan]WARNINGS:[/bold cyan]",
" • NEVER use [dim]logger.debug()[/dim] - use [dim]logger.info()[/dim] only",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/naming_check.py
+1 -1
View File
@@ -70,7 +70,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'naming', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'NAMING'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/naming_content.py
+1 -1
View File
@@ -34,7 +34,7 @@ def get_naming_standards() -> str:
" [green]✓[/green] [dim]cli/apps/handlers/error/decorators.py[/dim]",
" [green]✓[/green] [dim]cli/apps/handlers/error/formatters.py[/dim]",
" [green]✓[/green] [dim]prax/apps/handlers/config/load_config.py[/dim]",
" [green]✓[/green] [dim]seed/apps/handlers/domain1/ops.py[/dim]",
" [green]✓[/green] [dim]seedgo/apps/handlers/domain1/ops.py[/dim]",
"",
"[bold]Bad (current violations):[/bold]",
" [red]✗[/red] [dim]prax/apps/handlers/json/json_ops.py[/dim] - redundant 'json_'",
src/aipass/seedgo/apps/standards/aipass/handlers/standards/permission_flags_check.py
+1 -1
View File
@@ -96,7 +96,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'permission_flags', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'PERMISSION_FLAGS'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/readme_check.py
+3 -3
View File
@@ -69,7 +69,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'readme', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'README'
}
@@ -331,7 +331,7 @@ def check_directory_tree(lines: List[str], branch_root: Path, file_path: str, by
# Extract directory names from tree block, line by line
# Strip inline comments (text after #) to avoid false positives
# Skip the first non-empty line (root label, e.g., "seed/" or "src/aipass/.../cortex/")
# Skip the first non-empty line (root label, e.g., "seedgo/" or "src/aipass/.../spawn/")
# Common tree formats: "apps/", "├── apps/", "│ ├── handlers/", " apps/"
dir_pattern = re.compile(r'[\w\-_.]+/')
branch_name = branch_root.name.lower()
@@ -350,7 +350,7 @@ def check_directory_tree(lines: List[str], branch_root: Path, file_path: str, by
for match in dir_pattern.finditer(tree_line):
dir_name = match.group().rstrip('/')
# Skip the branch root name itself
# (trees typically start with the branch name, e.g., "seed/")
# (trees typically start with the branch name, e.g., "seedgo/")
if dir_name.lower() == branch_name:
continue
if dir_name in ('__pycache__', '.git', 'node_modules'):
src/aipass/seedgo/apps/standards/aipass/handlers/standards/readme_generator.py
+5 -5
View File
@@ -9,7 +9,7 @@ Sections generated:
- Directory tree (apps/ structure)
- Modules list (with docstring descriptions)
- Commands (from --help output)
- Header (from id.json)
- Header (from .trinity/passport.json)
- Last Updated timestamp
"""
@@ -476,9 +476,9 @@ def _parse_help_output(help_text: str) -> str:
def generate_header_section(branch_path: str) -> str:
"""
Generate the README header block from the branch's id.json.
Generate the README header block from the branch's passport.
Reads [BRANCH].id.json and extracts: branch_name, path, profile,
Reads .trinity/passport.json and extracts: branch_name, path, profile,
created, email.
Args:
@@ -490,8 +490,8 @@ def generate_header_section(branch_path: str) -> str:
branch_dir = Path(branch_path)
branch_name = branch_dir.name.upper().replace('-', '_')
# Find id.json
id_file = branch_dir / f'{branch_name}.id.json'
# Find passport.json
id_file = branch_dir / '.trinity' / 'passport.json'
if not id_file.exists():
return ""
src/aipass/seedgo/apps/standards/aipass/handlers/standards/shebang_check.py
+1 -1
View File
@@ -60,7 +60,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'shebang', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'SHEBANG'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/template_scanner.py
+2 -2
View File
@@ -1,7 +1,7 @@
"""
Template Scanner - Automatically scan template to discover structure
Scans Cortex template directory and generates baseline structure.
Scans Spawn template directory and generates baseline structure.
Respects .registry_ignore.json patterns.
"""
@@ -155,7 +155,7 @@ if __name__ == "__main__":
for f in sorted(structure['root_files']):
console.print(f" - {f}")
# Compare to SEED
# Compare to branch
if len(sys.argv) > 1:
branch_path = Path(sys.argv[1])
branch_name = branch_path.name
src/aipass/seedgo/apps/standards/aipass/handlers/standards/testing_check.py
+1 -1
View File
@@ -71,7 +71,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
if is_bypassed(module_path, 'testing', bypass_rules=bypass_rules):
return {
'passed': True,
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seed/bypass.json'}],
'checks': [{'name': 'Bypassed', 'passed': True, 'message': 'Standard bypassed via .seedgo/bypass.json'}],
'score': 100,
'standard': 'TESTING'
}
src/aipass/seedgo/apps/standards/aipass/handlers/standards/trigger_check.py
+3 -3
View File
@@ -7,7 +7,7 @@ Validates compliance with AIPass Trigger event bus standards:
- No print statements in event handlers
- Proper event naming conventions
Valid bypass categories for .seed/bypass.json:
Valid bypass categories for .seedgo/bypass.json:
- handler_layer: Function in handlers/ layer (orchestrator fires instead)
- initialization: One-time setup/config creation
- internal_ops: Same-module internal operation
@@ -45,7 +45,7 @@ def is_bypassed(file_path: str, standard: str, line: int | None = None, bypass_r
file_path: Path to file being checked
standard: Standard name (e.g., 'trigger')
line: Optional specific line number
bypass_rules: List of bypass rules from .seed/bypass.json
bypass_rules: List of bypass rules from .seedgo/bypass.json
Returns:
tuple: (is_bypassed: bool, category: str | None, reason: str | None)
@@ -109,7 +109,7 @@ def check_module(module_path: str, bypass_rules: list | None = None) -> Dict:
# Check if entire standard is bypassed
bypassed, category, reason = is_bypassed(module_path, 'trigger', bypass_rules=bypass_rules)
if bypassed:
bypass_msg = 'Standard bypassed via .seed/bypass.json'
bypass_msg = 'Standard bypassed via .seedgo/bypass.json'
if category:
bypass_msg += f' [category: {category}]'
if reason:
src/aipass/seedgo/apps/standards/aipass/handlers/verify/checker_sync.py
+6 -6
View File
@@ -176,18 +176,18 @@ def check_checker_sync() -> Dict:
if missing_in_doc:
issues.append(f"docs/checkers.md missing: {missing_in_doc}")
# Check SEED.id.json standards count
seed_id_path = PACK_ROOT / "SEED.id.json"
if seed_id_path.exists() and checkers_dir.exists():
seed_id_content = seed_id_path.read_text()
# Check .trinity/passport.json standards count
passport_path = PACK_ROOT / ".trinity" / "passport.json"
if passport_path.exists() and checkers_dir.exists():
passport_content = passport_path.read_text()
actual_checkers = len([f for f in checkers_dir.glob("*_check.py")])
# Find any "N standards" or "N core standards" mentions
id_counts = re.findall(r'(\d+)\s*(?:core\s*)?(?:AIPass\s*)?(?:code\s*)?standards?', seed_id_content, re.IGNORECASE)
id_counts = re.findall(r'(\d+)\s*(?:core\s*)?(?:AIPass\s*)?(?:code\s*)?standards?', passport_content, re.IGNORECASE)
for count_str in set(id_counts):
count = int(count_str)
if count != actual_checkers:
issues.append(f"SEED.id.json says {count} standards but {actual_checkers} checkers exist")
issues.append(f".trinity/passport.json says {count} standards but {actual_checkers} checkers exist")
# Check seedgo.py --help for consistent standards count
seed_entry_path = PACK_ROOT / "apps/seedgo.py"
src/aipass/seedgo/apps/standards/aipass/handlers/verify/freshness_check.py
+5 -5
View File
@@ -32,7 +32,7 @@ def check_file_freshness() -> Dict:
# Check if standards_audit.py exists
audit_file = seed_path / "apps" / "modules" / "standards_audit.py"
readme_file = seed_path / "README.md"
local_json = seed_path / "SEED.local.json"
local_json = seed_path / ".trinity" / "local.json"
if not audit_file.exists():
issues.append("standards_audit.py not found")
@@ -59,23 +59,23 @@ def check_file_freshness() -> Dict:
else:
issues.append("README.md not found")
# Check if SEED.local.json was updated today
# Check if .trinity/local.json was updated today
if local_json.exists():
local_mtime = datetime.fromtimestamp(local_json.stat().st_mtime)
if local_mtime.date() != datetime.now().date():
issues.append(
f"SEED.local.json last updated {local_mtime.date()} "
f".trinity/local.json last updated {local_mtime.date()} "
f"(not today)"
)
else:
issues.append("SEED.local.json not found")
issues.append(".trinity/local.json not found")
return {
'name': 'File Freshness',
'passed': len(issues) == 0,
'issues': issues,
'checked': [
f"SEED.local.json updated: {local_mtime.date()}" if local_json.exists() else "SEED.local.json: not found",
f".trinity/local.json updated: {local_mtime.date()}" if local_json.exists() else ".trinity/local.json: not found",
f"README.md updated: {readme_mtime.date()}" if readme_file.exists() else "README.md: not found"
],
'score': 100 if len(issues) == 0 else max(0, 100 - (len(issues) * 30))
src/aipass/seedgo/apps/standards/aipass/handlers/verify/help_check.py
+3 -3
View File
@@ -28,11 +28,11 @@ def check_help_consistency() -> Dict:
Returns:
Dict with check results
"""
seed_file = Path(__file__).resolve().parents[5] / "apps" / "seedgo.py" # seedgo root / apps / seedgo.py
seedgo_file = Path(__file__).resolve().parents[5] / "apps" / "seedgo.py" # seedgo root / apps / seedgo.py
issues = []
removed_flags = []
if not seed_file.exists():
if not seedgo_file.exists():
return {
'name': 'Help Consistency',
'passed': False,
@@ -42,7 +42,7 @@ def check_help_consistency() -> Dict:
# Read seedgo.py and check for removed flags in help text
try:
content = file_handler.read_file(str(seed_file))
content = file_handler.read_file(str(seedgo_file))
if content is None:
return {
'name': 'Help Consistency',
src/aipass/seedgo/apps/standards/aipass/handlers/verify/orchestrator.py
+1 -1
View File
@@ -40,7 +40,7 @@ def run_verification() -> Dict:
Dict with all check results
"""
console.print()
header("SEED SYNC VERIFICATION")
header("SEEDGO SYNC VERIFICATION")
console.print()
checks = [
src/aipass/seedgo/apps/standards/aipass/handlers/verify/stale_check.py
+5 -5
View File
@@ -1,7 +1,7 @@
"""
Stale Patterns Checker Handler
Checks for deprecated patterns in the seed codebase.
Checks for deprecated patterns in the seedgo codebase.
Returns violations found during grep search.
"""
@@ -29,7 +29,7 @@ def check_stale_patterns() -> Dict:
Returns:
Dict with check results
"""
seed_path = Path(__file__).resolve().parents[5] # -> seedgo root
seedgo_path = Path(__file__).resolve().parents[5] # -> seedgo root
deprecated_patterns = ignore_handler.get_deprecated_patterns()
violations = []
@@ -38,7 +38,7 @@ def check_stale_patterns() -> Dict:
try:
# Use grep to search for pattern
result = subprocess.run(
["grep", "-rn", pattern, str(seed_path),
["grep", "-rn", pattern, str(seedgo_path),
"--include=*.py", "--include=*.md"],
capture_output=True,
text=True,
@@ -53,8 +53,8 @@ def check_stale_patterns() -> Dict:
if len(parts) >= 2:
file_path = parts[0]
line_num = parts[1]
# Make path relative to seed for readability
rel_path = Path(file_path).relative_to(seed_path)
# Make path relative to seedgo for readability
rel_path = Path(file_path).relative_to(seedgo_path)
violations.append({
'pattern': pattern,
'reason': reason,
src/aipass/seedgo/apps/standards/aipass/modules/diagnostics_audit.py
+2 -2
View File
@@ -200,7 +200,7 @@ def handle_command(command: str, args: List[str]) -> bool:
def print_introspection():
"""Display module info when run without arguments (Seed pattern)"""
"""Display module info when run without arguments (Seedgo pattern)"""
console.print()
console.print("[bold cyan]Diagnostics Audit Module[/bold cyan]")
console.print()
@@ -232,7 +232,7 @@ def print_help():
console.print(" seedgo diagnostics flow")
console.print()
console.print(" seedgo diagnostics")
console.print(" seedgo diagnostics cortex")
console.print(" seedgo diagnostics spawn")
console.print()
console.print("[yellow]WHAT IT CHECKS:[/yellow]")
src/aipass/seedgo/apps/standards/aipass/modules/readme_update.py
+6 -6
View File
@@ -75,7 +75,7 @@ def handle_command(command: str, args: List[str]) -> bool:
elif subcommand == "check":
_handle_check(remaining_args)
else:
# Maybe it's a branch name without subcommand: `seed readme @cortex`
# Maybe it's a branch name without subcommand: `seedgo readme @spawn`
_handle_update(args)
return True
@@ -174,7 +174,7 @@ def _handle_check(args: List[str]) -> None:
def _print_target_error(error: str) -> None:
"""Display target resolution errors"""
if error == "no_args":
console.print("[yellow]Usage: seed readme update @branch[/yellow]")
console.print("[yellow]Usage: seedgo readme update @branch[/yellow]")
console.print("[dim]Use @all to update all branches[/dim]")
elif error == "no_branches":
console.print("[red]No branches found in registry[/red]")
@@ -213,15 +213,15 @@ def print_help():
header("README Auto-Update")
console.print()
console.print("[yellow]USAGE:[/yellow]")
console.print(" seed readme update @branch Update auto-generated sections")
console.print(" seed readme update @all Update all branch READMEs")
console.print(" seed readme check @branch Dry run - show what would change")
console.print(" seedgo readme update @branch Update auto-generated sections")
console.print(" seedgo readme update @all Update all branch READMEs")
console.print(" seedgo readme check @branch Dry run - show what would change")
console.print()
console.print("[yellow]AUTO-GENERATED SECTIONS:[/yellow]")
console.print(" TREE Directory structure")
console.print(" MODULES Module list from apps/modules/")
console.print(" COMMANDS Commands from --help output")
console.print(" HEADER Branch info from id.json")
console.print(" HEADER Branch info from .trinity/passport.json")
console.print(" LAST_UPDATED Timestamp")
console.print()
console.print("[dim]Sections are marked with <!-- AUTO:NAME --> comments in README.md[/dim]")
src/aipass/seedgo/apps/standards/aipass/modules/standards_audit.py
+3 -3
View File
@@ -208,10 +208,10 @@ def print_help():
console.print("[yellow]USAGE:[/yellow]")
console.print(" [dim]# Via drone[/dim]")
console.print(" seedgo audit")
console.print(" seedgo audit cortex")
console.print(" seedgo audit spawn")
console.print()
console.print(" seedgo audit")
console.print(" seedgo audit cortex")
console.print(" seedgo audit spawn")
console.print(" seedgo audit --help")
console.print()
@@ -220,7 +220,7 @@ def print_help():
console.print(" seedgo audit")
console.print()
console.print(" [dim]# Full audit of specific branch[/dim]")
console.print(" seedgo audit cortex")
console.print(" seedgo audit spawn")
console.print()
console.print("[yellow]REFERENCE:[/yellow]")
src/aipass/seedgo/apps/standards/aipass/modules/standards_checklist.py
+16 -16
View File
@@ -75,7 +75,7 @@ def _find_registry() -> Path:
REGISTRY_PATH = _find_registry()
# =============================================================================
# BYPASS SYSTEM - .seed/ config per branch
# BYPASS SYSTEM - .seedgo/ config per branch
# =============================================================================
@@ -142,9 +142,9 @@ def get_branch_from_path(file_path: str) -> Optional[Dict[str, Any]]:
return None
def ensure_seed_config(branch_path: str) -> Path:
def ensure_seedgo_config(branch_path: str) -> Path:
"""
Ensure .seed/bypass.json exists for a branch, create if missing
Ensure .seedgo/bypass.json exists for a branch, create if missing
Args:
branch_path: Path to branch root
@@ -152,12 +152,12 @@ def ensure_seed_config(branch_path: str) -> Path:
Returns:
Path to bypass.json file
"""
seed_dir = Path(branch_path) / ".seed"
bypass_file = seed_dir / "bypass.json"
seedgo_dir = Path(branch_path) / ".seedgo"
bypass_file = seedgo_dir / "bypass.json"
try:
# Create .seed directory if needed
seed_dir.mkdir(exist_ok=True)
# Create .seedgo directory if needed
seedgo_dir.mkdir(exist_ok=True)
# Create bypass.json if missing
if not bypass_file.exists():
@@ -171,13 +171,13 @@ def ensure_seed_config(branch_path: str) -> Path:
return bypass_file
except Exception as e:
logger.error(f"[standards_checklist] Error creating seed config: {e}")
logger.error(f"[standards_checklist] Error creating seedgo config: {e}")
return bypass_file
def load_bypass_rules(branch_path: str) -> List[Dict[str, Any]]:
"""
Load bypass rules from branch's .seed/bypass.json
Load bypass rules from branch's .seedgo/bypass.json
Args:
branch_path: Path to branch root
@@ -185,7 +185,7 @@ def load_bypass_rules(branch_path: str) -> List[Dict[str, Any]]:
Returns:
List of bypass rule dicts
"""
bypass_file = ensure_seed_config(branch_path)
bypass_file = ensure_seedgo_config(branch_path)
try:
if bypass_file.exists():
@@ -294,7 +294,7 @@ def print_json_handler_introspection():
# OVERVIEW
console.print("[bold white]OVERVIEW:[/bold white]")
console.print(" Handles default JSON files (config, data, log) for seed modules.")
console.print(" Handles default JSON files (config, data, log) for seedgo modules.")
console.print(" Never manually create JSONs - they build themselves on first use.")
console.print()
@@ -358,7 +358,7 @@ def print_json_handler_introspection():
console.print("[bold white]TYPICAL WORKFLOW IN A MODULE:[/bold white]")
console.print()
console.print("[bold cyan]Step 1:[/bold cyan] Import the handler")
console.print(" [dim]from seed.apps.handlers.json import json_handler[/dim]")
console.print(" [dim]from aipass.seedgo.apps.handlers.json import json_handler[/dim]")
console.print()
console.print("[bold cyan]Step 2:[/bold cyan] Log operations (auto-creates all JSONs)")
@@ -402,8 +402,8 @@ def print_json_handler_introspection():
# CONSTANTS
console.print("[bold white]CONSTANTS:[/bold white]")
console.print(" [dim]PACK_ROOT = Path(__file__).resolve().parent.parent.parent[/dim]")
console.print(" [dim]SEED_JSON_DIR = SEED_ROOT / 'seed_json'[/dim]")
console.print(" [dim]JSON_TEMPLATES_DIR = SEED_ROOT / 'apps' / 'json_templates'[/dim]")
console.print(" [dim]SEEDGO_JSON_DIR = SEEDGO_ROOT / 'seedgo_json'[/dim]")
console.print(" [dim]JSON_TEMPLATES_DIR = SEEDGO_ROOT / 'apps' / 'json_templates'[/dim]")
console.print()
console.print("─" * 70)
@@ -494,7 +494,7 @@ def print_checklist(args: List[str]):
logger.info(f"[{MODULE_NAME}] Starting standards compliance check on {file_path}")
# Detect branch and setup .seed/ config
# Detect branch and setup .seedgo/ config
branch = get_branch_from_path(file_path)
bypass_rules = []
branch_name = "Unknown"
@@ -514,7 +514,7 @@ def print_checklist(args: List[str]):
# Show branch info
console.print(f"[dim]Branch: {branch_name}[/dim]")
if branch_path:
bypass_file = Path(branch_path) / ".seed" / "bypass.json"
bypass_file = Path(branch_path) / ".seedgo" / "bypass.json"
console.print(f"[dim]Bypass config: {bypass_file}[/dim]")
if bypass_rules:
console.print(f"[dim]Active bypasses: {len(bypass_rules)}[/dim]")
src/aipass/seedgo/docs/aipass_code_standards/README.md
+3 -3
View File
@@ -29,10 +29,10 @@ Each file in this directory covers a specific aspect of code standards:
- CLI branch now provides centralized formatting and error handling services
- Follows Prax pattern: import once, use throughout
- Rich library integration for beautiful console output
- Error handling migrated from Cortex to CLI (eliminated ~10,300 lines duplicate code)
- Error handling centralized in CLI (eliminated ~10,300 lines duplicate code)
**Service Components:**
1. **Console Service** - Rich Console instance (`from cli.apps.modules import console`)
1. **Console Service** - Rich Console instance (`from aipass.cli.apps.modules import console`)
2. **Display Functions** - header, success, error, warning, section
3. **Operation Templates** - operation_start, operation_complete
4. **Error Handling** - OperationResult, decorators, automatic logging
@@ -46,7 +46,7 @@ Each file in this directory covers a specific aspect of code standards:
**Current Status:**
- CLI service implemented and tested (test_cli_errors.py passing)
- Seed pilot integration complete
- Seedgo pilot integration complete
- CLI branch self-adoption: 31% (needs error_handler.py and formatters.py migration)
- External adoption: 0 branches (ready for rollout)
src/aipass/seedgo/docs/aipass_code_standards/architecture.md
+28 -28
View File
@@ -28,15 +28,15 @@ apps/handlers/ (Implementation Layer)
**Result:** 25 files at 200-400 lines = AI processes fast, maintains context, makes fewer errors. Humans can scan any file in under a minute.
**Note:** All branches use `apps/` subdirectory for their code (e.g., `cortex/apps/`, `seed/apps/`, `flow/apps/`).
**Note:** All branches use `apps/` subdirectory for their code (e.g., `spawn/apps/`, `seedgo/apps/`, `flow/apps/`).
---
## Template Baseline Compliance
**Rule:** All branches must match the Cortex template structure.
**Rule:** All branches must match the Spawn template structure.
**Source of Truth:** `<project_root>/cortex/templates/branch_template/.template_registry.json`
**Source of Truth:** `<project_root>/spawn/templates/agent.template/.template_registry.json`
**What it checks:**
- All required files from template exist in branch (with proper name transformations)
@@ -44,21 +44,21 @@ apps/handlers/ (Implementation Layer)
- Template defines 30 files + 20 directories = 50 structural requirements
**Name transformations applied:**
- `{{BRANCH}}` placeholder → Branch name in uppercase (e.g., `SEED`, `API`, `CORTEX`)
- `BRANCH.ID.json` → `{BRANCHNAME}.id.json` (e.g., `SEED.id.json`)
- `LOCAL.json` → `{BRANCHNAME}.local.json` (e.g., `SEED.local.json`)
- `{{BRANCH}}` placeholder → Branch name in uppercase (e.g., `SEEDGO`, `API`, `SPAWN`)
- `BRANCH.ID.json` → `.trinity/passport.json` (identity file for every branch)
- `LOCAL.json` → `{BRANCHNAME}.local.json` (e.g., `SEEDGO.local.json`)
- `OBSERVATIONS.json` → `{BRANCHNAME}.observations.json`
- `AI_MAIL.json` → `{BRANCHNAME}.ai_mail.json`
- `BRANCH.py` → `{branchname}.py` (e.g., `seed.py`)
- `BRANCH.py` → `{branchname}.py` (e.g., `seedgo.py`)
- `README.md` → `README.json` (template uses .md, branches use .json)
**WHY:** Cortex creates branches from template. If branches drift from template structure (missing files/directories), updates break and branch becomes non-standard. Template is the contract - all branches must honor it.
**WHY:** Spawn creates branches from template. If branches drift from template structure (missing files/directories), updates break and branch becomes non-standard. Template is the contract - all branches must honor it.
**Verification:** Standards checker compares each branch against template registry, reports missing items.
**Example compliance scores:**
- BACKUP_SYSTEM: 98% (missing 1 directory)
- SEED: 98% (missing 1 directory)
- TRIGGER: 98% (missing 1 directory)
- SEEDGO: 98% (missing 1 directory)
- FLOW: 94% (missing 3 items)
- API: 86% (missing 7 items)
@@ -117,7 +117,7 @@ Result: ImportError on all drone commands, system broken
- Foundation services must be independent building blocks
**What CAN import foundation services:**
- Higher-level modules (Seed, Cortex, Flow, API, etc.) can import BOTH CLI and Prax
- Higher-level modules (Seedgo, Spawn, Flow, API, etc.) can import BOTH CLI and Prax
- Business logic can use both services together
- This is the correct pattern
@@ -141,9 +141,9 @@ Result: ImportError on all drone commands, system broken
## File Size Guidelines
- **Under 300 lines:** Perfect - AI quick scan, full comprehension, few errors
- **300-500 lines:** Good - manageable for AI and humans (most Cortex modules here)
- **300-500 lines:** Good - manageable for AI and humans (most Spawn modules here)
- **500-700 lines:** Getting heavy - watch it
- **700+ lines:** Consider splitting - AI context degrades, humans struggle (example: `cortex/apps/modules/update_branch.py` at 916 lines)
- **700+ lines:** Consider splitting - AI context degrades, humans struggle (example: `spawn/apps/modules/update_branch.py` at 916 lines)
**WHY:** AI comprehension drops with file size. Small files mean faster processing, cleaner context, fewer errors. Read a summary in seconds vs spending minutes processing a massive file.
@@ -166,7 +166,7 @@ apps/handlers/
└── cli/ → Everything about user interaction
```
**Verified from:** `<project_root>/cortex/apps/handlers/` - These are actual domains from Cortex.
**Verified from:** `<project_root>/spawn/apps/handlers/` - These are actual domains from Spawn.
**Note:** Actual domain names will vary by branch purpose. See naming.md for domain naming standards.
@@ -311,7 +311,7 @@ Run 'python3 create_plan.py --help' for usage
- Remove module → automatically gone
- Zero maintenance overhead
**Implementation:** See `/home/aipass/seed/apps/seed.py` and `/home/aipass/seed/apps/modules/architecture_standard.py` for reference pattern.
**Implementation:** See `<project_root>/seedgo/apps/seedgo.py` and `<project_root>/seedgo/apps/modules/architecture_standard.py` for reference pattern.
---
@@ -323,32 +323,32 @@ Run 'python3 create_plan.py --help' for usage
Drone handles TWO critical responsibilities:
1. **@ Resolution:** Converts branch handles (@flow, @seed, @cortex) to absolute paths (/home/aipass/flow, /home/aipass/seed, <project_root>/cortex)
1. **@ Resolution:** Converts branch handles (@flow, @seedgo, @spawn) to absolute paths via AIPASS_REGISTRY.json
2. **Command Routing:** Routes the resolved command to the target branch's entry point
### How @ Resolution Works
**User types:**
```bash
drone @flow create @seed "plan_name" "description"
drone @flow create @seedgo "plan_name" "description"
```
**Drone resolves @ symbols BEFORE passing to Flow:**
```bash
# What Drone does internally:
# 1. Sees target branch: @flow
# 2. Resolves @flow → /home/aipass/flow
# 3. Resolves @seed → /home/aipass/seed
# 4. Routes to: python3 /home/aipass/flow/apps/flow.py create /home/aipass/seed "plan_name" "description"
# 2. Resolves @flow → <project_root>/flow
# 3. Resolves @seedgo → <project_root>/seedgo
# 4. Routes to: python3 <project_root>/flow/apps/flow.py create <project_root>/seedgo "plan_name" "description"
```
**What Flow receives:**
```python
# Flow's sys.argv:
['flow.py', 'create', '/home/aipass/seed', 'plan_name', 'description']
['flow.py', 'create', '<project_root>/seedgo', 'plan_name', 'description']
# Flow receives the RESOLVED PATH, not the @ symbol
# Flow NEVER sees '@seed' - it sees '/home/aipass/seed'
# Flow NEVER sees '@seedgo' - it sees '<project_root>/seedgo'
```
### The Architecture Boundary
@@ -373,14 +373,14 @@ Handlers
**WRONG:**
```python
# DON'T DO THIS - Drone is NOT a library
from drone.apps.modules import resolve_branch
path = resolve_branch("@seed")
from aipass.drone.apps.modules import resolve_branch
path = resolve_branch("@seedgo")
```
**RIGHT:**
```bash
# Drone is a CLI tool - use it via command line
drone @seed architecture-standard
drone @seedgo architecture-standard
```
**WHY:** Drone is a CLI router, not a service provider. It sits OUTSIDE the branch ecosystem, routing commands TO branches. Branches receive commands that have ALREADY been processed by Drone.
@@ -401,7 +401,7 @@ def handle_command(command, args):
```python
# GOOD - Branch receives resolved path from Drone
def handle_command(command, args):
target = args[0] # Already a path like '/home/aipass/seed'
target = args[0] # Already a path like '<project_root>/seedgo'
if not os.path.exists(target):
print(f"Error: Path does not exist: {target}")
return False
@@ -436,7 +436,7 @@ def handle_command(command: str, args: List[str]) -> bool:
**NO ALIASES:** Session 14 removed all command aliases system-wide. One command per module.
**Note on args:** If command was routed through Drone, args will contain RESOLVED PATHS (like `/home/aipass/seed`), not @ symbols (like `@seed`).
**Note on args:** If command was routed through Drone, args will contain RESOLVED PATHS (like `<project_root>/seedgo`), not @ symbols (like `@seedgo`).
---
@@ -462,6 +462,6 @@ This pattern optimizes for CONSTRAINTS:
**Why agents matter:** Agents handle exploration/analysis separately (their own 200k context). Your main context stays clean. Process massive amounts of information in seconds without context pollution.
**Speed example:** 480k tokens of agent work in 5 minutes = what would take a full day of back-and-forth coding. Cortex builds a branch in less than a second. Updates entire system in ~10 seconds.
**Speed example:** 480k tokens of agent work in 5 minutes = what would take a full day of back-and-forth coding. Spawn builds a branch in less than a second. Updates entire system in ~10 seconds.
**Ignore these constraints at your peril.** System will slow down, become unreliable, eventually unmaintainable.
src/aipass/seedgo/docs/aipass_code_standards/cli.md
+18 -18
View File
@@ -33,7 +33,7 @@ Command-line interface design, arguments, the dual approach (interactive for hum
**For AI:** Argument-based commands via Drone
- `drone email send @recipient "subject" "message"`
- `drone dev add @cortex "category" "note"`
- `drone dev add @flow "category" "note"`
- Fast, scriptable, no interaction needed
**Rule:** If you build an interactive CLI, you MUST build argument equivalents.
@@ -49,7 +49,7 @@ drone <module> <command> [options] [arguments]
Examples:
drone email send @flow "Update" "Plan created successfully"
drone plan create @cortex "New Feature" "Add handler marketplace"
drone plan create @flow "New Feature" "Add handler marketplace"
drone dev add @prax "bug" "Logger not writing to file"
```
@@ -117,7 +117,7 @@ One line, done. No navigation.
### Approved Output Method
```python
from cli.apps.modules import console
from aipass.cli.apps.modules import console
console.print("[cyan]This is the ONLY approved way to output text[/cyan]")
```
@@ -173,7 +173,7 @@ parser.print_help()
```python
# Import CLI services
from cli.apps.modules import console, header, success, error, warning
from aipass.cli.apps.modules import console, header, success, error, warning
# Use throughout your module
console.print("[bold cyan]Starting operation...[/bold cyan]")
@@ -249,7 +249,7 @@ print("✅ Success!")
**After (CLI service):**
```python
from cli.apps.modules import console, header, success
from aipass.cli.apps.modules import console, header, success
console.print()
header("My Operation")
@@ -267,16 +267,16 @@ success("Operation complete!")
### Implementation Notes
- CLI branch provides service (like Prax for logging)
- Branches import from `cli.apps.modules`
- Branches import from `aipass.cli.apps.modules`
- Public API in `apps/modules/`, implementation in `apps/handlers/`
- Backward compatible (old usage still works)
**Reference:**
- Standard: `/home/aipass/standards/CODE_STANDARDS/cli.md`
- Implementation: `<project_root>/cli/`
- Example Usage: `/home/aipass/seed/apps/modules/test_cli_errors.py`
- Standard: `src/aipass/seedgo/docs/aipass_code_standards/cli.md`
- Implementation: `src/aipass/cli/`
- Example Usage: `src/aipass/seedgo/apps/modules/test_cli_errors.py`
- Interactive Demo: `<project_root>/planning/cli_layout_demo.py`
- Module Demo: `python3 /home/aipass/seed/apps/modules/cli_standard.py`
- Module Demo: `python3 src/aipass/seedgo/apps/modules/cli_standard.py`
---
@@ -409,7 +409,7 @@ parser.add_argument('--v1', type=str, help='First version for comparison')
**Every module MUST respond to `--help` using Rich formatting:**
```python
from cli.apps.modules import console
from aipass.cli.apps.modules import console
if __name__ == "__main__":
# Check for help FIRST
@@ -438,10 +438,10 @@ def print_help():
console.print()
```
**Reference: See any SEED module for complete examples**
**Reference: See any seedgo module for complete examples**
```bash
# See proper help formatting in action
python3 /home/aipass/seed/apps/modules/imports_standard.py --help
python3 src/aipass/seedgo/apps/modules/imports_standard.py --help
```
### Argument Types
@@ -635,7 +635,7 @@ if __name__ == "__main__":
**Real example from create_branch.py:**
```python
def handle_command(args) -> bool:
"""Orchestrator interface - called by cortex.py"""
"""Orchestrator interface - called by drone.py"""
if not hasattr(args, 'command'):
return False
@@ -687,7 +687,7 @@ def main():
**@-notation for targets:**
```bash
drone email send @flow "Subject" "Message"
drone plan create @cortex "Feature" "Description"
drone plan create @flow "Feature" "Description"
```
Implementation:
@@ -732,10 +732,10 @@ python backup.py snapshot --dry-run=true
**create_plan.py:**
```bash
# Simple positional args
python create_plan.py @cortex "New Feature" default
python create_plan.py @flow "New Feature" default
# With flags
python create_plan.py @cortex "New Feature" --template master
python create_plan.py @flow "New Feature" --template master
```
**delete_plan.py:**
@@ -974,7 +974,7 @@ def interactive_create_plan():
```bash
# Direct argument path
drone plan create @cortex "New Feature" default
drone plan create @flow "New Feature" default
```
### Synchronization Checklist
src/aipass/seedgo/docs/aipass_code_standards/cli_flags.md
+16 -24
View File
@@ -1,7 +1,7 @@
# CLI Flags Standard
**Status:** Active — Approved for Full Rollout
**Date:** 2026-02-21
**Proposed by:** SEED (Session 68, dispatch from DEV_CENTRAL)
**Proposed by:** SEEDGO (Session 68, dispatch from DEVPULSE)
## What This Covers
@@ -14,9 +14,9 @@ This is a companion to the existing CLI standard (`cli.md`), which covers output
## The Problem
Each branch independently decides which flags to support. Result:
- `--verbose` exists in 3 branches (PRAX, CORTEX, BACKUP_SYSTEM), absent from 13
- `--dry-run` exists in 3 branches (CORTEX, BACKUP_SYSTEM, MEMORY_BANK), absent from 13
- `--test` exists in 1 branch (BACKUP_SYSTEM only)
- `--verbose` exists in 3 branches (PRAX, SPAWN, TRIGGER), absent from 7
- `--dry-run` exists in 3 branches (SPAWN, TRIGGER, FLOW), absent from 7
- `--test` exists in 1 branch (TRIGGER only)
- `--version` exists in 0 branches
- `--help` is universal (the only consistent flag)
@@ -68,7 +68,7 @@ BRANCH_NAME v1.2.3
```python
def show_version():
"""Print version from META header."""
console.print("SEED v3.0.0")
console.print("SEEDGO v3.0.0")
# In main():
if args[0] in ['--version', '-V']:
@@ -119,13 +119,11 @@ Preview what would happen without executing.
**Branches where this applies:**
- FLOW (creating/deleting plans)
- AI_MAIL (sending emails)
- CORTEX (creating/deleting branches)
- BACKUP_SYSTEM (running backups)
- MEMORY_BANK (rolling over memories)
- SPAWN (creating/deleting branches)
- TRIGGER (firing events)
**Branches where this does NOT apply:**
- SEED (read-only checks)
- SEEDGO (read-only checks)
- CLI (display services)
- DEVPULSE (read-only dev notes display)
@@ -182,8 +180,8 @@ def run_self_test():
# Test 1: Dependencies
total += 1
try:
from cli.apps.modules import console # noqa: F811
from prax.apps.modules.logger import system_logger # noqa: F811
from aipass.cli.apps.modules import console # noqa: F811
from aipass.prax.apps.modules.logger import system_logger # noqa: F811
console.print(" ✅ Dependencies imported")
passed += 1
except ImportError as e:
@@ -252,7 +250,7 @@ Drone should NOT intercept or inject universal flags. Reasons:
1. **Transparency** — branches own their own behavior
2. **Simplicity** — drone is a router, not a preprocessor
3. **Consistency** — `python3 apps/seed.py --version` and `drone @seed --version` behave identically
3. **Consistency** — `python3 apps/seedgo.py --version` and `drone @seedgo --version` behave identically
Drone already passes `--help` through to branches correctly. The same pattern applies to all universal flags.
@@ -278,7 +276,7 @@ This standard does not require immediate system-wide changes. Recommended rollou
- Can be done branch-by-branch
**Phase 2: Add `--test` to core branches**
- SEED, DRONE, FLOW, AI_MAIL, PRAX, CORTEX first
- SEEDGO, DRONE, FLOW, AI_MAIL, PRAX, SPAWN first
- Each branch defines what "self-test" means for them
- Enables automated health checking
@@ -286,34 +284,28 @@ This standard does not require immediate system-wide changes. Recommended rollou
- Branches that already have these: verify they follow the convention
- Branches that need them: add as part of normal development
**No big-bang migration.** New branches get these flags from the Cortex template. Existing branches adopt them naturally.
**No big-bang migration.** New branches get these flags from the Spawn template. Existing branches adopt them naturally.
---
## Survey Results (2026-02-21)
Current flag support across 16 branch entry points:
Current flag support across 10 branch entry points:
| Branch | --help | --version | --verbose | --dry-run | --test | Parsing |
|--------|--------|-----------|-----------|-----------|--------|---------|
| SEED | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| SEEDGO | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| DRONE | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| FLOW | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| AI_MAIL | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| PRAX | ✅ | ❌ | ✅ | ❌ | ❌ | argparse |
| CORTEX | ✅ | ❌ | ✅ | ✅ | ❌ | argparse |
| BACKUP_SYSTEM | ✅ | ❌ | ✅ | ✅ | ✅ | argparse |
| SPAWN | ✅ | ❌ | ✅ | ✅ | ❌ | argparse |
| CLI | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| TRIGGER | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| MEMORY_BANK | ✅ | ❌ | ❌ | ✅ | ❌ | sys.argv |
| THE_COMMONS | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| DEVPULSE | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| SCHEDULER | ✅ | ❌ | ❌ | ❌ | ❌ | none |
| NEXUS | ✅ | ❌ | ❌ | ❌ | ❌ | argparse |
| SPEAKEASY | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
| API | ✅ | ❌ | ❌ | ❌ | ❌ | sys.argv |
**Summary:** --help is 16/16. Everything else is 0-3/16. Significant opportunity for standardization.
**Summary:** --help is 10/10. Everything else is 0-2/10. Significant opportunity for standardization.
---
src/aipass/seedgo/docs/aipass_code_standards/diagnostics.md
+6 -6
View File
@@ -40,18 +40,18 @@ The diagnostics checker runs pyright on Python files to detect:
### Single File
```bash
python3 /home/aipass/seed/apps/handlers/standards/diagnostics_check.py /path/to/file.py
python3 src/aipass/seedgo/apps/handlers/standards/diagnostics_check.py /path/to/file.py
```
### Entire Directory
```bash
python3 /home/aipass/seed/apps/handlers/standards/diagnostics_check.py /home/aipass/seed/apps/
python3 src/aipass/seedgo/apps/handlers/standards/diagnostics_check.py src/aipass/seedgo/apps/
```
### Branch Check
```python
from seed.apps.handlers.standards.diagnostics_check import check_branch
result = check_branch('/home/aipass/seed')
from aipass.seedgo.apps.handlers.standards.diagnostics_check import check_branch
result = check_branch('src/aipass/seedgo')
```
---
@@ -158,7 +158,7 @@ If you use VS Code with Pylance, you see the same errors in real-time. The diagn
### Audit Integration
The standards audit can include diagnostics:
```bash
drone @seed audit --diagnostics
drone @seedgo audit --diagnostics
```
---
@@ -183,6 +183,6 @@ drone @seed audit --diagnostics
## Reference
- **Checker:** `/home/aipass/seed/apps/handlers/standards/diagnostics_check.py`
- **Checker:** `src/aipass/seedgo/apps/handlers/standards/diagnostics_check.py`
- **Pyright Docs:** https://microsoft.github.io/pyright/
- **Python Typing:** https://docs.python.org/3/library/typing.html
src/aipass/seedgo/docs/aipass_code_standards/documentation.md
+3 -3
View File
@@ -9,7 +9,7 @@
Every Python file follows this header pattern:
```python
# =================== META ====================
# =================== AIPass ====================
# Name: filename.py
# Description: Brief description of the file
# Version: 1.0.0
@@ -40,7 +40,7 @@ AIPass is a pip package. All execution goes through entry points defined in `pyp
**Standard format (enforced by `meta_check.py`):**
```python
# =================== META ====================
# =================== AIPass ====================
# Name: example_module.py
# Description: Example module for demonstration
# Version: 1.0.0
@@ -57,7 +57,7 @@ AIPass is a pip package. All execution goes through entry points defined in `pyp
- **Modified:** Date the file was last modified (YYYY-MM-DD)
**Markers:**
- Header: `# =================== META ====================`
- Header: `# =================== AIPass ====================`
- Footer: `# =============================================`
**Rules:**
src/aipass/seedgo/docs/aipass_code_standards/encapsulation.md
+17 -17
View File
@@ -19,13 +19,13 @@ Handlers are implementation details. Modules are the public API.
**BAD:**
```python
# In api branch, importing flow's handlers
from flow.apps.handlers.plan.validator import validate_plan
from aipass.flow.apps.handlers.plan.validator import validate_plan
```
**GOOD:**
```python
# Use module entry point
from flow.apps.modules.plan_validator import validate_plan
from aipass.flow.apps.modules.plan_validator import validate_plan
```
**WHY:** Handlers are internal to their branch. If Flow restructures its handlers, API breaks. Modules provide stable interfaces.
@@ -39,17 +39,17 @@ Within the same branch, handlers shouldn't import other handler packages.
**BAD:**
```python
# In handlers/standards/imports_check.py
from apps.handlers.error.formatter import format_error
from aipass.seedgo.apps.handlers.error.formatter import format_error
```
**GOOD:**
```python
# Either use module entry point
from apps.modules.error_handler import format_error
from aipass.seedgo.apps.modules.error_handler import format_error
# Or use allowed default handlers
from apps.handlers.json import json_handler
from apps.handlers.file import file_handler
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.file import file_handler
```
**Allowed Handler Imports:**
@@ -66,13 +66,13 @@ Main entry points (`branch.py`) should use modules, not handlers directly.
**BAD:**
```python
# In api.py
from apps.handlers.openrouter.client import get_response
from aipass.api.apps.handlers.openrouter.client import get_response
```
**GOOD:**
```python
# In api.py
from apps.modules.openrouter_client import get_response
from aipass.api.apps.modules.openrouter_client import get_response
```
**WHY:** Entry points are the first code users see. They should show clean architecture - modules orchestrating, not reaching into handler internals.
@@ -85,10 +85,10 @@ These service imports ARE allowed everywhere because they provide system-wide ut
```python
# Prax logger - allowed anywhere
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# CLI services - allowed anywhere
from cli.apps.modules import console, header, success, error
from aipass.cli.apps.modules import console, header, success, error
```
**Note:** These are MODULE imports, not handler imports. Service branches expose functionality through modules, demonstrating the pattern.
@@ -101,12 +101,12 @@ Trigger is the ONE place where cross-branch handler imports are acceptable:
```python
# In trigger/apps/handlers/events/startup.py
from memory_bank.apps.handlers.mbank.rollover import check_and_rollover
from aipass.memory_bank.apps.handlers.mbank.rollover import check_and_rollover
```
**WHY:** Trigger's entire purpose is centralizing cross-branch reaction logic. It's the exception that proves the rule - instead of scattered cross-branch calls, Trigger owns them all in one place.
Configure bypass in `.seed/bypass.json`:
Configure bypass in `.seedgo/bypass.json`:
```json
{
"bypass": [{
@@ -131,13 +131,13 @@ The `encapsulation_check.py` validates:
- Parses import statements for `apps.handlers` pattern
- Extracts branch name from import path
- Compares against current file's branch context
- Respects bypass rules from `.seed/bypass.json`
- Respects bypass rules from `.seedgo/bypass.json`
---
## Bypass Configuration
For legitimate architectural exceptions, configure `.seed/bypass.json`:
For legitimate architectural exceptions, configure `.seedgo/bypass.json`:
```json
{
@@ -154,6 +154,6 @@ For legitimate architectural exceptions, configure `.seed/bypass.json`:
## Reference
- **Checker:** `/home/aipass/seed/apps/handlers/standards/encapsulation_check.py`
- **Handler Standard:** `/home/aipass/seed/standards/CODE_STANDARDS/handlers.md`
- **Architecture Standard:** `/home/aipass/seed/standards/CODE_STANDARDS/architecture.md`
- **Checker:** `src/aipass/seedgo/apps/handlers/standards/encapsulation_check.py`
- **Handler Standard:** `src/aipass/seedgo/docs/aipass_code_standards/handlers.md`
- **Architecture Standard:** `src/aipass/seedgo/docs/aipass_code_standards/architecture.md`
src/aipass/seedgo/docs/aipass_code_standards/error_handling.md
+17 -17
View File
@@ -14,7 +14,7 @@ Error handling, logging architecture, exception patterns, and the 3-tier separat
**Core Principle:** Logging responsibility follows the architectural hierarchy.
```
Entry Point (flow.py, seed.py)
Entry Point (flow.py, seedgo.py)
↓ (operational logging via Prax)
Module (apps/modules/*.py)
↓ (business logging via Prax - catches and logs everything)
@@ -32,7 +32,7 @@ Handler (apps/handlers/**/*.py)
## Tier 1: Entry Points
**Files:** `flow.py`, `seed.py`, `prax.py`, `drone.py`, `ai_mail.py`
**Files:** `flow.py`, `seedgo.py`, `prax.py`, `drone.py`, `ai_mail.py`
**Prax Import:** YES (minimal)
@@ -40,7 +40,7 @@ Handler (apps/handlers/**/*.py)
**What to Log:**
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# ✓ Module discovery results
logger.info(f"Discovered {len(modules)} modules")
@@ -85,7 +85,7 @@ logger.warning("Invalid input") # NO!
**Pattern:**
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
MODULE_NAME = "create_plan"
@@ -203,7 +203,7 @@ logger.warning(f"[{MODULE_NAME}] Invalid format: expected PLAN0001")
Regular handlers called by module orchestrators return results. The module logs on their behalf. These handlers MAY also log directly via Prax if they need to record operational details.
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
def create_plan_handler(location: str, subject: str) -> dict:
"""Create a plan file"""
@@ -228,7 +228,7 @@ def create_plan_handler(location: str, subject: str) -> dict:
Plugin and service handlers are mini entry points — invoked by schedulers, daemons, or running as long-lived processes. They MUST use Prax system_logger.
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# Plugin triggered by cron — no calling module exists
def run():
@@ -261,10 +261,10 @@ handler = logging.FileHandler('logs/output.log') # NO! Prax handles routing
```bash
# All modules MUST import Prax
grep -r "from prax.apps.modules.logger import" apps/modules/*.py
grep -r "from aipass.prax.apps.modules.logger import" apps/modules/*.py
# Handlers SHOULD import Prax (no longer prohibited)
grep -r "from prax.apps.modules.logger import" apps/handlers/**/*.py
grep -r "from aipass.prax.apps.modules.logger import" apps/handlers/**/*.py
# Handlers MUST NOT use stdlib logging.getLogger
grep -r "logging.getLogger" apps/handlers/**/*.py # Should find NOTHING
@@ -291,7 +291,7 @@ grep -r "logger.error" apps/modules/*.py # Should find ALL modules
```
2. **Replace stdlib with Prax system_logger**
- Replace `import logging` / `logging.getLogger()` with `from prax.apps.modules.logger import system_logger as logger`
- Replace `import logging` / `logging.getLogger()` with `from aipass.prax.apps.modules.logger import system_logger as logger`
- Remove any `logging.FileHandler()` creation (Prax handles routing)
- Keep logger calls as-is (logger.info, logger.error, etc.)
@@ -301,7 +301,7 @@ grep -r "logger.error" apps/modules/*.py # Should find ALL modules
- Log all errors with MODULE_NAME prefix
4. **Test compliance**
- Run `drone @seed audit @branch`
- Run `drone @seedgo audit @branch`
- Verify logs appear in system_logs/
- Verify no stdlib logging.getLogger remains
@@ -312,7 +312,7 @@ grep -r "logger.error" apps/modules/*.py # Should find ALL modules
### Module Error Handling Template
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
MODULE_NAME = "module_name"
@@ -405,8 +405,8 @@ def handler_function(param1: str, param2: int) -> dict:
- No more two-logging-system inconsistency
**Auditability:**
- Automated Seed checks verify Prax imports across ALL tiers
- `drone @seed audit @branch` catches stdlib logging violations
- Automated Seedgo checks verify Prax imports across ALL tiers
- `drone @seedgo audit @branch` catches stdlib logging violations
- One pattern to check: does it use Prax?
**Testability:**
@@ -427,9 +427,9 @@ def handler_function(param1: str, param2: int) -> dict:
- `<project_root>/flow/apps/modules/`
- `<project_root>/flow/apps/handlers/`
**See Seed for reference implementation:**
- `/home/aipass/seed/apps/modules/`
- `/home/aipass/seed/apps/handlers/`
**See Seedgo for reference implementation:**
- `<project_root>/seedgo/apps/modules/`
- `<project_root>/seedgo/apps/handlers/`
**Related Standards:**
- Architecture (3-tier pattern)
@@ -444,7 +444,7 @@ def handler_function(param1: str, param2: int) -> dict:
Prax handlers in `apps/handlers/logging/` use Python's stdlib `logging` instead of `system_logger`. This is **intentional** to avoid circular dependencies — the logging handlers ARE the logging infrastructure.
**Status:** Documented in `<project_root>/prax/.seed/bypass.json`
**Status:** Documented in `<project_root>/prax/.seedgo/bypass.json`
### Trigger Infrastructure Handlers
src/aipass/seedgo/docs/aipass_code_standards/handlers.md
+80 -80
View File
@@ -57,11 +57,11 @@ def handler_function(operation: str, module_name: str | None = None):
```python
# ✅ GOOD - Like Prax logger
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
json_handler.log_operation("operation", data)
# ❌ BAD - Modules shouldn't pass their own name
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
json_handler.log_operation("my_module", "operation", data) # Typo-prone, boilerplate
```
@@ -82,7 +82,7 @@ json_handler.log_operation("my_module", "operation", data) # Typo-prone, boiler
## Default Handlers
**Status:** Standard (packaged by Cortex into all branches)
**Status:** Standard (packaged by Spawn into all branches)
### json_handler.py - JSON Operations
@@ -107,13 +107,13 @@ json_handler.log_operation("my_module", "operation", data) # Typo-prone, boiler
**Usage Pattern:**
```python
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
# Module just calls - handler auto-detects caller
json_handler.log_operation("validation_run", {"files": 42})
```
**Cortex Integration:** This handler is packaged into every branch by Cortex during branch creation/updates. All branches use identical or near-identical implementations.
**Spawn Integration:** This handler is packaged into every branch by Spawn during branch creation/updates. All branches use identical or near-identical implementations.
**3-Tier Compliance:** Default handlers follow the same 3-tier error handling rules as custom handlers. Location (`handlers/`) determines rules, not conceptual role. json_handler.py raises exceptions; calling modules handle logging. See `error_handling.md` for 3-tier architecture details.
@@ -141,11 +141,11 @@ Handler → imports Module ✗ (creates cycle)
**✅ ALLOWED - Same-branch handler imports (even across packages):**
```python
# seed/apps/handlers/standards/imports_check.py
from seed.apps.handlers.json import json_handler # ✅ OK - same branch
# seedgo/apps/handlers/standards/imports_check.py
from aipass.seedgo.apps.handlers.json import json_handler # ✅ OK - same branch
# flow/apps/handlers/plan/create.py
from flow.apps.handlers.registry.load import load_registry # ✅ OK - same branch
from aipass.flow.apps.handlers.registry.load import load_registry # ✅ OK - same branch
```
**Why allowed:** Handlers within the same branch are coworkers. The security boundary is at BRANCH level.
@@ -163,8 +163,8 @@ from .logger import log_operation_start, log_operation_end
**❌ FORBIDDEN - Handler imports own branch's modules:**
```python
# seed/apps/handlers/json/json_handler.py
from seed.apps.modules.create_thing import something # ❌ NO - circular risk
# seedgo/apps/handlers/json/json_handler.py
from aipass.seedgo.apps.modules.create_thing import something # ❌ NO - circular risk
```
**Why forbidden:** Creates circular dependency risk. Modules import handlers, not the other way.
@@ -173,10 +173,10 @@ from seed.apps.modules.create_thing import something # ❌ NO - circular risk
```python
# flow/apps/modules/list_plans.py
from prax.apps.handlers.logging.setup import get_logger # ❌ BLOCKED
from aipass.prax.apps.handlers.logging.setup import get_logger # ❌ BLOCKED
# ✅ CORRECT - use the module (public API)
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
```
**Why forbidden:** Handlers are internal implementation. External branches use MODULES.
@@ -209,10 +209,10 @@ from .formatters import format_result, format_batch_header
```python
# modules/imports_standard.py
from prax.apps.modules.logger import system_logger as logger
from seed.apps.handlers.json import json_handler
from seed.apps.handlers.cli import prompts
from seed.apps.handlers.standards import imports_check
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.cli import prompts
from aipass.seedgo.apps.handlers.standards import imports_check
```
**Why this works:** Dependencies flow ONE way (modules → handlers). Better one module imports 20 handlers than handlers importing each other.
@@ -222,9 +222,9 @@ from seed.apps.handlers.standards import imports_check
**Error handlers are system-wide service:**
```python
# Any handler can import error system (current: cortex, future: CLI)
from cortex.apps.handlers.error import track_operation
from cortex.apps.handlers.error.result_types import OperationResult
# Any handler can import error system (current: cli)
from aipass.cli.apps.handlers.error import track_operation
from aipass.cli.apps.handlers.error.result_types import OperationResult
@track_operation
def create_branch(name):
@@ -234,9 +234,9 @@ def create_branch(name):
**Why exception:** Error handlers are infrastructure service - three-tier output (JSON log, system log, console). Not domain logic, but framework service.
**Current reality:** Error system lives in `cortex.apps.handlers.error` and is imported by handlers in speakeasy and other branches. This creates dependency on cortex, but is necessary for consistent error handling across system.
**Current reality:** Error system lives in `aipass.cli.apps.handlers.error` and is imported by handlers across branches. This creates dependency on cli, but is necessary for consistent error handling across system.
**Future direction:** Migrate error system to `cli.apps.handlers.error` (already started) so it's clearly infrastructure, not branch-specific.
**Current direction:** Error system in `aipass.cli.apps.handlers.error` — clearly infrastructure, not branch-specific.
**Rule:** Service providers (infrastructure shared across ALL branches) can be imported cross-domain.
@@ -265,13 +265,13 @@ External Branch
### Two Types of Branches
1. **CLI Tools** - Used via command line, not imported
- Flow, Seed, AI_Mail, Backup_System, Drone
- Flow, Seedgo, AI_Mail, Spawn, Drone
- You run `drone @flow create`, you don't `import flow` or `import drone`
- Drone is a CLI router that resolves @ and routes commands to branches
2. **Library Services** - Imported by other code
- Prax (logging), CLI (formatting), API (LLM calls), Memory Bank (vectors)
- You `import prax` then `from prax.apps.modules.logger import logger`
- You `import aipass.prax` then `from aipass.prax.apps.modules.logger import logger`
- **NOTE:** Drone is NOT a library service - it's a CLI router, never imported
### Same-Branch Handler Imports - ALLOWED
@@ -280,8 +280,8 @@ Handlers within the SAME BRANCH can import each other freely, even across packag
```python
# flow/apps/handlers/plan/create.py
from flow.apps.handlers.registry.load import load_registry # ✅ OK - same branch
from flow.apps.handlers.json.json_handler import log_operation # ✅ OK - same branch
from aipass.flow.apps.handlers.registry.load import load_registry # ✅ OK - same branch
from aipass.flow.apps.handlers.json.json_handler import log_operation # ✅ OK - same branch
```
**Rationale:** Handlers are unique to each branch. The security boundary is at the BRANCH level, not package level. Trying to enforce package-level isolation adds complexity without benefit.
@@ -292,18 +292,18 @@ from flow.apps.handlers.json.json_handler import log_operation # ✅ OK - same
```python
# ❌ WRONG - reaching into Prax handlers from Flow
from prax.apps.handlers.logging.setup import get_logger
from aipass.prax.apps.handlers.logging.setup import get_logger
# ✅ RIGHT - import Prax module (public API)
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
```
```python
# ❌ WRONG - reaching into Cortex handlers from Speakeasy
from cortex.apps.handlers.error_handler import track_operation
# ❌ WRONG - reaching into CLI handlers from Spawn
from aipass.cli.apps.handlers.error_handler import track_operation
# ✅ RIGHT - import Cortex module (public API)
from cortex.apps.modules.error_tracking import track_operation
# ✅ RIGHT - import CLI module (public API)
from aipass.cli.apps.modules.error_tracking import track_operation
```
### Security Guard Implementation
@@ -327,17 +327,17 @@ ACCESS DENIED: Cross-branch handler import blocked
============================================================
Caller branch: flow
Caller file: list_plans.py
Blocked: from prax.apps.handlers.logging.setup import get_logger
Blocked: from aipass.prax.apps.handlers.logging.setup import get_logger
Handlers are internal to their branch.
Use the module API instead:
from prax.apps.modules.<module> import <function>
from aipass.prax.apps.modules.<module> import <function>
Example:
from prax.apps.modules.logger import logger
from aipass.prax.apps.modules.logger import logger
For full standards guide:
drone @seed handlers
drone @seedgo handlers
============================================================
```
@@ -380,7 +380,7 @@ Example with library services:
**You import the service that owns the capability.** You don't care about its internal dependencies.
**Important:** CLI branches like Flow, Seed, AI_Mail don't import each other or Drone. They're invoked via `drone @branch command`, not imported.
**Important:** CLI branches like Flow, Seedgo, AI_Mail don't import each other or Drone. They're invoked via `drone @branch command`, not imported.
---
@@ -416,10 +416,10 @@ drone @flow create @project1 --name "test"
# Drone resolves @ symbols:
@flow → <project_root>/flow/flow.py
@project1 → /home/aipass/projects/project1
@project1 → <project_root>/projects/project1
# Flow receives:
sys.argv = ["flow.py", "create", "/home/aipass/projects/project1", "--name", "test"]
sys.argv = ["flow.py", "create", "<project_root>/projects/project1", "--name", "test"]
```
### Architectural Debt - @ Handling in Branches
@@ -428,7 +428,7 @@ sys.argv = ["flow.py", "create", "/home/aipass/projects/project1", "--name", "te
```python
# ❌ WRONG - Branch should NEVER handle @ resolution
from drone.apps.modules.resolve import resolve_path
from aipass.drone.apps.modules.resolve import resolve_path
def some_function(path_arg):
if "@" in path_arg:
@@ -465,14 +465,14 @@ def create_plan(project_path: str, name: str):
### Two Types of Branches (Updated)
**1. CLI Tools** - Invoked via Drone, never imported:
- Flow, Seed, AI_Mail, Backup_System, **Drone itself**
- Flow, Seedgo, AI_Mail, Spawn, **Drone itself**
- Usage: `drone @branch command`
- Communication: Via CLI arguments (@ pre-resolved)
- Never import each other
**2. Library Services** - Imported by other code:
- Prax (logging), CLI (formatting), API (LLM calls), Memory Bank (vectors)
- Usage: `from prax.apps.modules.logger import logger`
- Usage: `from aipass.prax.apps.modules.logger import logger`
- Communication: Via Python imports
- Can be imported by any branch
@@ -513,14 +513,14 @@ def create_plan(project_path: str, name: str):
**✅ GOOD - Single-purpose handlers:**
```
json_handler.py: 279 lines (JSON file operations - seed)
356 lines (speakeasy version)
json_handler.py: 279 lines (JSON file operations - seedgo)
356 lines (spawn version)
decorators.py: 257 lines (Error decorators)
formatters.py: 194 lines (Console formatting)
result_types.py: 248 lines (Result type definitions)
metadata.py: 119 lines (Branch metadata)
prompts.py: 72 lines (CLI prompts - seed)
59 lines (speakeasy version)
prompts.py: 72 lines (CLI prompts - seedgo)
59 lines (spawn version)
```
**These are perfect:** Each file has single clear purpose. AI processes fast, minimal context burn.
@@ -528,10 +528,10 @@ prompts.py: 72 lines (CLI prompts - seed)
**⚠️ GETTING HEAVY - Complex handlers:**
```
file_ops.py: 845 lines (Branch file operations - speakeasy)
file_ops.py: 845 lines (Branch file operations - spawn)
892 lines (Other branches)
981 lines (cortex - most complex)
json_ops.py: 762 lines (JSON migrations - speakeasy)
981 lines (spawn - most complex)
json_ops.py: 762 lines (JSON migrations - spawn)
```
**Why still okay:**
@@ -557,7 +557,7 @@ hypothetical_god_object.py: 2000+ lines
**Complex domains with many related operations:**
```python
# json_ops.py (762 lines in speakeasy)
# json_ops.py (762 lines in spawn)
# All JSON migration operations - breaking up would separate related logic
def migrate_key(data, old_key, new_key):
@@ -650,12 +650,12 @@ handlers/
- Technical organization: requires mental translation ("What technical category is this?")
- Domain organization: direct mapping ("What am I working with?")
### Real Example - Seed Handlers
### Real Example - Seedgo Handlers
**Current structure:**
```
/home/aipass/seed/apps/handlers/
<project_root>/seedgo/apps/handlers/
├── json/
│ ├── json_handler.py → JSON file operations (279 lines)
│ └── test_auto_detection.py → Tests
@@ -680,12 +680,12 @@ handlers/
3. **Easy extension:** Add new JSON operation → obvious where it goes
4. **Marketplace ready:** Grab entire `json/` package → self-contained
### Real Example - Speakeasy Handlers
### Real Example - Spawn Handlers
**Branch/registry/error separation:**
```
/home/aipass/speakeasy/apps/handlers/
<project_root>/spawn/apps/handlers/
├── branch/
│ ├── file_ops.py → 845 lines (file operations)
│ ├── metadata.py → 119 lines (branch metadata)
@@ -706,7 +706,7 @@ handlers/
└── prompts.py → 59 lines (user prompts)
```
**Note:** Speakeasy handlers currently import from `cortex.apps.handlers.error` for error tracking. This is the service provider exception - error handlers are infrastructure used across all branches.
**Note:** Spawn handlers currently import from `aipass.cli.apps.handlers.error` for error tracking. This is the service provider exception - error handlers are infrastructure used across all branches.
**Notice:**
- Each domain self-contained
@@ -777,7 +777,7 @@ error/
## Handler Testing Requirements
**Status:** Testing infrastructure in progress (started in Cortex, not yet standardized).
**Status:** Testing infrastructure in progress (not yet standardized).
### Current Reality
@@ -785,7 +785,7 @@ error/
- AIPass is custom system, building from scratch
- JSONs + Prax logs = current debugging infrastructure
- Fast iteration with manual testing
- pytest framework started in Cortex (future direction)
- pytest framework (future direction)
### Testing Approach When Infrastructure Ready
@@ -798,7 +798,7 @@ error/
```python
# test_json_handler.py
import pytest
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
def test_validate_json_structure_config():
"""Test config JSON validation"""
@@ -829,18 +829,18 @@ def test_validate_json_structure_invalid():
# test_json_handler_integration.py
import pytest
from pathlib import Path
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
@pytest.fixture
def temp_json_dir(tmp_path):
"""Create temporary JSON directory"""
json_dir = tmp_path / "seed_json"
json_dir = tmp_path / "seedgo_json"
json_dir.mkdir()
# Temporarily override SEED_JSON_DIR
original = json_handler.SEED_JSON_DIR
json_handler.SEED_JSON_DIR = json_dir
# Temporarily override SEEDGO_JSON_DIR
original = json_handler.SEEDGO_JSON_DIR
json_handler.SEEDGO_JSON_DIR = json_dir
yield json_dir
json_handler.SEED_JSON_DIR = original
json_handler.SEEDGO_JSON_DIR = original
def test_ensure_module_jsons_creates_files(temp_json_dir):
"""Test JSON auto-creation"""
@@ -870,9 +870,9 @@ def test_log_operation_rotation(temp_json_dir):
# test_registry_handler.py
import pytest
from unittest.mock import patch, Mock
from seed.apps.handlers.registry import registry_ops
from aipass.seedgo.apps.handlers.registry import registry_ops
@patch('seed.apps.handlers.registry.registry_ops.Path.exists')
@patch('aipass.seedgo.apps.handlers.registry.registry_ops.Path.exists')
def test_validate_registry_missing_file(mock_exists):
"""Test registry validation when file missing"""
mock_exists.return_value = False
@@ -961,17 +961,17 @@ tests/handlers/
```bash
# Test json_handler auto-creation
rm -rf /home/aipass/seed/seed_json/test_*
rm -rf <project_root>/seedgo/seedgo_json/test_*
# Run handler
python3 -c "from seed.apps.handlers.json import json_handler; json_handler.log_operation('test_op')"
python3 -c "from aipass.seedgo.apps.handlers.json import json_handler; json_handler.log_operation('test_op')"
# Check created files
ls /home/aipass/seed/seed_json/
ls <project_root>/seedgo/seedgo_json/
# Expected: test_module_config.json, test_module_data.json, test_module_log.json
# Inspect contents
cat /home/aipass/seed/seed_json/test_module_log.json
cat <project_root>/seedgo/seedgo_json/test_module_log.json
# Verify: operation logged with timestamp
```
@@ -1027,7 +1027,7 @@ def handle_error_detected(event_data: Dict[str, Any]) -> None:
```python
# Module layer - injects the callback at startup
from trigger.apps.handlers.events.error_detected import set_send_email_callback
from aipass.trigger.apps.handlers.events.error_detected import set_send_email_callback
set_send_email_callback(send_email_direct)
```
@@ -1247,18 +1247,18 @@ def _migrate_inbox_format(inbox_data: Dict, inbox_file: Path) -> Dict:
---
### 5. Direct BRANCH_REGISTRY.json Reads
### 5. Direct AIPASS_REGISTRY.json Reads
**Problem:** Handlers need branch routing data but can't import modules. Using subprocess to call drone is slow and fragile.
**Solution:** Read BRANCH_REGISTRY.json directly. It's a stable, well-defined JSON file at a known path.
**Solution:** Read AIPASS_REGISTRY.json directly. It's a stable, well-defined JSON file at a known path.
**Reference:** `ai_mail/apps/handlers/email/delivery.py`
```python
def get_all_branches() -> List[Dict]:
"""Read branch registry directly for email routing."""
registry_file = Path("/home/aipass/BRANCH_REGISTRY.json")
registry_file = Path("<project_root>/AIPASS_REGISTRY.json")
if not registry_file.exists():
return []
@@ -1282,13 +1282,13 @@ def get_all_branches() -> List[Dict]:
**Reference:** `trigger/apps/handlers/events/error_detected.py`
```python
BRANCH_REGISTRY_FILE = AIPASS_HOME / "BRANCH_REGISTRY.json"
AIPASS_REGISTRY_FILE = AIPASS_ROOT / "AIPASS_REGISTRY.json"
def _get_registered_emails() -> set:
"""Read registered branch emails from BRANCH_REGISTRY.json."""
"""Read registered branch emails from AIPASS_REGISTRY.json."""
try:
if BRANCH_REGISTRY_FILE.exists():
data = json.loads(BRANCH_REGISTRY_FILE.read_text(encoding='utf-8'))
if AIPASS_REGISTRY_FILE.exists():
data = json.loads(AIPASS_REGISTRY_FILE.read_text(encoding='utf-8'))
return {b["email"] for b in data.get("branches", [])}
except Exception:
return set()
@@ -1296,17 +1296,17 @@ def _get_registered_emails() -> set:
```
**Key principles:**
- Hardcoded path (`/home/aipass/BRANCH_REGISTRY.json`) - it's a system constant
- Hardcoded path (`<project_root>/AIPASS_REGISTRY.json`) - it's a system constant
- Read-only (handlers never write to registry)
- Defensive reads (missing file → empty result, not crash)
- No module import needed (pure file I/O)
**When to use:**
- Handler needs branch routing, naming, or path data
- The data is in BRANCH_REGISTRY.json (it usually is)
- The data is in AIPASS_REGISTRY.json (it usually is)
**When NOT to use:**
- Need to modify the registry (use Cortex module API)
- Need to modify the registry (use Spawn module API)
- Need complex registry queries (consider whether a module should handle this)
---
src/aipass/seedgo/docs/aipass_code_standards/imports.md
+93 -134
View File
@@ -3,116 +3,89 @@
**Date:** 2025-11-12
---
## Standard Import Order
#@comments:patrick:whole file needs updating
## Standard Import Order
**Every Python file follows this pattern:**
```python
#!/home/aipass/.venv/bin/python3
#!/usr/bin/env python3
# [META BLOCK]
"""Module docstring"""
# Infrastructure setup (if needed)
import sys
from pathlib import Path
AIPASS_ROOT = Path.home() / "aipass_core"
sys.path.insert(0, str(AIPASS_ROOT))
# Standard library imports
import json
from datetime import datetime
from typing import Dict, List, Optional, Tuple
# Prax logger (system-wide - nearly always imported)
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# Services (CLI, etc.)
from cli.apps.modules import console, header, success, error
from aipass.cli.apps.modules import console, header, success, error
# Internal/local imports
from seed.apps.handlers.json import json_handler
from seed.apps.handlers.domain1 import ops
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.domain1 import ops
```
**WHY this order:**
1. **Infrastructure first** - Must run before other imports can work
2. **Standard library** - Python built-ins grouped together
3. **Prax logger** - System-wide logging service
4. **Services** - CLI, other branch services (import before internal handlers)
5. **Internal imports** - After all external dependencies resolved
1. **Standard library** - Python built-ins grouped together
2. **Prax logger** - System-wide logging service
3. **Services** - CLI, other branch services (import before internal handlers)
4. **Internal imports** - After all external dependencies resolved
> **Note:** AIPass uses pip-installable namespace imports (`from aipass.{module}...`). No `sys.path` manipulation or `AIPASS_ROOT` path setup is needed.
---
## AIPASS_ROOT Pattern
## Import Namespace Pattern
**The standard:**
```python
from pathlib import Path
AIPASS_ROOT = Path.home() / "aipass_core"
from aipass.{module}.apps.modules.{name} import something
from aipass.{module}.apps.handlers.{domain} import handler
```
**WHY Path.home():**
- Works across all environments (no hardcoded paths)
- User-agnostic (any user can run AIPass)
- System-agnostic (Linux, Mac, Windows)
**WHY namespace imports:**
- Works across all environments (pip-installed package)
- No `sys.path` manipulation needed
- Explicit, traceable import paths
**Where it's used:**
```python
# Finding branch components
PRAX_ROOT = AIPASS_ROOT / "prax"
CLI_ROOT = AIPASS_ROOT / "cli"
SEED_ROOT = Path.home() / "seed" # Seed is outside aipass_core
# Cross-branch service imports
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.cli.apps.modules import console, header
# Accessing shared resources
TEMPLATES_DIR = AIPASS_ROOT / "templates"
# Internal branch imports
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.flow.apps.modules.plans import create_plan
```
**Consistency rule:** Always use `AIPASS_ROOT` or `Path.home()`, never hardcode `/home/username/`
**Consistency rule:** Always use `from aipass.{module}...`, never bare imports like `from prax...`
---
## sys.path Setup (When Needed)
## No sys.path Setup Needed
AIPass is a pip-installable package. All imports use the `aipass.*` namespace and resolve automatically via the installed package.
**Pattern:**
```python
import sys
from pathlib import Path
AIPASS_ROOT = Path.home() / "aipass_core"
sys.path.insert(0, str(AIPASS_ROOT))
# No sys.path manipulation required
# Just import directly:
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.seedgo.apps.handlers.json import json_handler
```
**WHY sys.path.insert(0, ...):**
- Allows imports from any branch without relative path gymnastics
- Makes `from prax.apps.modules.logger import system_logger` work from anywhere
- Adds aipass_core to Python's import search path
**When to use:**
- **Modules and handlers:** Need it (they're deep in directory structure)
- **Main entry points:** Usually need it
- **Standalone scripts:** Definitely need it
**Example enabling import:**
```python
# Without sys.path setup - fails
from prax.apps.modules.logger import system_logger # ModuleNotFoundError
# With sys.path setup - works
sys.path.insert(0, str(AIPASS_ROOT))
from prax.apps.modules.logger import system_logger # ✓
**Install for development:**
```bash
pip install -e .
```
### Branch-Specific sys.path Patterns
**Seed-specific pattern:**
```python
sys.path.insert(0, str(AIPASS_ROOT))
sys.path.insert(0, str(Path.home())) # Seed-specific: enables `from seed.apps.handlers...` imports
```
**Why seed needs both:** Seed lives at `/home/aipass/seed/` (outside `aipass_core`), so adding `Path.home()` to sys.path allows `from seed.apps.handlers...` imports to work. Other branches typically only need the `AIPASS_ROOT` line since they live inside `aipass_core`.
This registers the `aipass` namespace so all `from aipass.{module}...` imports work from anywhere.
---
@@ -121,7 +94,7 @@ sys.path.insert(0, str(Path.home())) # Seed-specific: enables `from seed.apps.h
**The most common import in the system:**
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
```
**WHY Prax is important:**
@@ -140,11 +113,11 @@ logger.error("Failed to backup branch", exc_info=True)
**Consistency:** Same import pattern everywhere
```python
# Always this
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# Never variations like these
from prax import logger # ✗
import prax.system_logger # ✗
from aipass.prax import logger # ✗
import aipass.prax.system_logger # ✗
```
**Output location:** Prax manages log files, branches don't need to worry about where logs go
@@ -155,25 +128,25 @@ import prax.system_logger # ✗
**Core rule:** Handlers CANNOT import from parent branch modules
**Example - Seed:**
**Example - Seedgo:**
```python
# ✓ ALLOWED - Handler imports another handler
# seed/apps/handlers/domain1/ops.py
from seed.apps.handlers.json import json_handler
# seedgo/apps/handlers/domain1/ops.py
from aipass.seedgo.apps.handlers.json import json_handler
# ✓ ALLOWED - Handler imports standard library
import json
from pathlib import Path
# ✓ ALLOWED - Handler imports Prax service
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# ✓ ALLOWED - Handler imports CLI service
from cli.apps.modules import console, error
from aipass.cli.apps.modules import console, error
# ✗ FORBIDDEN - Handler imports parent module
from seed.apps.modules.create_thing import something # BREAKS INDEPENDENCE
from aipass.seedgo.apps.modules.create_thing import something # BREAKS INDEPENDENCE
```
**WHY this matters:**
@@ -194,22 +167,22 @@ Handlers import modules ✗
**From modules to handlers:**
```python
# In seed/apps/modules/create_thing.py
from seed.apps.handlers.json import json_handler
from seed.apps.handlers.domain1 import ops
# In seedgo/apps/modules/create_thing.py
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.domain1 import ops
```
**From handlers to handlers (within same branch):**
```python
# In seed/apps/handlers/domain1/ops.py
from seed.apps.handlers.json import json_handler
# In seedgo/apps/handlers/domain1/ops.py
from aipass.seedgo.apps.handlers.json import json_handler
```
**Cross-branch service imports:**
```python
# Services can be imported anywhere (modules or handlers)
from prax.apps.modules.logger import system_logger as logger
from cli.apps.modules import console, header, success, error
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.cli.apps.modules import console, header, success, error
```
**Relative imports (avoided):**
@@ -217,8 +190,8 @@ from cli.apps.modules import console, header, success, error
# ✗ Don't use relative imports
from ...handlers.json import json_handler # Confusing, hard to trace
# ✓ Use absolute imports from sys.path
from seed.apps.handlers.json import json_handler # Clear, explicit
# ✓ Use absolute namespace imports
from aipass.seedgo.apps.handlers.json import json_handler # Clear, explicit
```
---
@@ -238,7 +211,7 @@ Some AIPass services need to know **which branch is calling them** to provide pr
**Router Services (CLI Invocation Only):**
- **Drone** - NOT a library service, it's a CLI router
- Resolves `@` targets before passing commands to branches
- Branches NEVER import from `drone.apps.modules`
- Branches NEVER import from `aipass.drone.apps.modules`
- Invoked via subprocess: `subprocess.run(["drone", "command", ...])`
### Context-Independent Services (Import & Use Anywhere)
@@ -247,11 +220,11 @@ Some AIPass services need to know **which branch is calling them** to provide pr
```python
# Prax Logger - context-independent
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
logger.info("Works from anywhere")
# CLI Services - context-independent
from cli.apps.modules import console, header
from aipass.cli.apps.modules import console, header
console.print("Works from anywhere")
```
@@ -271,14 +244,14 @@ import subprocess
# Drone resolves @ and routes the command
subprocess.run(["drone", "email", "send", "@recipient", "Subject", "Message"])
subprocess.run(["drone", "log", "show"])
subprocess.run(["drone", "@seed", "some-command"])
subprocess.run(["drone", "@seedgo", "some-command"])
```
**✗ FORBIDDEN - Never import from Drone:**
```python
# ✗ WRONG - Drone is not a library service
from drone.apps.modules import resolve_target # NO!
from drone.apps.modules.router import route_command # NO!
from aipass.drone.apps.modules import resolve_target # NO!
from aipass.drone.apps.modules.router import route_command # NO!
# Branches should NOT handle @ resolution themselves
# That's Drone's job - it resolves @ before passing to branches
@@ -300,35 +273,32 @@ from drone.apps.modules.router import route_command # NO!
```python
# ✓ CORRECT - Call from your branch directory
# Working dir: /home/aipass/seed/
# Working dir: src/aipass/seedgo/
import subprocess
subprocess.run(["python3", "<project_root>/ai_mail/apps/ai_mail.py",
"send", "@drone", "Subject", "Message"])
subprocess.run(["drone", "@ai_mail", "send", "@drone", "Subject", "Message"])
# AI_MAIL walks up from your CWD, finds SEED.id.json, knows you're @seed
# Your email sends FROM @seed (not @dev_central or @ai_mail)
# AI_MAIL walks up from your CWD, finds branch identity, knows you're @seedgo
# Your email sends FROM @seedgo (not @devpulse or @ai_mail)
```
```python
# ✗ WRONG - Call from wrong directory
# Working dir: /home/aipass/
# Working dir: / (no branch context)
subprocess.run(["python3", "<project_root>/ai_mail/apps/ai_mail.py",
"send", "@drone", "Subject", "Message"])
subprocess.run(["drone", "@ai_mail", "send", "@drone", "Subject", "Message"])
# AI_MAIL can't find branch identity, falls back to @dev_central
# AI_MAIL can't find branch identity, falls back to @devpulse
# Email sends from wrong identity
```
#### How PWD Detection Works
1. **AI_MAIL starts** at your current working directory
2. **Walks up** the directory tree looking for `*.id.json` file
3. **Finds** (e.g.) `SEED.id.json` at `/home/aipass/seed/`
4. **Derives identity**: Branch name = "seed", email = "@seed"
5. **Auto-generates config** at `/home/aipass/seed/seed_json/user_config.json`
6. **Uses correct sender**: Email sends FROM @seed
2. **Walks up** the directory tree looking for `.trinity/passport.json`
3. **Finds** (e.g.) `passport.json` at `src/aipass/seedgo/.trinity/`
4. **Derives identity**: Branch name = "seedgo", email = "@seedgo"
5. **Uses correct sender**: Email sends FROM @seedgo
#### Best Practice: Use Drone for AI_MAIL
@@ -356,8 +326,7 @@ from pathlib import Path
# Ensure you're in your branch directory
branch_dir = Path(__file__).parent.parent # Adjust based on file depth
result = subprocess.run(
["python3", "<project_root>/ai_mail/apps/ai_mail.py",
"send", "@recipient", "Subject", "Message"],
["drone", "@ai_mail", "send", "@recipient", "Subject", "Message"],
cwd=str(branch_dir), # Force working directory to branch root
capture_output=True
)
@@ -379,13 +348,10 @@ result = subprocess.run(
When you call AI_MAIL from your branch directory, it auto-generates:
```
/home/aipass/seed/
├── seed_json/
│ └── user_config.json # Your email config (@seed identity)
├── ai_mail.local/
src/aipass/seedgo/
├── .ai_mail.local/
│ ├── inbox.json # Your inbox
│ └── sent/ # Your sent folder
└── SEED.ai_mail.json # Your email summary dashboard
```
**Pattern:** Each branch gets its own isolated email configuration and mailbox.
@@ -449,16 +415,11 @@ pip install pillow
```
**Virtual environment:**
- AIPass uses `~/.venv/` (user's home directory venv)
- Shebang points to it: `#!/home/aipass/.venv/bin/python3`
- All branches share the same venv
- AIPass is pip-installable: `pip install -e .`
- Shebang: `#!/usr/bin/env python3`
- All branches share the same package namespace
- Packages install once, available everywhere
**EXCEPTION - MEMORY_BANK:**
- MEMORY_BANK uses its own venv: `/home/aipass/MEMORY_BANK/.venv`
- Shebang for MEMORY_BANK: `#!/home/aipass/MEMORY_BANK/.venv/bin/python3`
- Isolated environment for memory management operations
---
## Standard Library Organization
@@ -510,18 +471,18 @@ import shutil
```python
# ✗ Wildcard imports
from cortex.apps.handlers.json import * # What did I import? Who knows!
from aipass.flow.apps.handlers.json import * # What did I import? Who knows!
# ✗ Hardcoded paths
sys.path.insert(0, "/home/patrick/aipass_core") # Breaks on other machines
sys.path.insert(0, "/home/user/project") # Breaks on other machines
# ✗ Relative imports
from ...handlers import something # Hard to trace, confusing
# ✗ Import entire modules when you need one function
import seed.apps.handlers.json.json_handler # Long, repetitive
import aipass.seedgo.apps.handlers.json.json_handler # Long, repetitive
# Better:
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
# ✗ Circular imports (handler imports module that imports handler)
# Module imports handler ✓
@@ -534,12 +495,9 @@ from seed.apps.handlers.json import json_handler
| Import Type | Pattern | Required? |
|-------------|---------|-----------|
| Infrastructure | `AIPASS_ROOT = Path.home() / "aipass_core"` | When needed |
| sys.path | `sys.path.insert(0, str(AIPASS_ROOT))` | When needed |
| Prax logger | `from prax.apps.modules.logger import system_logger as logger` | **Nearly always** |
| CLI service | `from cli.apps.modules import console, header` | When needed |
| API service | `from api.apps.modules import llm_call` | When needed |
| Memory Bank | `from memory_bank.apps.modules import vector_search` | When needed |
| Prax logger | `from aipass.prax.apps.modules.logger import system_logger as logger` | **Nearly always** |
| CLI service | `from aipass.cli.apps.modules import console, header` | When needed |
| API service | `from aipass.api.apps.modules import llm_call` | When needed |
| **Drone** | `subprocess.run(["drone", "cmd", ...])` | **CLI only - NEVER import** |
| Standard lib | Grouped by category, alphabetical | Yes |
| Internal | Absolute imports (not relative) | Yes |
@@ -549,15 +507,15 @@ from seed.apps.handlers.json import json_handler
## Summary
**Import order:** Infrastructure → Standard lib → Prax → Services → Internal
**Import order:** Standard lib → Prax → Services → Internal
**AIPASS_ROOT pattern:** `Path.home() / "aipass_core"` - never hardcode paths
**Namespace pattern:** `from aipass.{module}...` - never bare imports or hardcoded paths
**Prax logger:** Nearly always imported - system-wide logging service
**Service imports:** CLI, API, Memory Bank imported as libraries; Drone invoked via CLI only
**Drone is special:** NOT a library service - it's a CLI router. Never import from drone.apps.modules
**Drone is special:** NOT a library service - it's a CLI router. Never import from aipass.drone.apps.modules
**Handler independence:** Same-branch handler→handler ✓, Handler→own-branch-module ✗, Cross-branch handler ✗
@@ -569,9 +527,10 @@ from seed.apps.handlers.json import json_handler
## Comments
#@comments:2025-11-13:claude: Updated examples to use seed/ instead of fictional cortex/ references
#@comments:2025-11-13:claude: Updated examples to use seedgo/ instead of fictional cortex/ references
#@comments:2025-11-13:claude: Added Services import section (CLI) to match actual codebase patterns
#@comments:2025-11-13:claude: Toned down "critical" language around Prax to "nearly always" for accuracy
#@comments:2025-11-29:claude: Added Service Categories section clarifying Drone is NOT a library service
#@comments:2025-11-29:claude: Added explicit "Drone: CLI Router Pattern" section with FORBIDDEN import examples
#@comments:2025-11-29:claude: Clarified that branches should NEVER import from drone.apps.modules - Drone resolves @ before calling them
#@comments:2025-11-29:claude: Clarified that branches should NEVER import from aipass.drone.apps.modules - Drone resolves @ before calling them
#@comments:2026-03-07:claude: Cleaned Dev-Pass references - updated to AIPass namespace imports, removed sys.path/AIPASS_ROOT patterns, fixed /home/aipass/ paths, seed->seedgo naming
src/aipass/seedgo/docs/aipass_code_standards/json_structure.md
+61 -71
View File
@@ -19,8 +19,8 @@ drone_discovery_log.json
```
**Location patterns:**
- Seed modules: `/home/aipass/seed/seed_json/`
- Branch modules: `<project_root>/{branch}/{branch}_json/`
- Seedgo modules: `src/aipass/seedgo/seedgo_json/`
- Branch modules: `src/aipass/{branch}/{branch}_json/`
---
@@ -63,16 +63,16 @@ Something breaks:
**Location:** `apps/handlers/json/json_handler.py` in your branch
**MUST update these constants (DO NOT copy SEED's paths):**
**MUST update these constants (DO NOT copy seedgo's paths):**
```python
# ❌ WRONG - Points to SEED
SEED_ROOT = Path.home() / "seed"
SEED_JSON_DIR = SEED_ROOT / "seed_json"
JSON_TEMPLATES_DIR = SEED_ROOT / "apps" / "json_templates"
# ❌ WRONG - Points to seedgo
SEEDGO_ROOT = Path(__file__).parents[4] # Points to seedgo branch
SEEDGO_JSON_DIR = SEEDGO_ROOT / "seedgo_json"
JSON_TEMPLATES_DIR = SEEDGO_ROOT / "apps" / "json_templates"
# ✓ CORRECT - Points to YOUR branch
API_ROOT = Path.home() / "aipass_core" / "api"
API_ROOT = Path(__file__).parents[4] # Points to api branch
API_JSON_DIR = API_ROOT / "api_json"
JSON_TEMPLATES_DIR = API_ROOT / "apps" / "json_templates"
```
@@ -81,32 +81,23 @@ JSON_TEMPLATES_DIR = API_ROOT / "apps" / "json_templates"
**1. Update BRANCH_ROOT constant:**
⚠️ **CRITICAL: Must use `Path.home() / "full" / "path"` format!**
⚠️ **CRITICAL: Must use `Path(__file__).parents[N]` for branch root discovery!**
The standards checker uses a regex that ONLY matches `Path.home() / "..."` patterns.
Using `AIPASS_ROOT / "branch"` will FAIL the check even though it resolves to the same path.
AIPass uses relative path resolution, not hardcoded paths.
```python
# ❌ WRONG - Fails checker (regex doesn't match AIPASS_ROOT variable)
AIPASS_ROOT = Path.home() / "aipass_core"
API_ROOT = AIPASS_ROOT / "api" # Checker can't validate this!
# ❌ WRONG - Hardcoded path
API_ROOT = Path("/home/user/workspace/AIPass/src/aipass/api")
# ✓ CORRECT - Passes checker (explicit Path.home() pattern)
AIPASS_ROOT = Path.home() / "aipass_core"
API_ROOT = Path.home() / "aipass_core" / "api" # Checker validates this!
# ✓ CORRECT - Relative path resolution
API_ROOT = Path(__file__).parents[4] # Adjust N based on handler depth
```
**Branch path patterns:**
```python
# For SEED (special case):
SEED_ROOT = Path.home() / "seed"
# For aipass_core branches:
{BRANCH}_ROOT = Path.home() / "aipass_core" / "{branch}"
# For aipass_os branches (dev_central):
DEVPULSE_ROOT = Path.home() / "aipass_os" / "dev_central" / "devpulse"
ASSISTANT_ROOT = Path.home() / "aipass_os" / "dev_central" / "assistant"
# All branches live under src/aipass/{branch}/
# Use Path(__file__).parents[N] to navigate up from handler location
{BRANCH}_ROOT = Path(__file__).parents[4] # from apps/handlers/json/json_handler.py
```
**2. Update JSON_DIR constant:**
@@ -125,53 +116,51 @@ JSON_TEMPLATES_DIR = {BRANCH}_ROOT / "apps" / "json_templates"
**4. Create required directories:**
```bash
mkdir -p <project_root>/{branch}/{branch}_json
mkdir -p <project_root>/{branch}/apps/json_templates/default
mkdir -p src/aipass/{branch}/{branch}_json
mkdir -p src/aipass/{branch}/apps/json_templates/default
```
**5. Copy templates from SEED:**
**5. Copy templates from seedgo:**
```bash
cp /home/aipass/seed/apps/json_templates/default/*.json \
<project_root>/{branch}/apps/json_templates/default/
cp src/aipass/seedgo/apps/json_templates/default/*.json \
src/aipass/{branch}/apps/json_templates/default/
```
### Validation
**Run standards checker on your json_handler.py:**
```bash
python3 /home/aipass/seed/apps/modules/standards_checklist.py \
<project_root>/{branch}/apps/handlers/json/json_handler.py
drone @seedgo audit {branch}
```
**Expected result:** 100/100 on JSON STRUCTURE standard
**If failing:**
- Check BRANCH_ROOT points to your branch (not "seed")
- Check BRANCH_ROOT points to your branch (not "seedgo")
- Check JSON_DIR uses {branch}_json pattern
- Check TEMPLATES_DIR uses your branch templates
### Common Mistakes
1. **Using `AIPASS_ROOT / "branch"` instead of `Path.home() / "full/path"`** ← Most common error!
- The checker regex only matches `Path.home() / "..."` pattern
- `BRANCH_ROOT = AIPASS_ROOT / "api"` → FAILS (even though path is correct)
- `BRANCH_ROOT = Path.home() / "aipass_core" / "api"` → PASSES
- This caused 5+ branches to fail at 33-66% despite having correct paths
1. **Using hardcoded paths instead of `Path(__file__).parents[N]`** ← Most common error!
- Always use relative path resolution from the handler file
- `BRANCH_ROOT = Path("/absolute/path/to/branch")` → FAILS
- `BRANCH_ROOT = Path(__file__).parents[4]` → PASSES
2. **Copying SEED's handler without changing paths**
2. **Copying seedgo's handler without changing paths**
- API and Drone both made this mistake
- Results in files created in wrong location
3. **Using SEED_ROOT variable name in other branches**
3. **Using SEEDGO_ROOT variable name in other branches**
- Should be API_ROOT, FLOW_ROOT, DRONE_ROOT, etc.
4. **Pointing TEMPLATES_DIR to SEED's templates**
4. **Pointing TEMPLATES_DIR to seedgo's templates**
- Each branch needs its own template copies
- Allows branch-specific template customization
5. **Wrong JSON directory naming**
- Must use pattern: `{branch}_json/`
- NOT `json/`, `seed_json/` (for non-SEED branches)
- NOT `json/`, `seedgo_json/` (for non-seedgo branches)
6. **Importing Prax logger in handlers**
- Handlers are tier 3 - no Prax imports allowed
@@ -183,10 +172,10 @@ python3 /home/aipass/seed/apps/modules/standards_checklist.py \
**Purpose:** Module settings, configuration, limits
**Real example from seed:**
**Real example from seedgo:**
```json
{
"module_name": "seed",
"module_name": "seedgo",
"version": "0.1.0",
"created": "2025-11-12",
"config": {
@@ -212,7 +201,7 @@ python3 /home/aipass/seed/apps/modules/standards_checklist.py \
**Purpose:** Metrics, tracking data, current module state
**Real example from seed:**
**Real example from seedgo:**
```json
{
"created": "2025-11-12",
@@ -242,19 +231,19 @@ python3 /home/aipass/seed/apps/modules/standards_checklist.py \
**Purpose:** Operations history - what module did, when, result
**Real example from seed:**
**Real example from seedgo:**
```json
[
{
"timestamp": "2025-11-12T17:57:20.688755",
"operation": "seed_startup",
"operation": "seedgo_startup",
"data": {
"modules_discovered": 6
}
},
{
"timestamp": "2025-11-13T00:22:22.793686",
"operation": "seed_startup",
"operation": "seedgo_startup",
"data": {
"modules_discovered": 12
}
@@ -299,7 +288,7 @@ drone_registry_log.json: 183KB (7,001 entries) ❌
**Handler implementation (automatic):**
```python
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
# Auto-detects module name, auto-rotates based on config
json_handler.log_operation("operation_name", {"key": "value"})
@@ -359,7 +348,7 @@ json_handler.log_operation("operation_name", {"key": "value"})
**Purpose:** Track collections of items (branches, handlers, modules)
**Real example: /home/aipass/BRANCH_REGISTRY.json**
**Real example: AIPASS_REGISTRY.json**
```json
{
"metadata": {
@@ -370,15 +359,15 @@ json_handler.log_operation("operation_name", {"key": "value"})
"branches": [
{
"name": "FLOW",
"path": "<project_root>/flow",
"path": "src/aipass/flow",
"email": "@flow",
"status": "active",
"created": "2025-10-30"
},
{
"name": "CORTEX",
"path": "<project_root>/cortex",
"email": "@cortex",
"name": "SEEDGO",
"path": "src/aipass/seedgo",
"email": "@seedgo",
"status": "active",
"created": "2025-10-30"
}
@@ -388,14 +377,14 @@ json_handler.log_operation("operation_name", {"key": "value"})
**Registry characteristics:**
- **Central source of truth** for collections
- Used by Cortex for branch management
- Used by DevPulse for branch management
- Used by Drone for command routing
- **Not part of three-JSON pattern** (special purpose)
- Typically located at system root level
**Other registries in use:**
- `<project_root>/drone/drone_json/drone_registry.json` - Drone commands
- `<project_root>/prax/prax_json/prax_registry.json` - Prax tracks
- `src/aipass/drone/drone_json/drone_registry.json` - Drone commands
- `src/aipass/prax/prax_json/prax_registry.json` - Prax tracks
**When to create registry:**
- Need to track multiple related items
@@ -444,7 +433,7 @@ json_handler.log_operation("operation_name", {"key": "value"})
- No test infrastructure yet (custom system, building from scratch)
- JSONs + logs = debugging infrastructure
- Fast iteration, manual testing
- Future: pytest framework (started in Cortex)
- Future: pytest framework
---
@@ -517,7 +506,7 @@ Handlers use Python's `inspect.stack()` to automatically detect which module is
**Bad (manual name passing):**
```python
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
json_handler.log_operation(
"imports_standard", # ❌ Module has to know its own name
@@ -534,7 +523,7 @@ json_handler.log_operation(
**Good (auto-detection):**
```python
from seed.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.json import json_handler
json_handler.log_operation(
"operation", # ✅ Handler figures out module name
@@ -592,8 +581,8 @@ def log_operation(operation: str, data: Dict[str, Any] | None = None, module_nam
```python
# Standard imports
from prax.apps.modules.logger import system_logger as logger
from seed.apps.handlers.json import json_handler
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.seedgo.apps.handlers.json import json_handler
def handle_command(command: str, args: List[str]) -> bool:
# Just call - handler auto-detects we're "imports_standard"
@@ -655,15 +644,14 @@ ls /branch/branch_json/
### Reference Implementation
**Primary handler:** `/home/aipass/seed/apps/handlers/json/json_handler.py`
**Primary handler:** `src/aipass/seedgo/apps/handlers/json/json_handler.py`
**Branch implementations:**
- `<project_root>/cortex/apps/handlers/json/json_handler.py`
- `<project_root>/drone/apps/handlers/json/json_handler.py`
- `<project_root>/prax/apps/handlers/json/json_handler.py`
- `src/aipass/drone/apps/handlers/json/json_handler.py`
- `src/aipass/prax/apps/handlers/json/json_handler.py`
- (Other branches follow same pattern)
**Status:** Production-ready, tested across Seed and core branches
**Status:** Production-ready, tested across seedgo and core branches
**Pattern established:** 2025-11-12
@@ -671,12 +659,14 @@ ls /branch/branch_json/
## Comments
#@comments:2025-11-13:claude: Updated markdown to reflect production reality - verified three-JSON pattern in use across seed and branches
#@comments:2025-11-13:claude: Updated markdown to reflect production reality - verified three-JSON pattern in use across seedgo and branches
#@comments:2025-11-13:claude: Confirmed auto-rotation implementation in seed handler (line 181-231 in json_handler.py)
#@comments:2025-11-13:claude: Confirmed auto-rotation implementation in seedgo handler (line 181-231 in json_handler.py)
#@comments:2025-11-13:claude: Drone logs still need fixing (171KB, 7001 entries) - demonstrates the problem this standard solves
#@comments:2025-11-13:claude: Log structure is array (not object with "entries" key) - corrected in examples
#@comments:2026-01-31:claude: Added critical warning about Path.home() pattern requirement - AIPASS_ROOT/branch fails checker regex even with correct path. Fixed 5 branches (API, DRONE, FLOW, BACKUP_SYSTEM, DEVPULSE) affected by this undocumented requirement.
#@comments:2026-01-31:claude: Added critical warning about path resolution pattern requirement. Fixed 5 branches (API, DRONE, FLOW, BACKUP_SYSTEM, DEVPULSE) affected by this undocumented requirement.
#@comments:2026-03-07:claude: Cleaned Dev-Pass references - seed->seedgo naming, removed /home/aipass/ paths, Cortex->DevPulse, updated imports to aipass.* namespace, Path.home()->Path(__file__).parents[N]
src/aipass/seedgo/docs/aipass_code_standards/log_handler.md
+3 -3
View File
@@ -20,7 +20,7 @@ All logging in AIPass MUST use `RotatingFileHandler` via prax's `system_logger`.
### REQUIRED
1. **Use prax system_logger** — `from prax.apps.modules.logger import system_logger as logger`
1. **Use prax system_logger** — `from aipass.prax.apps.modules.logger import system_logger as logger`
2. **All log output via logger methods** — `logger.info()`, `logger.warning()`, `logger.error()`
3. **Prax handles rotation automatically** — maxBytes + backupCount configured centrally
@@ -49,7 +49,7 @@ my_logger.addHandler(logging.FileHandler(log_file))
```python
# CORRECT: Use prax system_logger (handles rotation automatically)
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
logger.info("Operation completed successfully")
logger.warning("Invalid user input: %s", user_input)
@@ -69,7 +69,7 @@ All other branches using prax's `system_logger` rotated correctly (verified: `.l
## Checker
**File:** `/home/aipass/seed/apps/handlers/standards/log_handler_check.py`
**File:** `src/aipass/seedgo/apps/handlers/standards/log_handler_check.py`
Checks:
1. No raw `logging.FileHandler()` usage
src/aipass/seedgo/docs/aipass_code_standards/log_level.md
+2 -2
View File
@@ -130,8 +130,8 @@ The checker uses AST-aware docstring tracking to avoid false positives from code
| Date | Decision | By | Status |
|------|----------|----|--------|
| 2026-01-31 | ERROR vs WARNING distinction approved | Patrick | Active |
| 2026-02-13 | Automated checker created | SEED | Active |
| 2026-02-13 | Automated checker created | Seedgo | Active |
---
*Part of AIPass Code Standards - maintained by SEED branch*
*Part of AIPass Code Standards - maintained by Seedgo branch*
src/aipass/seedgo/docs/aipass_code_standards/log_visibility.md
+6 -6
View File
@@ -30,7 +30,7 @@ When any file uses raw `logging.getLogger()`:
### REQUIRED
- Import prax system_logger: `from prax.apps.modules.logger import system_logger as logger`
- Import prax system_logger: `from aipass.prax.apps.modules.logger import system_logger as logger`
- Use `system_logger` for ALL logging — modules, handlers, entry points
- If `logging.getLogger()` is needed for specific purposes, the prax import must also be present
@@ -38,13 +38,13 @@ When any file uses raw `logging.getLogger()`:
- **Prax logging infrastructure** — it IS the implementation (exempt from both checks)
- **Test files** — test isolation (exempt from both checks)
- **Files with `.seed/bypass.json` exceptions**
- **Files with `.seedgo/bypass.json` exceptions**
## Detection (Two-Check System v3.0.0)
### Check 1: Prax Import (ALL files — no handler exemption)
1. Scans for `logging.getLogger()` calls
2. If found, checks for `from prax.apps.modules.logger import`
2. If found, checks for `from aipass.prax.apps.modules.logger import`
3. If prax import is missing, flags as violation with line numbers
4. Applies to modules AND handlers — unified Prax logging everywhere
@@ -67,7 +67,7 @@ logger.info("This only writes to local logs/")
### Good — Visible System-Wide
```python
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
logger.info("Visible in Prax monitor and system_logs/")
```
@@ -75,7 +75,7 @@ logger.info("Visible in Prax monitor and system_logs/")
```python
import logging
from prax.apps.modules.logger import system_logger as logger
from aipass.prax.apps.modules.logger import system_logger as logger
# Raw logger for specific subprocess/library needs
subprocess_logger = logging.getLogger('subprocess')
@@ -97,4 +97,4 @@ logger.info("Application log — visible system-wide")
---
*Part of AIPass Code Standards — maintained by SEED branch*
*Part of AIPass Code Standards — maintained by seedgo branch*
src/aipass/seedgo/docs/aipass_code_standards/modules.md
+17 -17
View File
@@ -75,14 +75,14 @@ Modules are the aggregation point for functionality:
```python
# Service imports (shared infrastructure)
from prax.apps.modules.logger import system_logger as logger
from cli.apps.modules import console, header, success, error
from aipass.prax.apps.modules.logger import system_logger as logger
from aipass.cli.apps.modules import console, header, success, error
# Domain handler imports (business logic)
from seed.apps.handlers.json import json_handler
from seed.apps.handlers.standards.cli_content import get_cli_standards
from seed.apps.handlers.validation import validate_input
from seed.apps.handlers.operations import create_thing, update_thing
from aipass.seedgo.apps.handlers.json import json_handler
from aipass.seedgo.apps.handlers.standards.cli_content import get_cli_standards
from aipass.seedgo.apps.handlers.validation import validate_input
from aipass.seedgo.apps.handlers.operations import create_thing, update_thing
```
**Why 20+ imports is fine:** Better one module imports 20 handlers than handlers importing each other. Dependencies flow ONE direction: modules → handlers.
@@ -144,7 +144,7 @@ def create_branch(path: str):
"created": datetime.now().isoformat(),
"version": "1.0"
}
config_file = branch_path / f"{branch_path.name}.id.json"
config_file = branch_path / ".trinity" / "passport.json"
with open(config_file, 'w') as f:
json.dump(config, f, indent=2)
@@ -180,7 +180,7 @@ Use handlers for file operations:
# ❌ BAD - module does file operations
def update_config(branch: str, key: str, value: str):
"""Module handles files directly"""
config_path = Path(f"/home/aipass/{branch}/{branch}.id.json")
config_path = Path(f"src/aipass/{branch}/.trinity/passport.json")
with open(config_path) as f:
config = json.load(f)
@@ -219,7 +219,7 @@ def calculate_scores(data: List[dict]):
## File Size Expectations
Based on analysis of `/home/aipass/seed/apps/modules/` (14 modules):
Based on analysis of `src/aipass/seedgo/apps/modules/` (14 modules):
**Size Distribution:**
- **110-135 lines:** Simple modules (single operation, minimal workflow)
@@ -336,7 +336,7 @@ def publish_standard(standard_name: str):
**Use when:** User choice or runtime conditions determine next steps.
**Reference:** `/home/aipass/seed/apps/modules/cli_standard.py` (135 lines)
**Reference:** `src/aipass/seedgo/apps/modules/cli_standard.py` (135 lines)
```python
def print_standard():
"""Print cli standards - orchestrates handler call"""
@@ -370,7 +370,7 @@ def create_thing(name: str, thing_type: str):
**Use when:** Standard error handling is sufficient (most cases).
**Reference:** `/home/aipass/seed/apps/modules/test_cli_errors.py`
**Reference:** `src/aipass/seedgo/apps/modules/test_cli_errors.py`
```python
@track_operation
def example_success_operation():
@@ -418,7 +418,7 @@ def create_and_configure(name: str):
**Use when:** Operation needs multiple system services.
**Reference:** `/home/aipass/seed/apps/modules/cli_standard.py`
**Reference:** `src/aipass/seedgo/apps/modules/cli_standard.py`
```python
def handle_command(command: str, args: List[str]) -> bool:
"""Handle 'cli' command"""
@@ -594,7 +594,7 @@ Modules orchestrate workflows, so test the complete operation:
```python
# tests/test_standards_module.py
import pytest
from seed.apps.modules.cli_standard import handle_command, print_standard
from aipass.seedgo.apps.modules.cli_standard import handle_command, print_standard
def test_handle_command_cli():
"""Test cli command routing"""
@@ -720,7 +720,7 @@ If using error handling decorators, test they work:
```python
# tests/test_decorators.py
from cli.apps.modules import track_operation
from aipass.cli.apps.modules import track_operation
def test_track_operation_success():
"""Test decorator handles success"""
@@ -755,18 +755,18 @@ def test_track_operation_exception():
## Reference Examples
**Simple module (135 lines):** `/home/aipass/seed/apps/modules/cli_standard.py`
**Simple module (135 lines):** `src/aipass/seedgo/apps/modules/cli_standard.py`
- Single workflow (display standard)
- Conditional branching (offer demo)
- Service integration (CLI + JSON handler)
**Complex module (283 lines):** `/home/aipass/seed/apps/modules/test_cli_errors.py`
**Complex module (283 lines):** `src/aipass/seedgo/apps/modules/test_cli_errors.py`
- Multiple example workflows
- Decorator demonstrations
- Service integration examples
- Display integration
**Showroom module (152 lines):** `/home/aipass/seed/apps/modules/create_thing.py`
**Showroom module (152 lines):** `src/aipass/seedgo/apps/modules/create_thing.py`
- Documents module patterns
- Shows orchestration flow
- Demonstrates good practices
src/aipass/seedgo/docs/aipass_code_standards/naming.md
+3 -3
View File
@@ -121,7 +121,7 @@ Same operation should have same name everywhere:
cli/apps/handlers/error/decorators.py # Path: error domain, name: what it does
cli/apps/handlers/error/formatters.py # Path: error domain, name: what it does
prax/apps/handlers/config/load_config.py # Path: config domain, name: action
seed/apps/handlers/domain1/ops.py # Path: domain1, name: operations
seedgo/apps/handlers/domain1/ops.py # Path: domain1, name: operations
```
**Bad (real violations):**
@@ -163,9 +163,9 @@ prax/apps/handlers/
└── prompts.py # CLI prompt handlers
```
**Real Examples from seed:**
**Real Examples from seedgo:**
```
seed/apps/handlers/
seedgo/apps/handlers/
├── domain1/
│ └── ops.py # Domain operations (showroom)
├── standards/
src/aipass/seedgo/docs/aipass_code_standards/permission_flags.md
+1 -1
View File
@@ -63,7 +63,7 @@ The AIPass standard `--permission-mode bypassPermissions` provides:
## Checker
**File:** `/home/aipass/seed/apps/handlers/standards/permission_flags_check.py`
**File:** `seedgo/apps/handlers/standards/permission_flags_check.py`
Checks:
1. No `--dangerously-skip-permissions` usage in code (comments/docstrings excluded)
src/aipass/seedgo/docs/aipass_code_standards/readme.md
+7 -7
View File
@@ -6,7 +6,7 @@
## What This Covers
Standards for branch README.md files. Every branch must have a README that stays accurate without manual effort. Auto-generated sections update via Seed audit integration. Manual sections remain human-written.
Standards for branch README.md files. Every branch must have a README that stays accurate without manual effort. Auto-generated sections update via Seedgo audit integration. Manual sections remain human-written.
---
@@ -59,7 +59,7 @@ apps/
| `AUTO:TREE` | Directory structure | Filesystem scan |
| `AUTO:MODULES` | Module list with descriptions | `apps/modules/*.py` docstrings |
| `AUTO:COMMANDS` | CLI commands and usage | `--help` output |
| `AUTO:HEADER` | Identity block | `.id.json` fields |
| `AUTO:HEADER` | Identity block | `.trinity/passport.json` fields |
| `AUTO:LAST_UPDATED` | Timestamp | Most recent file modification |
**Rules:**
@@ -97,9 +97,9 @@ Auto-generation handles facts (file lists, timestamps). Humans handle meaning.
| Tool | Purpose | Location |
|------|---------|----------|
| `readme_check.py` | 6 automated checks, score >= 75% to pass | `seed/apps/handlers/standards/` |
| `readme_generator.py` | Auto-populates TREE, MODULES, COMMANDS, HEADER, LAST_UPDATED | `seed/apps/handlers/standards/` |
| `seed readme update @branch` | On-demand regeneration (Phase 4, coming soon) | CLI |
| `readme_check.py` | 6 automated checks, score >= 75% to pass | `seedgo/apps/handlers/standards/` |
| `readme_generator.py` | Auto-populates TREE, MODULES, COMMANDS, HEADER, LAST_UPDATED | `seedgo/apps/handlers/standards/` |
| `seedgo readme update @branch` | On-demand regeneration (Phase 4, coming soon) | CLI |
**Checks performed by `readme_check.py`:**
1. README.md exists
@@ -130,7 +130,7 @@ Auto-generation handles facts (file lists, timestamps). Humans handle meaning.
<!-- AUTO:TREE -->
```
apps/
├── seed.py
├── seedgo.py
├── modules/
│ ├── imports_standard.py
│ └── readme_standard.py
@@ -147,7 +147,7 @@ apps/
## Directory Structure
```
apps/
├── seed.py
├── seedgo.py
├── modules/
│ └── old_module.py # deleted 3 weeks ago
└── handlers/

Some files were not shown because too many files have changed in this diff Show More