WAYS OF WORKING · DEMO 15 NINO CHAVEZ
The harder deliverable
wasn't the build.
Building a working reference implementation of a BigCommerce-native subscriptions capability was the demonstrable part. What a global systems integrator (GSI) actually needs before it can bid on building it for real — a ten-document scoping and estimation package, projected from a 28-epic, 218-story spec corpus — took longer to get right and stayed the harder problem the whole way through.
→ or scroll to advance · ← to go back
02 TEN DOCUMENTS, ONE JOB EACH
Not a spec dump — ten documents, each answering one question
The vendor-facing package, files 01 through 10, projects a 28-epic, 218-story requirements corpus into the shape an estimator actually needs. Every document exists to answer one question a bidder would otherwise have to ask in a discovery call.
Ten capability domains — onboarding, catalog, purchase, billing, orders, self-service, operations, platform, commerce, trust — organize all 28 epics. Every story rolls up to exactly one epic; every epic rolls up to exactly one domain.
03 WHAT MAKES IT BID-READY
A spec dump doesn't have tiers, decision points, or a required format
Effort tiers, where set
Stories carry an indicative relative-size tier — extra-small through large — from internal planning, where one exists. Untiered rows are marked TBD rather than left blank, so a missing tier reads as a grooming gap, not a signal that the story is trivial.
Labeled, not silent — a blank cell would read as an error.
Ten costed decision points
The platform-integration contract surfaces ten gaps between what the platform already provides and what the build still needs. Each one ends in a decision the vendor must answer in its own solution design, with both options costed — never left open for later.
One comparable answer format
Bids return eight required sections — fixed-scope estimate, options pricing, decision-point positions, assumptions and risk registers, a team plan, a knowledge-transfer plan, a delivery timeline — so every vendor's bid reads side by side instead of needing to be reformatted first.
Comparable, not just complete — the format is the point.
Scope is fenced the same way. The initial engagement is fixed against the MVP-tagged stories — roughly 104 of the 218 — with later phases priced as separately exercisable options, not silent inclusions. A bid that redraws any of these boundaries without saying so is treated as non-responsive on that item.
04 PROJECTION, NOT CANON
The package has no facts of its own
Everything in 01–10 derives from a canonical spec corpus that stays the internal source of truth. The package is that corpus's external, architecture-neutral projection — not a second copy someone edits by hand once it exists.
"PRD.md/BRD.md remain the internal source of truth; this package is the external projection — architecture-neutral and swept of internal-sensitive content." the package's own provenance note, docs/gsi-package/README.md
The work-breakdown tables are generated from a derived sizing file, not hand-typed. When the underlying spec changes materially before the package ships, the fix is regenerating the tables and re-stamping every document's source commit — never hand-editing a row. Two sources of truth is how a bid package rots.
05 THE SANITIZATION PIPELINE
Leakage prevention is a lint, not a proofread
Whitelisted at the section level
Only five sections per story ship — the story sentence, acceptance criteria, UX notes, non-functional notes, dependencies. Everything else drops by default, so a new section type in the source is export-safe before anyone remembers to redact it.
Structure can't drift silently
The export expects exactly 218 stories across 28 epics.
Five documented failure modes already forced permanent fixes, not one-off patches: a forbidden-word match inside an unrelated string, a phase label written two ways that would have forked the export's phase vocabulary, a scrubbed link label that left its internal URL intact, a status-qualified section header the whitelist silently dropped, and reference-implementation route paths hiding inside sections that otherwise looked clean.
06 FROZEN, PER VENDOR
Every bidder gets the same package, name-stamped
Per-vendor frozen bundles
One script stages the sanitized export, stamps every document as issued, generates a cover page, and zips one identical, name-stamped copy per vendor — same content, different filename, so no bidder can argue a rival saw a different scope.
A gated preview, always marked draft
A basic-auth-gated web rendering exists for internal review and guided walkthroughs only. Every page carries a draft banner and is excluded from search indexing, and it is never the artifact handed to a bidder — the issued bundle only ever comes from the zip.
The rendered reading set — sidebar navigation, print styling for a PDF, zero external requests, no JavaScript — comes from the same staged files whether it's the gated preview or the delivered zip, so the reading experience can't fork from what actually ships.
07 THE HUMAN GATES
Every document here still says draft, internal review
Agents produced the ten-document package, the sanitization tool, and the bundling script. What they did not do is clear it for release. Every file in 01–10 carries a draft-internal-review status, and a sharing checklist gates anything leaving the repo — none of the following are checked yet.
The point isn't that agents can't be trusted with a bid package — it's where the boundary sits. Agents draft, sanitize, and freeze. A human decides the package is accurate and safe to leave the building. That decision doesn't get automated here.
08 YOUR VERSION OF THIS
Derive the package. Don't author it twice.
If you scope client work
Keep one canonical requirements source and generate every client-facing artifact from it — a bid package, a statement of work, a vendor RFP. The moment someone hand-edits the exported copy, there are two sources of truth and no way to tell which one is right.
If you ship anything to an outside party
Make leakage prevention a lint that runs before the file is written, not a review step someone can skip. A whitelist of what's allowed to ship beats a blacklist of what isn't — new content is unsafe by default until someone deliberately allows it.
If agents are doing the drafting
Write the release checklist before the package exists, and keep every draft labeled as a draft until every box on it is checked. The checklist is what keeps "the agent wrote it" from silently becoming "therefore it shipped."
09 WHAT SHIPPED, WHAT DIDN'T
A working build, and a package that still says draft
The reference implementation runs end-to-end against a live BigCommerce sandbox store — a working system a bidder can be walked through rather than take on faith. The bid package that would let a GSI actually build it for real stayed exactly where the checklist left it: drafted, sanitized, unshipped.