Workstream

Workstream is Flow's task evaluation and contribution infrastructure.

Workstream manages project guides, task queues, submission packets, automated checks, reviewer routing, evaluation sprints, revision loops, contribution records, payment status, and reputation signals.

Workstream is how Flow measures, certifies, and coordinates useful human-agent work.

It is not a workspace and it is not blockchain-first. Operators can work with any local tools, human-agent workflow, or external execution environment. Workstream owns the project guide, task queue, submission packet, automated checks, human review, revision loop, acceptance state, payment ledger, and reputation record.

Workstream is source-agnostic, but v0.1 is manual-first. External origin onboarding, source adapters, automated routing, owner-agent execution workspaces, and on-chain settlement remain later adapters until the internal evaluation loop is proven.

The first 30 days are focused on building serious internal infrastructure that can run real projects end to end:

Project Guide
-> Submission Artifact Policy
-> Pre-Submit Checker Policy
-> Task Queue
-> Task Record
-> Submission Packet
-> Platform Checkers
-> Human Review
-> Needs Revision / Accepted / Rejected
-> Contribution Record
-> Payment Record
-> Reputation Update
-> Lessons Learned

Core Thesis

Different projects speak different domain languages, but serious task evaluation and contribution systems share the same lifecycle:

• every project has a guide
• every project has an approved submission artifact policy
• every task belongs to a project
• every project has a base amount or payment policy
• every task has acceptance criteria
• every submission has required artifacts, evidence references, hashes, and worker attestation
• every invalid submission packet is blocked before submission creation
• every submission passes automated checks before human review
• every review creates a decision
• every revision must close prior feedback
• every accepted task updates payment and reputation

Workstream turns that operating knowledge into reusable infrastructure.

Planning Package

• Codex Agent Loop
• Repository Engineering Policy
• 30-Day Master Plan
• Roadmap Status
• Week 1 Backend Plan
• Week 2 Checker Framework Specification
• Chunk 6 Checker Contract And Records
• Chunk 7 Checker Runner And Registry
• Chunk 8 Submission Artifact And Policy Checkers
• Chunk 9 Pre-Review Gate
• Chunk 10 Checker Trial
• Day-by-Day Execution Plan
• Implementation Backlog
• Product Principles
• Product Brief
• First User Flows
• Architecture Brief PDF
• Architecture Diagrams
• System Architecture
• Data Model
• Lifecycle State Machine
• Checker Framework
• Operator Workflow
• Project Operating Manual
• Queue Policy
• Workspace And Packet Convention
• Reviewer Workflow
• Revision Replay
• Roles And Permissions
• Payment And Reputation
• Risk Register
• Process Pattern Baseline
• Architecture Lockdown
• Glossary

Review Passes

• Process Baseline Operations Review
• Final Product Strategy Review
• Final Architecture Review
• Final Adversarial Review
• Adversarial Quality Review
• Process Pattern Baseline Review
• Review Closure

Templates

• Project Guide Template
• Submission Artifact Policy Template
• Checker Policy Template
• Task Template
• Review Readiness Evidence Template
• Submission Packet Template
• Review Packet Template
• Task Status Template
• Prior Feedback Checklist Template

Decisions

• ADR 0001: Core Scope
• ADR 0002: Database Ledger Before Blockchain Settlement
• ADR 0003: Project Guides Are First-Class
• ADR 0004: v0.1 Implementation Stack Is Locked
• ADR 0005: Postgres Is The Record Database
• ADR 0006: Workstream Verifies External Flow Auth
• ADR 0007: Execution Is Async-First
• ADR 0008: Files Use An Object-Storage Abstraction
• ADR 0009: Review Decisions Are Canonical
• ADR 0010: Revision Context Rebase Is Controlled By Policy
• ADR 0011: Submission Artifact Policy Drives Pre-Submit Intake

Engineering Loop

Workstream is built with a Codex-native zero-trust engineering loop:

