agentleFS
notum-cznotum-cz/strapi-next-monorepo-starter/.claude/skills/start-work/SKILL.md

start-work

Skill316 starsChanged 5 months agoMITView on GitHub

Use when the user is ready to begin a new fix or feature and wants an isolated workspace — e.g. "start work on", "fix issue", "new feature", "begin task", "work on issue", "/start-work". Accepts a GitHub, Linear, or Jira issue (number, key, or URL) or a plain branch name.

18 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 5 are distinctive, and 12 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If $ARGUMENTS is empty, ask the user for an issue ref or a branch name.

    line 43
  2. Very specific:

    Check scripts/validate-branch-name.sh if present — its regex defines the required shape (this starter requires <type>/STAR-<n>-<slug>).

    line 55
  3. Very specific:

    Use it verbatim. Run scripts/validate-branch-name.sh (when present) against it before creating.

    line 59
  4. Distinctive:

    If the current branch matches the proposed/given name → reuse, skip Phase 3, jump to Phase 4.

    line 65
  5. Very specific:

    Default base branch: dev. Verify via git rev-parse --verify dev.

    line 70
  6. Very specific:

    If scripts/worktree/create.sh exists in the canonical repo root, call it:

    line 74
  7. Distinctive:

    If the script is absent:

    line 84
  8. Very specific:

    Use <branch-slug> = <branch> with / → - for the directory name.

    line 91
  9. Very specific:

    After the worktree exists, print its path.

    line 93
  10. Distinctive:

    Never create a worktree inside another worktree.

    line 97
  11. Very specific:

    Write .claude/plans/<branch-slug>.md (gitignored) with:

    line 101
  12. Very specific:

    If no issue was fetched, leave Summary as Manual task — no issue linked.

    line 129
  13. Distinctive:

    Keep the plan small. It is a working note, not a spec.

    line 131
  14. Distinctive:

    Stop there. Do not start implementing — that is the user's call (or another skill's job).

    line 146
  15. Very specific:

    Do not push the new branch.

    line 150
  16. Very specific:

    Do not run pnpm install yourself when the worktree script is absent — the user picks when to install.

    line 151
  17. Very specific:

    Never delete or reset existing worktrees.

    line 153

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “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

Start Work

Set up an isolated workspace for new work. Prefer a git worktree so the current checkout stays untouched. Fetch issue context when available, draft a short plan, then hand off to implementation.

Worktree mechanics + branch naming: apps/docs/docs/reference/workflow.md and worktree.config.json (manifest the scripts apply).

Be automated. Resolve arguments by shape, do not interrogate the user unless something is genuinely ambiguous (e.g. multiple plausible base branches, branch name fails the project's validation hook).

Phase 1 — Resolve $ARGUMENTS

Detect the tracker and ticket by shape — first match wins:

ShapeTrackerTicket
Pure digits (284), #284, or a github.com/.../issues/<n> URLGitHubissue <n>
linear.app/.../issue/<KEY> URLLinear<KEY>
<org>.atlassian.net/browse/<KEY> URLJira<KEY>
Bare key ABC-123 ([A-Z][A-Z0-9]+-\d+)Linear or Jira<KEY> — disambiguate below
Anything else—none — treat verbatim as a branch name, skip fetch

Bare keys are ambiguous between Linear and Jira. Resolve in order: the tracker whose MCP server is connected → ask the user once. (This starter's branch hook expects STAR-<n>, so a STAR-### key is the common case.)

Fetch issue context

  • GitHub → gh issue view <n> --json number,title,body,url,labels. Fall back if gh is missing or unauthenticated.
  • Linear → the connected Linear MCP server's get-issue tool.
  • Jira → the connected Atlassian (Jira) MCP server's get-issue tool.

For Linear and Jira, MCP is the only channel — never fall back to a REST API or env credentials, and never ask for or echo a token. If the tracker's MCP server isn't connected, skip the fetch, fall back to branch-name-only mode, and tell the user once (they can authenticate the connector with /mcp).

From whichever channel, capture: title, description/body, the key or number, the URL, and the issue type/labels.

If $ARGUMENTS is empty, ask the user for an issue ref or a branch name. Do not invent one.

Phase 2 — Determine the branch name

When the issue was fetched

Propose <type>/<ticket>-<slug>:

  • <ticket> — for Linear/Jira, the issue key verbatim (e.g. STAR-284); for GitHub, the issue number.
  • <type> — from issue type/labels: bug → fix; feature/enhancement/story/task → feat; default feat.
  • <slug> — lowercased, kebab-cased title, ≤ 5 words, ASCII only.

Check scripts/validate-branch-name.sh if present — its regex defines the required shape (this starter requires <type>/STAR-<n>-<slug>). A Linear/Jira STAR-### key satisfies it directly; a bare GitHub issue number will not, so ask the user once for the correct ticket id rather than inventing one.

When user passed a branch name

Use it verbatim. Run scripts/validate-branch-name.sh (when present) against it before creating; refuse early if it would be rejected.

Already inside a worktree?

Detect via git rev-parse --is-inside-work-tree + git rev-parse --git-common-dir differing from .git. If yes:

  • If the current branch matches the proposed/given name → reuse, skip Phase 3, jump to Phase 4.
  • Otherwise → ask: reuse current worktree (will switch branch in place) or create a new sibling worktree.

Phase 3 — Create the workspace

Default base branch: dev. Verify via git rev-parse --verify dev; fall back to main if missing.

Preferred: project worktree script

If scripts/worktree/create.sh exists in the canonical repo root, call it:

bash scripts/worktree/create.sh <branch> <base>

The script handles canonical-root resolution, env propagation, and pnpm install. Trust its exit code.

Fallback: plain git worktree add

If the script is absent:

git fetch origin <base>
git worktree add -b <branch> ../.worktrees/<branch-slug> <base>

Use <branch-slug> = <branch> with / → - for the directory name. Place at <repo-root>/../.worktrees/<slug> so worktrees stay siblings of the repo, not nested.

After the worktree exists, print its path. Do not cd for the user — print the command they'd run.

Refuse to nest

Never create a worktree inside another worktree. If the resolved target falls under an existing worktree path (git worktree list --porcelain to verify), abort with a clear message.

Phase 4 — Lay out an initial plan

Write .claude/plans/<branch-slug>.md (gitignored) with:

# <branch>

**Issue:** <url or "manual">
**Base:** <base-branch>
**Worktree:** <path>

## Summary

<2–4 sentences of issue body, paraphrased>

## Scope

- [ ] <first concrete step>
- [ ] <second>
- [ ] <third>

## Out of scope

- <known follow-ups not part of this task>

## Open questions

- <anything the issue leaves ambiguous>

If no issue was fetched, leave Summary as Manual task — no issue linked. and let the user fill Scope.

Keep the plan small. It is a working note, not a spec.

Phase 5 — Report

Print:

Branch: <branch>
Base:   <base>
Worktree: <path>
Issue:  <#num title> (or "no issue linked")
Plan:   .claude/plans/<branch-slug>.md
Next:   cd <path>  &&  open the plan

Stop there. Do not start implementing — that is the user's call (or another skill's job).

Notes

  • Do not push the new branch. make-pr handles that.
  • Do not run pnpm install yourself when the worktree script is absent — the user picks when to install. If the fallback path was used, mention it explicitly so they remember.
  • Supported trackers: GitHub, Linear, Jira. Asana and Azure DevOps are out of scope — for an untracked or unrecognized reference, fall back to branch-name-only mode and tell the user.
  • Never delete or reset existing worktrees. Hand off to scripts/worktree/cleanup.sh (when it exists) for that.

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.