Rewrite the README for a public audience - #276
Open
NathanTarbert wants to merge 3 commits into
Open
NathanTarbert wants to merge 3 commits into
NathanTarbert wants to merge 3 commits into
Conversation
The repo went public on 2026-09-15 and the README still described a four-app private project. It listed `packages/ai`, `packages/db`, `packages/queue` and `packages/shared` as top-level packages -- they have lived under `packages/outpost/` for some time -- and omitted six of the ten apps, including the worker that runs every job. Closes #119. What it says now, and why: LEADS WITH THE DIFFERENTIATOR. The groundedness gate and the reply-rule linter are the unusual thing in this codebase: a draft naming an API that appears in no retrieved source is suppressed rather than posted, and a draft that breaks a reply rule collapses into a short honest handoff rather than being cleaned up. "Answers only when it can show its work" is the product, so it is the first line rather than a feature bullet. STATES THE STATUS HONESTLY. Six channels still have open go-live sequences, so the README says pre-1.0, in cutover, and links the go-live issues as the authoritative list. Someone cloning this should know which parts run in production and which are built-and-tested, rather than inferring it. SEPARATES WHAT WORKS FROM WHAT IS PLANNED. The "what works today" section covers only shipped behaviour -- the pipeline, the Postgres job queue and its claim semantics, the dashboard surfaces, shadow mode, the syncs. The roadmap is three themes drawn from the roadmap: now/next/later labels rather than a copied issue list, with the two principles behind the ordering: a wrong answer costs more than a slow one, and a feature that reports success without doing anything is worse than one visibly missing. CARRIES THIS WEEK'S CONTRIBUTOR LESSONS. `next build` catches what `pnpm test` does not -- App Router routes may export only HTTP verbs, and a Node built-in reaching a client bundle fails the build while passing every unit test. Three separate pull requests hit exactly that. And fork CI needs maintainer approval, so a pull request showing no checks is waiting on us rather than on its author. Every claim verified rather than asserted: all fourteen referenced paths exist, all nine npm scripts exist, the three roadmap labels exist, and the 2,244 test figure is the measured sum across the ten packages. CLAUDE.md gains the matching guardrails, since the repo being public changes what belongs in an issue or a pull request body: findings carry what and verification rather than a reproduction, an unfixed hole gets a minimal tracking issue with the detail kept elsewhere, and no internal context or infrastructure values.
CLAUDE.md is hand-maintained spec prose carrying a wide trigger/skill reference table -- the same shape as the skill definitions already ignored above it. Prettier pads every cell out to the widest one, so a one-word edit rewrites the whole table and the real change disappears into the diff. It was already unformatted on main, so editing it pulled a pre-existing file into the format check's scope. That check reads whole changed files rather than diff hunks, which is working as intended -- it just means the first person to touch one of the 341 unformatted files inherits it. Applies the precedent set for /.claude/skills/ rather than inventing a second answer for the same file class. Anchored with a leading slash for the reason the /templates/ entry records. Verified with the CI step's own command over this PR's changed files: fails before, passes after. Repo-wide prettier --check is unchanged at 341 files, so nothing that was being checked has stopped being checked.
NathanTarbert
force-pushed
the
docs/readme-for-public-repo
branch
from
September 15, 2026 18:54
867c12a to
38134e5
Compare
…c-repo # Conflicts: # .prettierignore
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README now describes the project as it stands, for the audience that can actually read it. Closes #119.
What was wrong
It described a four-app private project. The structure section listed
packages/ai,packages/db,packages/queueandpackages/sharedas top-level packages — they have lived underpackages/outpost/for some time — and it omitted six of the ten apps, includingapps/worker, which runs every job the platform does.What it says now
It leads with the differentiator. The groundedness gate and the reply-rule linter are the genuinely unusual thing here: a draft naming an API that appears in no retrieved source is suppressed rather than posted, and a draft that breaks a reply rule collapses into a short honest handoff rather than being cleaned up and shipped. Most support bots answer anyway. That is the product, so it is the first line.
It states the status honestly. Six channels still have open go-live sequences, so the banner says pre-1.0, in cutover, and links the go-live issues as the authoritative list. Someone cloning this should be able to tell which parts run in production from which are built-and-tested, without inferring it from issue archaeology.
It separates shipped from planned. "What works today" covers only shipped behaviour — the pipeline, the Postgres job queue and its claim semantics, the dashboard surfaces, shadow mode, the syncs. The roadmap is three themes drawn from the
roadmap: now/next/laterlabels rather than a copied issue list, with the two principles behind the ordering stated: a wrong answer costs more than a slow one, and a feature that reports success without doing anything is worse than one visibly missing.It carries this week's contributor lessons.
next buildcatches whatpnpm testdoes not — App Router routes may export only HTTP verbs, and a Node built-in reaching a client bundle fails the build while passing every unit test. Three separate pull requests hit exactly that this week. And fork CI needs maintainer approval, so a pull request showing no checks is waiting on us rather than on its author. Both are in the contributing section now.Verified rather than asserted
CLAUDE.md
Included here because it is the same change: the repo being public alters what belongs in an issue or a PR body. Findings carry what and verification rather than a reproduction; an unfixed hole gets a minimal tracking issue with the detail kept off the public thread; no internal context, infrastructure values, or references to private threads.
Not included
Nothing else from the working tree — this is two files by path, so the in-flight corpus work is untouched.