Intent
-> Discovery
-> Plan
-> Chunk Map
-> Chunk Contract
-> Implementation
-> Evidence
-> Internal Review
-> PR
-> Human Checkpoint
-> Memory Update
-> Stop

Codex-discoverable skills live in .agents/skills/. Codex custom reviewer agents live in .codex/agents/. Durable engineering memory, policies, chunk contracts, reviews, and status live in .agent-loop/.

This engineering loop is separate from Workstream product state. It governs how the repository is changed; it does not define runtime task or review records.

Local Backend Database

Workstream uses Postgres locally and in CI. Start the local database with:

docker compose up -d postgres

The default local development URL is:

postgresql+asyncpg://workstream:workstream@localhost:5433/workstream

Destructive real API drills use the separate local test database:

postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test

Week 1 API Demo UI

The Week 1 API demo UI lives in demos/week1_api_demo_ui/. It is a temporary walkthrough client for the Week 1 backend APIs, not the canonical Workstream frontend implementation. It calls the real backend over HTTP through the Vite proxy and uses local Flow-style bearer tokens against the backend flow verifier.

Start the backend for the demo:

cd backend
WORKSTREAM_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream \
WORKSTREAM_AUTH_PROVIDER=flow \
WORKSTREAM_ENVIRONMENT=local \
WORKSTREAM_FLOW_AUTH_ISSUER=https://auth.flow.local/demo \
WORKSTREAM_FLOW_AUTH_AUDIENCE=workstream-demo \
WORKSTREAM_FLOW_AUTH_LOCAL_HMAC_SECRET=workstream-demo-local-secret \
WORKSTREAM_ENABLE_DEMO_ROUTES=true \
.venv/bin/alembic upgrade head

WORKSTREAM_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream \
WORKSTREAM_AUTH_PROVIDER=flow \
WORKSTREAM_ENVIRONMENT=local \
WORKSTREAM_FLOW_AUTH_ISSUER=https://auth.flow.local/demo \
WORKSTREAM_FLOW_AUTH_AUDIENCE=workstream-demo \
WORKSTREAM_FLOW_AUTH_LOCAL_HMAC_SECRET=workstream-demo-local-secret \
WORKSTREAM_ENABLE_DEMO_ROUTES=true \
.venv/bin/python -m uvicorn app.main:create_app --factory --host 127.0.0.1 --port 8000

Start the demo UI:

cd demos/week1_api_demo_ui
npm install
npm run dev -- --port 5173

Open:

http://127.0.0.1:5173/

The demo runs the Week 1 path from project guide to locked submission using real API calls. The local demo worker-profile route is guarded by WORKSTREAM_ENABLE_DEMO_ROUTES=true and local/test environments only.

Day-30 Success Standard

By day 30, Workstream runs a real internal task cycle with real people:

Create project guide
Create task
Assign task
Submit packet
Run checks
Review packet
Record review decision: accept, needs_revision, or reject
Create contribution record for accepted work
Record payment status separately for accepted work
Update reputation from review outcome
Review lessons learned

The system is successful only if it prevents weak work from reaching review, preserves evidence, and gives operators a clear path from task intake to accepted paid output.

Operating Standard

Workstream is built as durable operational infrastructure:

Governance:

• project rules live in guides and policies, not chat memory
• guide and policy versions are locked per task so rules do not drift silently
• out-of-band guidance is not enforceable until it becomes a guide, policy, template, or checker contract update

Lifecycle and revision:

• status is a ledger, not a loose label
• revisions replay prior findings one by one
• revision context is prepared before resubmission when guide or policy versions change

Artifacts, evidence, and auditing:

• reviews cite evidence and required changes
• submitted artifacts are immutable and hash-bound to checker runs
• every checker result is stored and auditable

Acceptance and payment:

• accepted work cites evidence before payment exposure is created
• accepted work creates an evidence-backed contribution record before payment or reputation updates
• payments are recorded separately from task acceptance

Checkers, lessons, and gates:

• lessons learned become guide updates or new checkers
• quality gates remain separate: project activation, task screening, and submission quality