Projects — Value Stream Containers

Projects — Value Stream Containers

See also: overview.md | value-streams.md | boards.md | sal.md

---

Component Card

Owner	Sal
MCP	@sector137/mcp-pipeline
Slash	/pipeline
CLI	sector137 pipeline projects
SDK	sdk.pipeline().listProjects()
Status	active

---

TL;DR

• Projects are product-area containers that sit between the universe and the pipeline
• Every issue, release, tag, persona, and API key belongs to a project
• Each project is a value stream with its own pipeline state, release cadence, and stakeholder audience
• A universe with multiple projects has multiple simultaneous value streams
• Projects contribute to U_global proportionally to their velocity — active streams dominate health
• The Workbench is the HUD visor mode where the Captain manages all value streams

---

What Projects Are

Projects sit between the universe and the pipeline. A project is not just a folder — it is a stream with its own physics:

• Its own U_local contributing to U_global
• Its own pipeline state (a project can be FLOWING while another in the same universe is CONSTRAINED)
• Its own release cadence (monthly vs continuous vs quarterly)
• Its own stakeholder audience

A team building a SaaS product might have:

• Core Product — the main application, where most engineering work lives
• Public API — a distinct surface with its own release cadence and stakeholder audience
• Mobile — a separate platform with different physics (different release gate, different QA requirements)
• Infrastructure — a stream that feeds the others but has no customer-visible release

Each of these is a different channel through which value reaches a different audience at a different pace. They share a universe — the same physics, the same crew, the same Observatory — but they are distinct streams.

---

Project-Scoped Resources

Every core resource in the Pipeline is scoped to a project:

Resource	Scoping	Notes
Issues	Every backlog item belongs to a project	Features, bugs, chores, improvements
Releases	Every release belongs to a project	The ship event that closes a sprint and signals stakeholders
Tags	Project-specific labels	Tags are scoped to a project, not the universe — defined in Settings > Tags
Personas	Linked to project-scoped issues	Personas can be connected to specific issues via personaIssues junction
Kano Studies	Research missions run within a project context	Studies are project-scoped
API Keys	Project-scoped API keys	Each key belongs to one project and sees only that project’s data

This scoping is a deliberate architectural choice. A project’s data is its own. API keys see only their project. Tags defined in one project do not leak into another. Each value stream maintains clean boundaries.

---

Multi-Stream Universe Model

A universe with multiple projects has multiple simultaneous value streams. Sal routes incoming work (issues) to the correct stream based on category, assignment, or explicit selection.

UNIVERSE: Acme Inc
|
+-- VALUE STREAM: Core Product
|   +-- Issues: 23 open (12 in active sprint)
|   +-- Releases: v2.4.0 (active), v2.3.x published
|   +-- Pipeline: FLOWING
|
+-- VALUE STREAM: Public API
|   +-- Issues: 8 open (3 in active sprint)
|   +-- Releases: v1.2.0 (draft)
|   +-- Pipeline: CONSTRAINED (rate limit issue blocking release)
|
+-- VALUE STREAM: Mobile
    +-- Issues: 14 open (0 in active sprint)
    +-- Releases: none active
    +-- Pipeline: HALTED (awaiting platform decision)

The universe-level HUD (U_global) aggregates health across all active streams. A CONSTRAINED stream in the API project drags down U_global just like a CONSTRAINED stream in the core product would — because both represent unrealized value delivery.

Value Stream Health

Each project contributes its own health signal to U_global. The contribution weight is proportional to velocity — a project shipping frequently has higher weight than a dormant one. This means the universe’s health is naturally dominated by the streams that are actively delivering value.

When a project goes dormant (no issues resolved, no releases shipped in a cycle), its contribution to U_global gradually diminishes. This is not a penalty — it is an accurate representation of where the crew’s energy is actually flowing.

---

How Projects Relate to Boards and Streams

Projects, boards, and streams serve different organizational functions in the Pipeline:

Layer	What It Is	Relationship
Project	Product-area container — scopes issues, releases, tags, API keys	The value stream boundary; all resources belong to a project
Board	Tactical work track — kanban-able, label-scoped, immutable issue placement	Organizes issues within the universe; boards are universe-level, not project-level
Stream	Strategic throughput channel (IN DESIGN) — multi-board, long-duration	Will contain boards; governs the macro direction when implemented

Projects scope what the resources are. Boards organize how work is tracked. Streams (when they land) will govern where work flows strategically.

The Workbench

The Workbench is the HUD visor mode where the Captain manages all value streams. From the Workbench, the Captain can:

• See all projects (value streams) in the universe
• Create new projects (open a new value stream)
• Navigate into a project to see its pipeline, issues, and releases
• Archive projects that have reached end-of-life

“The Workbench is where you look at the whole portfolio before you pick up a tool. Multiple projects, multiple states, one universe. You can see which streams are flowing and which ones are stuck.” — Sal

---

Blueprint Schema

Projects are configurable in universe.toml via [[projects]] — one entry per project, allowing the Captain to declare the universe’s project topology as a version-controlled artifact.

[[projects]]
project_id = "core"
name = "Core Product"
description = "The main application -- customer-facing features and bug fixes."
active = true
default_report_cadence = "monthly"
start_date = "2026-01-01"
end_date = ""
crew = ["sal", "kael", "wren"]
humans = ["captain"]

[[projects]]
project_id = "api"
name = "Public API"
description = "REST and webhook surface for integrators."
active = true
default_report_cadence = "continuous"
crew = ["sal", "kael"]
humans = ["captain"]

Key fields:

• project_id — stable slug, used for SDK scoping and API key assignment. Immutable after creation.
• default_report_cadence — informational; governs how often Sal generates a status report for the stream. Values: "continuous" | "weekly" | "monthly" | "quarterly" | "".
• start_date / end_date — the operational window. An active stream with no end_date is open-ended. An active stream with a future end_date is time-boxed.
• crew — agent slugs whose Tick cycles include this stream.
• humans — user roles or IDs for notification routing, triage priority, and HUD scoping.

Deploy semantics:

• Existing project (matched by project_id) updates fields
• New project_id inserts a new project linked to the universe
• Project in DB but absent from TOML is not affected (use active = false to archive explicitly)

Status: IN DESIGN — Blueprint [[projects]] deploy is not yet implemented.

---

Implementation Status

Capability	Status
Project CRUD	LIVE
Issues scoped to projects	LIVE
Releases scoped to projects	LIVE
Project-scoped API keys	LIVE
Project-scoped tags	LIVE
Kano studies per project	LIVE
Multi-project universe (Workbench)	LIVE
Per-project pipeline state	LIVE — computed from issue velocity + release cadence
Per-project U_local contribution	PARTIAL — U_global exists; per-project decomposition not yet surfaced
Blueprint [[projects]] deploy	IN DESIGN
Value stream health dashboard	IN DESIGN
Project archival (soft)	PARTIAL — projects can be deleted; soft archive not yet implemented

---

Packages

Package	Description
apps/app	Core system — projects table, project CRUD routes, project-scoped issue/release/tag queries
packages/sdk	TypeScript SDK — project-scoped resources, API key project binding
packages/mcp	MCP server — list_projects, project-scoped issue/release tools