Index of every page on this site: llms.txt
All skills
Run it yourself

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.

  • 8 files
  • 74.2 KB
  • Updated 3 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈156 tokens for metadata: the name and description. ≈3.5k when used: this file. ≈2.4k more on demand in 2 files.

Description uses 7.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈618 characters, or 7.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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)

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 7f168b8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago

README badge

README badge for colaberryintern/colaberryenterprise_ai_leadershipaccelerator/story-build