| name | start-task |
| description | Bootstrap a task into a synced feature branch — one shot, zero confirmations. Detects the source from the args: GitHub issue ('#100', 'issue 100', 'gh issue 100', or bare '100'), Jira key ('PROJ-42'), or a local spec file path; ad-hoc conversation otherwise. Fetches the task, derives {type}/{number}/{slug}, syncs the default branch, creates and pushes the branch, and writes specs/context/<id>.md. Use only when the user explicitly asks to start a task or create a work branch — never trigger automatically. |
| model | inherit |
| color | cyan |
Start-Task
Turn a task reference into a synced feature branch named
{type}/{number}/{slug} plus a context file at specs/context/<id>.md.
Zero confirmations on the happy path: detect → fetch → derive → execute → report.
1. Detect the source (no bash)
Match the args in this order:
- Jira —
[A-Z]+-\d+ (e.g. PROJ-42)
- GitHub issue — a numeric token, stripping any of
github, gh, issue, issues, #
- Local spec — a path ending in
.md, .txt, .yaml, .yml, or .json; reject any path containing ..
- Ad-hoc — nothing matched: ask once (a single question) for the task type, title, and identifier, then skip to step 3
2. Fetch (1 bash call)
GitHub:
gh issue view <ISSUE_NUM> --json title,labels --jq '{title: .title, labels: [.labels[].name]}'
Jira: which acli && acli jira issue view <KEY> — extract summary, type, key.
If acli is missing, hard-stop: the developer chose Jira; do not degrade to ad-hoc.
Local spec: read the file; extract title and scope. The identifier is the
developer-provided one or the filename stem.
On any fetch failure, hard-stop and print the error verbatim — no retries, no
paraphrasing, no follow-up questions.
3. Derive TYPE and SLUG (no bash)
TYPE — from GitHub labels (first match wins) or from the task's nature:
| Signal | TYPE |
|---|
bug, fix, hotfix | fix |
enhancement, feature | feat |
refactor | refactor |
docs, documentation | docs |
test, tests | test |
ci, github-actions | ci |
chore, deps, dependencies | chore |
| (no match) | feat |
SLUG — from the title: lower-case; drop articles, prepositions, and helper
verbs; keep the core action verb + object nouns; 2–4 words; hyphenated; only
[a-z0-9-].
Examples: "Add user authentication to the login form" → add-user-auth;
"Fix null pointer in payment processing flow" → fix-null-pointer-payment.
4. Execute
GitHub (1 bash call) — the script syncs the default branch, creates the
branch, writes and commits the context file on it, then pushes:
bash {base_directory}/gh-start-task.sh <ISSUE_NUM> <TYPE> <SLUG>
Non-zero exit → hard-stop, print stderr verbatim. It fails on a dirty working
tree by design — never stash or discard for the developer.
Jira / local / ad-hoc — do the same steps manually:
git status --porcelain
git fetch origin <default> && git checkout <default> && git pull origin <default>
git checkout -b <TYPE>/<ID>/<SLUG> && git push -u origin <TYPE>/<ID>/<SLUG>
If the branch already exists locally, switch to it instead of creating it.
Then write specs/context/<ID>.md with: identifier, title, type, source,
relevant details (description, acceptance criteria), and today's date. If the
file exists, update it in place — don't overwrite wholesale.
5. Report (no bash)
Branch: <TYPE>/<ID>/<SLUG>
Task: <ID> — <TITLE>
Context: specs/context/<ID>.md
Next:
/plan-requirements — capture WHAT and WHY
/plan-architecture — design the solution
/implement — start coding
You Must NOT
- Ask for confirmation on the happy path — ad-hoc's single intake question is the only interactive moment
- Stash, discard, or commit the developer's pre-existing uncommitted changes — hard-stop instead (the GitHub script committing the context file it just generated is the one sanctioned exception)
- Push to
main/master, or use --force on any push
- Paraphrase errors — print them verbatim so the developer gets the exact actionable message
- Fall back to ad-hoc when a chosen CLI tool is missing — fail clearly
- Trigger automatically — this skill is opt-in
