Skip to content

Refresh Flow README positioning #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmcte merged 1 commit into from
Jun 1, 2026
Merged

Refresh Flow README positioning #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 43 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,66 @@ Org-level autonomous flow protocol for OMT-Global issues, PRs, worker lanes, and

For the high-level relationship between `flow`, `bootstrap`, `.github`, individual repos, Pheidon, and worker lanes, see [OMT-Global Operating Map](docs/omt-global-operating-map.md).

Use `project.bootstrap.yaml` as the control plane for repo-local scaffolding, GitHub governance, CI policy, and portable Codex profile sync. Plan first, then apply repo, GitHub, and home targets deliberately.
## What Flow Defines

## What The Bootstrap Owns
- A GitHub-visible state machine for issues, pull requests, checks, reviews, labels, and merge readiness.
- Worker lane contracts for Pheidon, Apollo, Daedalus, Ares, Hephaestus, and Hermes.
- Autonomy classes that decide when a worker may observe, patch, repair, or must escalate.
- PR-first queue policy so open review, repair, mergeability, and CI work outrank starting new issues.
- Merge-gate rules for linked issues, validation evidence, approvals, requested changes, checks, and auto-merge.
- Baseline schemas, issue forms, labels, project fields, dashboards, and policy docs that `bootstrap` can project into product repos.

- GitHub governance, issue labels, environments, and optional org defaults
## Repository Map

- Repo-local `AGENTS.md`, `CONTRIBUTING.md`, and pull request template guidance
- Fast PR checks plus heavier extended validation lanes
- SemVer release automation with floating major/minor compatibility tags
- [`FLOW.md`](FLOW.md) - concise protocol and controller loop.
- [`agents/`](agents/) - lane contracts for the named worker roles.
- [`policies/`](policies/) - autonomy, WIP, stall-handling, and merge-gate policy.
- [`schemas/`](schemas/) - issue and PR contract schemas.
- [`github/`](github/) - canonical labels, issue templates, project fields, and PR template inputs.
- [`dashboards/`](dashboards/) - saved query patterns for operational review.
- [`scripts/flow/inspect_repo_flow.py`](scripts/flow/inspect_repo_flow.py) - local inspector for repo flow metadata.
- [`docs/autonomous-flow-platform.md`](docs/autonomous-flow-platform.md) - design rationale and rollout plan.
- [`docs/omt-global-operating-map.md`](docs/omt-global-operating-map.md) - org-level ownership map.

- Portable Codex home profile sync
- Operator docs for onboarding, hosted agents, and follow-up setup
## Controller Loop

## Quickstart
The controller should repeatedly:

```sh
bootstrap plan --manifest ./project.bootstrap.yaml
bootstrap apply repo --manifest ./project.bootstrap.yaml
bootstrap apply github --manifest ./project.bootstrap.yaml
bootstrap apply home --manifest ./project.bootstrap.yaml
bootstrap doctor --manifest ./project.bootstrap.yaml
```
1. Inspect live GitHub issues and pull requests.
2. Normalize each item into one flow state.
3. Choose one next action and one accountable actor.
4. Dispatch a worker only when autonomy policy permits.
5. Validate worker output.
6. Update GitHub-visible state.
7. Arm auto-merge or route approval only when gates are satisfied.

Daily fleet reconciliation should start in plan mode and write a report:
## PR-First Queue Policy

```sh
bootstrap reconcile --workspace-root ~/src --report bootstrap-reconcile.json
```
Open PR clearance has priority over starting new implementation work:

To discover GitHub repos first, add `--org OMT-Global`; repositories without local bootstrapped checkouts are skipped in the report.
1. Merge clean approved green PRs.
2. Refresh or repair dirty, behind, conflicted, or failing PRs.
3. Resolve requested changes.
4. Review PRs needing review.
5. Start new issues only when the PR queue is healthy.

Once the repo allowlist is trusted, run repo file drift through draft PRs:
## Validation

```sh
bootstrap reconcile --workspace-root ~/src --apply-repo --create-pr --report bootstrap-reconcile.json
python -m json.tool schemas/issue-contract.schema.json >/dev/null
python -m json.tool schemas/pr-contract.schema.json >/dev/null
python -m py_compile scripts/flow/inspect_repo_flow.py
```

It also syncs `github.issueLabels` for issue routing, risk, status, and review gates.
Run the repo CI gate before opening a PR:

Confirm branch protection points at the `CI Gate` status and require approval from someone other than the most recent pusher. When GitHub plan limits make auto-merge unavailable for a private repo, use the fallback merge-readiness policy: required checks pass or are intentionally skipped, approvals and conversation resolution are satisfied, no blocking review state remains, and a maintainer performs the merge manually.
```sh
bash scripts/ci/run-fast-checks.sh
Comment thread
jmcte marked this conversation as resolved.
```

## Contributor And PR Guidance
## Bootstrap Relationship

- `CONTRIBUTING.md` is the canonical contributor onboarding and local validation surface.
- `.github/PULL_REQUEST_TEMPLATE.md` is the canonical pull request format for summaries, governing issue links, validation notes, and merge-readiness checks.
- Existing bootstrapped repos can retrofit these surfaces with `bootstrap apply repo --manifest ./project.bootstrap.yaml`; repos with restricted `repo.managedPaths` should include both paths before applying.
`flow` defines the operating protocol. `bootstrap` projects the relevant repo-local pieces into OMT-Global repositories through `project.bootstrap.yaml`, managed templates, labels, workflows, and GitHub policy. Update policy here first, then let bootstrap reconcile downstream repos deliberately.

## Project Identity

Expand All @@ -59,16 +73,3 @@ Confirm branch protection points at the `CI Gate` status and require approval fr
- Visibility: `public`
- Default branch: `main`
- Archetype: `generic-empty`


## Release Standard

This bootstrap uses immutable exact SemVer tags such as `v1.2.3`, then automatically advances the floating compatibility tags `v1.2` and `v1` to the same commit.

Cut patch releases from `release/X.Y` branches when you maintain an older minor line. Cut new minor and major releases from `main`.



## Repository URL

- https://github.com/OMT-Global/flow
Loading