Skip to content
BranchesTags

Repository files navigation

STAR project icon

STAR

Systematic Toolchain for AI Research

A reusable foundation for reproducible and well-structured AI research.

Documentation site

Language: English | 简体中文

STAR is the working infrastructure for one AI research project, covering the whole chain: settle a topic, read the related work, write the idea down as a plan, set up the code and the environment, split that plan into sub-problems each of which can be checked on its own, run the experiments, judge what came back, take that judgment back to the plan, see at any point where the whole thing stands, and compile the finished plans into paper-ready method documents. It leaves a traceable experiment record — for each run, the question it was meant to answer, the sub-problems it depends on, the command and configuration that produced the numbers, the criteria those numbers were judged against, and the decision taken as a result. Researchers and AI coding agents work from one shared set of instructions, and because that record lives in project files rather than a chat window, the work resumes in the next session and can be audited long afterwards.

STAR is intentionally framework-agnostic: the research workflow defines only the process, file locations, and validation records, so you can still bring your own model stack, dependency manager, and experiment tracker.

When the research is ready to be written up, STAGE (Systematic Toolchain for Authoring, Guiding, and Editing, documentation site) is the writing-side companion: STAR produces the method documents, results, and digests; STAGE imports them as read-only, fingerprinted evidence and writes the paper on top, so every number in the manuscript traces back to the run that produced it. The pairing is optional — STAR does not depend on it.

Contents

STAR · STAGE · STORY

The three projects cover successive scales of a researcher's work. Use any one independently, or connect them through fingerprinted evidence.

Project Scope Links
STAR — Systematic Toolchain for AI Research Runs one research project from idea through reproducible experiments and paper-ready evidence. Current project · Website · GitHub
STAGE — Systematic Toolchain for Authoring, Guiding, and Editing Turns one research contribution into a traceable paper, review cycle, and submission package. Website · GitHub
STORY — Systematic Toolchain for Organizing Research over Years Shapes graduate research into a defensible master's thesis or doctoral dissertation, defense, and deposit. Website · GitHub

What STAR provides

  • A consistent project layout for code, data, weights, outputs, and research notes.
  • A runtime that travels with the project: machine-specific paths live in a local .env file rather than in scripts.
  • A single experiment entrypoint through execs/run.sh.
  • One skill per step of the research — fifteen of them: thirteen in the order the research goes, and two you can reach for at any moment.
  • A research process you can retrace and resume: plans under metds/plans/, each plan's execution intermediates under tasks/, and what a run generated under wkdrs/ — so picking the work back up reads files rather than chat history.
  • A memory the project owns: what a session learns that no plan or report holds — an environment quirk, a standing preference, a dead end — is recorded under .star/memory/ and put in front of the next session by a hook, in whichever harness you drive STAR with.
  • AI-friendly project guidance and research workflows shared across Codex, Claude, DSH, Kimi Code, Cursor, Pi, and Qwen Code, with support for both English and Chinese.
  • Evidence-bound natural prose in replies, plans, literature notes, digests, method documents, and release README files: formulaic patterns are revised without changing facts, citations, numbers, uncertainty, or negative results.
  • What is too big or too local to commit stays out of Git: local data, weights, outputs, and environment settings are excluded from version control.

See Research workflow for the fifteen skills grouped by research stage — what each is responsible for, what it writes, and how to invoke it in your harness. The Research Workflow Skills Guide adds a worked end-to-end example, the generated files, and troubleshooting. The human-writing guide defines the shared prose standard and its evidence-preservation boundary.

Project structure

STAR/
├── code/                   # Core project source code (configured by CODE_NAME)
├── docs/                   # Project documentation site
│   ├── index.html          # Documentation entrypoint for GitHub Pages
│   ├── htmls/              # HTML documentation pages
│   ├── mds/                # Markdown documentation grouped by topic
│   └── srcs/               # Documentation images and other static assets
├── datas/                  # Datasets and data-related files
├── inits/                  # Model weights, checkpoints, and initialization files
├── tasks/                  # Plan-specific execution-process intermediate files
├── wkdrs/                  # Generated outputs and run-specific artifacts
├── metds/
│   ├── ideas/              # Idea-storm topic explorations and finalized topic statements
│   ├── plans/              # Research plans and executable sub-plans
│   ├── refs/               # Related-work analyses and the verified reference.bib
│   └── overview.md …       # Method documents compiled from the plans
├── execs/
│   ├── run.sh              # Main experiment launcher
│   ├── update.sh           # Sync upstream STAR skills and workflow guides
│   └── scpts/              # Experiment-specific shell scripts
├── .agents/skills/         # Research workflow skills for any agent that follows AGENTS.md
├── .claude/skills/         # Research workflow skills for Claude
├── .cursor/skills/         # Research workflow skills for Cursor
├── .dsh/skills/            # Research workflow skills for DeepSeek Harness
├── .dsh/commands/star/     # DSH's repo-local /star and /star-auto command package
├── .kimi-code/skills/      # Research workflow skills for Kimi Code
├── .kimi-code/plugins/     # Kimi Code's repo-local /star and /star-auto plugin and marketplace
├── .pi/skills/             # Research workflow skills for Pi
├── .qwen/skills/           # Research workflow skills for Qwen Code
├── .codex/skills/          # Codex's per-skill manifests, linked from .agents/skills/
├── .codex/plugins/         # Codex's $star / $star-auto plugin and canonical marketplace
├── .claude/hooks/          # Hooks for Claude: model-id provenance, project memory, involve gate
├── .codex/hooks/           # Hooks for Codex: model-id provenance, project memory, involve gate
├── .cursor/hooks/          # Session hooks for Cursor
├── .dsh/hooks/             # Session hooks for DSH, listed in .dsh/hooks.json (see Per-harness setup)
├── .kimi-code/hooks/       # Session hooks for Kimi Code (see Per-harness setup)
├── .pi/extensions/         # Pi extensions: STAR's session hooks, plus sub-agents, plan mode, questions
├── .qwen/hooks/            # Hooks for Qwen Code: model-id provenance, project memory, involve gate
├── .star/memory/           # Project memory: what earlier sessions learned (local/ is git-ignored)
├── .agents/commands/       # Shared /star router and /star-auto procedure, read by each harness-owned command
├── .agents/plugins/        # Codex marketplace discovery: one file link into .codex/plugins/
├── .claude/commands/       # Claude Code slash commands: /star to route a request, /star-auto to pursue a goal
├── .cursor/commands/       # The same /star and /star-auto commands for Cursor
├── .qwen/commands/         # The same /star and /star-auto commands for Qwen Code
├── .cursor/rules/          # Always-on project rules for Cursor
├── .claude/agents/         # Claude Code's named tier delegates: star-plan, star-exec, star-read
├── .cursor/agents/         # Cursor's named tier agents: star-plan, star-exec, star-read
├── .qwen/agents/           # Qwen Code's named tier agents: star-plan, star-exec, star-read
├── .pi/agents/             # Roster star_subagent dispatches to: collector, implementer, auditor, runner
├── .pi/prompts/            # Pi slash commands: /star-<name> per skill, /star to route, /star-auto to pursue a goal
├── .pi/settings.json       # Pi project settings: keeps skill discovery off .agents/skills
├── .pi/APPEND_SYSTEM.md    # Always-on project rule for Pi: which skill root to follow
├── .vscode/                # Editor and debugging defaults
├── .github/                # STAR's own maintainer CI; delete it in your project
├── .env.example            # Portable environment configuration example
├── AGENTS.md               # Shared instructions for AI coding agents
├── CLAUDE.md               # Symlink to AGENTS.md, so Claude Code loads the same rules
└── README.md

The abbreviated directory names are deliberate:

Directory Meaning Contents
datas/ Data Raw, processed, or generated datasets
inits/ Initializations Pretrained weights and checkpoints
metds/ Methodologies Research plans, design notes, and methodology records
execs/ Executions Launchers and experiment scripts
scpts/ Scripts Individual runnable experiment definitions
tasks/ Tasks Each plan's own tool scripts plus the intermediate files produced while executing it, grouped by plan name
wkdrs/ Work directories Run logs, metrics, predictions, and other generated outputs
mds/ Markdowns Markdown documentation, grouped by topic
htmls/ HTMLs Rendered HTML documentation pages
srcs/ Static sources Images and other static assets the docs embed

For example, executing metds/plans/00_demo_plan.md creates tasks/00_demo/, holding the plan's own tool scripts — a verification or indexing script its done-criterion runs — and its intermediate execution files. Generated experiment artifacts still go to the applicable wkdrs/<run-name>/ directory.

Quick start

1. Start a project with STAR

Use this repository as a GitHub template, or clone/copy it into a new project:

git clone https://github.com/wanghao9610/STAR
cd STAR
rm -rf .git
rm -rf .github        # Upstream maintainer CI; it checks STAR's own skill mirrors.
cd ..
mv STAR YOUR_PROJ_NAME
cd YOUR_PROJ_NAME
mv code YOUR_CODE_NAME  # Or copy or clone your existing codebase into YOUR_CODE_NAME.
git init
git add .
git commit -m "First commit."

.github/ holds the generator that writes six harness skill trees from the neutral authored source in .agents/skills/, and the consistency check that keeps all seven roots in step — for maintaining STAR itself, not your project. Harness-only behavior is recorded in that tree's adapter rules or anchored overrides. Left in place, the checks run on every push to your main and fail the first time you edit a generated tree directly, edit AGENTS.md without its mirror, or delete a harness directory you do not use. The adopt path in step 1b never installs .github/.

If YOUR_CODE_NAME/ was cloned from another Git repository and its files belong directly in this project, remove its nested Git metadata with rm -rf YOUR_CODE_NAME/.git before git add ..

1b. Or adopt a project that already exists

If the project is already underway — real code, a working environment, months of commits, results already in hand — install the skeleton into it instead of moving it into STAR. Run this at the root of that repository:

curl -fsSL https://raw.githubusercontent.com/wanghao9610/STAR/main/execs/update.sh -o /tmp/star-update.sh
bash /tmp/star-update.sh --adopt

Nothing already there is overwritten: every existing file is left alone and reported. Add --harnesses claude — or any comma-separated set of claude, codex, cursor, dsh, kimi, pi and qwen — to install only the trees for the agents you use; without it all seven arrive. Then run /star-proj-adopt inside that repository. It surveys the layout and writes .env, reaches your existing data, weights, and output trees by symlink rather than moving them, wraps your existing launch commands, and records what is already built and run. Steps 2–4 below then apply unchanged.

2. Configure the local runtime

Prerequisites. STAR needs git and bash; execs/update.sh also needs curl. The session hooks parse their JSON payload with jq, falling back to python3, then to grep / sed, so a machine with neither parser still gets project memory, the commit guard, and a model id. DSH also needs zstd for model-id recovery (see Per-harness setup (optional)); installing its repo-local /star router through dsh plugin needs pnpm on PATH.

Copy the example environment file:

cp .env.example .env

Then edit .env:

CODE_NAME=YOUR_CODE_NAME
ENV_NAME=your-env
CONDA_HOME=/path/to/conda
PYTHON_HOME=/path/to/conda/envs/your-env
  • CODE_NAME is the source directory relative to the project root.
  • PYTHON_HOME selects the runtime: either the environment directory or its Python executable.
  • CONDA_HOME is the root of the local Conda installation, ENV_NAME the environment name inside it.

