Skip to content

docs: business-first org profile and registry-driven GitHub metadata #47

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

Open
abrichr wants to merge 14 commits into
base: main
Choose a base branch
from
Open

docs: business-first org profile and registry-driven GitHub metadata #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
3e6ebbb
wip: snapshot of interrupted build track
abrichr Oct 9, 2026
ed10629
feat: read the registry's public GitHub metadata and render an apply …
abrichr Oct 9, 2026
f488041
docs: tighten the registry's public copy and point it at the apply sc…
abrichr Oct 9, 2026
98dd966
docs: lead the org profile with what changes for a business team
abrichr Oct 9, 2026
ab79f4a
feat: enforce the registry as the source of truth for GitHub metadata
abrichr Oct 9, 2026
1e7292e
test: cover the metadata parser, the new profile rules, and the apply…
abrichr Oct 9, 2026
b3e27c6
docs: tell owners how to apply, pin, and verify the GitHub settings
abrichr Oct 9, 2026
28fb925
docs: point self-serve readers at hosted plans and drop a negative pa…
abrichr Oct 9, 2026
b946f58
fix: keep the rendered apply script clean under shellcheck
abrichr Oct 9, 2026
d41271a
wip: snapshot of interrupted build track
abrichr Oct 10, 2026
fd0fafa
docs: finish the profile wording for the break-it run and the caveats
abrichr Oct 10, 2026
e9ade65
docs: name every kind of wrong record in the fault test
abrichr Oct 10, 2026
ee4f7d0
docs: withdraw the billing-audit case study from the profile
abrichr Oct 10, 2026
8c5bff9
docs: say nobody has measured an after time, not no customer
abrichr Oct 10, 2026
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
720 changes: 720 additions & 0 deletions .overhaul/APPLY.sh
View file
Open in desktop

Large diffs are not rendered by default.

69 changes: 42 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,48 @@
# OpenAdaptAI Organization Configuration
# OpenAdaptAI organization configuration

This repository owns the public organization profile, lifecycle registry, and
the intended GitHub metadata for the repositories presented as the product. It
does not change GitHub organization settings automatically.
This repository holds the public organization profile, the repository
lifecycle registry, and the GitHub settings that visitors see for each
repository. The profile in [`profile/README.md`](profile/README.md) goes live
when a change merges. The GitHub settings don't: an organization owner applies
them.

The durable cross-repository launch acceptance contract is maintained in
[LAUNCH_PLAN.md](LAUNCH_PLAN.md). Current execution state belongs in the
workspace `STATUS.md`, not in this public repository.

## Manual GitHub Actions

Organization owners should apply these settings after this branch is merged:

1. Set the organization description to the `organization_description` value in
[`repository-lifecycle.yml`](repository-lifecycle.yml).
2. Apply the exact `repository_descriptions` values from that file. They keep
the Desktop, native Capture, and agent-bridge descriptions aligned with the
lifecycle registry.
3. Pin the exact `pinned_repositories` list so visitors see the product
surface: the flagship installer, the Flow engine, Desktop, Capture, Agent,
and evals.
4. The Cloud implementation repository is private and cannot be a public
organization pin. The documentation implementation is a public Support
repository and remains reachable through the docs link instead of occupying
a product pin.
5. Apply the archive queue in
[REPOSITORY_LIFECYCLE.md](REPOSITORY_LIFECYCLE.md) only after each repository
has an archive notice and any dirty local work is preserved.

Organization descriptions, repository descriptions, and pins are GitHub
settings. Editing `profile/README.md` does not change them; an organization
owner must apply the machine-readable values after merge.
## Apply the GitHub settings after a merge

[`repository-lifecycle.yml`](repository-lifecycle.yml) is the source of truth
for the organization description and website, the profile headline, the
pinned repositories, and each listed repository's description, website, and
topics. [`scripts/check_profile.py`](scripts/check_profile.py) checks these
values on every pull request.

An organization owner applies them:

1. Review the exact commands. Run `.overhaul/APPLY.sh`. This dry run prints
each `gh` command and its request body, and it doesn't call GitHub.
2. Apply them. Run `.overhaul/APPLY.sh --apply`. It needs `gh` signed in as an
owner of the organization, with the `admin:org` and `repo` scopes. It
changes nothing if the account isn't an owner. After the changes, it reads
every value back from GitHub and lists each one that differs.
3. Pin the repositories by hand, in the order that `pinned_repositories`
lists them. GitHub has no API for organization pins.
4. Confirm. Run `.overhaul/APPLY.sh --verify`. It exits 0 only when every
value on GitHub matches the registry, and 2 when only the pins are left.

After you edit the registry, render the script again. The profile check fails
until the script matches the registry.

```bash
python3 scripts/github_metadata.py render-apply --output .overhaul/APPLY.sh
```

The Cloud source repository is private, so it can't be a public pin. The
documentation source, `openadapt-ops`, is a public Support repository that the
profile links instead of pinning. Each repository's social preview image is
also set by hand, in that repository's settings.

Apply the archive queue in [REPOSITORY_LIFECYCLE.md](REPOSITORY_LIFECYCLE.md)
only after each repository has an archive notice and any uncommitted local work
is preserved.
22 changes: 13 additions & 9 deletions REPOSITORY_LIFECYCLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# OpenAdapt Repository Lifecycle Registry
# OpenAdapt repository lifecycle registry

Last reviewed: 2026-09-02
Last reviewed: 2026-10-09

This public registry separates the product from experiments and records the
intended lifecycle of organization repositories. It does not authorize moving
Expand All @@ -9,8 +9,12 @@ checkout state and credential-response details belong in private operations
records, not in this public repository.

The machine-readable source is [`repository-lifecycle.yml`](repository-lifecycle.yml).
It also holds each listed repository's public GitHub description, website,
and topics, and the organization pins. Support repositories include the
public [EHR Integration Directory](https://ehrintegrationdirectory.com),
which OpenAdapt publishes.

## Lifecycle Definitions
## Lifecycle definitions

| Status | Meaning |
|--------|---------|
Expand All @@ -26,7 +30,7 @@ The machine-readable source is [`repository-lifecycle.yml`](repository-lifecycle
| **Deprecated** | Superseded; migration fixes only, no new integrations |
| **Archived** | Historical and read-only |

## Production Admission
## Production admission

Production is a derived per-release state. It is not a static repository label.
A person cannot create it by changing a table or repository description. The canonical
Expand Down Expand Up @@ -83,7 +87,7 @@ Static Production membership is forbidden. Consumers derive current Production
at read time from the signed admission, its revocation state, and until-revoked
validity.

## Admission-Gated Targets
## Admission-gated targets

The seven product targets do not have fallback lifecycle labels. A target that
doesn't have a current admission is **not actively admitted**. Expiry,
Expand All @@ -110,19 +114,19 @@ These are the derived states:
| `agent` | **Production** | Local MCP and Agent Skills bridge for governed Flow workflows |
| `docs` | **Production** | `docs.openadapt.ai` deployment sourced from `openadapt-ops` |

## Other Repository Lifecycles
## Other repository lifecycles

| Group | Repositories |
|-------|--------------|
| **Support** | `.github`, `openadapt-web`, `openadapt-ops`, `openadapt-wright`, `openadapt-herald`, `openadapt-crier`, `openadapt-consilium`, `openadapt-telemetry`, `openadapt-viewer`, `openadapt-blog` |
| **Support** | `.github`, `openadapt-web`, `openadapt-ops`, `openadapt-wright`, `openadapt-herald`, `openadapt-crier`, `openadapt-consilium`, `openadapt-telemetry`, `openadapt-viewer`, `openadapt-blog`, `ehr-integration-directory` |
| **Experimental** | `openadapt-privacy`, `openadapt-types`, `openadapt-console`, `openadapt-tray` |
| **Research** | `openadapt-ml`, `openadapt-evals`, `openadapt-retrieval`, `openadapt-grounding`, `openadapt-verifier` |
| **Internal** | `openadapt-bootstrap`, `openadapt-internal`, `openadapt-yc`, `openadapt-presenter` |
| **Labs/forks** | `OmniMCP` (`omnimcp` locally), `SoM`, `PydanticPrompt` |
| **Archived historical directions** | `OpenAdapter`, `OpenReflector` |
| **Superseded** | `OpenSanitizer` (successor: `openadapt-privacy`) |

## Retirement Queue
## Retirement queue

| Repository | Lifecycle | Public action |
|------------|-----------|---------------|
Expand All @@ -136,7 +140,7 @@ Experimental, Research, Labs, and Internal repositories are not deprecated by
default. Moving local checkouts is a separate operational decision that must
use private, current evidence.

## Archive Procedure
## Archive procedure

1. Preserve or intentionally discard every tracked and untracked local change.
2. Confirm the branch is pushed and record the final commit in private
Expand Down
Loading
Loading