Feature: Get squads to use project boards

@bradygaster

Summary

Squad currently has no persistent, visual mechanism for agents to track the state of complex tasks. While logs exist, they are opaque and transient. This feature adds the capability for agents to autonomously create GitHub Project boards (V2) and manage task progress (Todo, In Progress, Done) directly within the GitHub UI.

Goals

Visualize Agent Workflow by mapping internal agent state to a GitHub Project Board.
Autonomously Initialize Boards so agents can spin up tracking for new initiatives without user intervention.
Track Item Status allowing agents to move tasks through columns (e.g., moving a task to "Done" upon completion).
Enhance Visibility for human users to see exactly what the squad is working on at a glance.

Proposed Approach

Layer 1: GraphQL API Integration

Integrate a GraphQL client (using https://api.github.com/graphql) as the REST API has limited support for Projects V2.
Implement core mutations: createProjectV2, addProjectV2ItemById, and updateProjectV2ItemFieldValue.
Ensure the GITHUB_TOKEN or PAT has the required scopes (project, repo).

Layer 2: Board Initialization & Configuration

A tool/skill that allows the Lead agent to check if a specific Project Board exists.
If the board is missing, the agent creates it with default fields (Status) and options (Todo, In Progress, Done).

Layer 3: Task & Status Management

Logic to convert existing Issues into Project Items.
A "Status Updater" skill that agents call when completing a step, which updates the specific field value on the board item.
Agents can query the board to see pending items in the "Todo" column.

Notes

This requires using the GitHub Projects V2 API (GraphQL); REST is not sufficient for V2.
The PAT used by the agents must have project (read/write) and repo scopes.
Ideally, the board columns should default to standard Todo / In Progress / Done, but could be configurable in the future.

/cc @bradygaster

love this idea. will put the Squad squad to work on it.

docs: v0.3.0 sprint planning — proposals 024-033a, blog posts, issue #6…

@londospark

Thanks for the detailed proposal, @londospark. This is actively being designed — your issue prompted us to write up a full technical assessment.

Here's where we landed:

Labels are the state machine, boards are the dashboard. Squad already uses status: labels to drive workflow automation via GitHub Actions. Project boards become a visual projection of that label state — one-way sync from labels to board columns. We don't reverse-sync (dragging a card doesn't change labels) because labels are what trigger Actions workflows, and board column changes don't fire API events.
5 columns, not 3. Our label taxonomy has 8 status labels, which map to 5 active board columns: Backlog, Ready, In Progress, Blocked, Done. Your proposed Todo/In Progress/Done is a reasonable starting point, but our workflow needs the additional states.
gh project CLI, not a GraphQL client library. We assessed your GraphQL suggestion — every Projects V2 mutation maps to a gh project subcommand (gh project create, gh project item-add, gh project item-edit, etc.). This keeps Squad at zero npm dependencies. The gh CLI handles auth, pagination, and the GraphQL protocol internally.
Boards are opt-in and user-triggered. No automatic board creation on squad init. The user asks for a board, the coordinator creates it. This avoids surprise side effects in repos where boards aren't wanted.
Provider abstraction is designed in. ADO has built-in boards (no create step needed). GitLab boards are label-driven, which aligns directly with our existing label workflow. The capability negotiation pattern lets Squad skip board operations on providers that don't support them.
Timeline: v0.4.0. v0.3.0 is shipping the label and issue infrastructure that boards depend on. Boards layer on top once that foundation is solid. Your three-layer architecture (GraphQL integration → Board init → Task management) maps cleanly to our work items.

The project token scope is required for Projects V2 API access, so board features will need gh auth refresh -s project. All board operations are additive — Squad works without them.

— 🎯 Keaton (Lead) · Posted by Squad

docs(ai-team): issue triage session - #8 and #6

@londospark

Issue #6 Go/No-Go Assessment & Sprint Plan

Verdict: GO (Conditional)

This feature is ready to implement as v0.4.0 scope, pending one prerequisite.

Executive Summary

Project Boards is sound architecture: labels drive automation, boards provide visualization. Proposal 033 is thorough. Proposal 033a confirms feasibility with zero dependencies using gh project * CLI. The only blocker is the missing project token scope — a one-time fix Brady must run before work starts.

Timeline: v0.4.0, 17-26 squad-hours across 3 phases
Agents: Fenster (core), Verbal (prompts), McManus (docs)
Risk profile: Low — graceful degradation means boards fail silently if scope is missing

Why GO?

Architecture is sound. Labels = state machine (per 032c), boards = dashboard. Zero conflict with existing 032/032c/PR#5 work. Additive feature.
Zero dependencies validated. Kujan confirmed gh project * CLI covers every operation. No npm packages needed. This preserves zero-dependency constraint.
Token scope is fixable. Missing project scope is the only blocker. Single command: gh auth refresh -s project. Not a design problem, not an architectural problem.
Three-phase decomposition is clear. Foundation (WI-1, WI-2) → Integration (WI-3, WI-4) → Polish (WI-5, WI-6). Each phase has clear definition of done. Can parallelize Fenster + Verbal in Phase 2.
Community signal is real. @londospark opened Issue Feature: Get squads to use project boards #6 with a concrete, well-structured proposal. First community feature request. Implementing it signals we listen and move fast.

Prerequisites — Brady Must Do This First

BLOCKING: Run this command before squad starts:

gh auth refresh -s project

This grants the project scope to the current token. One-time, interactive, ~10 seconds. Without this, all board operations fail with a permission error. The proposal includes graceful degradation, but the feature is useless without the scope.

Verification: After running the above, check:

gh auth status 2>&1 | grep "project"

Should show project in the Token scopes list.

Sprint Plan

Phase 1: Foundation (WI-1, WI-2) — v0.4.0 Wave 1

Duration: 6-9 squad-hours
Agent: Fenster (Core Dev)
Parallelizable: No — WI-2 depends on WI-1 validation

WI-1: GraphQL Command Templates for Projects V2

Validate and document gh api graphql / gh project * commands for all operations. This is the spike that proves feasibility.

Acceptance criteria:

All 5 core mutations validated via gh project * CLI
Error handling for missing project scope documented
Field ID discovery flow (4-step pipeline: list → field-list → item-list → item-edit) documented
SKILL.md created at .ai-team/skills/github-projects-v2-commands/SKILL.md
Sample board created and populated with test issue; column movement verified end-to-end

Why this first: If gh project item-edit doesn't work as expected, or if ID resolution is more complex than estimated, this is where we learn. Phase 1 gate: "Can we reliably move an issue between board columns using only gh CLI?"

WI-2: Provider Abstraction — Board Capabilities

Extend provider abstraction (032a) with board operations.

Acceptance criteria:

Board operations defined in provider interface spec (squad.agent.md Platform section)
GitHub provider implementation documented (uses WI-1 commands)
ADO/GitLab stubs documented as "future work"
Capability negotiation flow updated: coordinator checks projectBoards capability before attempting board ops
Graceful skip for missing scope documented (output message, no agent error)

Phase 2: Integration (WI-3, WI-4) — v0.4.0 Wave 2

Duration: 7-11 squad-hours
Agents: Verbal (Prompts, 3-5h) + Fenster (Workflow, 4-6h)
Parallelizable: Yes — WI-3 and WI-4 can run in parallel after WI-1 validation

WI-3: Board Initialization Flow

Coordinator prompt additions for user-triggered board creation.

Acceptance criteria:

Trigger patterns defined (user says "set up a project board", "create a board", etc.)
Board creation flow: check if board exists → create if missing → link to repo → configure default 5 columns
Board ID + field IDs cached in .ai-team/team.md under ## Project Board
Graceful degradation: if project scope missing, user gets a clear message and link to fix
Prompt additions to squad.agent.md coordinator template
End-to-end tested: user says "create a board", board appears in GitHub UI

WI-4: Label-to-Board Sync Workflow

GitHub Actions workflow that syncs label changes to board columns.

Acceptance criteria:

Workflow file: templates/workflows/squad-board-sync.yml
Triggers on issues: [labeled, unlabeled] for status:* labels
When a status:* label changes, board item status field updates (using field IDs from team.md)
When a new issue gets the squad label and a board exists, issue auto-added to board
Workflow skips gracefully if no board is configured (no errors, no noise)
Uses gh api graphql or gh project * commands only (no npm dependencies)
Tested in a real repo: apply status label to issue, verify board item moves to correct column

Note: This is silent automation. No issue comments, no notifications. Label changes propagate to board columns transparently.

Phase 3: Polish (WI-5, WI-6) — v0.4.0 Wave 3

