# Start Work

> Create a feature branch from a GitHub issue and set up the working context. Use whenever starting implementation on a new issue — creates the branch, fetches requirements, and begins building automatically. Use when this capability is needed.

- Skill: `tomevault-io/start-work-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/start-work-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/start-work-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/start-work-2

---


# Start Work

Create a feature branch from a GitHub issue and prepare the working context.

## Arguments

- `{issue}` — GitHub issue number (required). Pass as argument: `/start-work 42`

## Process

1. **Fetch issue details** — Read the issue title and body to understand the scope.
2. **Ensure clean working tree** — Check `git status` for uncommitted changes. Warn the user if the tree is dirty.
3. **Pull latest main** — Ensure the branch starts from the latest main.
4. **Create and checkout branch** — Use the naming convention below.
5. **Report** — Show the branch name and a summary of the issue tasks.

## Branch Naming Convention

```
{username}/{issue-number}-{short-slug}
```

Derive `{username}` from the git config `user.name` (lowercase, no spaces). Derive `{short-slug}` from the issue title (lowercase, hyphens, max 50 chars, no special characters).

Examples:
- `makigjuro/42-device-group-assignments`
- `makigjuro/15-bundle-versioning-api`

## Commands

Fetch the issue using MCP for structured data:

```
mcp__github-mcp-server__get_issue(owner: "signalbeam-io", repo: "signalbeam-edge", issue_number: {issue})
```

This returns structured JSON with title, body, labels, and state — no CLI parsing needed.

```bash
# Check working tree
git status --short

# Update main and create branch
git fetch origin main
git checkout -b {branch-name} origin/main
```

## After Starting — Automatic Implementation

Once the branch is created, **do not stop**. Immediately continue with implementation:

1. **Analyze the issue** — Parse acceptance criteria, identify affected services, and determine which layers need changes (Domain, Application, Infrastructure, Endpoints, Frontend, Tests).
2. **Create a task list** — Use TodoWrite to track each implementation step derived from the issue.
3. **Implement** — Follow the layer order: Domain → Application → Infrastructure → Endpoints → Frontend → Tests. Use the appropriate scaffolding skills (`/add-entity`, `/add-command`, `/add-query`, `/add-event-handler`, `/add-migration`, `/add-feature`) where they apply. Commit logically after each meaningful change.
4. **Verify as you go** — Run tests and architecture checks between steps. Fix issues before moving on.
5. **When done** — Run `/complete-task` to go through the full completion workflow (build, lint, tests, review, PR).

**Do not ask the user what to do next.** Read the issue, plan the work, and start building. Only ask clarifying questions if the issue has genuine ambiguity that blocks implementation.

## Output

After branch creation, report:
```
## Ready to Work

- Branch: `{branch-name}`
- Issue: #{issue} — {title}
- Labels: {labels}

### Acceptance Criteria
{parsed AC from issue}

### Implementation Plan
{task list derived from issue analysis}

Starting implementation...
```

## Error Handling

- **Dirty working tree:** List the uncommitted files and ask the user to commit or stash before proceeding.
- **Issue not found:** Verify the issue number and repo. Suggest checking with `gh issue view {number}`.
- **Branch already exists:** Ask the user if they want to check it out instead of creating a new one.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/signalbeam-io) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->