docs: add plugin architecture (agents-as-plugins)
Plugins are just more agents in the wasteland - with identities, mailboxes, and beads access. No special framework, just directory conventions and mail-based invocation. Added beads: - gt-axz: Plugin architecture epic - gt-8dv: CLI plugin commands - gt-pio: merge-oracle plugin (merge queue analysis) - gt-35x: plan-oracle plugin (work decomposition) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
@@ -1,10 +1,13 @@
|
||||
{"id":"gt-082","title":"Worker cleanup: Beads sync on shutdown","description":"Add beads sync verification to worker cleanup checklist and Witness verification.\n\n## Update to Decommission Checklist (gt-sd6)\n\nAdd to pre-done verification:\n- bd sync --status must show 'Up to date'\n- git status .beads/ must show no changes\n\n## Beads Edge Cases\n\nUncommitted beads changes:\n bd sync\n git add .beads/\n git commit -m 'beads: final sync'\n\nBeads sync conflict (rare):\n git fetch origin main\n git checkout main -- .beads/\n bd sync --force\n git add .beads/\n git commit -m 'beads: resolve sync conflict'\n\n## Update to Witness Verification (gt-f8v)\n\nWhen capturing worker state:\n town capture \u003cpolecat\u003e \"bd sync --status \u0026\u0026 git status .beads/\"\n\nCheck for:\n- bd sync --status shows 'Up to date'\n- git status .beads/ shows no changes\n\nIf beads not synced, nudge:\n WITNESS CHECK: Beads not synced. Run 'bd sync' then commit .beads/. Signal done when complete.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:21.757756-08:00","updated_at":"2025-12-15T20:48:37.663168-08:00","dependencies":[{"issue_id":"gt-082","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.977804-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-1le","title":"town handoff command (optional)","description":"CLI commands for session handoff workflow (optional convenience).\n\n## Commands\n\n### gt handoff\nGenerate handoff interactively.\n```\ngt handoff [--send]\n```\n- Collects current state (status, inbox, beads)\n- Prompts for additional notes\n- --send: Mail to self and exit\n\n### gt resume\nCheck for and display pending handoff.\n```\ngt resume\n```\n- Checks inbox for handoff message\n- Displays formatted handoff if found\n- Suggests next actions\n\n## Implementation\n\nThese are convenience wrappers. The same workflow can be done manually:\n```bash\n# Manual handoff\ntown status \u003e /tmp/handoff\ntown inbox \u003e\u003e /tmp/handoff\nbd ready \u003e\u003e /tmp/handoff\n# Edit and send\ntown mail send mayor/ -s \"Session Handoff\" -f /tmp/handoff\n```\n\n## Priority\n\nP2 - Optional. Manual workflow works fine. Nice to have for UX.\n\n## Notes\n\nPart of session cycling workflow designed in gt-u82.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-15T20:15:31.954724-08:00","updated_at":"2025-12-15T21:23:29.056772-08:00","dependencies":[{"issue_id":"gt-1le","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.647043-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-35x","title":"Plugin: plan-oracle (work decomposition)","description":"Plugin that helps decompose epics/issues into sub-tasks. Analyzes scope, identifies dependencies, estimates complexity for parallelization, creates beads for sub-tasks with dependency links.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-15T22:53:05.772986-08:00","updated_at":"2025-12-15T22:53:05.772986-08:00","dependencies":[{"issue_id":"gt-35x","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.587726-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-61o","title":"Review and audit all GGT beads","description":"Thorough review of all filed beads in gastown GGT repo. Check for: consistency, completeness, correct dependencies, accurate descriptions, proper prioritization. Ensure beads are self-contained and dont rely on external docs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:07.152386-08:00","updated_at":"2025-12-15T21:23:58.255447-08:00","closed_at":"2025-12-15T21:23:58.255447-08:00","close_reason":"Audit complete: fixed 4 stale doc refs, 1 arch inconsistency, enriched 25+ sparse descriptions"}
|
||||
{"id":"gt-82y","title":"Design: Swarm shutdown and worker cleanup","description":"Design for graceful swarm shutdown, worker cleanup, and session cycling.\n\n## Key Decisions\n\n1. Pre-kill verification uses model intelligence (not framework rules)\n2. Witness can request restart when context filling (mail self, exit)\n3. Mayor NOT involved in per-worker cleanup (Witness responsibility)\n4. Clear responsibility boundaries between Mayor/Witness/Polecat\n\n## Subtasks (implementation)\n\n- gt-sd6: Polecat decommission checklist prompting\n- gt-f8v: Witness pre-kill verification protocol\n- gt-eu9: Witness session cycling and handoff\n- gt-gl2: Mayor vs Witness cleanup responsibilities\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T19:47:44.936374-08:00","updated_at":"2025-12-15T20:49:22.849598-08:00","closed_at":"2025-12-15T20:12:05.441911-08:00","close_reason":"Design complete in docs/swarm-shutdown-design.md. Subtasks remain open for implementation."}
|
||||
{"id":"gt-8dv","title":"CLI: plugin commands (list, status)","description":"Add gt plugins \u003crig\u003e to list plugins and gt plugin status \u003cname\u003e to check plugin state. Simple directory scan of \u003crig\u003e/plugins/.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-15T22:53:02.694926-08:00","updated_at":"2025-12-15T22:53:02.694926-08:00","dependencies":[{"issue_id":"gt-8dv","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.413809-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-95x","title":"Remove stale migration docs from gastown-py","description":"The gastown-py repo has migration-related documentation that is now misinformation since we have made design decisions. Remove or clearly mark as obsolete: any docs about migration paths, old architecture assumptions, or superseded designs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:08.642373-08:00","updated_at":"2025-12-15T21:04:39.516436-08:00","closed_at":"2025-12-15T21:04:39.516436-08:00","close_reason":"Removed docs/go-port/ (4 files) and docs/town-design.md from gastown-py"}
|
||||
{"id":"gt-9a2","title":"Federation: Wasteland architecture for cross-town coordination","description":"## Overview\n\nA Wasteland is a federation of Towns across multiple machines. This enables:\n- Same project managed in multiple locations (local Mac + GCP VMs)\n- Cross-town swarm coordination\n- Unified UI for managing distributed work\n\n## Use Cases\n\n1. **Scale-out**: Spawn workers on cloud VMs when local resources exhausted\n2. **Geographic distribution**: Run workers close to data/services\n3. **Redundancy**: Continue work if one machine goes down\n\n## Design Questions\n\n- How do towns discover each other?\n- Cross-town mail routing protocol\n- Shared vs replicated beads databases\n- Conflict resolution for concurrent edits\n- Authentication between towns\n- UI for wasteland-level visibility\n\n## Placeholder Tasks\n\n- [ ] Design wasteland discovery/registration\n- [ ] Design cross-town mail protocol\n- [ ] Design beads synchronization strategy\n- [ ] Implement gt wasteland commands\n- [ ] Implement federation UI\n\n## Related\n\n- gt-f9x: Town \u0026 Rig Management (has federation basics)\n- gt-f9x.7-10: Connection interface and federation subtasks\n- docs/architecture.md: Future Federation section","status":"open","priority":2,"issue_type":"epic","created_at":"2025-12-15T19:21:32.462063-08:00","updated_at":"2025-12-15T21:15:30.395077-08:00"}
|
||||
{"id":"gt-av8","title":"Update Mayor prompting in gastown-py","description":"The Mayor CLAUDE.md and related prompting in gastown-py (still in production use) needs to reflect current design decisions: session cycling, handoff protocol, cleanup responsibilities, beads access model. Sync prompting with GGT design work.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:09.953043-08:00","updated_at":"2025-12-15T21:07:29.858267-08:00","closed_at":"2025-12-15T21:07:29.858267-08:00","close_reason":"Updated AGENTS-mayor.md with session cycling, handoff protocol, and cleanup authority clarification"}
|
||||
{"id":"gt-axz","title":"Design: Plugin architecture (agents-as-plugins)","description":"Plugin system where plugins are just additional agents with identities, mailboxes, and beads access. See docs/architecture.md Plugins section. No special framework - just directory conventions and mail-based invocation.","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T22:52:43.614095-08:00","updated_at":"2025-12-15T22:53:00.103419-08:00"}
|
||||
{"id":"gt-cjb","title":"Witness updates: Remove issue filing proxy","description":"Update Witness prompting to remove issue filing proxy, since polecats now have direct beads access.\n\n## Remove from Witness Prompting\n\nThe following is NO LONGER Witness responsibility:\n- Processing polecat 'file issue' mail requests\n- Creating issues on behalf of polecats\n- Forwarding issue creation requests\n\n## Add: Legacy Request Handling\n\nIf Witness receives an old-style 'please file issue' request:\n\n1. Respond with update:\n town inject \u003cpolecat\u003e \"UPDATE: You have direct beads access now. Use bd create to file issues yourself.\"\n\n2. Do not file the issue - let the polecat learn the new workflow.\n\n## Keep in Witness Prompting\n\n- Monitoring polecat progress\n- Nudge protocol\n- Pre-kill verification\n- Session lifecycle management","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:19.921561-08:00","updated_at":"2025-12-15T20:48:36.020922-08:00","dependencies":[{"issue_id":"gt-cjb","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.896691-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-cr0","title":"Consolidate design docs into beads descriptions","description":"The markdown design docs (swarm-shutdown-design.md, polecat-beads-access-design.md, mayor-handoff-design.md) will decay. Extract key decisions and prompting templates into the beads descriptions themselves, then archive or remove the markdown files. Beads are the source of truth.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:05.45131-08:00","updated_at":"2025-12-15T20:51:52.083465-08:00","closed_at":"2025-12-15T20:51:52.083465-08:00","close_reason":"Consolidated: created docs/architecture.md, moved design content into bead descriptions, deleted 4 individual design docs"}
|
||||
{"id":"gt-d3d","title":"Design: Additional design issues (placeholder)","description":"Placeholder for additional design issues the user wants to raise and work through. Convert to specific subtasks as issues are identified.","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:24:12.601585-08:00","updated_at":"2025-12-15T20:24:12.601585-08:00"}
|
||||
@@ -27,6 +30,7 @@
|
||||
{"id":"gt-iib","title":"Architecture: Decentralized rig structure with per-rig agents","description":"## Decision\n\nAdopt decentralized architecture where each rig contains all its agents (mayor/, witness/, refinery/, polecats/) rather than centralizing mayor clones at town level.\n\n## Town Level Structure\n\n```\n~/ai/ # Town root\n├── config/ # Town config (VISIBLE, not hidden)\n│ ├── town.json # {\"type\": \"town\"}\n│ ├── rigs.json # Registry of managed rigs\n│ └── federation.json # Wasteland config (future)\n│\n├── mayor/ # Mayor's HOME at town level\n│ ├── CLAUDE.md\n│ ├── mail/inbox.jsonl\n│ └── state.json\n│\n└── \u003crigs\u003e/ # Managed projects\n```\n\n## Rig Level Structure (e.g., wyvern)\n\n```\nwyvern/ # Rig = clone of project repo\n├── .git/info/exclude # Gas Town adds: polecats/ refinery/ witness/ mayor/\n├── .beads/ # Beads (if project uses it)\n├── [project files] # Clean project code on main\n│\n├── polecats/ # Worker clones\n│ └── \u003cname\u003e/ # Each is a git clone\n│\n├── refinery/\n│ ├── rig/ # Refinery's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n├── witness/ # NEW: Per-rig pit boss\n│ ├── rig/ # Witness's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n└── mayor/\n ├── rig/ # Mayor's clone for this rig\n └── state.json\n```\n\n## Key Decisions\n\n1. **Visible config dir**: `config/` not `.gastown/` (models don't find hidden dirs)\n2. **Witness per-rig**: Each rig has its own Witness (pit boss) with its own clone\n3. **Mayor decentralized**: Mayor's clones live IN each rig at `\u003crig\u003e/mayor/rig/`\n4. **Minimal invasiveness**: Only `.git/info/exclude` modified, no commits to project\n5. **Clone subdir name**: Keep `rig/` for consistency (refinery/rig/, witness/rig/, mayor/rig/)\n\n## Role Detection\n\n- Town root or mayor/ → Mayor (town level)\n- Rig root → Mayor (canonical main)\n- \u003crig\u003e/mayor/rig/ → Mayor (rig-specific)\n- \u003crig\u003e/refinery/rig/ → Refinery\n- \u003crig\u003e/witness/rig/ → Witness\n- \u003crig\u003e/polecats/\u003cname\u003e/ → Polecat\n\n## Migration from PGT\n\n- `mayor/rigs/\u003crig\u003e/` → `\u003crig\u003e/mayor/rig/`\n- `\u003crig\u003e/town/` → eliminated (rig root IS the clone)\n- Add `witness/` to each rig","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-15T19:21:19.913928-08:00","updated_at":"2025-12-15T19:21:40.461186-08:00","closed_at":"2025-12-15T19:21:40.461186-08:00","close_reason":"Design decision recorded","dependencies":[{"issue_id":"gt-iib","depends_on_id":"gt-u1j","type":"blocks","created_at":"2025-12-15T19:21:40.374551-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-j87","title":"Design: Swarm simulation and validation","description":"Validate GGT designs through simulation before implementation.\n\n## Validation Approaches\n\n### 1. Dry-Run Simulation (Recommended First)\nMayor walks through scenarios mentally/on paper:\n- \"If polecat Toast signals done with dirty git state, what happens?\"\n- \"If Witness context fills mid-verification, what state is lost?\"\n- \"If two polecats try to close same issue, what happens?\"\n\nCreate beads for any gaps discovered.\n\n### 2. Real Swarms in gastown-py\nUse Python Gas Town to stress-test assumptions:\n- Run actual swarms on test repos\n- Observe edge cases in practice\n- Document issues found\n\n### 3. Edge Case Analysis\nSystematic review of failure modes:\n- Agent crashes mid-operation\n- Network failures during sync\n- Concurrent access to shared state\n- Context limits hit at bad times\n\n## Key Scenarios to Validate\n\n- [ ] Witness session cycling (state preservation)\n- [ ] Polecat decommission with dirty state\n- [ ] Merge conflicts in queue\n- [ ] Beads sync conflicts between workers\n- [ ] Escalation path (stuck worker -\u003e Mayor)\n- [ ] Cross-rig communication\n- [ ] Federation mail routing (future)\n\n## Success Criteria\n\n- No data loss scenarios identified\n- Clear recovery paths for all failure modes\n- Edge cases either handled or documented as limitations\n- Design improves as model cognition improves\n\n## Output\n\nFor each scenario validated:\n1. Document in relevant bead if issue found\n2. Create new beads for missing functionality\n3. Update architecture.md if design changes","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:24:11.251841-08:00","updated_at":"2025-12-15T21:23:44.79455-08:00"}
|
||||
{"id":"gt-l3c","title":"Design: Polecat Beads write access","description":"Design for granting polecats direct beads write access.\n\n## Background\n\nWith Beads v0.30.0 tombstone-based rearchitecture, we have solid multi-agent support. Reversing the original read-only decision.\n\n## Benefits\n\n- Simplifies architecture (no mail-based issue filing proxy)\n- Empowers polecats to file discovered work\n- Beads handles work-disavowal\n\n## Complications\n\nFor OSS projects where you cannot commit to project .beads/, need per-rig beads repo configuration.\n\n## Subtasks (implementation)\n\n- gt-zx3: Per-rig beads configuration schema\n- gt-e1y: Worker prompting updates for beads access\n- gt-cjb: Witness proxy removal\n- gt-082: Beads sync in decommission checklist\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T19:37:42.191734-08:00","updated_at":"2025-12-15T20:49:24.598429-08:00","closed_at":"2025-12-15T20:14:04.174535-08:00","close_reason":"Design complete in docs/polecat-beads-access-design.md. Subtasks remain open for implementation."}
|
||||
{"id":"gt-pio","title":"Plugin: merge-oracle (merge queue analysis)","description":"Example plugin that analyzes changesets before Refinery processes them. Builds overlap graph, classifies disjointness (parallel-safe vs needs-sequencing), uses LLM for semantic complexity, identifies high-risk patterns. Based on merge-orchestration proposal. See docs/architecture.md.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-15T22:53:04.027073-08:00","updated_at":"2025-12-15T22:53:04.027073-08:00","dependencies":[{"issue_id":"gt-pio","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.507459-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-qh2","title":"Session cycling UX: smooth transitions via TUI wrapper","description":"## Problem\n\nCurrent CLI agent session cycling is painful:\n- Shell → CC starts → priming → context loads → ready → work → exit/crash → repeat\n- Each cycle is 30-60 seconds of cold boot\n- No continuity between shell and agent's inner state\n- Raw \"session not running, starting...\" loop is the baseline\n\n## GGT Advantages (already have)\n\n- Beads: Work state survives session death completely\n- Mail: Handoff notes from past-self to future-self \n- Prime commands: Structured context reload\n\n## Gap: Transition Mechanics\n\nIdeas to explore when actively using CLI:\n\n1. **In-band cycling** - `/restart` or `/cycle` command, agent handles own restart without dropping to shell\n\n2. **Hot standby** - TUI maintains pre-warmed session in background, switch to already-primed agent\n\n3. **Persistent wrapper** - Bubbletea TUI stays running across session cycles, CC sessions come/go inside it\n\n4. **Session pooling** - Keep 2-3 primed sessions ready, never wait for cold start\n\n## Deferred\n\nDeliberately P4 until we're actively using the simpler CLI and feel the pain firsthand.","status":"open","priority":4,"issue_type":"task","created_at":"2025-12-15T20:38:12.660716-08:00","updated_at":"2025-12-15T20:38:23.422132-08:00"}
|
||||
{"id":"gt-sd6","title":"Enhanced polecat decommission prompting","description":"Add decommission checklist to polecat AGENTS.md.template. Make crystal clear: verify ALL before signaling done.\n\n## Checklist for AGENTS.md.template\n\n```markdown\n## Decommission Checklist\n\n**CRITICAL**: Before signaling done, you MUST complete this checklist.\nThe Witness will verify each item and bounce you back if dirty.\n\n### Pre-Done Verification\n\n```bash\n# 1. Git status - must be clean\ngit status\n# Expected: \"nothing to commit, working tree clean\"\n\n# 2. Stash list - must be empty\ngit stash list\n# Expected: (empty output)\n\n# 3. Beads sync - must be up to date\nbd sync --status\n# Expected: \"Up to date\" or \"Nothing to sync\"\n\n# 4. Branch merged - your work must be on main\ngit log main --oneline -1\ngit log HEAD --oneline -1\n# Expected: Same commit\n```\n\n### If Any Check Fails\n\n- **Uncommitted changes**: Commit them or discard if unnecessary\n- **Stashes**: Pop and commit, or drop if obsolete\n- **Beads out of sync**: Run `bd sync`\n- **Branch not merged**: Complete the merge workflow\n\n### Signaling Done\n\nOnly after ALL checks pass:\n\n```bash\nbd close \u003cissue-id\u003e\nbd sync\ntown mail send \u003crig\u003e/witness -s \"Work Complete\" -m \"Issue \u003cid\u003e done.\"\n```\n```\n\n## Implementation\n\nAdd to AGENTS.md.template in the polecat prompting section.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:57.911311-08:00","updated_at":"2025-12-15T20:47:30.062333-08:00","dependencies":[{"issue_id":"gt-sd6","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:06.008061-08:00","created_by":"daemon"}]}
|
||||
{"id":"gt-sye","title":"Mayor startup protocol prompting","description":"Add startup protocol to Mayor CLAUDE.md template.\n\n## On Session Start\n\n1. Check for handoff:\n town inbox | grep \"Session Handoff\"\n\n2. If handoff found:\n - Read it: town read \u003cmsg-id\u003e\n - Process pending escalations (highest priority)\n - Check status of noted swarms\n - Verify rig health matches notes\n - Continue with documented next steps\n\n3. If no handoff:\n town status # Overall health\n town rigs # Each rig\n bd ready # Work items\n town inbox # Any messages\n Build your own picture of current state.\n\n4. After processing handoff:\n - Archive or delete the handoff message\n - You now own the current state\n\n## Handoff Best Practices\n\n- Be specific: 'Toast has merge conflict in auth/middleware.go' not 'Toast is stuck'\n- Include context: Why decisions are pending, what you were thinking\n- Prioritize next steps: What is most urgent\n- Note time-sensitive items: Anything that might have changed since handoff","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T20:15:27.915484-08:00","updated_at":"2025-12-15T20:48:57.555724-08:00","dependencies":[{"issue_id":"gt-sye","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.459108-08:00","created_by":"daemon"}]}
|
||||
|
||||
@@ -254,6 +254,19 @@ When an agent's context fills, it hands off to its next session:
|
||||
- **Clear role detection**: "Am I in a `/rig/` directory?" = I'm in an agent clone
|
||||
- **Refinery is canonical main**: Refinery's clone serves as the authoritative "main branch" - it pulls, merges PRs, and pushes. No need for a separate rig-root clone.
|
||||
|
||||
### 8. Plugins as Agents
|
||||
|
||||
**Decision**: Plugins are just additional agents with identities, mailboxes, and access to beads. No special plugin infrastructure.
|
||||
|
||||
**Rationale**:
|
||||
- Fits Gas Town's intentionally rough aesthetic
|
||||
- Zero new infrastructure needed (uses existing mail, beads, identities)
|
||||
- Composable - plugins can invoke other plugins via mail
|
||||
- Debuggable - just look at mail logs and bead history
|
||||
- Extensible - anyone can add a plugin by creating a directory
|
||||
|
||||
**Structure**: `<rig>/plugins/<name>/` with optional `rig/`, `CLAUDE.md`, `mail/`, `state.json`.
|
||||
|
||||
### 7. Rig-Level Beads via BEADS_DIR
|
||||
|
||||
**Decision**: Each rig has its own `.beads/` directory. Agents use the `BEADS_DIR` environment variable to point to it.
|
||||
@@ -358,6 +371,117 @@ gt wake <polecat> # Mark polecat as active
|
||||
gt sleep <polecat> # Mark polecat as inactive
|
||||
```
|
||||
|
||||
## Plugins
|
||||
|
||||
Gas Town supports **plugins** - but in the simplest possible way: plugins are just more agents.
|
||||
|
||||
### Philosophy
|
||||
|
||||
Gas Town is intentionally rough and lightweight. A "credible plugin system" with manifests, schemas, and invocation frameworks would be pretentious for a project named after a Mad Max wasteland. Instead, plugins follow the same patterns as all Gas Town agents:
|
||||
|
||||
- **Identity**: Plugins have persistent identities like polecats and witnesses
|
||||
- **Communication**: Plugins use mail for input/output
|
||||
- **Artifacts**: Plugins produce beads, files, or other handoff artifacts
|
||||
- **Lifecycle**: Plugins can be invoked on-demand or at specific workflow points
|
||||
|
||||
### Plugin Structure
|
||||
|
||||
Plugins live in a rig's `plugins/` directory:
|
||||
|
||||
```
|
||||
wyvern/ # Rig
|
||||
├── plugins/
|
||||
│ └── merge-oracle/ # A plugin
|
||||
│ ├── rig/ # Plugin's git clone (if needed)
|
||||
│ ├── CLAUDE.md # Plugin's instructions/prompts
|
||||
│ ├── mail/inbox.jsonl # Plugin's mailbox
|
||||
│ └── state.json # Plugin state (optional)
|
||||
```
|
||||
|
||||
That's it. No plugin.yaml, no special registration. If the directory exists, the plugin exists.
|
||||
|
||||
### Invoking Plugins
|
||||
|
||||
Plugins are invoked like any other agent - via mail:
|
||||
|
||||
```bash
|
||||
# Refinery asks merge-oracle to analyze pending changesets
|
||||
gt send wyvern/plugins/merge-oracle -s "Analyze merge queue" -m "..."
|
||||
|
||||
# Mayor asks plan-oracle for a work breakdown
|
||||
gt send beads/plugins/plan-oracle -s "Plan for bd-xyz" -m "..."
|
||||
```
|
||||
|
||||
Plugins do their work (potentially spawning Claude sessions) and respond via mail, creating any necessary artifacts (beads, files, branches).
|
||||
|
||||
### Hook Points
|
||||
|
||||
Existing agents can be configured to notify plugins at specific points. This is just convention - agents check if a plugin exists and mail it:
|
||||
|
||||
| Workflow Point | Agent | Example Plugin |
|
||||
|----------------|-------|----------------|
|
||||
| Before merge processing | Refinery | merge-oracle |
|
||||
| Before swarm dispatch | Mayor | plan-oracle |
|
||||
| On worker stuck | Witness | debug-oracle |
|
||||
| On PR ready | Refinery | review-oracle |
|
||||
|
||||
Configuration is minimal - perhaps a line in the agent's CLAUDE.md or state.json noting which plugins to consult.
|
||||
|
||||
### Example: Merge Oracle
|
||||
|
||||
The **merge-oracle** plugin analyzes changesets before the Refinery processes them:
|
||||
|
||||
**Input** (via mail from Refinery):
|
||||
- List of pending changesets
|
||||
- Current merge queue state
|
||||
|
||||
**Processing**:
|
||||
1. Build overlap graph (which changesets touch same files/regions)
|
||||
2. Classify disjointness (fully disjoint → parallel safe, overlapping → needs sequencing)
|
||||
3. Use LLM to assess semantic complexity of overlapping components
|
||||
4. Identify high-risk patterns (deletions vs modifications, conflicting business logic)
|
||||
|
||||
**Output**:
|
||||
- Bead with merge plan (parallel groups, sequential chains)
|
||||
- Mail to Refinery with recommendation (proceed / escalate to Mayor)
|
||||
- If escalation needed: mail to Mayor with explanation
|
||||
|
||||
The merge-oracle's `CLAUDE.md` contains the prompts and classification criteria. Gas Town doesn't need to know the internals.
|
||||
|
||||
### Example: Plan Oracle
|
||||
|
||||
The **plan-oracle** plugin helps decompose work:
|
||||
|
||||
**Input**: An issue/epic that needs breakdown
|
||||
|
||||
**Processing**:
|
||||
1. Analyze the scope and requirements
|
||||
2. Identify dependencies and blockers
|
||||
3. Estimate complexity (for parallelization decisions)
|
||||
4. Suggest task breakdown
|
||||
|
||||
**Output**:
|
||||
- Beads for the sub-tasks (created via `bd create`)
|
||||
- Dependency links (via `bd dep add`)
|
||||
- Mail back with summary and recommendations
|
||||
|
||||
### Why This Design
|
||||
|
||||
1. **Fits Gas Town's aesthetic**: Rough, text-based, agent-shaped
|
||||
2. **Zero new infrastructure**: Uses existing mail, beads, identities
|
||||
3. **Composable**: Plugins can invoke other plugins
|
||||
4. **Debuggable**: Just look at mail logs and bead history
|
||||
5. **Extensible**: Anyone can add a plugin by creating a directory
|
||||
|
||||
### Plugin Discovery
|
||||
|
||||
```bash
|
||||
gt plugins <rig> # List plugins in a rig
|
||||
gt plugin status <name> # Check plugin state
|
||||
```
|
||||
|
||||
Or just `ls <rig>/plugins/`.
|
||||
|
||||
## Future: Federation
|
||||
|
||||
Federation enables work distribution across multiple machines via SSH. Not yet implemented, but the architecture supports:
|
||||
|
||||
Reference in New Issue
Block a user