Duration: 4-6 squad-hours
Agents: Verbal (Queries, 2-3h) + McManus (Docs, 2-3h)
Parallelizable: Yes — independent tracks

WI-5: Board Query & Display

Coordinator prompt additions for reading board state from CLI.

Acceptance criteria:

User asks "what's on the board?" / "show me the board" / "what's in progress?"
Coordinator queries board via gh project item-list and renders a summary
Output grouped by column with issue numbers, titles, assignees
Link to the board URL for visual view
Prompt additions to squad.agent.md coordinator template

WI-6: Documentation & Skill

User-facing documentation.

Acceptance criteria:

Docs file at docs/features/project-boards.md explaining:
- What project boards are and why
- How to enable them ("create a board")
- Token scope requirements (project scope)
- How to customize columns (document as "coming soon" for v0.5.0)
- Troubleshooting: permission errors, project scope missing
README updated if boards are a headline feature
SKILL.md updated with board operation reference

Total Effort

Phase	Hours	Agents	Parallelizable
Phase 1 (Foundation)	6-9h	Fenster	No
Phase 2 (Integration)	7-11h	Verbal + Fenster	Yes
Phase 3 (Polish)	4-6h	Verbal + McManus	Yes
Total	17-26h	3 agents	Phases 2-3 overlap possible

Wall-clock estimate (if Fenster + Verbal + McManus work in parallel where possible): 12-16 days at 1 squad per day.

Agent Assignments

Fenster (Core Dev): WI-1, WI-2, WI-4 (workflows, provider integration, command templates)
Verbal (Prompt Engineer): WI-3, WI-5 (coordinator prompt additions, user interactions)
McManus (DevRel): WI-6 (documentation, user-facing content)

Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
`gh project item-edit` has unreliable ID handling	Low	High — Phase 1 gate catches this immediately	Phase 1 is a focused spike; if it fails, we revisit the dependency trade-off
`project` scope becomes unavailable (GitHub changes auth flow)	Very low	Medium — feature breaks silently	Graceful degradation + user messaging built into WI-3
Board sync workflow becomes noisy (too many actions)	Medium	Low — we control what triggers sync	Sync is label-driven and silent; no issue comments
GraphQL field IDs change per-project (they do)	High	Low — expected behavior	WI-1 documents the 4-step discovery pipeline; team.md caches IDs per board
Verbal's prompt additions bloat coordinator	Low	Low — coordinator is ~32KB today, proposals are the priority	Prompt engineering is Verbal's core skill; if it grows, we discuss splitting

What We're NOT Doing

No npm dependencies. Zero-dependency constraint is firm.
No automatic board creation on squad init. Opt-in only.
No custom column configuration in v0.4.0. 5-column default (Backlog, Ready, In Progress, Blocked, Done) is the shipped behavior. Custom columns are v0.5.0.
No Octomember. Coordinator handles board operations directly.
No board-to-label reverse sync. Labels are source of truth. Board is a projection.

Go/No-Go Decision Timeline

Brady runs gh auth refresh -s project (prerequisite)
Verbal/Fenster/McManus acknowledge sprint plan
Fenster starts Phase 1 (WI-1 foundation work)
After Phase 1 validation: Phase 2 can start (Verbal + Fenster parallel)
After Phase 2 ships: Phase 3 (Verbal + McManus parallel)

Why v0.4.0, Not v0.3.0?

Brady's directive for v0.3.0 is ONE feature: proposals as GitHub Issues (Proposal 032). Project boards layer on top of the issue/label foundation (032c). The right sequence:

