7e568770de
Wisps are now just a flag on regular beads issues (Wisp=true). No separate directory needed - hooks stored in .beads/. Changes: - wisp package: WispDir now points to .beads/, removed PatrolCycle - manager.go: removed initWispBeads() - no separate dir to create - mrqueue.go: MRs stored in .beads/mq/ instead of .beads-wisp/mq/ - doctor: removed obsolete wisp directory checks - docs: updated wisp-architecture.md to reflect simplified model 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
109 lines
2.8 KiB
Markdown
109 lines
2.8 KiB
Markdown
# Wisp Architecture: Simplified
|
|
|
|
> Status: Updated December 2024 - Simplified from separate directory to flag-based
|
|
|
|
## Overview
|
|
|
|
**Wisps** are ephemeral issues - transient workflow state that should not be synced
|
|
to the shared repository. They're used for operational messages (like lifecycle mail)
|
|
and patrol cycle traces that would otherwise accumulate unbounded.
|
|
|
|
## Core Principle
|
|
|
|
**Wisps are regular issues with `Wisp: true` flag.**
|
|
|
|
The old architecture used a separate `.beads-wisp/` directory. This was over-engineered.
|
|
The simplified approach:
|
|
|
|
| Old | New |
|
|
|-----|-----|
|
|
| `.beads-wisp/issues.jsonl` | `.beads/issues.jsonl` with `Wisp: true` |
|
|
| Separate directory, git init, gitignore | Single database, filtered on sync |
|
|
| Complex dual-inbox routing | Simple flag check |
|
|
|
|
## How It Works
|
|
|
|
### Creating Wisps
|
|
|
|
```bash
|
|
# Create an ephemeral issue
|
|
bd create --title "Patrol cycle" --wisp
|
|
|
|
# Send ephemeral mail (automatically sets Wisp=true)
|
|
gt mail send --wisp -s "Lifecycle: spawn" -m "..."
|
|
```
|
|
|
|
### Sync Filtering
|
|
|
|
When `bd sync` exports to JSONL for git:
|
|
- Issues with `Wisp: true` are **excluded**
|
|
- Only permanent issues are synced to remote
|
|
- No separate directory needed
|
|
|
|
### Querying
|
|
|
|
```bash
|
|
# List all issues (including wisps)
|
|
bd list
|
|
|
|
# List only wisps
|
|
bd list --wisp
|
|
|
|
# List only permanent issues
|
|
bd list --no-wisp
|
|
```
|
|
|
|
## Use Cases
|
|
|
|
### Ephemeral Mail (Lifecycle Messages)
|
|
|
|
Spawn notifications, session handoffs, and other operational messages that:
|
|
- Don't need to be synced to remote
|
|
- Would accumulate unbounded
|
|
- Have no long-term audit value
|
|
|
|
```bash
|
|
gt mail send gastown/polecats/nux --wisp \
|
|
-s "LIFECYCLE: spawn" \
|
|
-m "Work on issue gt-abc"
|
|
```
|
|
|
|
### Patrol Cycle Traces
|
|
|
|
Deacon, Witness, and Refinery run continuous loops. Each cycle would create
|
|
accumulating history. Wisps let them track cycle state without permanent records.
|
|
|
|
### Hook Files
|
|
|
|
Agent hook files (`hook-<agent>.json`) are stored in `.beads/` but are local-only
|
|
runtime state, not synced. These track what work is assigned to each agent for
|
|
restart-and-resume.
|
|
|
|
## Decision Matrix
|
|
|
|
| Question | Answer | Use |
|
|
|----------|--------|-----|
|
|
| Should this sync to remote? | No | Wisp |
|
|
| Is this operational/lifecycle? | Yes | Wisp |
|
|
| Would this accumulate unbounded? | Yes | Wisp |
|
|
| Does this need audit trail? | Yes | Regular issue |
|
|
| Might others need to see this? | Yes | Regular issue |
|
|
|
|
## Migration from .beads-wisp/
|
|
|
|
The old `.beads-wisp/` directories can be deleted:
|
|
|
|
```bash
|
|
# Remove legacy wisp directories
|
|
rm -rf ~/gt/.beads-wisp/
|
|
rm -rf ~/gt/gastown/.beads-wisp/
|
|
find ~/gt -type d -name '.beads-wisp' -exec rm -rf {} +
|
|
```
|
|
|
|
No migration needed - these contained transient data with no long-term value.
|
|
|
|
## Related
|
|
|
|
- [molecules.md](molecules.md) - Molecule system (wisps can be molecule instances)
|
|
- [architecture.md](architecture.md) - Overall Gas Town architecture
|