PYTHON_HOME is authoritative, so there are two ways to configure the runtime:

  • Set PYTHON_HOME. It is used as given, and CONDA_HOME / ENV_NAME may be left empty. Without CONDA_HOME, the interpreter runs directly instead of through conda activate — this is also how a plain .venv is used.
  • Leave PYTHON_HOME empty and set both CONDA_HOME and ENV_NAME. PYTHON_HOME is then derived as $CONDA_HOME/envs/$ENV_NAME.

Setting neither is an error.

Optionally, add INVOLVE=low|medium|high to set how much the STAR skills ask before deciding. At low a skill takes the recommended option on judgment calls and logs that it did, and in Claude Code, Codex and Qwen Code the permission prompt before each file edit is skipped — Cursor, DSH, Kimi Code and Pi have no such prompt for the level to answer, so there it governs only what the skills themselves ask; medium (the default) asks as documented; high confirms each step. Mandatory confirmation points — the STOP line, every deletion and every overwrite, and any ambiguity about what you meant — are asked at every level; the commit offer is a judgment call, so low takes it unasked and names every commit it made. For a single run, add the same token when you call a skill: star-plan-executor 00 involve=low, behind your harness's prefix — in Claude Code that token reaches the permission prompts too, since the hooks read it off the session's most recent STAR command and it holds until the next one; elsewhere the prompts follow .env alone. Full rule: research workflow conventions §7.7.

star-auto <goal> involve=low adds one explicit, invocation-scoped grant for unattended implementation. It accepts the executor's recommended plan, creates the recommended execution branch or worktree, stages named paths and commits verified actions, applies non-deleting mechanical review fixes, and performs a clean reviewed squash merge without asking for per-operation authorization. A worktree is removed only after its durable artifacts have moved out and its porcelain status is empty; the squash-merged branch is retained rather than force-deleted. Ambiguous targets, plan divergence, dirty trees, merge conflicts, deletion, overwrite, forced Git, history rewriting, push, and discarding unmerged work still stop. Calling star-plan-executor … involve=low directly does not receive this wider grant.

A second optional key, STAR_LANG=en|zh, fixes one language for both the agents' replies and newly generated workflow documents (plans, reports). Left unset, both follow the conversation's language. An explicit request in the conversation wins either way, and existing documents keep the language declared in their frontmatter. Full rule: research workflow conventions §7.6.

A third, STAR_REPOSITORY, names the repository execs/update.sh pulls later skill and workflow guide releases from; change it only to update from a fork. See Updating STAR skills and workflow guides.

A fourth, STAR_HARNESSES, names the agent harness trees that same updater installs and keeps current. Same section as STAR_REPOSITORY above.

STAR_PLAN_MODEL, STAR_EXEC_MODEL and STAR_READ_MODEL select models for research judgment, implementation and production, and read-only work. Each accepts one model name or comma-separated <harness>:<model> entries using the STAR_HARNESSES tags. A run uses its tagged entry, then an untagged fallback; with neither, it keeps the harness default. An optional @<depth> (low, medium, high, xhigh, max, or a positive integer) requests thinking depth where supported.

After editing these keys, run bash execs/configure.sh and reload sessions whose static definitions changed. For Kimi pool registration, use bash execs/configure.sh --kimi-pool. See harness adapters for dispatch mechanics and workflow conventions §10.8 for tier selection and run relocation.

The local .env file is ignored by Git, so machine-specific paths are not committed.

3. Add an experiment

Put reusable project code under the directory named by CODE_NAME, then add an experiment script under execs/scpts/. For example:

#!/usr/bin/env bash
set -euo pipefail

RUN_DIR="${WORK_DIR}/baseline"
mkdir -p "${RUN_DIR}"

python "${CODE_DIR}/train.py" \
    --data-dir "${DATA_DIR}" \
    --output-dir "${RUN_DIR}" \
    "$@"

The launcher resolves the interpreter from .env — activating Conda when CONDA_HOME is set, otherwise using PYTHON_HOME directly — and exports these paths for experiment scripts:

ROOT_DIR  CODE_DIR  DATA_DIR  INIT_DIR WORK_DIR  SCPT_DIR

4. Run it

# Show available experiment scripts
bash execs/run.sh --list

# Run the default experiment: execs/scpts/00_exp.sh
bash execs/run.sh

# Run a named experiment and forward additional arguments
bash execs/run.sh 00_exp --config config.yaml

The stock 00_exp.sh runs no science. It prints the interpreter the launcher resolved and the six exported paths, so a fresh checkout has one command that visibly succeeds and confirms .env is wired correctly. Run names and output directories should distinguish tasks, experiments, or repetitions, and generated artifacts belong under wkdrs/<run-name>/.

5. Start the research workflow

The skeleton above stands on its own — the layout, .env, and execs/run.sh are useful without any of the skills. To pick up the workflow, start at whichever of these describes you, using your harness's prefix from Research workflow:

Where you are Start with
An interest, but no defined topic yet star-idea-storm <your interest>
A topic in hand, ready to plan star-plan-coach <your topic>
A project you just adopted with step 1b star-proj-adopt
Returning to a project already under way star-flow-status

star-flow-status is the one to remember: it reads the plan tree and the reports on disk and names the single next action.

Research workflow

STAR ships fifteen skills covering the way from a vague interest to a written-up method: thirteen at a definite point in that sequence, two runnable at any time. They are listed below by stage — each stage opens with what it corresponds to in the research, then names its skills and what each one writes.

How to invoke them. The skill tables below name each skill without a prefix; the prefix is your harness's, and each harness spells it its own way:

Tool Invocation Example
Codex $star-<name> $star-plan-coach open-vocabulary detection
Claude Code /star-<name> /star-plan-coach open-vocabulary detection
Cursor /star-<name> /star-plan-coach open-vocabulary detection
DSH /skill:star-<name> /skill:star-plan-coach open-vocabulary detection
Kimi Code /skill:star-<name> /skill:star-plan-coach open-vocabulary detection
Pi /star-<name> /star-plan-coach open-vocabulary detection
Qwen Code /star-<name> /star-plan-coach open-vocabulary detection

Claude Code, Cursor, Pi, and Qwen Code expose /star [what you want to do] directly from project files. The command sends the request through .agents/commands/star.md; an empty request selects star-flow-status, and a match to one of the seven explicit-only skills returns the exact /star-<name> <argument> command and waits. The same trees expose /star-auto <goal> [stop=<stop line>], which pursues the typed goal autonomously under the grant conventions §10.7 defines.

Codex packages the shared router as the repo-local star plugin. Register and install it once from the repository root, then start a new session:

codex plugin marketplace add .
codex plugin add star@star

Use $star with no argument for the current research status, or pass a request such as $star review the implementation for plan 030. The plugin reads the same .agents/commands/star.md roster as the other harnesses' /star wrappers; it adds no second copy of that routing table. $star-auto <goal> from the same plugin pursues a typed goal autonomously.

Kimi Code packages the same router as a user-installed plugin under .kimi-code/plugins/star/. Start Kimi Code from the repository root and run these commands in its prompt; /new may replace /reload:

/plugins install ./.kimi-code/plugins/star
/reload

Use /star with no argument for the current research status, or pass a described task; /skill:star is the explicit spelling of the same external skill, and /star-auto <goal> (/skill:star-auto) pursues a typed goal autonomously. Kimi copies a local plugin into its user-level managed directory, so repeat the install command after STAR updates this plugin — picking up /star-auto needs that reinstall once.

DSH packages the same router under .dsh/commands/star/; installation requires pnpm on PATH. From the repository root, install it once into every profile that will run STAR, inspect the composed configuration, then restart that profile:

dsh plugin --profile YOUR_PROFILE add ./.dsh/commands/star
dsh --profile YOUR_PROFILE --dump-config

Use /star with no argument for the current research status, or pass a request such as /star review the implementation for plan 030. The command starts one follow-up turn against the shared .agents/commands/star.md roster, so DSH and the other harnesses route from the same source; /star-auto <goal> from the same package pursues a typed goal autonomously.

Seven skills are slash-only — star-proj-adopt, star-idea-storm, star-plan-coach, star-code-architect, star-plan-decomposer, star-plan-reviser, star-code-release: they run only when named, because each sits on a decision that belongs to you. The agent may start the other eight itself when the task plainly matches and the target is unambiguous; naming any skill explicitly always works. Which seven, and why, is conventions §10 (the skill roster); that table is the source of truth and this list follows it.

STAR research workflow: thirteen skills in the order they run in plus two that read across them, what each one writes, and how the per-leaf loop closes

Settle the topic, and write it down as a plan. Research starts from an interest too vague to test. This stage narrows it to a question that can come out false, writes that question into a plan saying what result would support it and what would not, and reads the closest work until you can state where your method differs. A project already under way starts at the first row below, which brings its existing code, data, weights, and finished runs into the same records.

Skill Purpose Main output
star-proj-adopt Adopt an already-started project without disturbing it: survey the repository, wire .env, reach existing data / weights / output trees by symlink, wrap existing launch commands, and record what is already built and run. Once the plan tree exists, backfill the leaves already finished metds/adopt.md, plus exec_status: / exec_runs: on confirmed leaves
star-idea-storm Converge a vague interest into a defensible research topic: diverge into candidate directions, scan the landscape at abstract level, score on six dimensions, and frame the winner with a first validation experiment. Every paper it names is transcribed from a fetched record metds/ideas/<slug>_idea.md
star-plan-coach Turn a research idea into a written plan through staged questions metds/plans/<digit>_<topic>_plan.md
star-refs-reviewer Survey the work related to the method: read the closest papers into analysis notes, and build a classified bibliography whose entries are each transcribed from a fetched record. survey reads a whole field in tiers and writes a standalone survey of it metds/refs/<ABBREV>.md, metds/refs/reference.bib, metds/refs/refs_index.md, and metds/refs/<slug>_survey.md

Get the code and the environment to where an experiment can actually run. This stage starts the codebase from a reference implementation scored rather than picked, installs what it needs, and treats the environment as ready only once the imports pass, the framework sees the GPU, and the project's own entrypoint runs.

Skill Purpose Main output
star-code-architect Set up ${CODE_NAME}/ from a scored reference implementation, or organize existing code, and record the architecture ${CODE_NAME}/ with UPSTREAM.md, plus metds/codearc.md
star-env-builder Build the conda env or venv from .env, resolve and install dependencies in the uv > pip > conda install order, and run the three-layer runnable check — imports, then framework and GPU, then the entrypoint. add installs new packages into the existing env and records them Environment plus wkdrs/env_<name>_<date>/ENV_REPORT.md and freeze.txt

Split the plan into sub-problems that can each be checked on their own, and build them one at a time. A plan as a whole cannot be run; a piece carrying its own done-criterion can. This stage splits, then implements one piece at a time with light validation — heavy runs (long or multi-GPU training, costly API calls) come back to you as commands to launch — and reads the resulting code against the project conventions and what that sub-plan promised.

Skill Purpose Main output
star-plan-decomposer Split a top-level plan into sub-plans that can each be verified on their own metds/plans/<prefix>_<task>_plan.md
star-plan-executor Implement and lightly validate one executable leaf plan The plan's own tool scripts and intermediate working files under tasks/<plan-name>/; code plus wkdrs/<run>/EXEC_PLAN.md, EXEC_LOG.md, and generated artifacts; confirmed deviations synced back into the plan with a Revision History entry
star-code-reviewer Review code against project conventions and a plan's promised implementation, then apply mechanical fixes — minor ones unasked, major ones as approved wkdrs/<run>/CODE_REVIEW_<date>.md or wkdrs/reviews/code_<scope>_<date>.md

