software-factory-bootstrap

Software Factory Bootstrap

Use this skill when the current issue has issueType: bootstrap. Your job is to read the brief, create project artifacts, and set up the issue backlog for the implementation phase.

Two modes: greenfield vs adjust

The bootstrap issue's description tells you which mode you're in:

• Greenfield (no source card) — build new cards from scratch. Create Project / IssueTracker / Knowledge Articles, then one feature Issue per entry-point card. This is the default; the rest of this skill describes it.
• Adjust (the brief carries a sourceCardUrl, surfaced in the bootstrap issue as "Source card to adjust:") — seed the target realm with a working copy of an existing card, confirm it's green, then create adjustment Issues that describe deltas to it. See "Adjust flow" below.

Everything from the implementation loop onward (scheduling, the validators, status transitions, project completion) is identical for both modes — adjust is a superset, not a fork. The only differences are the seed-from-source sub-phase below and that adjust emits adjustment Issues instead of feature Issues.

Adjust flow (when a source card is present)

Do this in addition to the standard Project / IssueTracker / Knowledge Article artifacts (steps still apply), and instead of creating feature Issues per entry-point card.

1. Seed the source card + its same-realm dependency graph. From inside the workspace dir, run the dedicated ingestion command (read-only from the source realm — it doesn't write to it):

   boxel realm ingest-card "<source-card-url>" .
   

   It copies, preserving realm-relative paths: the source card's module, every same-realm module it imports transitively (including type-only imports, which a runtime dep graph would miss but boxel parse needs), its sample instances, and its card-level Catalog Spec. Cross-realm imports (@cardstack/base/...) and component/function Specs are left out on purpose. Pass --realm <url> only if the source realm can't be auto-detected.
   • If the source card has no co-located test — common for catalog cards, which rarely ship .test.gts — write characterization tests that capture its current behavior: field defaults, computed-field outputs (e.g. a displayName / valueChange), and the key rendered output of its formats. These establish the green baseline; they are what the adjustment must not regress. Without them there is nothing to protect and run_tests (which fails on zero tests) can never go green.
2. Confirm a green baseline. Run run_parse, run_evaluate, run_instantiate, and run_tests against the seeded copy. They must all pass before you create any adjustment Issue — run_tests relies on the co-located or characterization tests from step 1; a zero-test run counts as failed. A red parse/eval/instantiate baseline usually means the copy is incomplete (a missed same-realm dependency) — copy the missing file and re-run. If you cannot get green, request_clarification rather than proceeding.
3. Write a source-provenance Knowledge Article (Knowledge Articles/<slug>-source-provenance.json, articleType per the schema): the sourceCardUrl, the list of files copied, and the baseline validator results. This is what later issues read to understand what the seed was.
4. Create adjustment Issues — one per coherent delta the brief describes (not one-per-entry-point-card; that's the greenfield rule). Use issueType: "adjustment" (confirm the enum via get_card_schema). Each adjustment Issue's description (immutable after creation) must name:
   • the workspace-relative target file(s) to edit — the seeded card and any support files the delta touches (they already exist in the workspace);
   • the delta — what changes, phrased as a diff against the seeded baseline, not a from-scratch card spec;
   • acceptance — the new expected behavior and its test assertions, plus the standing requirement that the pre-existing baseline tests keep passing (the delta must not regress the green baseline).