v0.3.0: Issues + labels + workflows (PR feat: Issue Assignment & Auto-Triage for Squad Members #5) — the infrastructure
v0.4.0: Project boards — the dashboard on top

Shipping boards before labels are solid would be backwards. We're deferring by design, not deferring because we're scared.

Community Signal

@londospark's Issue #6 is the first external feature request with a concrete technical proposal. Implementing it demonstrates that:

We listen to the community
We move fast (16-26 squad-days is quick for a 3-agent feature)
We ship features that compound (boards make the label-driven workflow visible)

This is a v0.4.0 win.

Next step: Brady grants the project scope, then Fenster kicks off Phase 1.

🤖 Assigning to @copilot for implementation. Keaton's go/no-go assessment (posted above) is the sprint plan — 3 phases, 6 work items, gh project * CLI approach.

Prerequisite: Brady must run gh auth refresh -s project before board operations will work. All other work (command templates, provider abstraction spec, prompt additions, workflow design, docs) can proceed without it.

Scope: Proposals 033 and 033a are the authoritative design docs. Implement per those specs.

— Squad (Coordinator)

docs(ai-team): issue #6 go/no-go, universe expansion decisions

Phase 1 Validation Complete — Project Boards Foundation (WI-1 + WI-2)

Agent: Fenster (Core Dev)
Sprint: 033 Phase 1 (Foundation)

What Was Validated

Every gh project * CLI command required for board operations was live-tested against this repo:

Command	Result
`gh project list`	✅ Lists existing projects with JSON output
`gh project create`	✅ Created test board "Squad Board (test)"
`gh project field-list`	✅ Returns Status field with option IDs (Todo/In Progress/Done)
`gh project item-add`	✅ Added issue #6 to board
`gh project item-edit`	✅ Moved issue between all status columns
`gh project item-list`	✅ Returns items with current status
`gh project item-archive`	✅ Archived completed item
`gh project view`	✅ Returns board metadata
`gh project link`	✅ Linked board to repo
`gh project delete`	✅ Cleaned up test board

Key Findings

Zero dependencies confirmed. gh project * commands handle everything — no GraphQL client needed.
project scope already present on current token. Runtime detection pattern works.
4-step field discovery pipeline works. Field IDs and option IDs are project-specific but stable.
item-add is idempotent — safe to re-add existing issues.
item-edit requires 4 opaque IDs — project ID, item ID, field ID, option ID. Most complex command but fully functional.
Windows compatible — PowerShell ConvertFrom-Json replaces jq for JSON parsing.

Deliverables

SKILL.md created: .ai-team/skills/github-projects-v2-commands/SKILL.md — complete command reference any agent can use
Implementation proposal: team-docs/proposals/006a-project-board-implementation.md — provider abstraction + board capabilities interface
Provider stubs documented — GitHub (implemented), ADO (future), GitLab (future)

Phase 1 Gate: PASSED ✅

Can we reliably create boards, add items, and move items between columns using only gh CLI?

Yes. No raw GraphQL needed. Phase 2 (WI-3 coordinator prompts + WI-4 label sync workflow) is unblocked.

What's Next (Phase 2)

WI-3: Board initialization flow in coordinator prompt (Verbal)
WI-4: Label-to-board sync GitHub Action workflow (Fenster)
WI-5: Board query & display (Verbal)

feat: project board + v0.4.0 docs (#6)

squad: log Gandalf decomposition + merge directives

squad: skills scan + catalog + merge decisions

feat(ci): CI hardening phase 2 — short-term improvements (#6-10)

spec(piece-48): add sub-proposal F — compliant fold state-branch writ…

fix(gh-aw): bind squad:{agent} labels to each issue's own plan row (#…

Feature: Get squads to use project boards #6

Description

Summary

Goals

Proposed Approach

Layer 1: GraphQL API Integration

Layer 2: Board Initialization & Configuration

Layer 3: Task & Status Management

Notes

Activity

bradygaster commented on Feb 10, 2026

bradygaster commented on Feb 11, 2026

bradygaster commented on Feb 12, 2026

Issue #6 Go/No-Go Assessment & Sprint Plan

Verdict: GO (Conditional)

Executive Summary

Why GO?

Prerequisites — Brady Must Do This First

Sprint Plan

Phase 1: Foundation (WI-1, WI-2) — v0.4.0 Wave 1

WI-1: GraphQL Command Templates for Projects V2

WI-2: Provider Abstraction — Board Capabilities

Phase 2: Integration (WI-3, WI-4) — v0.4.0 Wave 2

WI-3: Board Initialization Flow

WI-4: Label-to-Board Sync Workflow

Phase 3: Polish (WI-5, WI-6) — v0.4.0 Wave 3

WI-5: Board Query & Display

WI-6: Documentation & Skill

Total Effort

Agent Assignments

Risks & Mitigations

What We're NOT Doing

Go/No-Go Decision Timeline

Why v0.4.0, Not v0.3.0?

Community Signal

bradygaster commented on Feb 12, 2026

bradygaster commented on Feb 13, 2026

Phase 1 Validation Complete — Project Boards Foundation (WI-1 + WI-2)

What Was Validated

Key Findings

Deliverables

Phase 1 Gate: PASSED ✅

What's Next (Phase 2)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions