@katyella/legio 0.1.0

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,89 @@
+# {{PROJECT_NAME}} — Legio Orchestration
+
+> Auto-generated by `legio init`. You may edit this file.
+
+This project uses **legio** for Claude Code agent orchestration. Your session
+acts as the orchestrator: you decide what work to delegate, spawn worker agents,
+monitor progress, and merge results.
+
+## Quick Reference
+
+```bash
+# Spawn a worker agent
+legio sling <bead-id> --capability <type> --name <agent-name> \
+  [--spec <path>] [--files file1,file2] [--parent <agent>] [--depth <n>]
+
+# Check system status
+legio status              # Overview of all agents, worktrees, beads
+legio status --json       # Machine-readable output
+legio status --watch      # Live updating
+
+# Messaging (SQLite-backed, ~1-5ms per query)
+legio mail send --to <agent> --subject "..." --body "..."
+legio mail check          # Your inbox
+legio mail list --unread  # All unread messages
+legio mail reply <id> --body "..."
+
+# Merge completed work
+legio merge --branch <name>   # Merge a specific branch
+legio merge --all             # Merge all completed branches
+legio merge --dry-run --branch <name>  # Preview conflicts
+
+# Worktree management
+legio worktree list       # Show all worktrees with status
+legio worktree clean --completed  # Remove finished worktrees
+
+# Context and monitoring
+legio prime               # Reload context (config, mulch, recent activity)
+legio watch --background  # Start watchdog daemon
+legio metrics             # Performance summary
+legio log <event> --agent <name>  # Hook-driven event logging
+```
+
+## How to Spawn Agents
+
+1. Identify the work using beads: `bd ready` or `bd create "task title"`
+2. Choose a capability based on the task:
+{{AGENT_DEFINITIONS}}
+3. Assign exclusive file scope so agents do not conflict
+4. Spawn: `legio sling <bead-id> --capability <type> --name <unique-name> --files src/foo.ts,src/bar.ts`
+
+Each spawned agent gets its own git worktree, branch, CLAUDE.md overlay, and
+tmux session. Agents communicate via `legio mail` and report completion
+by closing their beads issue (`bd close <id> --reason "summary"`).
+
+## Hierarchical Delegation
+
+You can spawn **team leads** that themselves spawn sub-workers:
+
+```
+Orchestrator (this session)
+  └── legio sling bd-xyz --capability lead --name build-lead
+        ├── legio sling bd-abc --capability builder --name auth-login
+        ├── legio sling bd-def --capability builder --name auth-signup
+        └── legio sling bd-ghi --capability builder --name auth-reset
+```
+
+Depth limit is configurable (default: 2). Leads use `--parent` and `--depth`
+to track hierarchy.
+
+## Checking Status
+
+Run `legio status` to see:
+- Active agents and their states (booting, working, stalled, zombie)
+- Worktree locations and branches
+- Beads issue progress
+- Unread mail count
+
+## Canonical Branch
+
+All merges target **{{CANONICAL_BRANCH}}**. Agents work on branches named
+`legio/<agent-name>/<bead-id>`. Never push directly to {{CANONICAL_BRANCH}}.
+
+## Conventions
+
+- Agents own files exclusively — no two agents modify the same file
+- Use `legio mail` for all inter-agent communication (not beads)
+- Use `bd close` to report task completion (not mail)
+- Merge via `legio merge`, not raw `git merge`
+- Logs live in `.legio/logs/` — never delete them manually

package/templates/hooks.json.tmpl

