AIPass/src/aipass/flow

← Back to AIPass

Flow

Purpose: Unified plan lifecycle management for AIPass. Creates, tracks, closes, and archives numbered work plans across multiple plan types via a filesystem-driven template registry. Foreground archival with vector intake verification, cross-branch aggregation, and self-healing registries. Module: aipass.flow Created: 2025-11-15 Last Updated: 2026-04-22

---

Overview

What I Do

• Create numbered plans from type-specific templates via templates/ plugins
• Unified create/close/list commands for all plan types (FPLAN, DPLAN, RPLAN, TDPLAN, ...)
• Close plans with foreground archival to .backup/processed_plans/
• Vector intake on close via drone @memory process-plans with chroma verification
• List and filter plans across branches and plan types
• Restore plans from backups
• Template registry management: register, unregister, scan, auto-heal
• Aggregate plans across branches
• --dry-run for close preview

Commands / Usage

# Create plans
drone @flow create . "Subject"                  # Create FPLAN (default)
drone @flow create . "Subject" master           # Create FPLAN master template
drone @flow create . "Design topic" dplan       # Create DPLAN

# Close plans
drone @flow close FPLAN-0042                    # Close specific plan
drone @flow close DPLAN-0005                    # Close a DPLAN
drone @flow close --all                         # Close all open plans
drone @flow close --all --dry-run               # Preview what would close

# List plans
drone @flow list open                           # List open plans (all types)
drone @flow list all                            # List all plans

# Template management
drone @flow templates                           # List registered types
drone @flow scan                                # Find unregistered directories
drone @flow register <dir> <PREFIX>             # Register new plan type
drone @flow unregister <dir>                    # Remove plan type

# Other
drone @flow restore FPLAN-0042                  # Reopen a closed plan
drone @flow aggregate                           # Cross-branch plan aggregation
drone @flow --help                              # Full help

---

Architecture

flow/
├── apps/
│   ├── flow.py                  # Entry point (auto-discovers modules)
│   ├── modules/                 # Business logic (thin orchestrators)
│   │   ├── create_plan.py       # Plan creation with template support
│   │   ├── close_plan.py        # Closure with foreground archival + vector verify
│   │   ├── list_plans.py        # Plan listing and filtering
│   │   ├── restore_plan.py      # Plan recovery from backups
│   │   ├── registry_monitor.py  # Orphan detection, auto-healing
│   │   ├── aggregate_central.py # Cross-branch plan aggregation
│   │   ├── post_close_runner.py # Background post-processing *(partial — archival moved to foreground)*
│   │   └── template_manager.py  # Template registry management
│   └── handlers/                # Implementation details
│       ├── plan/                # Lifecycle, file ops, validation, close_ops
│       ├── registry/            # Load, save, auto-heal
│       ├── template/            # Plan type loader + template resolution + registry_ops
│       ├── dashboard/           # Status aggregation
│       ├── mbank/               # Memory archival
│       └── json/                # Auto-creating JSON handler
├── templates/                   # Plan type plugins (DATA, not code)
│   ├── flow_plans/              # FPLAN templates (default, master)
│   ├── dev_plans/               # DPLAN templates (default)
│   ├── research_plans/          # RPLAN templates (default)
│   ├── team_dev_plans/          # TDPLAN templates (default)
│   └── audit_plans/             # Unregistered — needs `drone @flow register`
├── flow_json/                   # Per-type registries + template_registry.json
├── tests/                       # 452 tests, 90/90 functions covered
├── docs/                        # Documentation
└── .archive/                    # Archived legacy code

---

Plan Types

Plan types are filesystem-driven. Drop a directory with .md templates into templates/, register it with a prefix. No per-directory JSON config needed.

Type	Prefix	Registry	Templates
flow_plans	FPLAN	fplan_registry.json	default, master
dev_plans	DPLAN	dplan_registry.json	default
research_plans	RPLAN	rplan_registry.json	default
team_dev_plans	TDPLAN	tdplan_registry.json	default

Plans follow the convention {PREFIX}-{NNNN}_topic_slug_YYYY-MM-DD.md where NNNN is auto-incrementing per type.

Auto-heal

• Template registry auto-prunes orphaned types (directory deleted → entry + plan registry JSON removed on next command)
• Plan registries auto-close entries for missing files

---

Close Pipeline

On drone @flow close:

1. Template check (fast-delete empty templates)
2. Mark as closed in registry
3. Archive to .backup/processed_plans/ (foreground, sets processed/cleanup flags atomically)
4. Vector intake: drone @memory process-plans + is_plan_vectorized() verification
5. Dashboard updates (local + central + branch)
6. Append to CLOSED_PLANS.local.json

---

Integration Points

Depends On

• aipass.cli -- Terminal formatting (console, header, success, error)
• aipass.prax -- Structured logging via system_logger
• aipass.trigger -- Error reporting (optional)
• aipass.memory -- Vector intake on plan close (process-plans + verify)
• Python stdlib (pathlib, json, importlib, sys, signal, subprocess, shutil)

Provides To

• All branches -- Plan creation, tracking, closure, and archival
• aipass.devpulse -- Plan status aggregation for system dashboards
• Registry: Per-type registries in flow_json/

---

Quality

• Seedgo: 100% (all 33 standards)
• Tests: 452 tests, 90/90 public functions covered
• Last audit: 2026-04-09

---

Last Updated: 2026-04-07

---

← Back to AIPass