projtool-bootstrap

This skill activates the first time a user wants to bring a project under projtool. It is intentionally narrow: the user must mention projtool by name or use a clearly-projtool verb such as retrofit, install, set up, or onboard.

When You Should Not Act

• The project already has .claude/skills/ml-research-workflow/; that

project-level skill owns day-to-day projtool work.

• The user is asking about agent/client skills in general, not projtool.
• The user is discussing ML workflow but has not asked to use projtool.

Main Flow

The full flow is in references/retrofit-flow.md. Follow that file, and trust the live MCP tool schema over this document if they ever disagree.

Briefly:

1. Check MCP availability. mcp__projtool__detect_project_structure

should be callable. If not, tell the user to run projtool setup once from a shell and restart the active MCP client in this directory.

1. Detect. Call mcp__projtool__detect_project_structure and summarize

the detected train script, config directory, invocation style, package manager, data path hint, git state, and docs repo status.

1. Negotiate v4 config. Build a ProposedConfig using the v4 schema:

paths.code_dir, main_worktree_name, data_dir, docs_dir, output_dir, remote_workspace, outputs_remote, data_remote, plus paths.docs_repo_url. Do not use removed v3 fields such as docs_repo_path or outputs_local.

1. Write templates. Call mcp__projtool__retrofit_write_template with

the agreed config. Surface conflicts and warnings exactly; do not claim success if conflicts remain.

1. Tell the user what changed. The raw git repo is converted into a v4

container layout: code/main/ holds the git worktree, while .proj-tool/, .claude/, .codex/, docs/, data/, and output/ live at container root.

1. Step out. After retrofit, the project-level ml-research-workflow

skill handles experiments, image builds, training, reports, and sync work.

Negotiation Defaults

Show a compact proposal and ask "anything to change, or go?":

• project_name: directory basename, normalized to projtool's slug rules.
• paths.code_dir: code
• paths.main_worktree_name: main
• paths.data_dir: data
• paths.docs_dir: docs
• paths.output_dir: output
• paths.remote_workspace: /workspace
• paths.outputs_remote: /root/autodl-fs/runs/<project_name>
• paths.data_remote: /root/autodl-fs/datasets/<project_name>
• paths.docs_repo_url: empty unless the user already has a remote docs repo.
• entrypoint.train_script, entrypoint.config_dir,

entrypoint.invocation_style: from detection, with user override allowed.

• autodl.default_gpu_spec: detected/preferred GPU spec, usually 4090.

If the raw repo already has a root data/:

• If it is untracked and gitignored, retrofit preserves it as

<container>/data/ and creates code/main/data -> ../../data.

• If it is tracked, tell the user to either choose another paths.data_dir

such as datasets, or rename the tracked directory to something like fixtures/ and commit before retrying.

Git Preconditions

Retrofit needs a git repository with at least one commit. If detection says the directory is not a git repo, do not silently choose a different directory. If the user's intent is unambiguous, offer to initialize git in the current directory and make an initial commit; otherwise ask them to run git init and commit once, then continue.

Invariants

• retrofit_write_template is the only projtool writer. Do not create

projtool files with ad hoc Write/Edit calls.

• Use the v4 schema names. docs_repo_path and outputs_local are removed

from retrofit input.

• Container-root .claude/ is the active Claude Code config. If the raw repo

had .claude/settings.local.json, retrofit should preserve or merge it at container root so local permissions keep working.

• Container-root .codex/ is the active Codex project-local hook bundle.

Codex users may need to review/trust project-local hooks when opening the retrofitted project.

• Image build is optional at retrofit time. A project image can be built later;

instance_up will prefer [image].project_image_uuid once it exists.

Done Means

• .proj-tool/project.toml exists at container root, has a non-empty

[project].project_id, retrofit_complete = true, and v4 [paths].

• code/main/ is the git worktree; container root no longer has .git.
• data/ and output/ exist at container root.
• code/main/data is a symlink to the configured container data root.
• .claude/settings.json, commands, hooks, and project skills exist at

container root.

• .codex/hooks.json and .codex/hooks/run-claude-pretooluse-hook.sh exist

at container root.

• docs/ is an independent docs git repo with an initial commit.
• .mutagen.yml, CLAUDE.md, AGENTS.md, and code/main/.gitignore are written or

updated according to the template rules.

• The user knows to review and commit the code repo changes.

If any of those is missing, retrofit is not done.