jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-10-29 05:21:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: call the shared workspace a channel

Browse Source 
Signed-off-by: Fizz <400e8babadcee6a7f420103f10a2849d84c4a9c71d5bd04f3948c814216648a3@buzz.block.builderlab.xyz>
This commit is contained in:
Fizz
2026-09-05 10:22:34 -07:00
parent 17f302f452
commit 09ff9efa71
5 changed files with 62 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
AGENTS.md
View File

@@ -23,13 +23,13 @@ against that direction. Scale validation to the change's risk and exercise the
real workflow for user-visible or integration behavior when practical; green CI
and runtime evidence answer different questions.
### Room and Object Model
### Channel and Object Model
For changes involving projects, tasks, repositories, branches, documents, or
channel navigation, read [VISION_ROOMS.md](VISION_ROOMS.md).
channel navigation, read [VISION_CHANNELS.md](VISION_CHANNELS.md).
A room has one conversation and can have several object views. Each object has
one canonical room; a task and its branch can share the **same room**. Do not
A channel has one conversation and can have several object views. Each object has
one canonical channel; a task and its branch can share the **same channel**. Do not
create a second conversation merely to add a view. Apply this model consistently
across desktop, web, mobile, CLI, and agents.

4
VISION.md
View File

@@ -152,9 +152,9 @@ Beyond chat: channels are workspaces.
The relay hosts git repos. Smart HTTP — standard `git clone`, `git push`, nothing special. Your npub signs pushes. Same domain, same auth, same identity as everything else on the relay.
The target is **one room, many views**. Projects, tasks, repositories, branches, and documents resolve to canonical conversation rooms; a task and its branch can share the same channel UUID. Time-bound projects can span durable repositories, each with its own ongoing room. See [VISION_ROOMS.md](VISION_ROOMS.md) for the shared model, nested relationships, and backend specification.
The target is **one channel, many views**. Projects, tasks, repositories, branches, and documents resolve to canonical conversation channels; a task and its branch can share the same channel UUID. Time-bound projects can span durable repositories, each with its own ongoing channel. See [VISION_CHANNELS.md](VISION_CHANNELS.md) for the shared model, nested relationships, and backend specification.
In that model, creating a feature branch creates or reuses its room — CI results, review comments, and the merge decision belong there. A completed branch-only room can archive into a permanent record; merging a branch must not archive other active work sharing the room.
In that model, creating a feature branch creates or reuses its channel — CI results, review comments, and the merge decision belong there. A completed branch-only channel can archive into a permanent record; merging a branch must not archive other active work sharing the channel.
See [VISION_PROJECTS.md](VISION_PROJECTS.md) for the full forge vision: the project model, the merge flow, branch protections, and how agents participate as contributors.

81
VISION_ROOMS.md → VISION_CHANNELS.md
View File