Read what the run produced, and take it back to the plan. A finished run is evidence, not a conclusion. This stage checks artifacts and log against what the plan expected and scores the metrics against the done-criteria and the baseline — every number re-opened at its source before it counts, what does not hold up downgraded or dropped — then revises the plan against that evidence: the assumption that did not survive, the criterion that was wrong, what to do next.

Skill Purpose Main output
star-expt-analyst Audit what a run produced against what the plan expected: artifacts, log health, metrics scored against the done-criteria, and what the result means for the claim wkdrs/<run>/EXPT_ANALYSIS_<date>.md plus wkdrs/<run>/analysis/ figures; wkdrs/results/results.md (or wkdrs/results/results_<slug>.md when scoped) in aggregate mode
star-plan-reviser Review one plan against its execution evidence and revise it in place wkdrs/<run>/REVIEW_<date>.md plus the plan revised with a Revision History entry

Write it up, and leave the repository runnable by someone else. By this point the plans are the record of the method, and the repository is what a reader will actually try to run. This stage compiles the one into paper-ready text and cleans up the other.

Skill Purpose Main output
star-metd-summarize Once every experiment is finished and the plans are finalized, compile the plan tree into paper-ready method documents, turning what no plan covers into TODOs metds/overview.md, dataset.md, framework.md, training.md, and evaluation.md
star-code-release Prepare the repository for release: promote scattered code into ${CODE_NAME}/ by the recorded placement rules, polish the files a reader will open, compile the README from the method documents and the results table, and sweep for secrets, machine-local paths, and commands that do not resolve README.md plus wkdrs/release/RELEASE_<date>.md

Two that belong to no stage. These read across all of the above and answer the two questions that come up at any moment: where the work stands and what to do next, and what the last stretch of experiments produced. Neither writes into a plan or a run's own directory.

Skill Purpose Main output
star-flow-status Report progress across the whole flow — the plan tree, plus finished work whose review, analysis, or write-up is missing or stale — and the single next action Read-only status summary
star-expt-digest Summarize recent progress on the time axis: resume from the previous digest, or cover an explicit window or a whole plan family. Tabulate each run's verdict and headline metrics from its analysis report, derive what moved since last time, and list the gaps wkdrs/digests/EXPT_DIGEST_<date>.md

Model selection

The skills divide into two kinds of work, each rewarding a different model strength. Model names are as of 2026-07 and will age; a parenthesis marks an equally good alternative at that tier.

Kind of work Skills Recommended
Judgment and writing — research directions, plans, how related work positions the method, what results mean, method write-ups star-idea-storm, star-plan-coach, star-refs-reviewer, star-plan-decomposer, star-expt-analyst, star-plan-reviser, star-metd-summarize Claude Fable5 Extra, ChatGPT5.6 Sol High, or Kimi K3
Building and running — codebase, environment, plan execution, code review, progress digests, status, release star-proj-adopt, star-code-architect, star-env-builder, star-plan-executor, star-code-reviewer, star-expt-digest, star-flow-status, star-code-release Claude Opus4.8 Medium (Sonnet5 High), ChatGPT5.6 Sol Medium (Terra High), Cursor Grok4.5 High, or Kimi K3

When resources permit, the strongest available model across all fifteen skills generally gives the best overall results.

The Research Workflow Skills Guide covers invocation details, a complete example, generated files, and troubleshooting; the rules every skill shares — git, the STOP line, the .env runtime, dates, delegation, and dialogue discipline — are in the Research Workflow Skill Conventions.

Per-harness setup (optional)

Neither is needed to get started. Do them when the harness you drive STAR with needs them.

Session hooks

Two hooks run at the start of a session: one records the model id skills write into every artifact, the other puts the project memory index in front of the agent. In Claude Code both also run when a sub-agent starts, since a session hook does not fire for one: the provenance hook hands the delegate the command that resolves the delegate's own transcript, so an artifact a delegate writes records the model that wrote it rather than the session's, and the memory hook repeats the index for it. Claude, Codex and Qwen Code carry a third that is not a session hook: while .env reads INVOLVE=low it answers the permission prompt before a file edit, and does nothing at every other level. It ships registered in .claude/settings.json, .codex/hooks.json and .qwen/settings.json like the other two. Claude additionally registers star_bash_gate.sh: at low it allows ordinary local shell commands — including the guarded worktree and commit flow above — while deletion, sudo, system changes, process control, git push, and forced copy/move keep the host's normal prompt. Cursor, DSH, Kimi Code and Pi do not carry the edit gate: Cursor has no hook that fires before a file edit, Kimi's PermissionRequest only observes the prompt it fires beside, and Pi ships no permission prompts at all. DSH has none to answer for a reason of its own: its default workspace-write sandbox lets an edit inside the project run without asking, and the only approval a file operation raises there is a one-shot escalation for a write outside the workspace — which this gate declines to answer anywhere, since it already passes on every path outside the project root. Its bridge would not honor an allow in any case. All seven carry a further hook, also not a session hook, running at every level: star_commit_guard.sh declines the git commands the conventions §1 forbids — blanket or forced staging, the history rewrites, and a commit whose staged files exceed 10 MB — and the launch of a run's prepared command (execs/scpts/<run>.sh) while that run has no code review, or one older than its log. Claude, Codex, DSH, Kimi Code and Qwen Code run it on PreToolUse, Cursor on beforeShellExecution, Pi on its tool_call event — where a shell command is decided in each. The matcher is the harness's own tool name: Bash for Claude, Codex and Kimi Code, run_shell_command for Qwen Code, whose matcher reads the tool identifier rather than the display label, and lowercase bash for DSH and Pi. It is the floor under INVOLVE=low answering the commit offer itself: what it declines is yours to run.

With Kimi Code or DSH, run the matching installer once per machine so the hooks are registered and skills record the real model_id instead of unrecorded:

bash .kimi-code/hooks/install.sh   # Kimi Code
bash .dsh/hooks/install.sh         # DSH

Each backs up and then writes the machine's own global config — ~/.kimi-code/config.toml for Kimi, $DSH_HOME/cordis.patch.yml for DSH; running either twice changes nothing, and one run covers every STAR project on the machine. Codex, Claude, Cursor, Pi and Qwen Code ship both hooks already registered, so skip this step there. On Codex, though, registered is not yet running: a project hook fires only once the project is trusted and the hook approved. Run /hooks in the Codex CLI to approve them, and again whenever a hook changes. Until then, model_id reads unrecorded in every report and no memory reaches the session, with nothing pointing out the gap. On Qwen Code the same caveat applies only with folder trust on (security.folderTrust.enabled, off by default): an untrusted project runs no project-level hook, again with nothing pointing out the gap. Qwen Code also prefers QWEN.md to AGENTS.md, so if your project has one, STAR's instructions in AGENTS.md are not loaded — import them from QWEN.md with @AGENTS.md, or delete the file. Pi needs no install step and no registration file: it discovers .pi/extensions/star-hooks/index.ts by itself, and that extension wires all three hooks — but only once the project is trusted, so answer Pi's trust prompt, run /trust, or set defaultProjectTrust. Until then no project extension loads, no .pi/skills/ are found, model_id reads unrecorded, and the sub-agents, plan mode and structured questions .pi/extensions/ vendors are all absent — with nothing pointing out the gap. Pi is also the one runtime whose model id cannot go stale: the extension reads the live model before each prompt and injects a fresh line whenever /model changes it. DSH needs its installer plus one more step: the row it writes loads DSH's Claude Code hook bridge, not a dsh dependency, so add it to each profile you use with dsh plugin --profile <name> add @deepseek-ai/dsh-hooks-claude-code — the installer names the profiles that still need it. The bridge resolves its config path against the directory dsh was launched in, so that one row serves every STAR project; launch dsh from the project root, and check with dsh --profile <name> --dump-config. Recovering the model id there needs zstd on PATH, since DSH stores its session log as Zstandard frames; without it model_id falls back to unrecorded. A project adopted before one of these hooks existed keeps its own registration file — execs/update.sh never overwrites it, and names the hook missing from it instead. Pi is exempt, its registration being code the updater always replaces. See .kimi-code/hooks.example.toml for the manual route and details. What each runtime reports for model_id, and what it falls back to, is Model id provenance.

Pre-approve the status collector

Six skills open the same plans, run logs, and reports before doing anything else: star-flow-status, star-expt-digest, star-plan-decomposer, star-plan-executor, star-plan-reviser and star-metd-summarize. Rather than one file at a time, each gathers them with a single read-only script — scripts/scan.sh, in that skill's own directory inside your harness's directory. That is a shell call, so your agent asks to approve it the first time it runs.

Claude Code needs nothing on a fresh install: .claude/settings.json ships allow rules for exactly those six scripts and nothing else. A project adopted earlier keeps its own settings.json — execs/update.sh installs that file only when missing and never overwrites it — so add the rules there yourself:

"permissions": {
  "allow": [
    "Bash(bash .claude/skills/star-flow-status/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-flow-status/scripts/scan.sh:*)",
    "Bash(bash .claude/skills/star-expt-digest/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-expt-digest/scripts/scan.sh:*)",
    "Bash(bash .claude/skills/star-plan-decomposer/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-plan-decomposer/scripts/scan.sh:*)",
    "Bash(bash .claude/skills/star-plan-executor/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-plan-executor/scripts/scan.sh:*)",
    "Bash(bash .claude/skills/star-plan-reviser/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-plan-reviser/scripts/scan.sh:*)",
    "Bash(bash .claude/skills/star-metd-summarize/scripts/scan.sh)",
    "Bash(bash .claude/skills/star-metd-summarize/scripts/scan.sh:*)"
  ]
}

Elsewhere, approve it once when asked, or pre-approve it in the harness:

Tool Where to pre-approve
Codex its approval-policy / sandbox setting (global config, not per project)
Cursor its command allowlist, in the app's settings
DSH your global $DSH_HOME/cordis.patch.yml — DSH reads no plugin configuration out of a project
Kimi Code your global ~/.kimi-code/config.toml — Kimi Code does not read project-level config
Pi nothing to pre-approve — Pi has no permission system. .pi/extensions/star-permission-gate.ts confirms rm -rf, sudo and chmod 777, and refuses them outright in a headless run
Qwen Code permissions.allow in .qwen/settings.json, which ships with the scan commands already listed

The script only globs metds/ and wkdrs/, prints frontmatter and file listings, and writes nothing anywhere.

Project memory

What a session learns that no plan, log, or report owns — a build that only works after a module load, a standing preference of yours, an experiment not worth repeating — is recorded in the project at .star/memory/, not in whichever harness you happened to be driving. One file per fact, one line per fact in .star/memory/MEMORY.md, and a session hook puts that index in front of the agent at every session start, in all seven tools.

Two rules keep it from becoming a second, competing source of truth:

  • A fact is recorded there only when no file in the project already owns it. Results belong to their run's EXEC_LOG.md, decisions about the research to their plan, papers to metds/refs/. Memory holds the residue.
  • Where a memory disagrees with a file in the repository, the file wins, and the memory is corrected or dropped.

Facts that hold only on this machine go to .star/memory/local/, which git ignores the way it ignores .env. Nothing is recorded without your say-so — the agent offers, you decide — and INVOLVE=low in .env turns that into record-and-tell. The four kinds of memory, the file format, and how one is retired are in Project Memory.

Updating STAR skills and workflow guides

After creating a project from STAR, later skill and research workflow guide releases sync without changing project code, experiment configuration, or Git remotes:

bash execs/update.sh

By default, the command updates these paths from STAR's main branch — every harness tree among them, unless STAR_HARNESSES or --harnesses narrows the set. The shared .agents/skills/ and .agents/commands/ roots are outside that narrowing, so every run updates them whichever trees were named.

  • .cursor/rules/skill-roots.mdc and .pi/APPEND_SYSTEM.md — which skill root each harness owns, and which copy Cursor and Pi must follow
  • .agents/skills/ — the shared root — then .claude/skills/, .cursor/skills/, .dsh/skills/, .kimi-code/skills/, .pi/skills/, .qwen/skills/
  • .codex/skills/ — the per-skill manifests Codex reads, installed with the rest of its tree; upstream .agents/skills/ links to them, and a project receives both as real files
  • .codex/plugins/ — the Codex-only $star router plugin and canonical marketplace; .agents/plugins/marketplace.json is only a file link to that marketplace, never a link over the directory
  • .dsh/commands/ and .kimi-code/plugins/ — the DSH and Kimi /star and /star-auto command packages, updated only when their respective harness is selected
  • .agents/commands/ — the single shared /star routing roster and the /star-auto procedure — then the thin harness wrappers in .claude/commands/, .cursor/commands/, .qwen/commands/, and .pi/prompts/, plus Pi's one prompt per skill, /star-<name>
  • .claude/agents/, .cursor/agents/ and .qwen/agents/ — the named star-plan, star-exec and star-read agents those three harnesses dispatch a tier's run to, stamped from .env by bash execs/configure.sh: Cursor and Qwen take the tier's model, Claude Code its effort
  • .pi/agents/, .pi/extensions/star-plan-mode/, .pi/extensions/star-subagent/, .pi/extensions/star-permission-gate.ts, and .pi/extensions/star-questionnaire.ts — the sub-agents, plan mode, and structured questions Pi's core does not ship; your project's own extensions sit beside them and are kept
  • .claude/hooks/, .codex/hooks/, .cursor/hooks/, .dsh/hooks/, .kimi-code/hooks/, .pi/extensions/star-hooks/, .qwen/hooks/, and the files that register them where registration is not automatic — .dsh/hooks.json with .dsh/cordis.patch.yml, .kimi-code/hooks.example.toml, and .pi/extensions/star-hooks/index.ts — the model-id provenance, project memory, and involve-gate hooks
  • docs/mds/star-workflow/, and docs/srcs/ — the workflow documentation, and the icon and workflow diagram STAR's own pages use
  • execs/run.sh — the stock experiment launcher; your own edits to it are replaced, while the experiment scripts it launches, under execs/scpts/, are yours and are never touched
  • execs/update.sh — the updater itself, so that a path added upstream after your project was created still reaches it
  • execs/configure.sh — the model configuration and Kimi pool registration command

The agent instructions are the project's own: AGENTS.md and .cursor/rules/agent-instructions.mdc, which carries its body, are not in that list. They follow the same rule as the hook registration configs below, so a project that wrote its own keeps them, and one with none gets upstream's.

The repository it pulls from is STAR_REPOSITORY, resolved in that order: the environment, then .env, then the default https://github.com/wanghao9610/STAR.git. Set it in .env to track a fork permanently, or prefix a single command — STAR_REPOSITORY=… bash execs/update.sh — to override it once.

Which of the seven harness trees it touches is STAR_HARNESSES, resolved the same way: the environment, then .env, then every one of them. Write STAR_HARNESSES=claude,pi into .env to keep only those two current; the other two values are all and none, and none leaves the shared skeleton — .agents/skills/, .agents/commands/, the workflow documentation, execs/run.sh, the updater itself, AGENTS.md — as the whole update. A tree left out is not touched at all: not installed, not updated, never deleted — so a project that removed the trees it does not use does not get them back on the next update, and one that keeps them all changes nothing by leaving the key unset. A narrowed run fetches only the trees it will write, and its refusal over uncommitted changes covers only those.

Hook registration configs — .claude/settings.json, .codex/hooks.json, and .cursor/hooks.json — are installed only when missing, and never overwritten unless you pass --force. When a kept config does not register the STAR hook, the command prints a note.

Three things an existing project therefore picks up by hand, all new in v0.3.0. The three model keys: .env.example reaches a project at --adopt time only, not on an update, and your .env is yours in any case, so add STAR_PLAN_MODEL, STAR_EXEC_MODEL and STAR_READ_MODEL to it yourself — upstream's .env.example carries the comment that explains them. And the sub-agent registration: a .claude/settings.json written before it has no SubagentStart block, the note names it as the missing SubagentStart delegate context hook, and the fix is to copy that block's two hook commands out of upstream's file into yours. The third is the tier bullet in AGENTS.md: a project that has written its own instructions owns them, so an update keeps yours rather than overwriting it, silently — copy that line over too.

The updater is in its own update set, so what it syncs grows with upstream instead of staying frozen at your project's creation — that is how the slash commands and the Pi extensions reach a project that predates them. It is replaced by rename: the run doing the replacing finishes with the copy it started from and the new one applies from the next run; the command says so when it replaced itself, and running it once more picks up any path the new updater adds. A project whose updater predates this — its Updated: line does not name execs/update.sh — needs one manual refresh before that can start:

curl -fsSL https://raw.githubusercontent.com/wanghao9610/STAR/main/execs/update.sh -o execs/update.sh

The general forms are bash execs/update.sh [--diff] [ref] [--harnesses LIST] [--skill NAME] [--force], bash execs/update.sh [ref] [--harnesses LIST] --adopt, and the offline bash execs/configure.sh:

bash execs/update.sh --diff
bash execs/update.sh TAG_OR_BRANCH
bash execs/update.sh --harnesses claude
bash execs/update.sh --skill star-flow-status
bash execs/configure.sh
  • --diff previews an update without changing a file, and exits 2 when one is available, 0 when everything already matches, 1 on error — so a script can tell an available update from a failed check.
  • A ref pins the update to a tag or branch.
  • When a pinned ref predates .dsh/commands/ or .kimi-code/plugins/, both a normal update and --adopt report the absent optional package and continue; a missing required path still stops the run.
  • --harnesses LIST limits one run to the trees named — claude,pi, or all, or none — overriding STAR_HARNESSES for that run alone. Deleting .agents/skills/ or .agents/commands/ is undone by the next run, unlike a harness tree. An unknown name stops the command and lists the seven valid ones.
  • --skill NAME updates that one skill across the shared root and all six harness directories, or across the ones a selection leaves, and leaves the workflow documentation and the hooks alone. An invalid name, or one missing from any of the upstream skill directories in scope, stops the command without overwriting anything.
  • bash execs/configure.sh synchronizes model settings offline; ordinary updates also call it after syncing files. Use bash execs/configure.sh --kimi-pool for pool registration; see harness adapters for host-specific behavior.
  • --force updates the same paths with both refusals lifted: uncommitted changes under them are overwritten instead of stopping the command, and the hook registration configs are overwritten instead of kept. It widens nothing — a file upstream does not have is still left alone, so your own skills and documents under those directories stay.

bash execs/update.sh --help carries the full usage summary, so it stays correct when the flags change.

STAR_PLAN_MODEL, STAR_EXEC_MODEL and STAR_READ_MODEL select research judgment, implementation and production, and read-only collection respectively. Set them in .env using the examples; a tagged value such as claude:fable,codex:gpt-6-astra keeps one host's aliases out of another host. The three keys do not change which work is authorized, and a run that still owes the user a question remains in the main session.

Harness How STAR selects a delegate's model
Claude Code Passes the model per dispatch; configure.sh synchronizes model and depth fields in named agents and skill manifests.
Codex Passes model and a supported reasoning_effort per dispatch; an explicit depth triggers a fresh-context delegate even when the model is unchanged.
Kimi Code Passes an alias when the current tool exposes model through a selectable secondary-model pool. The user's Kimi configuration owns that pool.
Pi Passes model on single tasks or individual parallel/chain items through STAR's extension.
Cursor Uses named agents; model selection and fallback rules live in harness adapters.
Qwen Code Selects the same named agents with actual model ids in their frontmatter; the tool's per-call model field is a different mechanism for configured grades.
DSH Keeps the existing route because the current tool exposes no per-dispatch model selector; a set key gets an explanation.

A missing interface, unavailable model, or stale named-agent configuration is reported without pretending the requested model ran. Reports record the delegate's actual model. Status and digest runs use the READ entry route on hosts without native skill forks; star-auto uses the same tier selection when starting each skill.

Files at matching paths are overwritten, new upstream files added, and project-specific files that exist only in the updated directories preserved. To avoid deleting custom content, files removed upstream are not removed locally. The update does not modify other directories, the current branch, Git remotes, or the staging area. Commit current work before updating, then review and commit the result with git status and git diff.

Project conventions

  1. Keep reusable implementation in ${CODE_NAME}/.
  2. Keep data in datas/, weights in inits/, plan-execution intermediates in a plan-named subdirectory under tasks/, and generated artifacts in wkdrs/.
  3. Keep research plans and methodology notes in metds/; plan files belong in metds/plans/.
  4. Use execs/run.sh as the main entrypoint and place experiment scripts in execs/scpts/.
  5. Read runtime paths from .env; do not hardcode machine-specific paths.
  6. Give each run a distinct output directory and record the command, configuration, and verification evidence needed to reproduce it.
  7. Make small, goal-driven changes and verify them with the narrowest relevant check before broadening validation.

The full collaboration and implementation guidelines are defined in AGENTS.md.

Adapting STAR to a new project

When starting a new research repository from STAR:

  • Replace the title and description with the new research project identity.
  • Set CODE_NAME and rename code/ if a different source package name is preferred.
  • Add the project's dependency specification and lock file.
  • Replace execs/scpts/00_exp.sh with the first meaningful experiment.
  • Document how datasets and pretrained weights are obtained; do not commit large artifacts directly.
  • Define the expected outputs, metrics, and reproduction commands for the project.
  • Update the copyright holder and year in LICENSE.
  • Replace docs/htmls/star.html, docs/htmls/star_zh.html and docs/srcs/ — they are STAR's own landing pages and images, not your project's. docs/index.html and docs/index_zh.html are symlinks that serve those pages at the site root. The two pages link to each other by absolute path (/STAR/index_zh.html), so rewrite that /STAR prefix to your own repository name, or the language switch will break. Leave docs/mds/star-workflow/ alone; execs/update.sh keeps it current.
  • Delete the harness directories you will not use. .agents/ (the shared root the AGENTS.md convention puts skills at), .claude/, .cursor/, .dsh/, .kimi-code/, .pi/ and .qwen/ hold the same fifteen skills, ~150 files each; keep the one your agent reads and rm -rf the rest. On Codex, keep .codex/ beside .agents/: its hooks are there, and so are the fifteen per-skill manifests .agents/skills/ links to at the path Codex scans. In a project installed or updated through execs/update.sh every tree is a self-contained copy of real files and deletion order does not matter — the updater writes out whatever a link points at. In a clone of STAR itself, or a repository made from the GitHub template, it does: the files that read the same under every harness are stored once under .agents/skills/, and the other six trees reach them through relative symlinks. There, make the tree you keep standalone first — tar -chf - .claude/skills | tar -xf -, your own tree substituted, rewrites its links as the files they point at (-h follows them; BSD and GNU tar alike) — and delete .agents/ last. Deleting is not the only route: --harnesses names the trees to install at adopt time, and STAR_HARNESSES in .env keeps a later bash execs/update.sh from putting a deleted one back — see Updating STAR skills and workflow guides. On Pi and DSH this is worth doing rather than optional: both read .agents/skills/ as well as their own root (.pi/skills/, .dsh/skills/), and deleting .agents/ removes the name collision — otherwise .pi/APPEND_SYSTEM.md has to talk the agent out of it, and DSH resolves it silently by rank, right but invisible.

