Skip to content

Flow-Research/workstream

BranchesTags

Repository files navigation

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, compensation award and fulfillment state, 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, contribution record, conditional compensation award and fulfillment state, and reputation signals.

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
-> FinalAcceptance on Accepted
-> Contribution Record
-> Compensation Award / Fulfillment when payable
-> Reputation projection when separately implemented
-> 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 an active published contribution policy version with explicit accepted_submission and completed_review rules, including explicit unpaid rules where intended
  • every task has acceptance criteria
  • every submission has required artifacts, evidence references, hashes, and contributor attestation
  • every invalid submission packet is blocked before submission creation
  • every submission passes automated checks before human review
  • every valid human decision appends an immutable Review; submitted findings and later resolutions are immutable
  • every revision responds to unresolved blocking feedback without rewriting it
  • every valid human review creates a reviewer contribution
  • every accepted Review creates one immutable FinalAcceptance
  • every submitter accepted_submission contribution consumes FinalAcceptance
  • every payable contribution updates compensation fulfillment; all contributions may feed a separately implemented reputation projection

Workstream turns that operating knowledge into reusable infrastructure.

Planning Package

Review Passes

Templates

Decisions

Authorization Baseline

Workstream verifies externally issued Flow authentication tokens and owns its product authorization. Token role claims, email, display name, skills, reputation, and typed workflow profiles are not product authority. Canonical authority comes from local actor identity links, administrative grants, exact-project contributor grants, registered permissions, resource/lifecycle guards, revocation, and append-only evidence.

All public API documentation uses /api/v1. Imported reference specifications are immutable archival inputs. ADR 0012 and the canonical authorization service specification control authorization; ADR 0016 and the canonical contribution and compensation specification control contribution recognition, award eligibility, and fulfillment boundaries. Older chunk specifications remain implementation history until their owning migrations replace the runtime.

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. It uses Celery with Redis for durable local project setup jobs and automatic pre-review checker gates. MinIO provides the S3-compatible artifact protocol in local development and CI. Start the local services with:

docker compose up -d postgres redis minio

MinIO uses the compose-only static credentials and the private workstream-artifacts bucket. The integration tests create that bucket automatically. For local runtime use, create the private bucket with an S3 client against http://localhost:9000 after MinIO is healthy, using access key workstream-minio and secret key workstream-minio-secret-key, before starting Workstream. Configure the runtime with the exact artifact storage settings. The repository-managed MinIO port is bound to host loopback. A Workstream process running on a separate non-production container network may instead use an operator-controlled private MinIO endpoint; that remains development/test protocol proof and never qualifies as hosted-provider activation evidence. Native AWS S3 accepts workload-identity configuration but remains runtime-ineligible until live deployment proof is approved; startup fails with artifact_provider_live_proof_required before credential probing or provider I/O.

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

Project guide sufficiency, submission artifact policy derivation, and post-submit checker policy derivation run through the OpenAI Agents SDK adapter. Install the backend agent extra and set the model explicitly before running automatic project setup:

cd backend
.venv/bin/pip install -e ".[agents]"
WORKSTREAM_PROJECT_AGENT_OPENAI_AGENT_SDK_MODEL=<approved-model>
WORKSTREAM_PROJECT_AGENT_RUN_TIMEOUT_SECONDS=1800
WORKSTREAM_PROJECT_AGENT_MAX_PROMPT_BYTES=2000000
OPENAI_API_KEY=<runtime-secret>
WORKSTREAM_PROJECT_SETUP_PIPELINE_AUTOSTART=true
WORKSTREAM_CELERY_BROKER_URL=redis://localhost:6379/0

The Celery project setup pipeline uses the OpenAI Agents SDK runtime. The Celery worker environment must include OPENAI_API_KEY and the approved model settings. Persisted sufficiency and derivation agent identity is Workstream-owned; runtime or provider-returned identity fields are not trusted as audit provenance.

Run the Celery worker before creating project guides that should automatically prepare pre-submit policy, continue into post-submit policy derivation after setup submission artifact policy approval, and advance locked submissions through the automatic pre-review checker gate:

cd backend
WORKSTREAM_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream \
WORKSTREAM_AUTH_PROVIDER=flow \
WORKSTREAM_ENVIRONMENT=local \
WORKSTREAM_PROJECT_AGENT_OPENAI_AGENT_SDK_MODEL=<approved-model> \
OPENAI_API_KEY=<runtime-secret> \
WORKSTREAM_PROJECT_SETUP_PIPELINE_AUTOSTART=true \
WORKSTREAM_CELERY_BROKER_URL=redis://localhost:6379/0 \
.venv/bin/celery -A app.workers.celery_app.celery_app worker --loglevel=INFO

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 reviewer contribution for every valid human review
For accept, create FinalAcceptance
Use FinalAcceptance as the sole source of the submitter contribution
Record compensation status only for payable contribution awards
Project reputation only after its separate implementation
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 through review, contribution, conditional compensation, and fulfillment.

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 append one response and later resolution per required prior finding
  • revision context is prepared from the active Project Guide before resubmission; exact stamped identity/activation-sequence match keeps context, and any different valid active pair rebases forward or backward

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

Contribution and compensation:

  • every valid human review creates a reviewer contribution from locked evidence
  • for an accept decision, FinalAcceptance alone sources the submitter contribution
  • only payable contributions create immutable awards and fulfillment tracking; explicit unpaid rules create none
  • compensation fulfillment is 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

About

Source-agnostic task evaluation and contribution infrastructure for verified human-agent work.

Resources

Readme
Activity
Custom properties

Stars

6 stars

Watchers

0 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages