Pluggable Backends for Tasks, History, and Decisions #162

Most of this was written by Keaton

Squad uses markdown files for agent state: history.md, decisions.md, and the decisions/inbox/ drop-box pattern. This works and it's the right default, but some teams may want queryable backends, auto-compaction, or integration with external trackers they already use.

I have been toying around with beads, and I would like to propose the idea of a skill-based plugin model so teams can choose their own backends for Tasks, History, and Decisions, without changing the coordinator or agent prompts. Markdown stays the default. Teams that want something else (like beads, GitHub Issues, or Linear) just swap a skill file.

The Interface: Tracking Table + Skills

Each team's team.md gets a ## Tracking section that maps concerns to backend skills:

## Tracking

| Concern | Backend | Skill |
|---------|---------|-------|
| Tasks | beads | `.squad/skills/tasks-beads/SKILL.md` |
| Decisions | github | `.squad/skills/decisions-github/SKILL.md` |

At spawn time, the coordinator:

1. Reads the tracking table from team.md
2. Loads each skill file's ## Spawn Prompt Block
3. Injects these blocks into the agent's prompt

The agent doesn't know or care what backend is behind the commands — they just follow the injected instructions.

Example: Different Backends for Tasks

Beads backend (tasks-beads/SKILL.md):

## Spawn Prompt Block

Ready work: run `bd ready --json`
Your history: `bd list -a {agent-name} --status closed --json`
Close a task: `bd close {id} --reason "Done: {summary}" --json`

GitHub Issues backend (tasks-github/SKILL.md):

## Spawn Prompt Block

Ready work: `gh issue list -R {repo} --label "ready" --json`
Your history: `gh issue list -R {repo} --assignee "@me" --state closed --json`
Close a task: `gh issue close {id} -c "Done: {summary}"`

Markdown backend (tasks-markdown/SKILL.md):

## Spawn Prompt Block

Ready work: see `tasks.md` under "## Ready"
Your history: grep agent name in `history.md`, collect closed items
Close a task: append to `history.md` under your section

Same concern (Tasks), completely different backend. Coordinator and agents don't change.

What the Agent Sees

At spawn, the agent gets injected blocks like this — they never see the skill file or the tracking table:

TASK CONTEXT:
  Ready work: run `bd ready --json`
  Your assigned work: check `bd list --status open --json` for items you claimed
  Your work history: run `bd list -a {name} --status closed --json`

  TASK OUTPUT:
  When you complete a task: `bd close {id} --reason "Done: {summary}" --json`

DECISION CONTEXT:
  Active decisions: `gh issue list -R {repo} --label "decision" --state open --json`

  DECISION OUTPUT:
  When you make a team-relevant decision:
    `gh issue create -R {repo} --label "decision" --title "{title}" --body "..."`

Notice: tasks on beads, decisions on GitHub Issues. Mix and match.

What Changes

What stays: agent charters, orchestration logs, session archives.

Open Questions

1. Skill interface spec — what fields must a skill's ## Spawn Prompt Block define so the coordinator can reliably inject them? Do we need a schema?
2. Migration tooling — how do we help existing teams import markdown history into a new backend?
3. Fallback behavior — if a skill is missing or misconfigured, should the coordinator warn, fail, or fall back to markdown?
4. Scribe's role — with history summarization and decision merging potentially handled by backends, does Scribe shrink to just orchestration logs and session archives?

Labels: enhancement, architecture, discussion