feat(spawn): feat(spawn): template updates, prompt refresh, gitkeep to README, module fixes

Co-Authored-By: @spawn <spawn@aipass>

src/aipass/spawn/README.md

@@ -119,7 +119,7 @@ spawn/
 ### 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__`, `.gitkeep`)
+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** — Regenerate `.template_registry.json`, register in `AIPASS_REGISTRY.json`

src/aipass/spawn/apps/handlers/file_ops.py

@@ -133,9 +133,6 @@ def _should_skip(rel_path):
     for part in parts:
         if part in SKIP_NAMES:
             return True
-    # Skip .gitkeep files (template needs them, branches don't)
-    if rel_path.name == ".gitkeep":
-        return True
     return False
 
 

src/aipass/spawn/apps/modules/core.py

@@ -80,6 +80,10 @@ def handle_command(command: str, args: List[str]) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     if command == "create":
         if not args:
             logger.error("spawn create requires a target path")

src/aipass/spawn/apps/modules/delete.py

@@ -54,6 +54,10 @@ def handle_command(command: str, args: list) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     return handle_delete(args) == 0
 
 

src/aipass/spawn/apps/modules/passport.py

@@ -50,6 +50,10 @@ def handle_command(command: str, args: list) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     return handle_passport(args) == 0
 
 

src/aipass/spawn/apps/modules/sync_registry.py

@@ -54,6 +54,10 @@ def handle_command(command: str, args: list) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     return handle_sync_registry(args) == 0
 
 

src/aipass/spawn/apps/modules/sync_templates.py

@@ -54,6 +54,10 @@ def handle_command(command: str, args: list) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     return handle_sync_templates(args) == 0
 
 

src/aipass/spawn/apps/modules/update.py

@@ -57,6 +57,10 @@ def handle_command(command: str, args: list) -> bool:
         print_introspection()
         return True
 
+    if "--help" in args:
+        print_introspection()
+        return True
+
     return handle_update(args) == 0
 
 

src/aipass/spawn/docs/README.md

@@ -0,0 +1,4 @@
+# Docs
+
+This directory holds branch documentation for spawn.
+Design notes, usage guides, and reference material live here.

src/aipass/spawn/templates/birthright/.aipass/aipass_local_prompt.md

@@ -1,14 +1,87 @@
-# {{BRANCHNAME}} Branch-Local Context
-<!-- Source: {{CWD}}/.aipass/branch_system_prompt.md -->
+# {{BRANCHNAME}} — Branch Prompt
 
-> Auto-created by aipass init. Customize for your branch.
+<!--
+INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE
+==========================================
 
-## Status: NEEDS CONFIGURATION
+This file is your local prompt. It gets injected every turn alongside the global prompt.
+The global prompt already covers: dispatch syntax, git workflow, hard rules, logging,
+memory system, breadcrumbs philosophy, and system-wide commands. Don't repeat any of that here.
 
-This file is injected into every AI conversation when working from this branch directory. Configure it with:
+Your job: fill out each section below with content specific to YOUR branch.
+Replace the guidance text (in italics) with real content, then delete this instruction block.
 
-- Who this branch is (role, purpose)
-- Key commands and workflows
-- Architecture overview
-- Critical files and operational rules
-- Integration points with other branches
+PRINCIPLES:
+- Breadcrumbs, not encyclopedias. Enough to navigate, not everything there is to know.
+- Operational, not descriptive. Tell the agent how to ACT, not just what things ARE.
+- Include concrete reference data — lookup tables, checklists, decision trees.
+- If you can run `drone @{{BRANCH}} --help` to get it, don't duplicate it here.
+- This file should be STABLE. If it changes every session, that content belongs in
+  STATUS.local.md or .trinity/ instead.
+
+WHEN YOU'RE DONE:
+- Delete this instruction block
+- Delete all italic guidance text
+- What remains should be pure operational reference
+-->
+
+*Injected every turn. Breadcrumbs only — details in README, --help, .trinity/ memories, STATUS.local.md.*
+
+## Identity
+
+*One line. Who you are and what your role is. This is the first thing the agent reads every turn — make it count.*
+
+You are {{BRANCHNAME}} — {one-line role description}.
+
+## What I Do
+
+*3-5 bullets covering what happens in this branch. Not a mission statement — concrete actions. Think "if someone asked what this branch does day-to-day, what would you say?"*
+
+- {Primary responsibility}
+- {Secondary responsibility}
+- {What you build/maintain/operate}
+
+## Key Commands
+
+*The 5-8 commands you use most, with real arguments. Not your full command list — just the ones you'd need in 80% of sessions. Always show the full `drone @branch command [args]` syntax.*
+
+```
+drone @{{BRANCH}} {command1} [args]    # What it does
+drone @{{BRANCH}} {command2} [args]    # What it does
+```
+
+## Architecture
+
+*Your directory tree showing the code layout. Helps the agent find things without guessing. Skip this section entirely if your branch has no apps/ directory.*
+
+```
+apps/
+├── {{BRANCH}}.py          # Entry point
+├── modules/
+│   ├── {module1}.py     # What it orchestrates
+│   └── {module2}.py     # What it orchestrates
+└── handlers/
+    ├── {domain1}/       # What it handles
+    └── {domain2}/       # What it handles
+```
+
+## Integration
+
+*Which branches you depend on or serve. Every branch connects to others — document those relationships so the agent knows who to ask and who's asking.*
+
+- **Depends on:** @{branch} for {what}, @{branch} for {what}
+- **Serves:** @{branch} uses my {feature}, @{branch} calls my {command}
+
+## Working Habits
+
+*Behavioral patterns specific to this branch. How you approach work differently from other branches. Decision frameworks, common workflows, domain-specific patterns. Only include habits that are unique to this branch — if it applies to all branches, it's in the global prompt.*
+
+- {Habit or pattern that shapes how you work}
+- {Decision framework or workflow unique to this domain}
+
+## Known Gotchas
+
+*Non-obvious quirks, hard-won lessons, things that will waste 20 minutes if you don't know them. These are the breadcrumbs that save time — the stuff you'd tell a new agent on day one.*
+
+- {Gotcha or non-obvious behavior}
+- {Hard-won lesson from a past session}