Keep only the structure that remains useful—STAR should support the research, not constrain it. The skeleton stands alone, so removing every harness directory is a supported way to use STAR.

Change log

Highlights by release, newest first. Each release is a git tag, so bash execs/update.sh v0.1.0 pins an update to that version.

  • v0.3.7 (2026-09-07) — Model configuration leaves the updater: bash execs/configure.sh reads the three tier keys from .env and stamps each harness's model and depth fields offline, --kimi-pool registers the configured aliases in Kimi's own config, and bash execs/update.sh --models is gone. Per-host mechanics — Cursor's flat id form, Claude Code's manifest stamps, Codex's reasoning_effort — move to the new harness adapters, leaving the conventions with the shared rule and a link. star-flow-status now ships at effort: medium, the depth star-expt-digest already had.
  • v0.3.6 (2026-09-07) — Cursor now applies a tier's @depth on its named agents: bash execs/update.sh --models rewrites cursor:cursor-grok-4.6@xhigh as unquoted model: cursor-grok-4.6-xhigh on star-plan, star-exec and star-read — the flat one-id-per-depth form its catalog lists, since a parameterised id[effort=<depth>] does not resolve — so PLAN, EXEC and READ can share one model at different thinking depths. A configured Cursor depth is therefore reason enough to dispatch even when the tier model is the one already running — the rule Claude Code and Codex already follow — while Qwen still takes the model without the suffix. check_model_routing.sh covers the encoding; start a new session after the stamp.
  • v0.3.5 (2026-09-06) — Claude Code now applies a tier's @depth per dispatch: bash execs/update.sh --models stamps it into the new .claude/agents/ delegates star-plan, star-exec and star-read, and a relocating run or a handed-over phase is dispatched as one of them, so STAR_PLAN_MODEL=claude:opus@xhigh beside STAR_EXEC_MODEL=claude:opus@high gives the execution phase a delegate that reasons at high. A configured depth is therefore reason enough to dispatch even when the tier model is the one already running — the rule Codex has followed since v0.3.4 — while a delegate dispatched as a plain subagent type still inherits its caller's depth. check_model_routing.sh covers the new stamps, and check_consistency.sh rejects a subagent_type naming an agent .claude/agents/ does not hold.
  • v0.3.4 (2026-09-06) — Codex now passes each tier's supported @depth as reasoning_effort, so PLAN, EXEC and READ can use one model at different efforts through star-auto, direct READ skills and execution-phase handoffs. No model stamp or restart is needed; direct planning dialogues retain the main thread's effort. Regression checks now cover direct READ routing and keep zero-valued suffixes in model names.
  • v0.3.3 (2026-09-06) — A tier key's entry may now end in @<depth> — low, medium, high, xhigh, max, or a positive integer — so STAR_PLAN_MODEL=claude:opus@xhigh beside STAR_EXEC_MODEL=claude:opus@high names one model at two thinking depths. bash execs/update.sh --models writes each tier's depth into the effort: frontmatter of that tier's Claude Code manifests, which the harness applies to a run invoked as /star-<name>; only a suffix spelling one of those depths is read as one, so a model name carrying an @ of its own reaches its harness whole. A delegate still takes the depth of the run that dispatched it — a model can be named per dispatch, a depth cannot — and a harness with no depth to set reads the entry as the model alone.