@@ -1,86 +1,89 @@
# Buzz Rooms — One Conversation, Many Views
# Buzz Channels — One Conversation, Many Views
## The Model
A **room is a channel**: one stable channel UUID and one working conversation.
Projects, tasks (including subtasks), repositories, branches, and living documents
each have a canonical room. They are **facets** of that room, not mutually
exclusive room types. An ordinary conversation can have no object facets.
A **channel** is where people and agents discuss work. It has one stable UUID
and one shared conversation. Task details, documents, and code diffs are views
alongside that conversation, not separate chats.
One object has one conversation home. One room can be home to several objects.
A task and its implementation branch can therefore be two views of **the same
channel UUID**, not separate channels with synchronized messages. Switching from
task details to the diff changes the view, not the conversation. Adding a facet
Projects, tasks (including subtasks), repositories, branches, and living documents
each have one home channel. A channel can be home to several objects, or just
be a conversation with none. These objects do not impose mutually exclusive
channel types.
For example, a task and its implementation branch can share **the same channel
UUID**. Switching from task details to the diff changes the view, not the
conversation. Opening either object leads back to that channel; adding a view
does not create another chat.
Object state stays in its own representation: a task has status and assignees,
a repository has refs, and a document has content. The room brings these views
a repository has refs, and a document has content. The channel brings these views
and their conversation together.
## Projects and Repositories
Projects organize a time-bound outcome. Repositories are durable homes for code
and ongoing conversation. A project can span several repositories, and a
repository can support many projects over time or concurrently. Their rooms have
repository can support many projects over time or concurrently. Their channels have
different purposes and do not normally share a one-to-one relationship.
For example, a **Simplify sign-in** project spans the identity service and mobile
app repositories:
```text
Project room: Simplify sign-in
├── Task room: Improve account recovery
│ ├── Room S: Fix recovery tokens [subtask + identity-service branch]
│ └── Room M: Add recovery screen [subtask + mobile-app branch]
└── Design room: Recovery experience [document]
Project channel: Simplify sign-in
├── Task channel: Improve account recovery
│ ├── Channel S: Fix recovery tokens [subtask + identity-service branch]
│ └── Channel M: Add recovery screen [subtask + mobile-app branch]
└── Design channel: Recovery experience [document]
Repository room: identity-service [ongoing code and maintenance discussion]
└── Branch view: fix-recovery-tokens → room S
Repository channel: identity-service [ongoing code and maintenance discussion]
└── Branch view: fix-recovery-tokens → channel S
Repository room: mobile-app [ongoing code and maintenance discussion]
└── Branch view: recovery-screen → room M
Repository channel: mobile-app [ongoing code and maintenance discussion]
└── Branch view: recovery-screen → channel M
```
The subtask and branch in S open the same room; likewise for M. The repository
branch listings link to those rooms rather than creating new conversations.
The subtask and branch in S open the same channel; likewise for M. The repository
branch listings link to those channels rather than creating new conversations.
Completing the sign-in project does not end either repository's ongoing work.
## Nested Rooms and Relationships
## Nested Channels and Relationships
Rooms nest to organize work: a project contains task rooms, a task contains
subtask rooms, and a document can have its own room or be a view of an existing
room. A channel canvas is the document view within a room.
Channels nest to organize work: a project contains task channels, a task contains
subtask channels, and a document can have its own channel or be a view of an existing
channel. A canvas is the channel’s document view.
A room has at most one containment parent. The navigation tree is not the entire
relationship model: a task's room can sit under its project while its branch
A channel has at most one containment parent. The navigation tree is not the entire
relationship model: a task's channel can sit under its project while its branch
still belongs to a repository elsewhere. Project-to-repository links and
branch-to-repository links remain available independently of that tree. Multiple
routes to a room all lead to the same conversation.
routes to a channel all lead to the same conversation.
## Access
A room and its object views should feel like one workspace. Someone admitted to
A channel and its object views should feel like one workspace. Someone admitted to
that workspace should be able to read its conversation and the objects presented
as part of it, rather than encountering an arbitrary inaccessible subset. The
same principle applies when presenting nested rooms as a shared project workspace.
same principle applies when presenting nested channels as a shared project workspace.
Reading the work and permission to push, merge, or administer it are distinct
capabilities.
The permissions design must make that experience consistent across linked rooms
The permissions design must make that experience consistent across linked channels
and objects. For repositories, it must choose whether access is governed through
the canonical room relationship or through repository permissions coordinated
with the room. The model does not prescribe a separate, unrelated channel link
the canonical channel relationship or through repository permissions coordinated
with the channel. The model does not prescribe a separate, unrelated channel link
just for Git authorization. The choice of permission authority and inheritance
rules remains an explicit design decision; the required user experience is
coherent access, not disconnected permission islands.
## Backend Specification
Persist room relationships on the channel:
Persist channel relationships on the channel:
- `parent_channel_id`: nullable channel UUID, in the same community, indexed for
child lookup.
- `object_bindings`: a list of typed object references stored as JSONB. A room
- `object_bindings`: a list of typed object references stored as JSONB. A channel
can bind several objects, including a task and its branch.
Bindings reference the object they represent: an issue ID for a task, an
@@ -98,8 +101,8 @@ The relay validates management authority, bounded binding shapes, and an existin
same-community parent. It rejects self-parenting and cycles, including concurrent
moves that would create a cycle.
All clients use the same relationships to resolve an object's canonical room.
Creating another view reuses that room. Repeated creation requests must converge
on the same room rather than create parallel conversations. Conflicting bindings
All clients use the same relationships to resolve an object's canonical channel.
Creating another view reuses that channel. Repeated creation requests must converge
on the same channel rather than create parallel conversations. Conflicting bindings
must be reconciled consistently across clients, not resolved by local discovery
order. The metadata storage does not require a global unique-binding constraint.

22
VISION_PROJECTS.md
View File

