[← Back to AIPass](../../../README.md)

# 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

```bash
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

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

### Update

```bash
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

```bash
drone @spawn delete @branch_name                               # Archive + deregister
```

### Sync and Regenerate

```bash
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

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

### Python API

```python
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](../../../README.md)