Earlier releases
  • v0.3.2 (2026-09-06) — Every skill manifest now states the shared load as one paragraph instead of a fixed recipe: the awk that selected conventions sections, the reuse-an-earlier-load paragraph and the per-tier delegation preamble are gone, replaced by citations of conventions §7.6, §7.7 and §10.8, and the host picks its own file reader and output budget. check_consistency.sh drops the three checks that audited those passages — opening-load invariants, the selective conventions load, the reuse-an-earlier-load paragraph — and gains one over the shared environment and language controls. AGENTS.md and .env.example restate involvement as proportionate care under existing authorization: routine implementation stays in scope, new research decisions and destructive operations still need specific authority, and a read-only request never starts a writing successor.
  • v0.3.1 (2026-09-06) — A prepared STOP-line command now launches only after its code review, in every mode. star-plan-executor no longer offers to skip the review it starts at the end of a run; star_commit_guard.sh declines the run's launch script (execs/scpts/<run>.sh) and the wkdrs/<run>/.await marker a star-auto launch writes while wkdrs/<run>/ holds no CODE_REVIEW_<date>.md or its newest one is dated before the log; and a review that applied fixes names star-plan-executor <leaf> next, so the touched steps' checks run again before the launch. Your own terminal is outside the guard's reach: it sees the commands the agent runs, not the ones you type.
  • v0.3.0 (2026-09-04) — STAR_PLAN_MODEL, STAR_EXEC_MODEL and STAR_READ_MODEL in .env say which model does research judgment, implementation and read-only work; each holds one model name or comma-separated <harness>:<model> entries, so one .env names a model per tree, and an empty key leaves every run exactly as it was. Conventions §10.8 carries the rule: the roster gains a Tier column, a mode can override its skill's tier, star-plan-executor and star-code-architect hand their implementing phase to EXEC, and a run started in the main session relocates itself once — never recursing, and never while a confirmation point is still owed to you. Claude Code names the model on each dispatch, Cursor and Qwen Code route through the named star-plan / star-exec / star-read agents that bash execs/update.sh --models fills in from .env (start a new session afterward), Pi passes it to star_subagent, and a harness that cannot name a delegate's model ignores all three keys.
  • v0.2.17 (2026-08-30) — star-auto now waits on launched heavy commands by event, not refresh: the command starts detached with a wkdrs/<run>/.await marker and the run holds its turn in one blocking shell call until exit — no log re-reads, status passes, or watch runs while the process lives — and a fresh invocation finding a live marker resumes the same wait, so goal-mode redrives cost one turn each. star-auto involve=low runs the executor chain's Git lifecycle unattended — staging, commits, execution branches, non-deleting review fixes, a reviewed squash merge — and the involve= token now reaches Claude's gate hooks. Codex model-id provenance states the exact SessionStart id and adds a write-after --check that blocks reporting completion or committing when an artifact's model_id mismatches the rollout.
  • v0.2.16 (2026-08-27) — /star-auto <goal> [stop=<stop line>] drives the workflow toward a stated goal: status first, then the next action each run names — the seven explicit-only skills included, because typing the command is the researcher's decision, made once for the pursuit. Prepared heavy commands launch by default, halted only by the natural-language line a stop= token draws; mandatory confirmation points still ask, and deletions and overwrites never auto-run. Conventions §2 and §10.7 record the grant, and all seven harness entry points carry the command, from one shared procedure under .agents/commands/star-auto.md.
  • v0.2.15 (2026-08-26) — INVOLVE=low now reaches the plan approval: .claude/hooks/star_plan_gate.sh answers PermissionRequest for ExitPlanMode with an allow that also sets the session to auto mode (acceptEdits), so star-plan-executor's plan-mode confirmation point is presented in full but not waited on, the questions riding it taking their recommended answers. Claude only, by capability: no other harness raises plan approval as a prompt a hook can answer. Conventions §7.7 records the carve-out — the one confirmation point low moves — and execs/update.sh warns when a kept .claude/settings.json lacks the registration.
  • v0.2.14 (2026-08-25) — star-plan-executor's delegation is no longer serial: the main agent orchestrates from EXEC_PLAN's step order and dependencies, dispatching independent steps concurrently or one by one as it judges — no cap, no order imposed beyond the dependencies themselves. Concurrent writers still never share a file, and EXEC_LOG.md keeps one writer: the main agent records each step as it verifies that step's returned result. star-refs-reviewer's candidate collectors open the same way, bounded only by the per-host request budget, each concurrent collector's share written into its brief.
  • v0.2.13 (2026-08-25) — star-plan-decomposer now expands lazily by default: only the next runnable unit becomes a sub-plan file, while later units stay one-line outline units in the parent's ## Sub-plans — no file, no prefix — expanded on a re-invocation as execution reaches them, the outline checked against the newest results first. The conventions pin the - (outline) / - （概要） marker, star-flow-status counts unexpanded units and recommends the next expansion, star-plan-reviser amends outline lines as local candidates, and star-metd-summarize's readiness gate waits until none remain.
  • v0.2.12 (2026-08-24) — The fifteen skills are now authored once under .agents/skills/, with the six harness trees generated from it by port.sh — per-tree rules and anchored overrides replace seven-times hand porting, CI proves each tree reproduces byte for byte, and an anchor that no longer matches fails the port before it fails the tree. A STAR-tailored human writing guide lands in docs/mds/star-workflow/, and a repository-wide pass against the Humanizer and Humanizer-zh pattern lists rewords both READMEs, the AGENTS pair, the landing pages, the workflow documents and the skills' authoring copies — commands, pinned strings and citations untouched — while star_memory.sh learns to index entry lines outside fenced blocks.
  • v0.2.11 (2026-08-23) — Kimi Code and DeepSeek Harness gain repo-local generic STAR routers under .kimi-code/plugins/star/ and .dsh/commands/star/. Kimi installs its external skill through /plugins install and exposes /star with /skill:star as the explicit spelling; DSH installs once per profile through dsh plugin, injects its commands service, and starts a follow-up turn for the shared .agents/commands/star.md roster. All seven harness entry points now carry English and Chinese wrappers, applying STAR_LANG to user-facing routing while keeping .agents/commands/star.md authoritative. execs/update.sh installs and refreshes each package only with its harness, while the README and CI cover installation, naming, injection, bilingual wording, and shared routing.
  • v0.2.10 (2026-08-23) — Codex gains the generic STAR router as a repo-local $star plugin. The plugin and canonical marketplace live under .codex/plugins/; .agents/plugins/ exposes only marketplace.json as a relative symlink, avoiding a directory-level link that could collide with future harness plugins. execs/update.sh installs and refreshes both only when Codex is selected, and falls back to a real discovery file where symlinks are unavailable. The README documents marketplace registration, plugin installation, and $star usage, while CI locks the ownership and link layout.
  • v0.2.9 (2026-08-23) — /star now has one tool-neutral routing roster under .agents/commands/; Claude, Cursor, Pi, and Qwen keep only thin wrappers, the updater installs and refreshes the shared source, and CI holds every wrapper and both roster languages to the same fifteen-skill and † sets. Human-facing project and maintainer instructions gain Chinese counterparts—AGENTS.zh-CN.md, CLAUDE.zh-CN.md, .github/CONTRIBUTING.zh-CN.md, and the architect's upstream template—with the updater carrying the project-level copies into adopted repositories. STAR_LANG now also binds replies drafted in a fork or sub-agent and relayed back to the user; a run with no user turn falls back to the invocation's language when the setting is absent.
  • v0.2.8 (2026-08-20) — A skill now loads only what a run of it uses: the conventions arrive as the sections that skill acts on rather than the whole document, the document itself says the same thirteen dialogue rules and every other rule in 8.8% fewer bytes, and the procedure a run never enters — aggregate, watch, ledger, add, backfill, dropping a plan, the architect's reference-implementation branch, the executor's resume rules, the reference reviewer's three offline modes — waits in its own file until that path is taken, behind a stub naming the file, the trigger, and the runs that read none of it. Across the fifteen skills the text pulled in before the first step falls from about 446k tokens to about 380k (-15%), and a measured English /star-plan-coach session now loads 14944 tokens before its first step where it loaded 27265; two new invariants keep that honest — a references/… path a skill names has to exist, and a reference file it ships has to be named by some step — and the shared memory store now keeps only its template header, every entry moving to a git-ignored local/. A skill is named one way in that text now, the bare star-plan-executor, because the / and /skill: prefixes were the only difference in most of the files each tree kept its own copy of — a name a skill hands you is yours to prefix, and the slash commands that define the invocation are unchanged — which, with one stored copy per wording rather than one per tree, takes the seven trees from 859 stored files to 538, every link pointing into .agents/skills/ and nowhere else; an installed project sees none of this, since execs/update.sh writes out what a link points at.
  • v0.2.7 (2026-08-20) — Every authored document now says the same thing in fewer words — the fifteen skills and their references in both languages, the workflow documents, both README bodies — restatement and scaffolding cut, every claim, condition, prohibition and citation kept: 334k prose words down to 322k, and the SKILL.md a run loads every time 4.7% shorter. The selector naming which harness trees execs/update.sh installs becomes STAR_HARNESSES, its flag --harnesses, since tool here already means what an agent calls, not the harness a tree is for. The old names are gone rather than deprecated, so an .env still setting STAR_TOOLS is ignored and that update installs every tree.
  • v0.2.6 (2026-08-20) — .agents/skills/ is the shared root every agent that follows the AGENTS.md convention reads, not one harness's private directory, so the fifteen skills there stop naming any one harness's tools — a role stands in for each name, and the reader is addressed as the agent — and stop carrying any one harness's invocation prefix, since each tool spells it its own way and knows its own. Codex's own per-skill manifests — display name, default prompt, and the flag that makes a skill slash-only — move to .codex/skills/<skill>/agents/openai.yaml, reached from the path Codex scans by a relative symlink, because Codex reads a manifest only from inside the skill directory it belongs to. execs/update.sh now syncs .agents/skills/ on every run, first and whichever trees --tools names, since it is the copy an agent STAR ships no tree for would read — so deleting it is undone by the next update, unlike a tool tree, while --tools codex narrows to .codex alone and a project still receives real files, the links written out as it copies.
  • v0.2.5 (2026-08-19) — The files that read the same in every one of the seven tool trees are stored once, under .agents/skills/, with the other six carrying a relative symlink at the same path; every SKILL.md, and every reference or template that names a tool's own built-ins, stays a real file in each tree. Installing and updating a project is unchanged, because execs/update.sh writes out what a link points at: an adopted or updated project still gets real files, one self-contained copy per tree. Only a clone of this repository carries the links, and there the tree you keep is made standalone with tar -chf - .claude/skills | tar -xf -, with .agents/ deleted last.
  • v0.2.4 (2026-08-19) — A run that produces a list of items for you to accept or reject stops asking about them one at a time: conventions §7.13 makes the whole list one question — the numbered rows on the page first, each with what it changes and on what evidence, then adopt all as listed / adopt all but the ones I name / answer my questions on the ones I name first / adopt none, with the rows you pull out settled in a second round of the same shape. star-plan-reviser's revision candidates and star-code-reviewer's asked fixes stop walking item by item; star-code-architect, star-code-release, star-plan-executor and star-metd-summarize gain the "explain these first" path their batched questions never had; and what must be asked alone still is — anything on the STOP line, every deletion and overwrite, and giving a plan up. Elicitation is untouched, since a coaching series where each answer decides the next question has nothing drafted to lay out, and involve=high puts any list back to one row at a time.
  • v0.2.3 (2026-08-19) — execs/update.sh stops treating the seven tool trees as one indivisible unit: --tools claude,pi limits a run to the trees named, STAR_TOOLS in .env makes that choice standing, and all and none are the other two values — none leaving the shared skeleton, the workflow documentation with execs/run.sh, the updater and AGENTS.md, as the whole update. A tree left out is not touched at all: not installed by --adopt, not updated, and never deleted, so a project that removed the trees it does not use no longer gets them back on the next update. A narrowed run fetches only the trees it will write, and refuses over uncommitted changes only in those.
  • v0.2.2 (2026-08-18) — star-code-reviewer's fix pass stops asking about every mechanical fix: a minor or nit one — a docstring, a comment, an unused import, a rename whose references all live inside the reviewed scope — is applied unasked, named in the digest as it is applied and recorded as applied unasked in the report, while blocker and major fixes keep their per-item question at every involve level, as does every fix that deletes code, since a symbol nothing appears to reference may still be reached through a registry string. A review whose eligible findings are all minor now applies them without stopping to ask about a single one, which is the point: the attention a per-docstring approval spends is the attention the report itself needs. involve=high puts the unasked half back to the user, batched by type.
  • v0.2.1 (2026-08-18) — Reviewed against how algorithm research actually proceeds, the flow could not express several shapes of work that the one-leaf-one-run assumption ruled out: a set of configurations — a hyper-parameter grid, a repeat over seeds — is now one leaf that declares its axes in §3, writes one directory per cell under wkdrs/<run>/cells/, and is judged on the whole grid, with the analyst reporting the chosen cell only alongside the spread on its own axis; and the expected and actual cost of every heavy run goes into a new Cost section of EXEC_LOG.md, the one place the root plan's §4 compute budget is ever reconciled. Where the method is not settled yet, a pilot leaf is a legitimate unit — its §5 states what to look at and which decision each outcome triggers, and its numbers stay provisional so a guess cannot be promoted into a claim — and a direction that dies now rolls one line up to the root plan's §5 beside the kill-criteria that predicted it, since nothing reopens a dropped subtree. A leaf that builds data is no longer accepted on file counts and checksums (headline statistics, a hand check, an overlap check against the evaluation sets), a configuration an ablation settles must be written to a named file for the downstream leaf to cite by path, and one defect is fixed: the extraction map the method documents are compiled through named five plan-template sections by their old names in its Chinese edition; upgrading swaps the templates and leaves files already written alone — a sub-plan on disk and an existing EXEC_LOG.md do not grow the new sections, which are filled in on the next run of the skill that owns them, or carried in by star-plan-reviser when it next revises that plan.
  • v0.2.0 (2026-08-18) — The workflow is re-worded from a software-development register into how algorithm research is actually talked about: spilled to a file becomes written out to a file, smoke test becomes runnable check (the spec file renamed with it), contract splits by sense into the dispatch brief a subagent is handed and the return format it owes back, and what a log asserts is now a claim until an artifact confirms it. checkpoint means model weights and nothing else — the git sense is a commit per group, the verb sense is record — and the conventions glossary (§0) gains eleven rows pinning the new terms, while git's own vocabulary, the plan templates' section headings, an ML codebase's own registry and every literal another skill greps byte-exactly are left alone. README and the skills guide are regrouped into the five stretches of doing the work — settle a topic and write it into a plan, get the code and the runtime to where an experiment runs, split the plan into sub-problems and do them one at a time, read the results back into the plan, write it up — and the guide now opens with a "where to start" table, so you read the one section you are on instead of the other fourteen.
  • v0.1.46 (2026-08-13) — .pi/ gains the three mechanisms v0.1.44 had to substitute for, vendored from pi's own examples/extensions (MIT): star_subagent over a new .pi/agents/ roster — collector, implementer, auditor, one per delegate kind conventions §6 names — star_questionnaire for questions, /star-plan for read-only exploration, and a confirm before rm -rf, sudo and chmod 777. Every name they claim is prefixed, down to the injected context marker: pi exits 1 with no session at all when two extensions claim one tool name or flag, these same examples are commonly installed user-level, and an unprefixed marker lets that copy filter this one's messages silently; all four load only once the project is trusted, and without them a skill falls back to §6.1's local fill and plain text. Invocation is now /star-<name> alone — .pi/prompts/ supplies one command per skill and enableSkillCommands: false removes the /skill: twin — and the hooks moved into .pi/extensions/star-hooks/, since a bare .pi/hooks/ is the old name for the extensions directory and Pi warns on every start that it exists.
  • v0.1.45 (2026-08-13) — A seventh skill tree, .dsh/, brings the fifteen skills to DeepSeek Harness, which discovers .dsh/skills/ ahead of .agents/skills/ and invokes them as /skill:star-*. Three things had to be built rather than renamed: every description was rewritten under 500 characters, because DSH's catalog silently truncates there and the cut falls on the trailing trigger clause; DSH has no agent-type parameter, no tool that enters plan mode, and lowercase tools, so subagent_type, EnterPlanMode and Bash are substituted rather than spelled differently; and the hooks run through DSH's Claude Code bridge from .dsh/hooks.json, registered once per machine by .dsh/hooks/install.sh. The involve gate is deliberately absent — DSH's default workspace-write sandbox lets an in-project edit run unasked, so there is no prompt to answer — and model_id is recovered from the session log, which needs zstd on PATH.
  • v0.1.44 (2026-08-13) — A sixth skill tree, .pi/, brings the fifteen skills to Pi: /skill:star-*, Pi's own lowercase built-ins (read, bash, edit, write, grep, find, ls), and three hooks wired by a TypeScript extension Pi discovers itself — no registration file to merge, and a model_id that cannot go stale, since the extension reads the live model before each prompt and re-injects on every /model. Pi ships no sub-agents, no plan mode and no permission prompts, so this tree is the first where all three are substituted rather than renamed: questions are plain text, the executor gates its own writes and commands behind approval, and every dispatch becomes conventions §6.1's local fill. The involve gate is deliberately absent — it answers a permission prompt, and there is none — and .pi/APPEND_SYSTEM.md settles which copy to follow, since Pi reads .agents/skills/ too.
  • v0.1.43 (2026-08-12) — Where a new model_trail or ## Revision History entry goes was never written down: conventions §8 said append-only and left the position implied, so Claude Code sessions wrote the newest entry last while Cursor sessions put it on top. It now says the entry goes at the end of the list, below every older one, whatever the runtime — in the three places a writer reads it: §8, the model_trail comment in every artifact template, and the two files that govern Revision History entries. The compiled views are untouched and keep their own order: this change log, MODEL_LEDGER.md and the MEMORY.md index are regenerated newest first.
  • v0.1.42 (2026-08-12) — star-plan-executor no longer ends by recommending the review: the report step keeps only what the report says, and a new step starts star-code-reviewer on the leaf in the same turn, which is what conventions §10.6 asked for all along. The one narrow skip — an exploratory leaf whose handed-back command is cheap — stays a question, and low takes the review. §10.6 now also says which moment "after the run ends" is: the turn the report goes out, not the next time the user speaks.
  • v0.1.41 (2026-08-12) — Which skills mention the involve level had been arbitrary: the twelve that write now say so in their invocation paragraph, after the description, and the read-only reporters stay silent — except star-flow-status, which keeps one mechanical line because it loads conventions §7 by item and not the item that strips the token, so nothing else would. The .claude and .qwen argument hints name a level where one is usually wanted — involve=high for the three plan-writing skills, involve=low for the five that build or run — and the rest inherit INVOLVE from .env. .qwen's Chinese hints also pick up the description slot they missed when v0.1.37–38 added it.
  • v0.1.40 (2026-08-12) — star-plan-executor and star-plan-decomposer now introduce their arguments in the order conventions §7.12 writes them — plan name, then description, then involve= — rather than the level first, ahead of the text it is stripped from. That sentence now says the token belongs to neither the plan name nor the description and is stripped before either is read; parsing is unchanged, since the token was never positional.
  • v0.1.39 (2026-08-11) — star-plan-executor now judges whether a leaf is still one unit of work before it starts, on signals the plan itself carries: more than one independent done-criterion, more than one crossing of the STOP line, or data acquisition mixed in with building and running, with past-12-steps and deliverables spread over unrelated artifact families as the weaker pair that counts only together. Where it fires the run shows a preview of how that leaf would divide — 2–5 units, each with the done-criterion it would own, a sketch and not a file — and recommends star-plan-decomposer <leaf> with the sketch carried along as the description; executing as it stands stays an option with its cost stated. A run being resumed is never asked, and the finished EXEC_PLAN gives the same question a second reading at the approval confirmation point, where it costs no round trip of its own.
  • v0.1.38 (2026-08-11) — The description §7.12 defined now reaches the rest of the roster: eleven more skills take free text after their argument, and each says what it may do — steer where the run looks, supply words the run records — and what it may not, which is stand in for a confirmation point. Prose matching none of a skill's arguments is a description, so the run proceeds as if none was given and says so first, while a lone token that looks like an argument and matches nothing stays a question to ask rather than prose to read. The three whose first argument is already free text — star-idea-storm, star-plan-coach, star-refs-reviewer — need no change, because that argument is the description.
  • v0.1.37 (2026-08-11) — Conventions §7 gains item 12: <skill> [TARGET] [DESCRIPTION] [involve=<level>] is the shape the whole roster shares, and free text after the target is the user saying, in their own words, what the run is for. It is a lead and not a command — it may route a run and supply text that run then records, and it never stands in for a confirmation point, never settles a target §5.2 would have asked about, and never authorizes anything on the STOP line — with a description-routed run saying which path it took before it writes, so a misreading costs one line rather than one wrong edit. star-plan-reviser is the first to trade keywords for it: drop and undrop are gone, and "this one is finished, 02 replaces it" both takes the drop path and becomes the reason written into the plan.
  • v0.1.36 (2026-08-11) — The two skills that load only the conventions sections they act on — star-refs-reviewer and star-expt-digest — now split that excerpt across two calls in one message, because the size limit is per tool result and one call carrying seven sections had come within ~10 bytes of the budget guarding it. Each call is now 12–17 KB with room to grow, and the load costs what it did before: calls sent in one message cost one round trip between them, not one each. Consistency check 20 follows — it reads every selector in a file rather than the first, sizes each on its own, and checks the prose, the citations and the quoted total against their union — and its budget goes back to the 28400 bytes it was before this session pushed against it.
  • v0.1.35 (2026-08-11) — A pass over the fifteen skills for redundancy found two things worth removing. star-flow-status's "no word budget" had been loosening conventions §7.1's ~500-word cap, which the precedence rule lets a skill tighten and never loosen, so the exception moves into §7.1 where it belongs — a reply whose length is set by what it must enumerate is bounded by shape instead — and the report cites it rather than declaring itself unbounded. level:, written into every sub-plan by the template, turned out to be read by nobody and equal to the length of the prefix, so it goes; what looked duplicated elsewhere is either text CI keeps identical across the five trees or a boundary already written down where it could be confused.
  • v0.1.34 (2026-08-11) — Five leftovers the new drop field exposed. exec_status: skipped turned out to have no producer in any skill, so it stops being a legal value and is recognised only where a plan hand-wrote one, while abandoned — which had no status symbol of its own and no place in the method-doc gate — now has a symbol of its own, ✖, carried by the status spec's example tree beside the dropped pair, counts out of the execution-progress denominator exactly as a dropped leaf does instead of holding that ratio under 100% for good, and clears star-metd-summarize's readiness check without contributing a line to any document. The stale-code-review check compares against the newest date its EXEC_LOG.md carries — the scan's per-run dates line already collects every date in the file — rather than against a step-table date column the log template never had, which is why the spec had been admitting that row usually could not fire.
  • v0.1.33 (2026-08-11) — A plan can now be given up on without being deleted: star-plan-reviser <plan> plus a description that gives the direction up writes dropped: <date> — <reason> on that node — a path that skips the audit, since a drop records a decision already made, and takes its reason from the words you used — and every skill reads the field as inherited by the whole subtree, so one line takes the node and its descendants out of the counts, the follow-up checks and the next action. star-flow-status renders them ⊗ with their pre-drop state in parentheses and outside its three numbers, star-plan-executor and star-plan-decomposer refuse to act on them, and star-metd-summarize compiles nothing from them — while the parent keeps its children: entry and its index line, marked — dropped <date>, so what was tried stays readable. What a drop does not hide is anything still on disk: a live leaf depending on a dropped node, an unmerged execution branch, or a worktree under it each still get a drift flag.
  • v0.1.32 (2026-08-11) — star-flow-status now prints every node in scope on its own line, and the ~500-word reply budget that had been forcing a large tree into sentences like "8 leaves, all done" is gone: how long the report runs is set by the tree it has to show, and shape bounds the rest — one line per node, one clause per count, one line per triggered check. A PLAN_NAME argument now narrows what is rendered and not only what is checked, with the tree pruned to the resolved subtree in Step 2 and the three summary counts computed over it. Its spec gains a Scope section settling what an ambiguous name does in a skill that never asks: an exact numeric-prefix match separates two roots sharing a slug, several matches render every one of them, and no match lists the candidates and stops.
  • v0.1.31 (2026-08-11) — The read-only collectors seven skills send out — star-code-reviewer, star-expt-analyst, star-plan-reviser, star-proj-adopt, star-code-architect, star-idea-storm, and the executor's orientation steps — now name model: sonnet in .claude/, the one tree whose harness takes the parameter: each transcribes into a closed return format, decides nothing, and has every line it cites reopened by the main agent before that line reaches a report or a confirmation point. Delegates whose judgment or writing is the product keep the session model — the executor's step agents, the architect's migrators, star-refs-reviewer's per-paper notes, star-plan-coach's blind rubric read. star-code-reviewer also stops collecting in the main agent at any scope, since a context that has been discussing the code is not a neutral reader of it, and sizes the fan-out instead: one collector up to ~50 files, groups of 10–15 past that.
  • v0.1.30 (2026-08-10) — The seven skills that show material before asking about it — star-plan-coach, star-idea-storm, star-plan-executor, star-code-release, star-metd-summarize, star-refs-reviewer, star-proj-adopt — now carry that instruction where the question is asked as well as where the material is written, the material end being the phrasing v0.1.29 found insufficient in star-plan-decomposer. Each Dialogue Discipline gains one line naming that skill's own material — a rubric finding, a candidate table, an amendment batch — with the read-back it implies: options and nothing above them mean the material was skipped, not shortened. The rule stayed out of conventions §7.3, where all fifteen skills would have inherited it, because star-refs-reviewer's selective load of that document had 49 bytes of headroom left against its 28400-byte budget.
  • v0.1.29 (2026-08-10) — star-plan-decomposer puts the sub-plan list back through the question tool, so its three answers are selectable again rather than typed, with the cards in the same message's text above the call. v0.1.28 had moved that whole confirmation into plain text on the theory that a client may drop text preceding a tool call in the same turn; a run since has shown the text above the axis question rendering fine, which leaves only the drafting skipping the cards, so the instruction now guards that where the call is made rather than where the cards are written. Dialogue Discipline follows: material too large for the options — a sub-plan draft, the drafted parent index, the rubric failures — goes above the call, never instead of it.
  • v0.1.28 (2026-08-10) — A confirmation question no longer stands in for the material it asks about: the rubric findings in star-plan-coach and star-idea-storm, the pending amendments in star-plan-executor, and the change lists in star-code-release and star-metd-summarize are now written out line by line before anything is asked. Where the material never fitted in the options — ~15 ranked papers in star-refs-reviewer, an unbounded run or leaf list in star-proj-adopt — the rows are numbered, the recommendation is marked in the table, and the question asks over the numbers, since conventions §7.3 caps a question at four. In star-plan-decomposer the sub-plan list and the question about it now leave as one message with no tool call between them — cards shown and then asked about through the question tool in the same turn had been reaching users as three options with nothing above them.
  • v0.1.27 (2026-08-10) — star-plan-decomposer now puts the sub-plan list in front of you as one card per unit — objective, steps, deliverables, done-criterion — before it asks you to confirm it, where it used to show a row of titles whose content arrived only a step later. The cards are a sketch, not a draft: Step 4 still writes the six sections, expanding the card it was handed and naming any line drafting forces it to change. Involve is unmoved — low adopts the list unasked and still prints the cards in full, high also confirms each sub-plan's draft before it is written.
  • v0.1.26 (2026-08-09) — A star-refs-reviewer analysis note may now carry up to three figures instead of one architecture figure, chosen by what the paper is: the method-as-a-whole figure keeps the first claim, while a dataset paper's construction pipeline, the plot an analysis paper's claim rests on, or a qualitative comparison earns its place only where the note's prose cannot carry it. Every figure kept now brings 2–4 sentences on what it shows and how to read it, written from the caption in full and the passages citing that figure by number — a figure that cannot be described from those is not kept, and a detail neither states is marked [unverified]. The note collector returns referenced_at beside each caption for exactly that, and captions are no longer trimmed at 200 characters.
  • v0.1.25 (2026-08-08) — A fifth skill tree, .qwen/, brings the fifteen skills to Qwen Code: /star-* as in Claude and Cursor, with all four hooks registered in the project's own .qwen/settings.json — the involve gate among them, landing on a third harness because Qwen Code's PreToolUse answers with permissionDecision: "allow". The port writes Qwen Code's tool identifiers (run_shell_command, read_file) rather than the display labels it also publishes, since its own bundled skills never write the labels, and check 23 now pins that choice per tree. allowed-tools is deliberately absent: Qwen Code's allowedTools grants session-scoped auto-approval instead of restricting, so carrying those blocks across would have widened what a skill may do rather than narrowing it.
  • v0.1.24 (2026-08-08) — A run can now be housed in a git worktree the executor itself creates: the branch keeps isolating history, and the tree answers the orthogonal question of a busy checkout — HEAD on another run's branch, foreign uncommitted paths, handed-back commands still awaiting results — settled at the same approval confirmation point, with a housed run always carrying a branch (conventions §11.7–9). The tree lives at ../<root>--wt/<run> with .env, datas/, and inits/ symlinked in and its path recorded as worktree: in the run's records; the merge squashes in the main checkout with nothing switching, and removal moves the non-md artifacts out first — never --force, which star_commit_guard.sh now denies. star-flow-status lists worktrees beside execution branches and flags one left behind.
  • v0.1.23 (2026-08-08) — star-code-reviewer stops letting the conversation that wrote the code collect the findings on it: when earlier turns of the session wrote or edited files now in scope, even a small scope hands collection to one fresh-context read-only collector carrying the whole file list, and the report's scope line records the delegation. An author rereads its own code through the reasoning that produced it; larger scopes already collected through fresh subagents, so this closes the small-scope (≤ ~20 files, the usual diff review) gap.
  • v0.1.22 (2026-08-08) — The execution branch is named for its run, <run>, so the branch and its wkdrs/<run>/ pair by name with no prefix to strip, and the listing every skill opens with becomes a glob over the run naming scheme. Separately star-flow-status and star-expt-digest, the only context: fork skills, read their argument from a $ARGUMENTS placeholder in their Invocation line: a fork sees no user turn, so the harness appends the typed value after the whole manifest, where /star-flow-status 030 reproducibly missed it and reported the whole tree instead of that plan's subtree. An absent argument substitutes to empty in all three invocation paths, leaving no literal behind.
  • v0.1.21 (2026-08-07) — Delegating stops being the exception: §6 hands the call to the main agent, drops the flat "at most three run at once", and no longer reserves file-changing delegates to star-plan-executor and star-code-architect, while star-flow-status loses the roster's one outright ban on subagents. What is kept is everything that was never about caution — disjoint file ownership among concurrent delegates, the main agent re-running every check and owning every judgment, read-only delegates that write nothing, and the per-host request budget that is the real reason a fetch fan-out is bounded at all. Separately the Claude manifests gain argument-hint and turn-scoped allowed-tools, with Write granted beside Edit wherever a skill creates files instead of editing them; allowed-tools pre-approves and never restricts.
  • v0.1.20 (2026-08-06) — A leaf that edits existing code can now run on its own branch, and the base branch stays canonical until the change earns its merge: conventions §11 has the plan-approval confirmation point recommend exec/<run>, and choosing it chooses per-step commits, because only commits merge. Until the merge everything the run wrote exists only on the branch, which reads from the base branch as a leaf simply not done yet, so a dependent leaf stays blocked with no new check written anywhere; the merge is a mandatory confirmation point, squash by default, and discarding commits the run records first so a dead end keeps its evidence. Around the executor, star-code-reviewer reviews a branch run as its <base>...HEAD diff, star-expt-digest names unmerged branches among its gaps, and star_commit_guard.sh gains arms for the spellings that break this in one keystroke.
  • v0.1.19 (2026-08-06) — The Kimi tree stops naming two tools Kimi Code CLI does not have: thirty manifests called the file reader ReadFile and the terminal Shell, where that harness publishes Read and Bash — the same two words Claude uses — so forty-five of the forty-six changed lines come out byte-identical to their Claude counterparts. The rename it undoes came from v0.1.8, which swept .kimi-code in on suspicion rather than on Kimi's published list, the more expensive direction of that defect because it leaves behind a record saying the name was checked and nobody re-checks a checked name. Check 23 now pins, per tree, the file reader, the terminal and the subagent_type values each harness publishes, and .cursor was re-read and deliberately left alone, since Cursor documents capabilities rather than tool identifiers.
  • v0.1.18 (2026-08-06) — A paper's architecture figure now lands in the note that reads it: star-refs-reviewer's analysis note may carry one image in its Method section, identified from the captions and never from the numbering, and copied from the paper's own arXiv HTML rendering. Absence is a valid answer whose two causes are told apart in one line — a paper that has no such figure, and one arXiv has not rendered — while a results plot promoted into the empty slot is graded a failure. What is fetched is written as fetched into metds/refs/figs/, with the figure number, the caption's first sentence, the image URL and the fetch date beneath it, so a figure copied out of the note can still be traced.
  • v0.1.17 (2026-08-05) — The commit offer stops being a question you have to answer: §7.7 no longer counts it among the mandatory confirmation points, so medium and high ask exactly as before while low takes it unasked, and either way the final reply names every commit made. What the confirmation actually guarded was never the commit but the staging beside it, so §1.4 gains the mechanism it always needed — a git status snapshot taken at the start of the run. A new hook in all four tool trees, star_commit_guard.sh, declines blanket or forced staging, the history rewrites §1.3 names, and any commit whose staged files exceed 10 MB.
  • v0.1.16 (2026-08-05) — The involve gate reaches Codex: .codex/hooks/star_involve_gate.sh answers PermissionRequest — the event that fires just before the CLI waits on you — with an allow for apply_patch while .env reads INVOLVE=low. It is not the Claude block ported across, because Codex reports an edit as a patch envelope rather than a path field, so the paths come from its *** Add File: and *** Update File: headers and every one must sit inside the project and outside the dot-directories at its root. Two harnesses of four, by capability rather than by choice: Cursor has no hook that fires before a file edit at all, and Kimi Code's PreToolUse documents deny and no allow.
  • v0.1.15 (2026-08-05) — INVOLVE=low now reaches the permission prompt, not only the questions a skill asks: .claude/hooks/star_involve_gate.sh answers PreToolUse for Edit, Write and NotebookEdit with an allow, while a path outside the project and every dot-directory at the project root keep their prompt and Bash stays out of the matcher entirely. It moves permission prompts and nothing else, which is §7.7's own division carried down to the harness — the STOP line, commit offers, deletions and plan approval hold at low exactly as at high. The same release gives every reference.bib entry a % src: provenance line, puts a paper note's headline number on one self-contained line with its dataset, metric and setting, and teaches §10.6's pickup rule the mixed case.
  • v0.1.14 (2026-08-04) — Eight of the fifteen skills may now start themselves: conventions §10 rosters all fifteen and marks seven slash-only with †, because a decision reached on an agent's own initiative is a decision nobody made. Being picked up changes nothing about how the run then behaves — the STOP line, commit offers, deletions and overwrites, and every mandatory confirmation point hold exactly as when you type the name — and three rules bound it: an unresolved target is asked about rather than guessed, one skill per invocation, and a line in the decisions record. Permission alone moved nothing, since every skill's text still handed the reader a command, so §10.6 closes the gap: a run ending on one of the eight with a settled target runs it instead of printing it.
  • v0.1.13 (2026-08-04) — Every reference entry carries an impact score: star-refs-reviewer composes citations per year, venue tier and code adoption into a 0–10 total by fixed weights, from metrics fetched and dated during the run — never an impression, and never a reference.bib field. The score decides emphasis, not membership, since "close beats famous" still picks the core set, and a new score mode re-fetches a whole bib's metrics in one batch so an existing base adopts the feature with one command. The same release stops the updater from ever overwriting AGENTS.md and the Cursor rule that mirrors it.
  • v0.1.12 (2026-08-03) — A project keeps its own memory: what a session learns that no plan, log or report owns is recorded under .star/memory/, one file per fact with a one-line index beside them, and a second session hook puts that index in front of the agent at the start of every session. AGENTS.md gains §10 carrying the whole write rule — record only what no file in the project already owns, offer rather than assume, and let the repository win wherever a memory disagrees — which moves Verification to §11 and every citation of it across the four skill trees with it. The format and the retirement rules are memory_spec.md, and facts true only of one machine go to .star/memory/local/, git-ignored the way .env is.
  • v0.1.11 (2026-08-03) — The project points at its writing-side companion, STAGE: the landing subtitle becomes "Every STAGE needs a STAR", the closing call to action gains a "Pair it with STAGE" button, and the footer a STAGE link, symmetric with the links STAGE has always kept to STAR. Both READMEs now open on the division of labor — STAR runs the research and produces the method documents, results and digests, while STAGE imports them as read-only, fingerprinted evidence and writes the paper on top, so a number in the manuscript traces back to the run that produced it. The pairing stays optional in both directions.
  • v0.1.10 (2026-08-02) — The "change granularity" answer in star-plan-decomposer's sub-plan-list confirmation gains defined behavior as a direction, asked first: coarser merges units sharing a category or a dependency and shows the list again, asking whether to stop rather than merging below three, while finer never adds a sibling and instead carries the units named too coarse into the recursion step. The updater's upstream becomes configurable, execs/update.sh resolving STAR_REPOSITORY from the environment, then .env, then its built-in default, so tracking a fork is one line. The update set also gains execs/run.sh, while the experiment scripts under execs/scpts/ remain the project's own and are never touched.
  • v0.1.9 (2026-08-02) — The code review moves ahead of the STOP-line command: when star-plan-executor stops for a heavy run, its report now names star-code-reviewer above the command it hands back, because a defect caught before the compute costs a review while the same defect caught after costs the compute and the re-run too. The loop back closes as well, a CODE_REVIEW_<date>.md whose blocker or major findings the log does not record as settled reopening the steps they land in. star-flow-status recommends the review in the same order, and the rubric scores a deliverable only the un-run command can produce as pending rather than absent.
  • v0.1.8 (2026-08-01) — Every skill tree is checked against its own harness's published tool list and the SKILL.md spec, instead of against how the other trees are written: the Cursor tree regains structured questions through AskQuestion, and three trees stop naming tools their harness has never had. Codex has no file-reading tool at all, so its loads say so and cat the files into the shell call, and its selective delegation is executable — spawn_agent with agent_type: explorer for bounded read-only work, worker for implementation. Descriptions now fit the spec's 1024-character limit in all four trees, and the checks enforce both that limit and each harness's delegation vocabulary.
  • v0.1.7 (2026-08-01) — The Kimi skill tree regains the mechanisms its port had flattened to prose — AskUserQuestion structured questions, plan-mode approval via EnterPlanMode/ExitPlanMode, and Agent subagent dispatch — with subagent types mapped to Kimi's explore/coder and multiSelect renamed to Kimi's multi_select. The legitimate adaptations stay: /skill: invocation, AGENTS.md references, Kimi model-id wording, and the kimi -p fallback.
  • v0.1.6 (2026-07-30) — star-flow-status splits its opening load into two commands sent together — the conventions excerpts, whose size is fixed, and the collector's digest, which grows with the project's history. The two shared one result-size limit, so on a project with history the pair overran it and both were written out to a file; split, the excerpts always arrive and only the digest can still be written out.
  • v0.1.5 (2026-07-30) — Four more skills — star-plan-decomposer, star-plan-executor, star-plan-reviser, star-metd-summarize — read the plan tree through the shared read-only collector instead of opening each plan, and a second skill in the same conversation may reuse the opening load it can still see, the collector's digest excepted. star-plan-decomposer renames its three decomposition axes to phase, component and experiment, each named for the unit that level holds. It recommends the experiment axis only once the code runs end to end, that axis holding experiment groups with the individual claims one digit deeper.
  • v0.1.4 (2026-07-29) — Every skill opens with a single load message, and SKILL_zh.md is no longer read at runtime — it stays a full mirror for human readers. Two skills load only the conventions sections they act on.
  • v0.1.3 (2026-07-29) — star-refs-reviewer gains a survey mode, which writes a standalone field survey to metds/refs/, and an add form that takes several papers in one call.
  • v0.1.2 (2026-07-28) — One wording rule, in AGENTS.md §7 and conventions §7.11: write the action, not its name. All fifteen skills are audited against it.
  • v0.1.1 (2026-07-27) — star-flow-status scans the plan tree once and star-expt-digest reads the same scan. Adds STAR_LANG to pin the language of replies and generated documents; execs/update.sh gains AGENTS.md sync and --force; the provenance hooks read the model id at the moment a skill records it.
  • v0.1.0 (2026-07-24) — First official release: fifteen bilingual research workflow skills for Codex, Claude, Cursor, and Kimi, model-id provenance hooks, an INVOLVE=low|medium|high dial (default medium) setting how much the skills ask before deciding, and an updater with hook sync and --diff preview.
  • 2026-07-15 — Initial STAR release.

Citation

If you find STAR useful in your research, please cite:

@misc{star2026,
  title = {{STAR}: Systematic Toolchain for AI Research},
  author = {Hao Wang},
  howpublished = {\url{https://github.com/wanghao9610/STAR}},
  year = {2026}
}

License

STAR is released under the MIT License.

About

STAR: Systematic Toolchain for AI Research (Harness, WIP)

wanghao9610.github.io/STAR/

Topics

harnessproject-managementworkflow

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

52 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages