slaguru666/AIPass
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60c36cccc66a7b7158c26d6849ac16aa6eeaa111
AIPass/src/aipass/spawn/README.md
T

11 KiB
Raw Blame History

← Back to AIPass

SPAWN

The agent factory and branch lifecycle manager for AIPass.

Module: aipass.spawn | Version: 1.0.0 | Created: 2026-03-05

What I Do

  • Create new branches from class-scoped templates (builder, birthright)
  • Grant birthright citizenship via the passport command
  • Update branches from templates (single or batch by class, with --dry-run)
  • Delete branches (archive + deregister)
  • Sync registry and templates against filesystem
  • Regenerate template registries with fresh file hashes
  • Replace all {{PLACEHOLDER}} patterns with branch-specific values
  • Register new citizens in AIPASS_REGISTRY.json

Citizen Classes

Every branch belongs to a citizen class, which determines its template:

Class Template What It Creates
builder (default) templates/builder/ Full 3-layer scaffold: .trinity/, .aipass/, apps/ (modules/ + handlers/), tests/, docs/, logs/
birthright templates/birthright/ Minimal citizenship: .trinity/, .aipass/, README.md

Commands

All commands run through drone @spawn <command>.

Create

drone @spawn create <path>                                    # Create builder branch
drone @spawn create <path> --role "Analyst" --purpose "Reports"  # With identity
drone @spawn create --template birthright <path>               # Specific class
drone @spawn create <path> --dry-run                           # Preview without touching disk
drone @spawn create @existing                                  # Adopt pre-existing agent
drone @spawn create ~/Projects/MyProject/agent_name            # External project (auto-detects registry)

Passport

drone @spawn passport @dirname                                 # Grant birthright citizenship
drone @spawn passport @dirname --role "Observer" --purpose "Monitoring"

Update

drone @spawn update @branch_name                               # Single branch (uses passport class)
drone @spawn update builder --all                              # All builder-class branches
drone @spawn update birthright --all                           # All birthright-class branches
drone @spawn update @branch_name --dry-run                     # Preview changes
drone @spawn update builder --all --dry-run                    # Preview batch update

Delete

drone @spawn delete @branch_name                               # Archive + deregister

Sync and Regenerate

drone @spawn sync-registry                                     # Report healthy/stale/unregistered
drone @spawn sync-registry --fix                               # Rebuild .spawn/ tracking + fix passport registry_ids
drone @spawn sync-templates                                    # Pull managed files from sources (partial — see Known Issues)
drone @spawn regenerate-registry                               # Regenerate builder template hashes
drone @spawn regenerate-registry --all                         # All template classes

# Repair
drone @spawn repair <project_path>                             # Scan project for structural issues
drone @spawn repair <project_path> --dry-run                   # Preview only
drone @spawn repair --relocate @branch src/pkg/branch          # Move branch to new location
drone @spawn repair --relocate @branch path --relocate-artifacts  # Move branch + .chroma/ into it
drone @spawn repair <project_path> --clean-pollution            # Archive + remove duplicate dirs

Introspection

drone @spawn                                                   # No args — lists connected modules
drone @spawn --help                                            # Full help text
drone @spawn --version                                         # Version string

Python API

from aipass.spawn import spawn_agent

result = spawn_agent(
    "/path/to/new/agent",
    role="Data Analyst",
    purpose="Process incoming reports",
    traits="Precise, thorough"
)
# Returns: { success, branch_name, path, files_copied, validation_issues }

Architecture