@@ -0,0 +1,132 @@
+{
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio prime --agent {{AGENT_NAME}}"
+					}
+				]
+			}
+		],
+		"UserPromptSubmit": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio mail check --inject --agent {{AGENT_NAME}}"
+					}
+				]
+			}
+		],
+		"PreToolUse": [
+			{
+				"matcher": "AskUserQuestion",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Legio agents run non-interactively — use legio mail send --type question to ask your parent instead\"}'"
+					}
+				]
+			},
+			{
+				"matcher": "EnterPlanMode",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Legio agents run non-interactively — execute immediately per the propulsion principle\"}'"
+					}
+				]
+			},
+			{
+				"matcher": "EnterWorktree",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; echo '{\"decision\":\"block\",\"reason\":\"Legio agents already have assigned worktrees — nested worktrees are not allowed\"}'"
+					}
+				]
+			},
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '\\bgit\\s+push\\b'; then echo '{\"decision\":\"block\",\"reason\":\"git push is blocked — use legio merge to integrate changes, push manually when ready\"}'; exit 0; fi;"
+					}
+				]
+			},
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio log tool-start --agent {{AGENT_NAME}} --stdin"
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio log tool-end --agent {{AGENT_NAME}} --stdin"
+					},
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio mail check --inject --agent {{AGENT_NAME}} --debounce 500"
+					}
+				]
+			},
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio mail check --inject --agent {{AGENT_NAME}} --debounce 30000"
+					}
+				]
+			},
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; read -r INPUT; CMD=$(echo \"$INPUT\" | sed 's/.*\"command\": *\"\\([^\"]*\\)\".*/\\1/'); if echo \"$CMD\" | grep -qE '\\bgit\\s+commit\\b'; then mulch diff HEAD~1; fi;"
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio log session-end --agent {{AGENT_NAME}} --stdin"
+					},
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; mulch learn"
+					}
+				]
+			}
+		],
+		"PreCompact": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "[ -z \"$LEGIO_AGENT_NAME\" ] && exit 0; legio prime --agent {{AGENT_NAME}} --compact"
+					}
+				]
+			}
+		]
+	}
+}

package/templates/overlay.md.tmpl

@@ -0,0 +1,79 @@
+# DO NOT EDIT — Auto-generated by legio
+# This overlay was written by `legio sling`. Manual edits will be
+# overwritten on the next spawn. Modify the template at
+# templates/overlay.md.tmpl in the legio repo instead.
+
+{{BASE_DEFINITION}}
+
+---
+
+## Your Assignment
+
+- **Agent Name:** {{AGENT_NAME}}
+- **Task ID:** {{BEAD_ID}}
+- **Spec:** {{SPEC_PATH}}
+- **Branch:** {{BRANCH_NAME}}
+- **Worktree:** {{WORKTREE_PATH}}
+- **Parent:** {{PARENT_AGENT}}
+- **Depth:** {{DEPTH}}
+
+{{SPEC_INSTRUCTION}}
+
+## Working Directory
+
+Your worktree root is: `{{WORKTREE_PATH}}`
+
+**CRITICAL**: All file operations MUST use paths within this directory.
+- Use paths relative to your worktree root, or absolute paths starting with `{{WORKTREE_PATH}}`
+- Writing to the canonical repo root instead of your worktree is a critical error (PATH_BOUNDARY_VIOLATION)
+- You may READ files from the canonical repo for context, but all WRITES go to your worktree
+
+## File Scope (exclusive ownership)
+
+These paths are relative to your worktree root: `{{WORKTREE_PATH}}`
+
+You may ONLY modify the files listed below within your worktree. Do not touch any other files.
+If you need changes outside your scope, send mail to your parent agent
+requesting the modification.
+
+{{FILE_SCOPE}}
+
+## Expertise
+
+Prime relevant domain knowledge before starting work:
+
+{{MULCH_DOMAINS}}
+
+{{MULCH_EXPERTISE}}
+
+## Communication
+
+Use `legio mail` for all communication. Your address is **{{AGENT_NAME}}**.
+
+```bash
+# Check your inbox (mail arrives automatically via hooks — only use this if you suspect a missed delivery)
+legio mail check --agent {{AGENT_NAME}}
+
+# Send a status update to your parent
+legio mail send --to {{PARENT_AGENT}} --subject "status" \
+  --body "Progress update here" --type status --agent {{AGENT_NAME}}
+
+# Ask a question
+legio mail send --to {{PARENT_AGENT}} --subject "question" \
+  --body "Your question here" --type question --priority high --agent {{AGENT_NAME}}
+
+# Report completion
+legio mail send --to {{PARENT_AGENT}} --subject "done" \
+  --body "Summary of what was done" --type result --agent {{AGENT_NAME}}
+
+# Reply to a message
+legio mail reply <message-id> --body "Your reply" --agent {{AGENT_NAME}}
+```
+
+## Spawning Sub-Workers
+
+{{CAN_SPAWN}}
+
+{{QUALITY_GATES}}
+
+{{CONSTRAINTS}}