---
name: story-build
description: Turn any project (a requirements doc or a one-paragraph idea) into a canonical, Claude-Code-buildable, gated Basecamp build plan - a single story-driven to-do list with a 🤖 AI / 🧑 Human task split, an assigned builder, milestone approval gates for an approver, and 5 linked Docs & Files. Invoke when Ali says "story-build this", "run the story-driven build", "turn this doc into a project", hands over a build requirements document, or wants a project made assignable to an intern in Basecamp. This is the same process that produced Detroit, VA ERP, Selective Service, Fairfax, Social Pilot AI, and IPOS.
title: story-build
canonical_url: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build
last_updated: 2026-11-18T12:03:55.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [MYDAY_SYNC.md](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/MYDAY_SYNC.md), [scripts/add_launch_scaffolding.js](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/scripts/add_launch_scaffolding.js), [scripts/gen_story_plan.py](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/scripts/gen_story_plan.py), [scripts/lib/artifactBody.js](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/scripts/lib/artifactBody.js), [scripts/lib/artifactContract.js](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/scripts/lib/artifactContract.js), [scripts/publish_story_build.js](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/scripts/publish_story_build.js), [story_configs/EXAMPLE.json](https://skilld.dev/api/skills-raw/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build/story_configs/EXAMPLE.json).
>
> If the user asked to install this Skill, run `npx skilld install colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/story-build`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/story-build`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/story-build --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/story-build --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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.

1. **The project** - a requirements doc (attach/point me at it) OR a one-paragraph description.
2. **Where it lands** - a new Basecamp project, or an existing one (default: the Internship project 24865175).
3. **Who builds it** - the intern/operator who owns every build task.
4. **Who approves, and how** - a per-release approver (heavy involvement, a gate per milestone) or a phase-gate approver (4 light-touch exec gates).
5. **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)

```bash
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 .bctok
```

**Step 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)

1. **no-code = 0** - no Bubble/Retool/Zapier/Airtable/minimal-code mentions anywhere.
2. **shape** - >= 12 stories AND >= 3 releases.
3. **trace.ok = true** - every `must` covered, every story cites a real REQ, no thin/orphan.
4. **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_story` skeleton
  for exactly the stories that need one. That skeleton **cannot validate as pasted**: its `type`
  is a `CHOOSE_ONE_OF` placeholder 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_paths` that
  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_RULES` is the single source of the rules.
- `visual/__tests__/humanAiFlowSvg.test.ts` has 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.
- `renderHumanAiFlowSvg` is 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.json` and 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.js` *is* 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, `--dry` supported.
- `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.