@@ -1,6 +1,6 @@
# 🐝 Buzz Projects — A Nostr-Native Forge
> Someone pushes a fix. Buzz creates or reuses the branch’s canonical room, which can already be the task’s room. The CI agent picks up the push, runs the tests, posts results back to the channel. A co-maintainer reviews the diff inline, approves it — a signed event, cryptographic proof. Merge. The workflow runs the integration. Once all work sharing the room is finished, it can archive into a permanent record of why that code exists.
> Someone pushes a fix. Buzz creates or reuses the branch’s canonical channel, which can already be the task’s channel. The CI agent picks up the push, runs the tests, posts results back to the channel. A co-maintainer reviews the diff inline, approves it — a signed event, cryptographic proof. Merge. The workflow runs the integration. Once all work sharing the channel is finished, it can archive into a permanent record of why that code exists.
>
> Bug report to merged patch. One place. One search index. One identity system. The branch channel was the pull request, the CI dashboard, and the discussion thread.
@@ -10,10 +10,10 @@ This document is the software-forge slice of the broader Buzz platform. [VISION.
## The Project Model
The shared room contract is [VISION_ROOMS.md](VISION_ROOMS.md): a project, repo,
task, branch, or document is a facet of a canonical room, not an exclusive channel
type. Several facets may share one conversation. Projects organize time-bound
outcomes across repositories; repository rooms support ongoing code and
The shared channel contract is [VISION_CHANNELS.md](VISION_CHANNELS.md): a project, repo,
task, branch, or document has a home channel, not an exclusive channel
type. Several objects may share one conversation. Projects organize time-bound
outcomes across repositories; repository channels support ongoing code and
maintenance discussion.
A project lives on the relay. `myproject.com` in a browser shows the project home. Click a repo and you're at `repoa.myproject.com` — README rendered, file tree navigable, code syntax-highlighted, clone URL at the top. The same URL serves HTML to a browser and git protocol to `git clone`. Content negotiation. One URL, two audiences.
@@ -84,9 +84,9 @@ The cost is stated plainly: a third-party NIP-34 client sees the member repos in
A feature branch is a conversation.
When you create a branch, Buzz should create or reuse its canonical room. If the branch implements a task in an existing room, task details and the branch diff can be views of that same channel UUID. The branch's patches, review comments, CI results, and merge decision belong to that conversation, not a parallel branch chat. Room nesting preserves the task/subtask structure; a separate branch-to-repository reference preserves code ownership.
When you create a branch, Buzz should create or reuse its canonical channel. If the branch implements a task in an existing channel, task details and the branch diff can be views of that same channel UUID. The branch's patches, review comments, CI results, and merge decision belong to that conversation, not a parallel branch chat. Channel nesting preserves the task/subtask structure; a separate branch-to-repository reference preserves code ownership.
When a branch-only room's work finishes, it can archive as the permanent record of why that code exists. A merge must not automatically archive a shared room whose task or other facets are still active. The example below is the branch-only case.
When a branch-only channel's work finishes, it can archive as the permanent record of why that code exists. A merge must not automatically archive a shared channel whose task or other objects are still active. The example below is the branch-only case.
```
#feat-auth-fix
@@ -134,7 +134,7 @@ Push CI Review Merge
│ │ │ │ Merge to main
│ │ │ │ kind:1631
│ │ │ │
│ │ │ │ Branch-only room archives
│ │ │ │ Branch-only channel archives
```
The approval event is signed by the maintainer's npub. The merge status references the approval. The audit log chains them together. Cryptographic proof of who approved what.
@@ -192,7 +192,7 @@ Every step traced. Every trace a signed event. Change the project CI once and ev
### Issues → Forum + NIP-34
Bug reports and tasks retain their NIP-34 kind:1621 identity. In the target model, task details, forum presentation, and branch work can open the same canonical room; subtasks can have nested rooms. A forum is a view, not a reason to fork the conversation.
Bug reports and tasks retain their NIP-34 kind:1621 identity. In the target model, task details, forum presentation, and branch work can open the same canonical channel; subtasks can have nested channels. A forum is a view, not a reason to fork the conversation.
Threaded comments use NIP-22 kind:1111. Labels, assignees, and milestones are nostr tags. Design discussions and RFCs use the forum's long-form async surface.
@@ -200,8 +200,8 @@ NIP-34 clients can discover and interact with issues. Buzz's forum gives them a
### Docs → Canvases
A channel canvas is the initial document facet of a room. A document may share
its project's or task's room, or have a dedicated nested room; opening the
A canvas is the initial document view in a channel. A document may share
its project's or task's channel, or have a dedicated nested channel; opening the
document should not create a parallel discussion stream.
Living documents, collaboratively editable by humans and agents via MCP tools. Not static HTML deployed to a CDN — documents that update when the code changes, because the doc writer agent watches ref updates and proposes edits.

6
VISION_SOVEREIGN.md
View File

@@ -79,8 +79,8 @@ They read the triage summary, confirm it's real, assign it. Thirty seconds of th
time instead of five minutes.
Someone picks up the bug. They create a branch. Buzz creates or reuses its
canonical room: `#feat-auth-fix`. The task and branch can be views of the same
channel UUID, as defined in [VISION_ROOMS.md](VISION_ROOMS.md). They work there.
canonical channel: `#feat-auth-fix`. The task and branch can be views of the same
channel UUID, as defined in [VISION_CHANNELS.md](VISION_CHANNELS.md). They work there.
They push commits. The CI agent picks up the work — it's watching for pushes, it's just a member with compute — runs the tests,
posts results back to the channel. Green. The patch lands in the channel as a
reviewable diff. A co-maintainer reviews it inline, leaves a comment on line 45,
@@ -88,7 +88,7 @@ approves it. The approval is a signed event — cryptographic proof of who said
and when.
Merge. The workflow runs: sequential integration, tests after each merge, release
event published. A finished branch-only room archives; a shared room stays active
event published. A finished branch-only channel archives; a shared channel stays active
while its other work continues. The conversation is now the permanent record
of why that code exists. Not a chat thread that scrolled away. Not a PR that might
get deleted. The event log, on your relay, in your database. Someone reading that