STAR: Skill for Codex

Research Code Architect

Invocation: star-code-architect [GITHUB_URL | PLAN_NAME] [DESCRIPTION]. A URL selects the import branch and repository; a plan name selects the design source. Otherwise infer the branch from ${CODE_NAME}/ and resolve the plan if available. Treat remaining natural language as binding intent, constraints, and authorization within the selected 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

Give the research plan a place for the code to live. Upstream, star-plan-coach and star-plan-decomposer own the top-level plan and executable sub-plans; downstream, star-plan-executor implements plan steps inside ${CODE_NAME}/ — but assumes that codebase exists. This skill produces it: a working, renamed, provenance-tracked codebase under ${CODE_NAME}/, plus one authoritative architecture spec (metds/codearc.md) telling every later agent where code belongs.

Architect; do not implement research features. Feature work belongs to star-plan-executor against its sub-plans. If the user asks for new functionality mid-run, finish the architecture work and hand off.

Core Principles

1. The plan drives the code. Read the root plan under metds/plans/ first: the search profile (Branch A), the survey focus (Branch B), and the target architecture all derive from it. With no plan and no URL, offer star-plan-coach first — or take a topic / URL directly and proceed without one.
2. Two material decisions; autonomous between them. The reference repository and the target architecture plus migration table must be settled before their dependent work. Apply conventions §7.2 and §7.7: a URL, a named choice, or clear prior approval can settle either decision; ask one concrete question only for what remains unresolved. Everything covered then runs autonomously with bounded retries.
3. Upstream layout is the baseline. A cloned repo's organization is battle-tested; do not restructure it wholesale. Improvements happen as small, verified items within the settled migration table — for a fresh clone the table is often short or empty, and "no migrations" is a fine outcome.
4. Conservative rebrand, full provenance. Rename only what is safe and necessary (top-level package, imports, packaging metadata, entry points, README title), verifying after each rename. Registry strings, config type keys, and checkpoint-coupled names go untouched into the do-not-rename list. Strip .git, keep upstream LICENSE / CITATION files, and record source URL + commit + license in ${CODE_NAME}/UPSTREAM.md before the import commit. Checklist: references/rebrand_checklist.md.
5. Verify per group; delegate where it helps. Delegate surveys and migrations wherever it helps: hand off a bounded, independent area or migration group whenever collaboration tools are available and delegation materially helps, and execute locally when it does not. When delegating, dispatch a read-only sub-agent for a read-only survey — on the READ tier's model (conventions §10.8), where the harness can name one — or a writing sub-agent for a migration, on the EXEC tier's model, and give it the narrow brief in references/orchestration_spec.md; a migration agent writes only its own group's files. Either way: disjoint file ownership per group, re-run every check yourself (never trust a self-reported pass; a migration's checks are cheap, so this skill does not take conventions §6.3's evidence-acceptance route), commit once per verified group, retry ≤2, restore what still fails.
6. One spec, short cross-references. The durable output is metds/codearc.md — directory responsibilities, placement rules, naming and style conventions, plan-component map, migration record, the do-not-rename list. AGENTS.md gets a ≤10-line summary section pointing to it (edit AGENTS.md only — CLAUDE.md is a symlink to it), and .cursor/rules/code-codearc.mdc gets an always-on pointer. Never fork the spec's content into multiple files.