src/aipass/spawn/templates/builder/.aipass/aipass_local_prompt.md

@@ -1,14 +1,87 @@
-# {{BRANCHNAME}} Branch-Local Context
-<!-- Source: {{CWD}}/.aipass/branch_system_prompt.md -->
+# {{BRANCHNAME}} — Branch Prompt
 
-> Auto-created by aipass init. Customize for your branch.
+<!--
+INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE
+==========================================
 
-## Status: NEEDS CONFIGURATION
+This file is your local prompt. It gets injected every turn alongside the global prompt.
+The global prompt already covers: dispatch syntax, git workflow, hard rules, logging,
+memory system, breadcrumbs philosophy, and system-wide commands. Don't repeat any of that here.
 
-This file is injected into every AI conversation when working from this branch directory. Configure it with:
+Your job: fill out each section below with content specific to YOUR branch.
+Replace the guidance text (in italics) with real content, then delete this instruction block.
 
-- Who this branch is (role, purpose)
-- Key commands and workflows
-- Architecture overview
-- Critical files and operational rules
-- Integration points with other branches
+PRINCIPLES:
+- Breadcrumbs, not encyclopedias. Enough to navigate, not everything there is to know.
+- Operational, not descriptive. Tell the agent how to ACT, not just what things ARE.
+- Include concrete reference data — lookup tables, checklists, decision trees.
+- If you can run `drone @{{BRANCH}} --help` to get it, don't duplicate it here.
+- This file should be STABLE. If it changes every session, that content belongs in
+  STATUS.local.md or .trinity/ instead.
+
+WHEN YOU'RE DONE:
+- Delete this instruction block
+- Delete all italic guidance text
+- What remains should be pure operational reference
+-->
+
+*Injected every turn. Breadcrumbs only — details in README, --help, .trinity/ memories, STATUS.local.md.*
+
+## Identity
+
+*One line. Who you are and what your role is. This is the first thing the agent reads every turn — make it count.*
+
+You are {{BRANCHNAME}} — {one-line role description}.
+
+## What I Do
+
+*3-5 bullets covering what happens in this branch. Not a mission statement — concrete actions. Think "if someone asked what this branch does day-to-day, what would you say?"*
+
+- {Primary responsibility}
+- {Secondary responsibility}
+- {What you build/maintain/operate}
+
+## Key Commands
+
+*The 5-8 commands you use most, with real arguments. Not your full command list — just the ones you'd need in 80% of sessions. Always show the full `drone @branch command [args]` syntax.*
+
+```
+drone @{{BRANCH}} {command1} [args]    # What it does
+drone @{{BRANCH}} {command2} [args]    # What it does
+```
+
+## Architecture
+
+*Your directory tree showing the code layout. Helps the agent find things without guessing. Skip this section entirely if your branch has no apps/ directory.*
+
+```
+apps/
+├── {{BRANCH}}.py          # Entry point
+├── modules/
+│   ├── {module1}.py     # What it orchestrates
+│   └── {module2}.py     # What it orchestrates
+└── handlers/
+    ├── {domain1}/       # What it handles
+    └── {domain2}/       # What it handles
+```
+
+## Integration
+
+*Which branches you depend on or serve. Every branch connects to others — document those relationships so the agent knows who to ask and who's asking.*
+
+- **Depends on:** @{branch} for {what}, @{branch} for {what}
+- **Serves:** @{branch} uses my {feature}, @{branch} calls my {command}
+
+## Working Habits
+
+*Behavioral patterns specific to this branch. How you approach work differently from other branches. Decision frameworks, common workflows, domain-specific patterns. Only include habits that are unique to this branch — if it applies to all branches, it's in the global prompt.*
+
+- {Habit or pattern that shapes how you work}
+- {Decision framework or workflow unique to this domain}
+
+## Known Gotchas
+
+*Non-obvious quirks, hard-won lessons, things that will waste 20 minutes if you don't know them. These are the breadcrumbs that save time — the stuff you'd tell a new agent on day one.*
+
+- {Gotcha or non-obvious behavior}
+- {Hard-won lesson from a past session}

src/aipass/spawn/templates/builder/docs/README.md

@@ -0,0 +1,3 @@
+# Docs
+
+Documentation files for the `{{BRANCHNAME}}` branch.