feat/integrations - Agent-assisted Linear workflow with human approval gates

## Summary

Explore a Linear integration that turns a Buzz conversation with an agent into a trackable engineering workflow, while keeping a human in control before planning, implementation, and merge.

This is a product proposal for discussion. It is not an implementation request yet.

## Problem

Buzz is a place where humans and agents can discuss ideas and technical work. Once a useful feature or bug is identified, the conversation currently has no structured path into project tracking and delivery.

Users should be able to move from:

> conversation → approved work item → implementation → pull request

without losing the original context or allowing the agent to start coding prematurely.

## Proposed experience

### 1. Discuss in Buzz

A human and an agent discuss a feature, bug, or improvement in a channel or thread.

The agent can prepare a draft containing:

- Title
- Problem statement
- Proposed outcome
- Scope
- Acceptance criteria
- Open questions
- Relevant repository context

### 2. Review and create a Linear issue

The user selects **Create Linear issue**.

Buzz presents the generated issue for review and editing before sending it to Linear. The created issue links back to the originating Buzz discussion.

### 3. Approve planning

After the issue is created, the agent prepares an implementation plan and posts it to the Linear issue and Buzz thread.

The agent must wait for an explicit human action such as **Approve plan and start implementation**.

### 4. Implement from the approved issue

After approval, the agent works in an isolated branch or worktree, follows the repository guidance, runs relevant checks, and posts progress updates.

Linear is the project-tracking source of truth. Buzz remains the conversational surface for steering the agent.

### 5. Open a draft pull request

When implementation is complete, the agent opens a linked draft GitHub pull request containing:

- Summary of changes
- Tests/checks run
- Known limitations
- Link to the Linear issue
- Link to the original Buzz discussion

The agent must not merge the pull request. Normal GitHub review and branch protections remain in place.

## Approval gates

The workflow should have three distinct human gates:

1. Approve the generated issue before it is created in Linear.
2. Approve the implementation plan before the agent changes code.
3. Review and approve the pull request before merge.

## Proposed status flow

`Draft → Ready for approval → Planned → Approved → In progress → Review → Done`

The exact mapping to Linear statuses should be configurable rather than hard-coded.

## Initial scope

The first version could focus on:

- Create a Linear issue from a Buzz thread.
- Include a durable link between the Buzz discussion and Linear issue.
- Sync important Linear status changes back to Buzz.
- Generate an implementation plan after issue creation.
- Require explicit approval before implementation.
- Start an agent task from the approved issue.
- Report progress into Buzz and Linear.
- Create a linked draft GitHub pull request.
- Keep merge approval human-controlled.

## Out of scope for the first version

- Replacing Linear’s project, cycle, and issue management.
- Automatic issue creation without a review step.
- Automatic coding before plan approval.
- Automatic pull request merging.
- Automatically deciding whether an upstream Buzz feature should be accepted.
- Supporting every project-management provider at launch.

## Upstream contribution flow

For proposed changes to Buzz itself, a separate workflow could be supported:

`Buzz discussion → draft GitHub issue → maintainer approval → Linear implementation issue → implementation approval → draft PR`

This lets contributors propose an idea to the upstream project before asking an agent to build it.

## Why this fits Buzz

Buzz already treats conversations, agent activity, workflows, and other actions as relay events. The existing agent harness can provide the conversation-to-agent bridge, while the relay/workflow layer can coordinate external integrations and approval events.

The integration should preserve Buzz’s existing architectural principle: model user actions and state transitions as signed events, with the relay coordinating side effects such as Linear and GitHub updates.

## Design questions

- Should Linear be the source of truth for engineering status while Buzz remains the conversational source of truth?
- Should Buzz support Linear’s built-in agent, external coding agents, or both?
- Should the first implementation use Linear webhooks, workflow actions, or a dedicated integration service?
- Which Buzz roles may create issues, approve plans, or start implementation?
- Should every agent update be mirrored to Linear, or only milestones and decisions?
- Should the first release support GitHub only, or leave the provider boundary open for GitLab later?

## Success criteria

A user can:

1. Discuss a feature with an agent in Buzz.
2. Review and create a structured Linear issue without retyping the conversation.
3. Approve an implementation plan explicitly.
4. Follow agent progress from Buzz and Linear.
5. Receive a linked draft pull request.
6. Review and merge the work manually.

This proposal should be discussed and refined before implementation begins.

This is a proposal, not an implementation request, and names no files or tests. Read the existing agent harness and relay/workflow layer described in the issue, then clarify the Linear and GitHub boundaries and approval events. Done means the workflow and scope are discussed and refined before implementation begins.

Written by the indexing model from the issue text.