Prepare your first ecosystem task

This tutorial prepares a cross-repository change without modifying package code. You will bootstrap the workspace, record the task locally, identify its owner, inspect repository state, and create an isolated branch destination.

Execution status

Spine CI tests the underlying status and configuration contracts, but it does not clone sibling repositories, create local task contexts, or run this tutorial end to end. Follow it manually in a maintainer workspace and inspect each command's result before continuing.

1. Bootstrap the workspace

HSSMSpine is currently access-controlled. Ask a maintainer for repository access and authenticate with GitHub before cloning it.

Clone Spine and its five core sibling repositories:

git clone https://github.com/lnccbrown/HSSMSpine.git
cd HSSMSpine
./setup.sh

setup.sh uses the nested repos/ layout by default. If your workspace keeps repositories beside Spine, pass --sibling consistently to setup, launchers, and worktree commands.

2. Check the coordination layer

./scripts/doctor.sh
python3 scripts/repo_state.py --include-spine --target main

The doctor reports required tools and optional capabilities. The JSON status report shows the current branch, local changes, upstream divergence, and what a switch to main would remove. Do not change branches until that report is safe.

3. Record the task locally

Create a gitignored task context. The title is only an example:

scripts/set_task_context.sh --new "Trace a simulator contract change"

The generated context keeps goals, a plan, a log, and scratch notes out of the tracked repositories. See Manage task context for selection and cleanup options.

4. Identify the owner

Read the ecosystem map and source-ownership reference. For a simulator output contract, ssm-simulators owns the producer behavior; downstream checks may also be needed in LANfactory, the pipeline, or HSSM. Record those consumers in the task plan before editing.

5. Create an isolated destination

Use a worktree only when you need a second branch without disturbing an existing checkout:

scripts/worktree.sh add ssm-simulators codex/example-contract --new origin/main
scripts/worktree.sh list ssm-simulators

Continue operating from the fully loaded Spine session and treat the printed worktree path as the file destination. The worktree guide explains cleanup and sibling layout.

6. Verify the handoff point

Run the status report again:

python3 scripts/repo_state.py --include-spine --target main

You are ready to implement when the report matches your plan, the owning repository is explicit, and unrelated checkouts are untouched. Next, use the owning repository's contributor documentation for its build and test commands; Spine does not replace package-specific instructions.