story-build - the locked-in Story-Driven Build
Turn any project (an RFP, a requirements doc, or a described idea) into a canonical, Claude-Code-buildable, traceable Basecamp build plan, self-gated so nothing biased or incomplete ships. One project = one config = one command to generate + one to publish.
This skill is unchanged by the project-lifecycle work
A governed front door for project creation now exists as project-lifecycle: one lifecycle
record per project, registered at creation, with stage prerequisites that refuse rather than
warn. It does not replace this skill and does not change what this skill produces.
The split is clean: project-lifecycle owns GOVERNANCE (does this project exist legitimately,
what stage is it in, what is blocking it, who acts next). This skill owns BASECAMP STRUCTURE
(the story-driven to-do list, the AI/Human split, the milestone gates, the 5 Docs & Files). The
Basecamp integration, the 4 publish gates and the assignment model below are untouched.
If you are standing up a delivery project and want it governed, run project-lifecycle
first and then story-build the structure onto it. Student capstones are not governed yet
(P6-T1b, blocked), so nothing changes for them at all.
What to say to run it
Give me the five things below. Everything else has a sane default.
- The project - a requirements doc (attach/point me at it) OR a one-paragraph description.
- Where it lands - a new Basecamp project, or an existing one (default: the Internship project 24865175).
- Who builds it - the intern/operator who owns every build task.
- Who approves, and how - a per-release approver (heavy involvement, a gate per milestone) or a phase-gate approver (4 light-touch exec gates).
- Timeline - default 4 weeks from today.
Optional: a marketing co-assignee (co-assigned on marketing/social/prompt tasks, like Sohail on Social Pilot).
Example: "story-build the attached IPOS doc into the Internship project; Anvi builds, Ram approves every milestone, 4 weeks."
What it produces
One story-driven to-do list per project, with per-release groups (R0 walking skeleton
-> launch). Each story is a to-do carrying Fulfills:REQ-### · Owner agent · Gherkin acceptance · Build (Claude Code) · Vibe · Trust (TBI) · Loop-stop, marked 🤖 [AI]
or 🧑 [Human] (drives the My Day tier split via task_kind) and assigned to the
builder. Plus a MILESTONE APPROVALS group assigned to the approver, and 5 Docs &
Files documents (Requirements, Architecture & Agent Map, Trust/TBI Primer, Build Guide,
Traceability Matrix) deep-linked from every task, so a Claude Code session on another
machine can assess the whole project from Basecamp alone.
The pipeline
The AI Project Architect story-driven pipeline (execution/advisory/deep_plan.py, a
6-stage maker/checker: reqs -> agents -> stories (Gherkin + trust) -> releases -> build guide -> trace gate + RTM + TBI primer). It assumes Claude Code / real code
(React, Node, Express, PostgreSQL, Docker), never no-code tools (Bubble/Retool/Zapier/
Airtable). Run it from the AI Project Architect repo path via PYTHONPATH.
Run it (two commands)
cd .claude/skills/story-build/scripts
# 0. secrets: pull at runtime, never commit, wipe after (see Rails)
ssh root@95.216.199.47 "docker exec ai-project-architect-app-1 printenv OPENAI_API_KEY" > .oaikey
ssh root@95.216.199.47 'docker exec -w /app -e PYTHONPATH=/app ai-project-architect-app-1 \
python3 -c "from execution.products.ops import tokens; tok,_=tokens.get_user_token(\"ali@colaberry.com\"); print(tok)"' > .bctok
# 1. generate (real 6-stage pipeline; ~10 min; run in background for parallel projects)
PYTHONPATH="C:/Users/ali_m/OneDrive/Business/Colaberry Novedea/AI Projects/AI Project Architect & Build Companion" \
python gen_story_plan.py ../story_configs/<slug>.json
# 2. publish (gates first; identity-guards Ali; refuses to publish unless all 4 gates pass)
node publish_story_build.js ../story_configs/<slug>.json
# 2b. scaffolding (REQUIRED - the generated plan never includes these two tasks)
node add_launch_scaffolding.js \
--bucket <bucket> --list <list_id> --builder <builder_id> \
--project "<Project Name>" --domain <slug>-demo.colaberry.dev \
--repo ColaberryIntern/<slug> --due <YYYY-MM-DD>
# 3. wipe secrets
rm -f .oaikey .bctokStep 2b is not optional. The generated plan describes what to build. It never says where the code lives or how it gets in front of anyone, so both get assumed and both get skipped. Audited 2026-08-11 across the four Gov Contracts builds: all four proposal tracks deep-linked a live demo, all four demo domains were dead, and across 171 story tasks there was not one deploy task and not one repo task. One intern sat blocked 28 days on a demo URL nobody had been asked to create; another spent three weeks unable to push because no repo existed and her tooling defaulted to the production platform repo. Both failures were structural, not personal.
Run several projects in parallel by kicking off step 1 for each config in the background, then publishing each as its plan lands.
The 4 generator gates (publish is BLOCKED unless all pass)
- no-code = 0 - no Bubble/Retool/Zapier/Airtable/minimal-code mentions anywhere.
- shape - >= 12 stories AND >= 3 releases.
- trace.ok = true - every
mustcovered, every story cites a real REQ, no thin/orphan. - real code - strong React/Node/PostgreSQL/Docker signal (> 10 hits).
If a gate fails (usually an occasional under-generation), just re-run step 1; do not hand-fix the plan. The pipeline's guards (drop-untraceable, deterministic release-split,
= 12 floor) make failures rare.
The artifact contract: what a story HANDS OVER
A story used to stop at "all acceptance scenarios pass", which is a claim about behaviour with nothing handed over. That single omission is why a story could be ticked and leave nothing behind, and why a board can look finished while nobody can say what exists.
A story may now carry a contract: an array of artifacts it must produce, each with a stable
key, a type, the accepted file types, the path in the builder's repo, and the sentence it will be
judged by. Author it in the config under artifacts.by_story.<story id> (see
story_configs/EXAMPLE.json) or in the generated plan's story itself, where the story's own
block wins.
The vocabulary lives in code, not here. The artifact types, their file types, where
each is handed over, and the sentence each is judged by are declared once, as data, in
backend/src/services/artifacts/storyArtifactTypes.json, with
backend/src/services/artifacts/storyArtifactTypes.ts as its typed door. Read that file; do not
restate the catalog in Markdown. A second copy in prose is how two versions of a type start
disagreeing, and the prose copy is the one with no test behind it.
Gate 5, as of A1: a story with no artifact key cannot be published at all. Not discouraged, impossible. Nothing already on a board is re-validated, so this costs the roughly 200 stories that predate the rule nothing; it only stops a NEW story being published with nothing named to hand over.
- A story with no contract is refused. The refusal prints a paste-ready
by_storyskeleton for exactly the stories that need one. That skeleton cannot validate as pasted: itstypeis aCHOOSE_ONE_OFplaceholder the schema refuses by name. A skeleton that validated on paste would recreate this whole problem one level up, as a declared contract nobody thought about. Story ids come from the generated plan, so contracts are authored after the generator runs. - A story with a malformed contract is refused and nothing is published. The refusal
names the story, the key and the field. An unrecognised field is refused rather than ignored:
the block ends up in a ticket a person is judged against, so a misspelled
repo_pathsthat everything quietly skips would publish a contract that does not say what its author meant. "artifacts": []is refused. Absent is not empty. A story with no contract has not declared one; a story declaring zero artifacts is claiming everything is handed over and handing over nothing.- A contract aimed at a story id the plan does not contain is refused, because it would otherwise be written, never rendered, and never verified.
What the builder sees, as of A1. The contract is rendered into the to-do body: for each
artifact, the key, the name, the type, whether it is handed over in the repo (with the exact
path) or on the platform, the accepted file types, anything it must contain, whether a capture is
owed, the one sentence it will be judged by, and which gate it is owed at. The renderer lives in
scripts/lib/artifactBody.js so it can be tested without running the publisher, and
storyArtifactBody.test.ts holds its field list against the real resolved shape, so a field
added to the contract fails a test until the ticket shows it.
The loop stop changed with it. It used to read "all acceptance scenarios pass" and, worse, was
rendered inside the trust line, so a story with no trust field showed no stop condition at all.
It is now rendered for every story, and where there is a contract it reads "all acceptance
scenarios pass AND every artifact key is present", naming the keys.
The schema has two implementations, one for this publisher
(scripts/lib/artifactContract.js) and one for the platform
(backend/src/services/artifacts/storyArtifactContract.ts), because the publisher is CommonJS
and the platform is TypeScript. They read the same catalog file, so the data cannot diverge,
and contractValidatorParity.test.ts runs both over one fixture corpus and fails by name if the
logic does.
Assignment model
- builder_id - owns every build task (🤖 and 🧑 alike).
- approver_id + approver_mode:
per-release-> one approval gate per release (e.g. Ram on IPOS: 11 milestones).phase-gates-> 4 consolidated gates across the window (e.g. Ali on Social Pilot).
- marketing_co_assignee_id (optional) -> co-assigned on marketing/social/prompt/content tasks (e.g. Sohail on Social Pilot).
Story visuals: the eight rules live in code, not here
Any human/AI visual this skill produces obeys eight standing rules. They are declared once, as
data, in backend/src/services/factory/visual/humanAiVisualRules.ts - id, the rule in one line,
the renderer behaviour that satisfies it, and why it exists. Read that module; do not restate it
here.
This section is a pointer on purpose. Until L10.5 this skill said nothing about visuals at all, so every diagram was drawn from scratch and the rules lived wherever they were last written down. A second copy in Markdown is how two versions of a rule start disagreeing, and the Markdown copy is the one with no test behind it.
What the arrangement guarantees:
HUMAN_AI_VISUAL_RULESis the single source of the rules.visual/__tests__/humanAiFlowSvg.test.tshas one test per rule id, plus a completeness test asserting the declared ids and the tested ids are the same set. A ninth rule added without a test fails the suite.renderHumanAiFlowSvgis what obeys them. Drawing a story visual some other way means the rules are unenforced, so use the renderer or extend it.
The one thing worth repeating, because it is the rule most often broken by accident: every empty state has to say WHICH empty it is. "Not generated" and "generated, found nothing" are different facts, and a blank panel renders them identically.
Rails (non-negotiable)
- Claude Code assumed end to end. If a story ever says "use Airtable/Zapier/Bubble", the generator is misconfigured, not the plan.
- Secrets from prod at runtime only.
.oaikey(advisor OPENAI_API_KEY) and.bctok(Ali BC token) are pulled from the prod container, never stored or committed, and wiped after the run. BC token rotates every 2 weeks. - Identity guard. The publisher fetches
/my/profile.jsonand refuses to write unless the token is Ali (17454835). A degraded token halts instead of writing as someone else. - No em-dashes anywhere in generated content.
- Idempotency. Re-running the publisher creates a NEW list; it does not de-dupe an existing one. To re-publish cleanly, trash the prior list first. (
add_launch_scaffolding.jsis idempotent and safe to re-run.) - Every build ships with a repo and a deploy. Run step 2b. A build with nowhere to push and nothing to show is not a build, and the intern will be the one who eats the delay.
- Bid builds never share a repository with the production platform. One repo per build, under
ColaberryIntern, with the builder granted write on theirs and nothing else.
Known Basecamp targets
| Project | bucket | todoset | vault |
|---|---|---|---|
| Internship (Forward Deployed AI Engineer Accelerator) | 24865175 | 4327600402 | 4327600403 |
| Gov Contracts | 47346103 | 9908475794 | 9908475797 |
People seen so far: Anvi 52639032, Meghana 52489233, Sohail 47335940, Ram 17346350, Ali 17454835.
For anyone else, scan GET /people.json (paginate; ~1800 people, ~60 pages).
Files in this skill
scripts/gen_story_plan.py- config-driven generator (runs the real pipeline).scripts/publish_story_build.js- generalized, gated, identity-guarded publisher (builder + approver-mode + optional marketing co + create-or-existing target).scripts/add_launch_scaffolding.js- required step 2b. Adds the repo task (first release) and the deploy task (Launch release) that the generated plan always omits. Idempotent, identity-guarded,--drysupported.story_configs/EXAMPLE.json- fully annotated config template. Copy per project.MYDAY_SYNC.md- the companion prompt to run in the AI Project Architect repo so a project created on My Day follows this exact process end to end.