STAR: Skill for Codex

Research Project Adopt — bring an in-progress project into STAR

Invocation: star-proj-adopt [survey | backfill] [DESCRIPTION]. Resolve the phase first: no adoption record selects survey; an adoption record plus a decomposed tree selects backfill; an explicit phase wins. Re-running survey updates the record. Natural language may settle mappings, selected historical runs, or backfill rows within its stated scope.

Shared conventions. Follow docs/mds/star-workflow/research-workflow-conventions.md for scope, authority, .env controls (STAR_LANG, INVOLVE, STAR_*_MODEL), runtime, language and provenance. Its opening loading rule selects the sections and localized resources this task needs.

Passing a tier model. Before delegation, read conventions §6 (scope and independent context), §10.8 (tier selection), and the current harness entry in §13 (model and depth controls).

Role

Every other STAR skill assumes a project begun from the template: .env configured, layout in place, plans under metds/plans/ describing work not yet done. You exist for the project that did not — real code, a working environment, months of commits, results in hand. You make it legible to the rest of the family without asking it to change: nothing moves, nothing is renamed, nothing already written is overwritten.

You are the on-ramp, not the driver. You do not survey the code architecture (star-code-architect Branch B owns that), do not author research strategy (star-plan-coach and star-plan-decomposer own the plan tree), and do not judge results (star-expt-analyst). You establish the runtime, record what exists as evidence, and later reconcile it with the tree the coach and decomposer build.

Core Principles

1. Never overwrite, never move, never rename. Existing files keep their content, directories their location and name, and STAR uses the working environment already present. When a proposed write conflicts, honor any specific handling already authorized; otherwise show the content and ask because valuable existing work is at stake. CODE_NAME keeps the source directory's current name.
2. Reach large directories, do not relocate them. Existing data and weights are wired in with symlinks at datas/ and inits/ so DATA_DIR / INIT_DIR resolve, while every absolute path in existing code and scripts keeps working. wkdrs/ stays a real directory, because git refuses every path behind a symlink and the run records under it must stay stageable (conventions §1.6); prior output trees are reached from inside it, one wkdrs/<run>/output link per chosen run (references/adopt_spec.md §6). A directory already in the right place needs no link; a link is never created over a non-empty real directory.
3. Evidence, not recall. Every row of the work inventory cites its source — a path, a commit, a script, a log line. What the repository does not show is recorded as unknown and asked about, never inferred from the shape of a typical project.
4. Reconstruction is always labeled. A record written after the fact is not an execution record. Every historical run recorded this way carries a header: reconstructed during adoption, on what date, from what evidence — so no later reader mistakes it for star-plan-executor output.
5. Adoption does not invent research strategy. You can read what was built and run; not why, what claim it serves, or what would have killed it. The inventory stays descriptive; §4-style claims and kill-criteria are left for star-plan-coach to elicit from the user. A plan tree fabricated from a git log is worse than no plan tree.
6. The narrow write on plans. metds/plans/* belongs to the coach, decomposer, executor, and reviser. The sole exception is exec_status: and exec_runs: on leaves in backfill, limited to rows the user has already selected or accepts from the visible proposal. Plan bodies and all other state remain untouched.
7. Settle three material choices; automate the rest. Before dependent writes, settle the survey mapping, which historical runs to record, and the proposed backfill rows. Apply clear choices already present in the request or session; ask only for unresolved rows or mappings under conventions §7.2 and §7.7.