Pluggable Backends for Tasks, History, and Decisions

[EmmittJ]

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

Current	With Pluggable Backends
history.md (per agent)	Backend-specific — backends that support compaction can auto-manage this
decisions.md + decisions/inbox/	Agents write directly to their backend — no inbox, no Scribe merge
Scribe merges inbox, summarizes history	Those responsibilities move to the backend (or disappear entirely)

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

[bradygaster]

Awesome proposal, @EmmittJ. Let's park this until I can move the new codebase in that has a brand-spankin new SDK that sits atop the Copilot SDK, better optimization, the works. Experimental CLI but, baby steps! I'm glad you proposed this idea but let's park it until the new codebase arrives and revisit the proposal against the new codebase. Awesome idea!

[EmmittJ]

@bradygaster yeah, sounds good. I am really interested to see where this goes, and I will continue to play around with different back-ends. I am really happy with how light-weight this is compared to some of the other options.

[EmmittJ]

@bradygaster it seems something like #191 would cover a bit of this. The issue here is really just about abstracting away managing tasks/decisions/history, and the adapter would be a good start. It would be nice if it was a bit more extensible or bring-your-own kind of situation. for example, configuring tool calls that map to some set group of actions like create_issue, update_issue, etc.

[bradygaster]

This is excellent architecture thinking, and we're genuinely excited about it! The SDK mode (squad.config.ts, defineSquad()) is the foundation for exactly this. Your beads example is spot-on. The current filesystem-based .squad/ structure is the "local" backend, and we see MCP patterns for external services emerging. This is a great direction that builds naturally on the SDK work — we'll keep it in mind as we scale! Thanks for the detailed proposal. 🔧