create-project-flows
Give a repo its own worktree and ship skills. Use when new worktrees start broken (no deps, env, port or backend), shipping is done by hand, or a repo has no worktree-<app> or ship-<app> skill.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- create-project-flows
- description
- Give a repo its own worktree and ship skills. Use when new worktrees start broken (no deps, env, port or backend), shipping is done by hand, or a repo has no worktree-<app> or ship-<app> skill.
03 SKILL.md 正文
Create project flows
I start every task in a fresh T3 worktree and ship from there. Two things keep breaking:
- New worktrees. They start without dependencies or
.env.local, on a port another worktree already uses, and pointed at a dev backend that other worktrees overwrite. - Shipping. It's done by hand. The main checkout falls weeks behind, and stale worktrees pile up.
This skill writes two project skills that fix both, tailored to this repo:
.agents/skills/worktree-<app>/: make any checkout of this repo work, isolated, in one command..agents/skills/ship-<app>/: take verified work to production and leavemain, the main checkout and the worktree list clean.
.claude/skills must link to .agents/skills (gitignore the link) so Claude Code and Codex both find them.
1. Read the repo first
Find out, from the code and history rather than by asking:
- Install: the package manager. Keep the one the lockfile uses. My "bun only" is for new projects.
- Dev: how dev starts, and which ports it really binds. Check them; Next ignores
PORTin.envfiles, for example. - Env: where dev config comes from. Usually the main checkout's untracked env files (
git rev-parse --git-common-dir), sometimes a folder like~/.<app>/dev-env. Separate dev values from production values, and from tokens a CLI pulled. - What must be isolated per checkout:
- Web: port and backend. For Convex,
convex dev --localor an anonymous local deployment. - Desktop: data folder, IPC or pipe names, hotkeys, registry entries, the updater, and my installed copy, which agents never touch.
- Name the shared backend that worktrees must stop pushing to.
- Web: port and backend. For Convex,
- Production: every surface and what ships each one. Push to
mainwith Vercel or CI,convex deploy, npm publish, tags and GitHub releases, an APK or installer build. Check whether pushing a non-main branch makes a preview, and what that costs (Convex preview quota). Read CI, AGENTS.md,docs/ops.md,git log, and my recent T3 threads where I said "merge and deploy" (t3_thread_list; search misses them) to see what actually worked. - Git flow: personal repos merge straight into
main; public ones go through a PR with CI, and my "ship" is the go to merge once CI passes. Take this from AGENTS.md ordocs/me.mdin my skill library.
2. The setup script
Write or extend scripts/setup.mjs, or the repo's equivalent, plus a doctor. Setup must:
- Be safe to rerun and fast. When nothing is missing it finishes in seconds.
- Copy dev env when it's missing. Refuse values that name production.
- Install dependencies when they're missing or older than the lockfile.
- Claim a port per surface. Derive it from a hash of the worktree path. Skip ports other worktrees have claimed, even ones not running now. Check that nothing answers on either
127.0.0.1or::1. Write it where dev really reads it, or wrap the dev command so it does. - Give the checkout its own backend, and make
devuse it.- Point the frontend env at the local backend.
- Change the dev script so nothing pushes to the shared backend by default.
- Keep any opt-in to the shared backend explicit, read-only for functions, and say what it's for (third-party keys the local one lacks).
- If isolation is impossible, say so in the skill and in the doctor output.
- Link the skills. Create the
.claude/skillslink (a junction on Windows). - Finish with the doctor and one summary line.
The doctor checks the same things read-only and prints the fix command for each failure. It also reports how far the checkout is behind origin/main. Add setup and doctor to the repo's scripts.
Give the repo a remove command too. On Windows, git worktree remove leaves the .claude\skills junction and the folder behind. Delete the junction with rmdir (never a recursive delete through it), stop the checkout's backend and dev process trees (taskkill /T /PID), then remove the worktree.
3. worktree-<app>
The description says to use it at the start of every task in a new worktree, whenever install, env, port or backend look wrong, and before giving a helper agent its own checkout. The body covers:
- The setup, doctor, dev and remove commands, and what a healthy summary looks like.
- Helpers.
git worktree addfromorigin/mainunder the same parent folder as T3's worktrees, then setup. One worktree and one backend per helper; never two agents in one checkout. - Never edit the main checkout. Say where it is.
- Cleanup. Stop only processes you started, by PID and with their children. Remove a worktree only when its work is merged or I say so, and never one that another live thread is using (check
t3_thread_list).
4. ship-<app>
The description says to use it only when I say ship, deploy, release, or merge and deploy. Each step is this repo's exact commands:
- Ready:
- The tree is clean and up to date with
origin/main. - The full check passes.
- Every changed feature was driven with
verify-<app>and has evidence. - List what's going out (
git log origin/main..HEAD) and which surfaces it touches. - Write down how to roll back.
- The tree is clean and up to date with
- Backend first: if landing deploys the frontend (Vercel on push), deploy schema and functions before landing.
- Land:
- Personal: fast-forward push from the worktree (
git push origin HEAD:main). Don't merge in the main checkout. - Public: open the PR, wait for CI, then merge.
- Personal: fast-forward push from the worktree (
- Deploy and release the surfaces this change touches: say what deploys on push, and run the rest (tags, releases, package publishes, app builds). When app code changed, the release is part of the ship, not a follow-up question. Watch each to the end; never end the turn while a build is queued or running.
- Check production with a read-only smoke test of each shipped surface: the URL, the version, release assets, and a probe that reads but never writes.
- Update the main checkout:
- If it's clean and on
main:git -C <main> pull --ff-only, then rerun setup there. In some repos this step is itself a deploy (globally linked skills); say so. - If it's dirty or on another branch: leave it alone and tell me.
- If it's clean and on
- Clean up: delete the merged branch locally and on the remote (not
gh pr merge --delete-branchinside a worktree). A thread can't remove its own worktree, so list it for removal later. - Report in a few lines: what shipped, to which surfaces, the evidence, and anything skipped or left.
Rules:
- Production needs my go in this conversation. "Ship" is that go for every step above, including cleanup: don't stop to ask between steps.
- When a step fails because of this change (a deploy limit, a failing check), fix it, rerun the checks and carry on. Stop and tell me only when the cause is outside the change or the fix needs my decision.
- Never force-push, never skip checks, and never raise a warning cap to get through.
5. Wire it in
- AGENTS.md: the setup, doctor and remove commands, plus two lines. "Every task in a new worktree starts with
worktree-<app>." "Ship only withship-<app>, when I say so." - T3: the worktree-create script must run setup.
- When project settings are folded (
projectSettingsFolded: truein~/.t3/userdata/settings.json), T3 reads scripts only fromprojectSettingsOverrides["<projectId>"].defaultProjectScripts. That list replaces the project's scripts, so carry the others over. - Use this entry:
{"id":"setup","name":"Setup","command":"<setup cmd>","icon":"configure","runOnWorktreeCreate":true,"async":false}. It runs in PowerShell. t3_project_updatewrites a field T3 ignores. The T3 project'sworkspaceRootmust be the git repo itself, or T3 can't make worktrees.- Back up
settings.json, then set it there, or tell me.
- When project settings are folded (
6. Cloud sessions
I also run tasks in cloud threads (megha: Claude Code on the web or Codex Cloud). A cloud VM is Linux with a bare clone: no global skills, no .claude/skills link, no deps. Make the repo start working there by itself:
scripts/cloud.mjs: exits at once unlessCLAUDE_CODE_REMOTE=true,CODEX_CIorCLOUD=1is set, so local sessions don't notice it. Otherwise:- Runs
curl -fsSL https://raw.githubusercontent.com/kausthubh-coder/skills/main/cloud/session.sh | bashwith stdout passed through: that's how the session gets my global skills and rules. - Runs the repo's setup with its output on stderr, so it doesn't flood the context. Setup must work on Linux, including the
.claude/skillssymlink and the per-checkout backend, and must not import a dependency at load time: it runs before the install. - Installs the browser the repo's Playwright version wants, if it uses Playwright.
- Prints one line: ready, or what failed.
- Runs
.claude/settings.json: a SessionStart hook runningnode scripts/cloud.mjs, with"timeout": 600. Codex: the repo's Codex environment setup script isCLOUD=1 node scripts/cloud.mjs.- Browsers: the VM has Playwright's Chromium under
$PLAYWRIGHT_BROWSERS_PATH, not Google Chrome, and its build may not match the repo's Playwright. One launcher module picks Chrome when installed, else that Chromium'sexecutablePath; every script and the doctor use it. Dev servers that scripts start run in their own process group, so stopping the group stops them on Linux. - AGENTS.md gets a
## Cloud sessionssection: what works there (setup, checks, headless verify, ship), what only works on my machine, and the names of any env vars the cloud environment needs. Never values. - Prove it from a new cloud thread on the pushed commit. Ask it to list its skills, run setup and the full check, drive one feature headless, and say what it couldn't do.
7. Prove both
- Worktree:
- Make a brand-new worktree with nothing in it and run setup.
- Run the doctor.
- Start dev in it next to a second worktree. Confirm the ports and backends differ: data written in one is missing from the other.
- Remove both with the remove command.
- If you set the T3 script, launch an idle T3 thread in a new worktree and check that setup ran (its terminal log is in
~/.t3/userdata/logs/terminals/).
- Ship: walk every step without doing anything that leaves the machine: print the push, deploy, publish and release commands instead of running them. Only actually ship when I asked for it.
- Report what you ran and what you saw. A flow that never ran is a draft.
04 同仓库更多 Skills
writing-for-agents
Write docs that agents read (skills, AGENTS.md, CLAUDE.md). Use when creating or editing a skill, or changing AGENTS.md or CLAUDE.md.
unslop
Make prose sound human, not AI-written. Use whenever you write a PR description, commit message, doc, README, release note, post, email or UI copy, or when asked to unslop or de-AI text.
tutor
Run a study session from my exam plan and progress files in the study repo. Use when I say study, teach me, quiz me, practice for an exam, or check whether I really understand a topic.
threads
Start, steer and read T3 threads on my laptop or Mac mini from either machine. Use to move a thread to the Mac, get a Windows check from the laptop, manage threads on both, or answer a message from the other machine.
statechart
Check a TLA+ model and draw it as a Mermaid statechart, with the shortest path to each broken rule. Use for /statechart, to read a TLC result, or to show a bug as a path through states.
sol-loop
Review a change with GPT Sol in a loop until we both agree. Use when I say "sol loop".