spawn/
├── __init__.py                          # Public API (exports spawn_agent)
├── apps/
│   ├── spawn.py                         # Entry point — CLI routing, version, help
│   ├── modules/
│   │   ├── core.py                      # Create orchestrator (_spawn_agent, handle_command)
│   │   ├── passport.py                  # Passport CLI — birthright citizenship
│   │   ├── update.py                    # Update CLI — single/batch by class
│   │   ├── delete.py                    # Delete CLI — archive + deregister
│   │   ├── sync_registry.py             # Registry repair CLI
│   │   ├── sync_templates.py            # Template sync CLI
│   │   └── regenerate_registry.py       # Template registry regeneration CLI
│   └── handlers/
│       ├── class_registry.py            # Citizen class → template directory mapping
│       ├── file_ops.py                  # Template copy, path renaming, registry regeneration
│       ├── metadata.py                  # Branch name extraction, profile detection
│       ├── placeholders.py              # {{PLACEHOLDER}} replacement engine
│       ├── registry.py                  # AIPASS_REGISTRY.json CRUD, find_registry()
│       ├── meta_ops.py                  # Branch metadata generation, hash computation
│       ├── change_detection.py          # ID-based file diff between template and branch
│       ├── reconcile.py                 # Registry/filesystem reconciliation
│       ├── passport_ops.py             # Passport grant implementation
│       ├── update_ops.py                # Update workflow (Phase 0 snapshot → detect → execute)
│       ├── delete_ops.py                # Delete workflow (resolve → archive → cleanup → deregister)
│       ├── sync_registry_ops.py         # Registry sync (CWD-aware, external project support)
│       ├── sync_templates_ops.py        # Template sync implementation
│       ├── regenerate_registry_ops.py   # Template registry hash regeneration
│       ├── json_ops.py                  # JSON deep merge, backup utilities
│       └── json/
│           └── json_handler.py          # Standard JSON I/O, operation logging, 7 API functions
├── templates/
│   ├── builder/                         # Full scaffold template (45 files, 24 dirs)
│   └── birthright/                      # Minimal template
├── tests/                               # 14 test files, 316 tests
├── spawn_json/                          # JSON tracking directory
├── tools/                               # Branch verification utilities
├── docs/                                # Documentation
└── logs/                                # Prax log output

Three-Layer Design

  1. Entry point (spawn.py) — Routes CLI commands, never imports handlers directly
  2. Modules (modules/) — Business logic coordinators, parse arguments, delegate to handlers
  3. Handlers (handlers/) — Implementation details, pure functions where possible

Workflows

Create (builder class)

  1. Resolve — Extract branch name from target path, validate path doesn't exist
  2. Lookup — Resolve citizen class to template directory via class_registry
  3. Copy — Recursive copy of class template to target (skips __pycache__)
  4. Rename — Replace {{BRANCH}} in directory and file names
  5. Replace — Substitute all {{PLACEHOLDER}} patterns in file contents
  6. Registry — Generate .branch_meta.json, register in AIPASS_REGISTRY.json
  7. Validate — Scan for any remaining {{...}} patterns

Passport (birthright class)

  1. Check — Verify .trinity/ doesn't already exist
  2. Copy — Copy birthright template (.trinity/, .aipass/, README.md)
  3. Replace — Substitute placeholders in copied files
  4. Register — Add to AIPASS_REGISTRY.json

Update (class-aware, Phase 0)

  1. Snapshot — Back up current .branch_meta.json and .template_registry.json
  2. Detect — Compare branch files against template via ID-based change detection
  3. Execute — Apply renames, additions, JSON merges (.py files skipped by design)
  4. Refresh — Regenerate .branch_meta.json with current state

Adopt Existing (create @existing)

  1. Fix — Repair registry_id in passport if stale (from registry recreation)
  2. Register — Add to project registry
  3. Update — Run template update to sync scaffold files

Tests

316 tests | 0 skipped | 0 failed across 14 test files:

File Focus
test_lifecycle.py End-to-end spawn lifecycle workflows
test_json_handler.py JSON I/O, operation logging, standard API
test_handlers.py Handler function behavior and integration
test_regenerate_registry_ops.py Template registry regeneration
test_update.py Branch update mechanics
test_citizen_classes.py Citizen class validation and template discovery
test_file_ops.py File copy, rename, placeholder replacement
test_cli_routing.py Command routing and argument parsing
test_contracts.py Handler contracts and interface compliance
test_spawn.py Basic CLI routing and help
test_error_resilience.py Error handling and edge cases
conftest.py Fixtures: mock templates, registry protection

Public functions: 45 total, 41 tested (91%)

Integration

Depends On

  • aipass.prax — Logging via system_logger
  • aipass.cli — Console output (header, error, warning)
  • Python stdlib (pathlib, json, shutil, hashlib, re, argparse)

Provides To

  • All branches — creation, template updates, registry management, citizenship
  • Registry: CRUD operations on AIPASS_REGISTRY.json and *_REGISTRY.json

Known Issues

  • sync-templates is a no-op — template_owners.json has no entries (template IS source of truth, not downstream consumer)
  • .py files never auto-update during drone @spawn update (by design) — template .py changes need individual branch dispatch
  • 4 untested public functions remain (45 total, 41 tested)

Metrics

  • Seedgo: 100% (34/34)
  • Tests: 253 passed, 0 skipped, 0 failed
  • Module coverage: 23/23 (100%)
  • Template registry: 45 files, 24 dirs (builder)
  • Battle test: 17/17 commands pass (2026-04-22)

Last Updated: 2026-05-15

← Back to AIPass

Reference in New Issue View Git Blame Copy Permalink