README narrative refresh: framework story is first-class#207
Merged
Conversation
Codex's product narrative spec (after the framework + examples
rounds closed) called out that the README still read like "a bundle
of useful agent commands" while the product had become a workflow
framework with a working domain stack on top. This PR is the
narrative pass; PR 2 adds the lint locks.
Hero. "Turn your AI coding agent into a local delivery workflow."
The challenge/plan/build sentence ends with the new framework
hook: "Use the default sprint, or build your own workflow stack on
top." Pillar line is now "Plain text skills. Local artifacts. No
Nanostack cloud. No build step." (precise, no "zero dependencies"
overclaim).
Opening context. "Nanostack ships 13 built-in skills, a seven-phase
default sprint, and a framework for adding your own skills or
workflow stacks." Replaces the "13 skills total" line that read as
closed. Still credits gstack and Garry Tan.
What is Nanostack? Three layers — agent + delivery structure +
framework — replace the prose-heavy single block. The seven-phase
table now sits under "The built-in sprint is the default stack:" so
it does not crowd out the framework story.
Choose your path. New table between "right for you" and "Try it
safely first": four reader jobs (new user, shipping with AI,
evaluating safety, building a workflow) each linking to the right
starting point.
Try it safely first. compliance-release added as a fifth row
("teams building a custom workflow stack") with an explicit
"advanced, not a starter app, not a compliance certification" note.
Quick start. Adds the "see the workflow before installing" pointer
to the sandbox examples.
Skill rows.
- /think shifts from "CEO / Founder" personality framing to
"Product discovery": structured brief, guided archetypes, search
privacy modes, --retro, --autopilot.
- /nano-run gains the post-vNext positioning: session-first,
capability-honest, repair-aware, setup artifact.
- /guard tightens to the actual six-tier order (block rules first,
allowlist after) and mentions the Write/Edit symlink-resolving
matcher. No specific rule counts in public copy.
"Right for you" list drops the "and more" tail and names the five
verified adapters explicitly.
Privacy. Adds "/think supports local_only, private, and public
search modes, so sensitive ideas do not require public web search."
Spanish. Hero matches the new English shape (local delivery
workflow + workflow stack hook + new pillar line). Opening drops
"cero dependencias" and matches the "13 built-in skills, seven-phase
default sprint, framework for adding skills or workflow stacks"
opening. Sprint flow corrects /qa-before-/security to the canonical
/review → /security → /qa → /ship order.
Forbidden phrases all gone from public copy:
- "full engineering team"
- "4 commands"
- "under 15 minutes"
- "zero dependencies" / "cero dependencias"
- "Amp", "Cline", "Antigravity"
- "marketplace", "plugin ecosystem"
- "GDPR ready", "SOC2 ready", "compliance certified"
- "on every workflow run"
- "npx create-nanostack install"
- "works in every agent identically"
PR 2 adds the lint lock that prevents these (and the load-bearing
required tokens) from drifting back in.
All 10 suites still green. No skill or harness changed; this PR is
public copy only.
Codex's PR 1 review caught three real items. P1 CI red on the existing readme-public-copy lock. The required- strings list still demanded "13 skills total" and "default sprint uses seven", which the narrative refresh deliberately replaced with "13 built-in skills" and "seven-phase default sprint". Updated the required set to match the new pillars and added "build your own workflow stack" as a third required token (the load-bearing framework hook from the new hero). Stale strings list already blocks "Four commands" / "Antigravity, Amp" / "Zero dependencies" so the regression coverage stays. P2 Spanish example dropped /security and /qa, ending with "Cuatro comandos. Eso no es un copilot." That line directly violated the forbidden-phrase set the rest of the PR cleared. Added /security and /qa to the example walkthrough (mirrors the English flow) and replaced the close with "El loop de delivery completo, no solo generación de código." P2 Spanish sandbox table missing the compliance-release row that landed in English. Added the fifth row + the same advanced/no- starter/no-certification note. Suites green: 83 unit, 100 user-flows, 49 stack contract, 25 think archetypes, 32 examples (sample). All other suites unchanged because nothing structural moved.
12 tasks
garagon
added a commit
that referenced
this pull request
Apr 26, 2026
* README claim locks: lock the new narrative against drift PR 2 of the README narrative refresh round. PR 1 (#207) rewrote the public copy; this PR adds the lint job that prevents the new claims from drifting back to the older wording or accepting the disallowed phrases the spec called out. Spec readme-product-narrative-refresh-2026-04-26 lists the required and forbidden surfaces. The existing readme-public-copy job already tracks an earlier round's claim set; this new readme-narrative-locks job is additive. Five new check groups: 1. Required English tokens. Five-adapter set + opt-in E2E framing must appear by name so the public claim cannot quietly degrade to "and more" or imply always-on coverage: - opt-in E2E workflow - Verified adapters - OpenAI Codex - OpenCode - Gemini CLI 2. Required Spanish form. Either "E2E opt-in" or "workflow E2E opt-in" must appear in README.es.md so the Spanish surface is honest about the runtime harness being workflow_dispatch. 3. Forbidden literal phrases (across both READMEs). Tightens the stale-strings list with phrases that have appeared in drafts: - npx create-nanostack install (specific bad install command) - on every workflow run / every workflow run - 4 commands / Cuatro comandos - zero dependencies / Zero dependencies / cero dependencias / Cero dependencias - marketplace / plugin ecosystem - GDPR ready / SOC2 ready / compliance certified - works in every agent identically - full engineering team 4. Forbidden agent names with bare-word boundary. Spec rejects bare references to Amp, Cline, and Antigravity because Nanostack does not have verified adapters for them today. Word-boundary regex (\bAmp\b, \bCline\b, \bAntigravity\b) so legitimate uses like "amplifier" or "decline" do not trip the lock. 5. Sprint-order arrow check. Any arrow form that places /qa before /security (-> or unicode →) is a regression on the "do not show /qa before /security" rule. Each rule was sabotage-tested locally: drop a required token, inject a forbidden phrase, plant a bare agent name, plant a mis-ordered arrow, drop the Spanish E2E form -- every sabotage fired the corresponding lock, the happy path passes clean. YAML parses. All 10 suites green: 83 unit, 100 user-flows, 30 framework e2e, 51 stack examples e2e, 49 stack contract, 32 examples contract, 25 think archetypes, 32 think, 34 onboarding, 17 delivery matrix. * readme-narrative-locks: full adapter set + case-insensitive sweep Codex's PR 2 review caught two real gaps in the lock surface. P2.1 The required-tokens loop only locked OpenAI Codex, OpenCode, and Gemini CLI by name — Claude Code and Cursor lived under the generic "Verified adapters" header. A future edit could drop them from the public claim and the lint would still pass. Added Claude Code and Cursor as required tokens so the five-adapter set is locked element-wise, not just by header. P2.2 The forbidden-phrase sweep used grep -nF / grep -nE without -i, so trivial case variants like Marketplace, GDPR Ready, Every workflow run, Full engineering team, AMP, Cline, ANTIGRAVITY all slipped through. For a public-narrative lock the casing should not matter; switched both the literal sweep (now grep -niF) and the bare-word agent-name sweep (now grep -niE "\b...\b") to case-insensitive. Spanish forms collapse with -i (cero/Cero, cuatro/Cuatro), so the previous "two entries per Spanish form" duplication is gone. Word-boundary semantics still hold under -i: \bamp\b (case-i) matches "Amp" / "AMP" / "amp" but not "amplifier" / "ramp", because the boundary is at start of "amplifier" / end of "ramp". Sabotage replay (case-flipped): - Marketplace, Plugin Ecosystem, Every workflow run, GDPR Ready, Full engineering team, Zero Dependencies, Cuatro Comandos - bare AMP, CLINE, antigravity - dropping Claude Code or Cursor from the required set All caught. Happy path stays clean on current README.md + README.es.md. 10 suites green; lint.yml parses.
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.
Summary
Narrative pass on the README per Codex's product-narrative spec. The framework + examples rounds (PRs #196-#206) shifted the product surface enough that the README needed a structural rewrite, not a copy patch. PR 1: narrative + minimal lock alignment. PR 2 adds the new claim locks.
What changed
Hero
Adds the framework hook in the second sentence and replaces the vague pillar line. No "zero dependencies" overclaim.
Opening context
Replaces "13 skills total" so the framework story is visible from the first paragraph.
What is Nanostack? — three layers
Build on Nanostack).The seven-phase table now sits under "The built-in sprint is the default stack:" so it does not crowd out the framework.
New section: "Choose your path"
starter-todo, then run/nano-run/thinkor/featureEXTENDING.mdandcompliance-releaseThe biggest UX move: stops forcing every reader through the whole document.
Try it safely first
Adds a fifth row for
compliance-release("teams building a custom workflow stack | license + privacy + release gate | 15-30 min") with an explicit advanced / not-a-starter / not-a-certification note. Spanish table gets the same row and note.Quick start
Adds: "If you want to see the workflow before installing into a real repo, use one of the sandbox examples above."
Skill rows
/thinkshifts from "CEO / Founder" personality framing to "Product discovery": structured brief, guided archetypes, search privacy modes,--retro,--autopilot./nano-rungains the vNext positioning: session-first, capability-honest, repair-aware, setup artifact./guardtightens to the actual six-tier order (block rules first, allowlist after) and mentions the Write/Edit symlink-resolving matcher. No specific rule counts in public copy.Right for you
Drops the "and more" tail and names the five verified adapters explicitly.
Privacy
Adds the
/thinksearch-mode line:local_only,private,public.Spanish
README.es.mdmatches the new English shape: hero rewritten ("Convertí tu agente... flujo de delivery local... usá el sprint por defecto, o construí tu propio workflow stack arriba"); pillar line is "Skills en texto plano. Artefactos locales. Sin Nanostack cloud. Sin paso de build."; opening drops "cero dependencias" and matches "13 skills built-in, sprint default de siete fases, framework para sumar tus propios skills o workflow stacks"; sprint arrow corrected from/qa → /securityto the canonical/security → /qa; example walkthrough now passes through/review → /security → /qa → /ship(was missing/securityand/qa); close replaced from "Cuatro comandos. Eso no es un copilot." to "El loop de delivery completo, no solo generación de código."; sandbox table gains thecompliance-releaserow..github/workflows/lint.yml— minimal touchThe existing
readme-public-copyjob's required-strings list demanded'13 skills total'and'default sprint uses seven', which this PR deliberately replaces. Updated the required set to the new pillars:13 built-in skills,seven-phase default sprint,build your own workflow stack. Stale-strings list (which already blocksFour commands,Antigravity, Amp,Zero dependencies. Zero build step, etc.) untouched.PR 2 of this round adds the new claim locks (forbidden tokens,
opt-in E2Ewording, the five-adapter set, and the matching Spanish surface).Forbidden phrases sweep
All gone from
README.mdandREADME.es.md:PR 2 adds the lint lock that prevents these from drifting back in.
Test plan
/qa → /securityarrow forms remainREADME.mdOut of scope (PR 2 of this round)
opt-in E2E workflow,Verified adapters,OpenAI Codex,OpenCode,Gemini CLI), and a Spanish-surface lock so the EN/ES claim set never drifts.