agentleFS
tenstorrenttenstorrent/tt-studio/.claude/skills/feature-branch-pr/SKILL.md

feature-branch-pr

Skill52 starsChanged 31 days agoApache-2.0View on GitHub

Make a change in TT-Studio the team way: branch off `dev` with a `<username>/<feature>` branch, keep the diff minimal and in-scope, verify the running app via its health endpoints before pushing, leave every other branch untouched, and open a PR against `dev` with a human, professional title and description. Use whenever the user asks to start a feature/fix/branch, make a change and open a pull request, or "do this properly on a new branch" in this repo. Enforces no AI-tool attribution in commits, PR text, or review comments.

  • Reads credentials
  • Deletes or force-pushes
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Follow this when asked to make a change and/or open a PR in tt-studio.

    line 15
  2. Distinctive:

    Leave other branches alone: No checkout-and-edit of unrelated branches, no rebasing or deleting branches you didn't create for this task.

    line 26
  3. Distinctive:

    No AI attribution anywhere: Commit messages, PR titles/descriptions, and review comments must read as a human wrote them.

    line 28
  4. Very specific:

    Use the lowercased first name / email local-part (e.g.

    line 57
  5. Very specific:

    Always start from the latest dev, and remember where you came from:

    line 63
  6. Distinctive:

    If two approaches would both work, take the more minimal one — fewer files, fewer lines, less new machinery.

    line 78
  7. Very specific:

    Do not stage untracked files/dirs that aren't part of your change (e.g.

    line 86
  8. Distinctive:

    Tests (backend logic): Run the relevant suite, e.g.:

    line 110
  9. Distinctive:

    Do not proceed to commit/push until verification passes.

    line 120
  10. Distinctive:

    Remove anything added only to validate: debug prints, temporary logging, scratch test files, commented-out experiments.

    line 125
  11. Distinctive:

    Never git add -A blindly. Stage explicit paths, then audit:

    line 131
  12. Distinctive:

    Leave the tree as you found it:

    line 194

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

TT-Studio Feature Branch + PR Workflow

Follow this when asked to make a change and/or open a PR in tt-studio. The goal is a small, verified, professional change that touches nothing it shouldn't.

Guardrails (always true)

  • Base everything on dev. Features branch off dev and PRs target dev. main is production/tagged code only — never branch a feature off it or open a feature PR against it.
  • Never commit on dev or main directly, and never git push --force (or --force-with-lease) to a shared branch.
  • Leave other branches alone. No checkout-and-edit of unrelated branches, no rebasing or deleting branches you didn't create for this task.
  • No AI attribution anywhere. Commit messages, PR titles/descriptions, and review comments must read as a human wrote them. Do not add Co-Authored-By trailers for AI tools and do not mention "Claude", "Claude Code", "Cursor", "AI assistant", or similar.

Workflow checklist

Copy this and tick as you go:

- [ ] 1. Identify the username
- [ ] 2. Branch off dev
- [ ] 3. Make the minimal change
- [ ] 4. Verify (endpoints / tests)
- [ ] 5. Clean up instrumentation
- [ ] 6. Stage only intended files
- [ ] 7. Commit (human message)
- [ ] 8. Push + open PR against dev
- [ ] 9. Return to the original branch

1. Identify the username

Derive the branch prefix from git config:

git config user.name; git config user.email

Use the lowercased first name / email local-part (e.g. johnsingh@... → john). If it's ambiguous, ask the user which prefix to use. This repo's convention is <username>/<feature> (e.g. john/ttft-fix).

2. Branch off dev

Always start from the latest dev, and remember where you came from:

ORIG=$(git branch --show-current)        # so you can return in step 9
git fetch origin
git checkout -b <username>/<short-kebab-feature> origin/dev

Pick a short, descriptive kebab-case feature name (reset-view-fix, p100-support). Confirm git status is clean before editing.

3. Make the minimal change

  • Touch only the files required for the stated task. No drive-by refactors, no reformatting, no unrelated renames, no dependency bumps "while we're here."
  • If two approaches would both work, take the more minimal one — fewer files, fewer lines, less new machinery.
  • New code files (.py / .ts / .tsx / .js) must carry the SPDX headers required by .cursor/rules/general.mdc:
    # SPDX-License-Identifier: Apache-2.0
    # SPDX-FileCopyrightText: © 2026 Tenstorrent AI ULC
  • Do not stage untracked files/dirs that aren't part of your change (e.g. fastapi_logs/, local .env, editor scratch).

4. Verify before pushing

Verification is mandatory before any push. Pick what fits the change:

Running app (code changes). Bring the stack up and confirm services are healthy:

python run.py --dev
ServiceHealth check
Backend (Django)curl -f http://localhost:8000/up/ → 200
Backend model APIcurl -f http://localhost:8000/models/health/
Inference server (FastAPI)curl -f http://localhost:8001/health → {"status":"ok",...}
Frontend (Vite)curl -f http://localhost:3000/ → HTML

Then exercise the specific endpoint/flow your change affects and confirm the new behavior actually works (don't just trust that it compiles).

Tests (backend logic). Run the relevant suite, e.g.:

cd app/backend && pytest model_control/test_model_api.py -v

Docs / config-only changes. App endpoint checks are N/A — instead state that explicitly and validate the artifacts you changed (frontmatter parses, links resolve, content is correct).

Do not proceed to commit/push until verification passes. If it can't be verified (e.g. needs hardware), say so explicitly rather than implying it was checked.

5. Clean up instrumentation

Remove anything added only to validate: debug prints, temporary logging, scratch test files, commented-out experiments. The committed diff should contain only the intended change.

6. Stage only intended files

Never git add -A blindly. Stage explicit paths, then audit:

git add <path> <path>
git status
git diff --cached

Confirm the staged set is exactly your change — nothing unrelated, no stray untracked dirs.

7. Commit with a human message

Imperative, specific, professional. Describe what changed and why, as a teammate would. No AI attribution, no Co-Authored-By AI trailers. Use the same Conventional Commits form as the PR title (step 8) so a squash-merge reads cleanly either way.

git commit -m "fix: hide board reset button while a model is deployed"

8. Push and open the PR against dev

The PR title must follow Conventional Commits — <type>(<optional scope>): <subject>. CI (Validate PR Title) rejects anything else, and since the repo squash-merges, this title becomes the commit message on dev. Allowed types are listed in CONTRIBUTING.md: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, release. The subject after the type still has to read like a teammate wrote it — lowercase, imperative, specific:

fix: hide board reset button while a model is deployed
feat(ui): add Wan2.2 video model to the deploy list
git push -u origin <username>/<short-kebab-feature>
gh pr create --base dev \
  --title "<type>(<scope>): <human, specific subject>" \
  --body "<what changed, why, and how it was verified>"

(release: vX.Y.Z and the bare Rc vX.Y.Z title are for rc-* release PRs into main only — not for feature work.)

PR description guidance: keep it short and human — a few plain sentences on what changed and why, then a simple to-do list of the changes (and how they were verified). No walls of text, no section headers, no AI mention. Example:

Board reset button was clickable mid-deploy and could wedge the chip.

- [x] Hide reset button while a model is deployed
- [x] Verified against /up/ and the deploy flow

The repo squash-merges into dev; leave the merge to a human reviewer unless the user explicitly tells you to merge.

9. Return to the original branch

Leave the tree as you found it:

git checkout "$ORIG"

Anti-patterns

  • Don't branch off main or off whatever branch happens to be checked out — always origin/dev.
  • Don't bundle unrelated cleanups into the PR. Minimal and in-scope.
  • Don't push without verifying, or claim verification you didn't run.
  • Don't force-push, rebase shared branches, or modify branches you didn't create.
  • Don't mention Claude / Claude Code / AI tooling, or add AI co-author trailers, in commits, PR text, or review comments.
  • Don't open a PR with a prose title (Hide board reset button...) — commitlint fails it. Prefix a Conventional Commits type: fix: hide board reset button....

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.