As of mid-2026 I hold 14.5k+ stars across public GitHub work - yet cold visitors still bounce on two install paths and zero verify.
Teams treat public code as free distribution. That assumption is wrong: stars are not demand but a receipt for attention you already had, and the cold install is the thing that goes unmeasured.
If you ship without a cold-visitor verify, you lose demand and burn support cost. Why does install path beat star count? Here is the exact breakdown. The checklist is below - one job, one path, one receipt, then stop.
Open the system layers. Keep the operator stack private. Ship each public surface with a closed loop - not a complete company in a monorepo.
By the end you will have
- The OSS Product Ship Checklist to run before every public push
- A README minimum that a stranger can act on in one screen
- A three-surface weekly mix that does not turn into five half-repos
- A cold-visitor scorecard for deciding whether a surface still earns its place
- Rules for what stays private, and when not to open-source at all
The real job of public repos
Public code is a distribution surface, not a side quest.
On my public surface that means agent harnesses, skills, control planes, CLIs - pieces other builders can install without joining the private stack. Graph claim I use in public: 14.5k+ stars across public GitHub work (as of mid-2026). When I need a stricter owned-only cut I say so - I do not hide forks or inflate with silent double-counts.
If a repo does not help a stranger ship faster this week, it is not a launch. It is a backup.
Distribution works when a cold visitor can:
- Understand the problem in one screen
- Install or clone without a sales call
- See one receipt that it works for someone
Skip any of those three and you collect dust, not demand. Stars lag. Install path leads. A 200-star repo with a working one-command install beats a 5K-star museum piece that needs a private Discord to boot.
Why product-sized beats perfect
Product-sized means you ship a thin public surface with a closed loop, not a complete company in a monorepo.
A product-sized OSS drop has:
- one job in the README first paragraph
- one supported path (language, runtime, OS assumptions stated)
- one verification command a stranger can run
- one known failure mode in plain language
- one stop rule so issues do not become a free SaaS queue
Perfect means you wait until every edge case has a policy. That is how private tools never leave the private tree. If the README takes longer than the install path, you are polishing identity instead of shipping a surface.
Three surfaces, one week
A healthy week for a solo operator mixes three surfaces. Not five launches.
1) Single-repo ship. One public surface. One failure it kills. One full GitHub URL. One install command. One receipt.
2) Catalog rotation. Re-pin a proven repo with a one-line update: what changed, what still works, what to ignore. Rotation is distribution when the update is real.
3) System lesson. An agent/ops post that teaches craft without requiring a clone. This keeps OSS posts readable for people not installing that day.
Practical cadence: Mon/Tue ship or ship update; midweek system lesson; Friday rotation only if something earned it. If nothing is ready, skip. Silence beats a dump of five half-repos.
What stays private on purpose
Open-sourcing everything is not transparency. It is a leak of the operator factory.
Keep private: the full multi-agent control plane, credential and wallet routing, internal scorecards and revenue experiments, client-specific harnesses, scripts that turn private receipts into public posts.
Open the installable layer: CLIs, skills, templates, harnesses a stranger can run without inheriting your ops.
Rule of thumb: if a file would let a competitor rebuild your weekly loop without your judgment, it stays private. If a file helps a stranger finish a job this week, it can be public. When unsure, ship thinner first. You can always open more. You cannot un-leak a factory.
A weekly mix that compounds
Stars compound when the public surface keeps showing up next to real work.
- Ship a harness, then write the failure mode it was built to kill
- Quote a user issue only when the fix is already merged
- Link one repo inside an agent lesson, never five
- Prefer full github.com URLs in the body for OSS list posts
Do not create an OSS day. Create a habit: every public surface earns a lesson, and every lesson can point at one surface when the fit is clean. Archive surfaces that fail the cold-visitor test for a full month. A dead repo in the bio is a tax on trust.
Soft conversion (do not overfit)
OSS is distribution, not a funnel hack. Soft conversion stays honest when it follows a real ship post. Offer a checklist or install pack after the surface works. Offer consulting only when the public surface cannot solve the problem alone. Never gate core install behind email.
Magnet: OSS Product Ship Checklist
Name: OSS Product Ship Checklist. Use this before every public push.
Replication tree for a product-sized public surface:
repo/
README.md # job in first 20 lines
INSTALL.md # one path only
scripts/verify.sh # exit 0/1 with expected output
docs/failure.md # one known failure mode
LICENSE
A. Problem (one screen)
- Write the failure in one line (who hits it, what breaks).
- Write the job the repo does in one line.
- Delete any second job from the README hero.
B. Install path
- One primary install or clone path.
- State runtime and OS assumptions.
- One verification command with expected output.
C. Receipt
- One proof artifact (test output, screenshot, star note, or used-in production line).
- One known failure mode and the workaround.
D. Stop rule
- Issue template that routes feature requests away from free support.
- Explicit non-goals so support does not become a second job.
E. Ship post
- One full GitHub URL in the post body.
- One lesson that stands alone if the reader never clones.
If any of A-C fails, do not post. Fix the surface.
You should see: a stranger running your verification command and getting a pass or fail with expected output, without opening an issue to ask what the repo is for.
Copy-paste: README minimum for a public surface
# <name>
<one-sentence job>
## Install
<one path>
## Verify
<one command + expected output>
## Failure it kills
<one line>
## Non-goals
- No multi-product monorepo dump in the first public surface
- No private operator stack, secrets, or client data in the README
- No "coming soon" install path that cannot be verified cold
## LicenseIf you need a second install path on day one, you are already supporting two products.
Copy-paste: what not to open-source this month
- full private operator stacks
- credential graphs and wallet routers
- client deliverables and branded forks of private systems
- half-finished renames that still import private packages
- coming-soon READMEs with no verify step
If it cannot pass the cold-visitor test this week, it is not a public surface yet.
Failure modes I see weekly
The dump. Five links, zero install paths. Fix: one link, one failure line, one verify command.
The second job. You support every issue like a SaaS. Burnout, then silence. Fix: stop rule + non-goals + issue templates.
The leak. Full operator stack for clout. Competitors copy the loop. Fix: public installable layer only.
The museum. Stars rise while install path rots. Fix: monthly cold-visitor test; archive failures.
The vanity total. Double-counting the same repos across orgs, or mixing private forks as if they were public product. Fix: state the full public graph (here: 14.5k+) and say when a stricter owned-only cut applies.
The identity monorepo. One repo tries to be harness, docs, dashboard, and brand site. Fix: split public surfaces by job.
When not to open-source
- Code only works with private credentials or client data
- You cannot write a one-line failure it kills
- You will not answer install issues for even one week
- The real value is the private loop, not the installable layer
- You are shipping for applause instead of distribution
In those cases, write the lesson as a post. Keep the code private until the surface is product-sized.
Measuring whether the surface still earns its place
Once a month, pick one public repo and run the cold-visitor test as a stranger:
- Understand the job in 60 seconds.
- Install without reading monorepo history.
- Verify passes on a clean machine.
- One receipt newer than 30 days.
If two answers are no, fix or archive before you launch anything new. Stars without install path are a trophy case. Install path without a lesson is a black box. You want both.
Worked example: one week, three surfaces
Monday: ship a thin CLI that validates agent config files. Job line: catch broken agent config before the run. One install. One verify. Failure killed: silent misconfig that wastes a full agent session.
Wednesday: system lesson on why config validation belongs outside the model. Mention the CLI once with a full GitHub URL after the lesson stands alone.
Friday: rotate an older harness with one line - verify still passes on clean CI. No new features. Proof of life.
If Monday fails the cold-visitor test, cancel Friday and fix install first. Cadence without quality is still a dump.
The cold-visitor script
Open a private browser profile. Land on the README from the GitHub URL only. Timer: 60 seconds to state the job. Follow only the primary install path. Run verify. Find one receipt younger than 30 days. The minute you get stuck is the product defect. Builders who skip this script ship for themselves. Builders who run it ship for distribution.
Support budget without becoming a helpdesk
Budget 30 minutes twice a week for install issues that include logs. No private free debugging. Feature requests must pass the one-job test. Write the budget in the README. When support exceeds the budget for two weeks, narrow the surface or archive. Do not expand marketing while support is on fire.
Portfolio rules for multiple public surfaces
Keep a one-page catalog: surface, job, install OK, last receipt, status. Cap active public surfaces you will support. For a solo operator, three to five is plenty. When you want a sixth, retire one first. Separate identity repos from product surfaces. Identity can be witty. Product surfaces must be boringly clear.
Pricing, stars, and honesty
Do not sell what the public surface already gives away. If the OSS tool solves the job, the commercial offer should be adjacent: setup, custom harnesses, training, or hosted path - not a paywalled README. Track install success reports, real-use issues, and inbound questions that match consulting. If stars rise while install questions stay zero, you are collecting spectators.
Cold-visitor scorecard
Run this after every public surface change. Score each line 0 or 1. Ship only when the total is 4.
- Failure named in one line at the top of the README.
- One install path that works on a clean machine.
- One verify command with expected output.
- Support budget written (what you will and will not answer).
If the score is under 4, stop adding features. Fix the path first. This scorecard is the OSS Product Ship Checklist in operator form, not a marketing badge.
Support budget template
Write this into the README before the first public link:
Support hours: N per week Channels: issues only / issues + email Out of scope: private operator stack, custom deploys without a paid path Response target: best effort within X business days
If you cannot fill those four lines honestly, the public surface is not ready. Stars without a support budget become inbox debt.
Solo-week release checklist (product-sized, not ceremony)
A solo builder does not need a release train. You need a closed loop that fits one week without turning OSS into a second job.
Monday (decide): pick one surface and one failure it kills. Write both in the README hero. If you cannot name the failure in one line, you are not shipping this week - you are shopping for a theme.
Tuesday (install path): one primary install or clone path. State language, runtime, OS. One verify command with expected output. Delete "also works if..." until the first path is boring.
Wednesday (receipt): one proof artifact a stranger can trust - test output, short demo, or "used on real work" with a date. One known failure mode in plain language. No second product inside the monorepo.
Thursday (stop rule): issue template that routes feature requests. Explicit non-goals. Support budget line (hours and channel). If you cannot fill the budget line, the surface is not public-ready.
Friday (ship post, then stop): one full GitHub URL. One lesson that stands alone if nobody clones. Do not open a second README until the cold-visitor test passes on this surface.
Weekend rule: silence beats a dump of five half-repos. Catalog rotation only if something earned an update (merge that fixes the stated failure, not a star-chase).
This is the product-sized week. Ceremony is optional. The closed loop is not.
Receipt: public template vs private factory
Public Mission Control-style templates and harnesses are meant to be installable without your private ops. That boundary is the whole point of product-sized OSS.
What a stranger should get from a public template:
- clone or install in one path
- a verify command that fails closed when misconfigured
- a skill or AGENTS skeleton they can own
- no requirement to run your crons, wallets, or client pipelines
What stays in the private factory:
- multi-venture control plane wiring
- credential and browser session handling
- revenue experiments and internal scorecards
- scripts that turn private receipts into public posts
If your public README needs a private Discord to boot, you shipped a club, not a product. If your public surface includes the keys to rebuild the weekly operator loop without your judgment, you shipped a leak.
Test the boundary with a cold machine: new clone, no chat history, no your env files. If install fails, the surface is not ready. If install succeeds and still exposes operator secrets, the surface is too thick - cut until the private factory cannot be reconstructed from the public tree.
Field notes you can steal this week
- Pick one public surface and run the cold-visitor test today.
- Write the failure it kills in one line at the top of the README.
- Delete a second install path if you have one.
- Add a verify command with expected output.
- Set a support budget in writing.
- Archive one dead repo that fails the test.
- Ship one post with a single full GitHub URL and one lesson.
- Do not open a second README until the first surface passes.
- Keep the operator stack private even if clout tempts you.
- Revisit stars only after install path works.
Bottom line
Open source is not charity and not a resume.
It is a public product surface for the layers that should compound without you in the loop - mixed into a feed that still teaches agent systems and shipping craft.
Install something real. Rotate the catalog. Keep the operator stack yours.
Your next action: run the OSS Product Ship Checklist against one repo you already published. Write the failure in one line, put a full GitHub URL under it, and ship the post before you open a second README.
If you could instrument one bottleneck this week, which one would you pick first?
Closing operator note
Ship less surface. Ship it product-sized. Measure with cold visitors, not applause. The checklist is the magnet; the weekly habit is the system. Keep the factory private, the install path public, and the claims honest. That is how open source compounds without becoming a second unpaid company.
Get the next field note
I publish practical field notes for builders running agents in production - what shipped, what broke, and the system behind it.
Get the next one free: https://nyk.dev/#newsletter
Free. Unsubscribe anytime.
Join the private NYK alpha channel for early notes and updates: https://t.me/+GJ-FEpzcZrtmMTky
Follow @nykdotdev for the daily build in public.
