Start Issue
Pull the next Marshroom cart issue for this repo, sync main, create Feature/HotFix branch, and atomically mark the issue running in state.json.
Overview
start-issue is an agent skill most often used in Build (also Ship review prep) that starts a Marshroom cart issue by branching and marking it running in state.json.
Install
npx skills add https://github.com/vkehfdl1/marshroom --skill start-issueWhat is this skill?
- Matches cart entries to current origin owner/repo via HTTPS or SSH URLs
- Mandates checkout main, pull, then branch Feature/#N or HotFix/#N
- Hard requirement: set issue status to running in Marshroom state.json or stop on failure
- Supports marsh start CLI with jq atomic-write fallback in step 10
- Resolves $ARGUMENTS issue number or prompts when multiple cart items match
- 10 documented steps including mandatory state.json update
- Branch pattern Feature/#N or HotFix/#N tied to issue number
Adoption & trust: 1.2k installs on skills.sh; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have issues in the Marshroom cart but no enforced agent ritual that syncs main, names the branch, and updates running status before coding.
Who is it for?
Repos already connected to Marshroom with cart issues and a developer who wants git plus state updates in one agent invocation.
Skip if: Projects without Marshroom state.json, repos with no matching cart entries, or workflows that skip mandatory issue status tracking.
When should I use this skill?
User wants to start working on a Marshroom cart issue in the current repository.
What do I get? / Deliverables
You land on the correct Feature or HotFix branch with main refreshed and the cart issue marked running, ready for implementation commits.
- Checked-out Feature/#N or HotFix/#N branch
- Cart issue status set to running in state.json
- User-visible error if state update fails
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because the skill starts implementation work from a queued issue—the moment coding PM meets git execution. PM subphase matches issue selection, branch naming (Feature/#N or HotFix/#N), and cart-to-repo matching before any feature code lands.
Where it fits
Select issue #42 from the cart, pull main, and open Feature/#42 before writing code.
Match repoCloneURL to origin so only this repository’s cart rows are considered.
Spin a HotFix/#N branch from an urgent cart item right before a release patch.
Resume the next queued improvement after shipping without re-entering issue metadata by hand.
How it compares
Use instead of manual git checkout when Marshroom cart context and running status must stay in sync with the app.
Common Questions / FAQ
Who is start-issue for?
Solo and indie builders using Marshroom to queue GitHub issues who want their coding agent to start work with correct branches and state.
When should I use start-issue?
In Build pm when picking up the next cart ticket, at the start of a hotfix, or in Ship launch prep when resuming a running issue after main was updated.
Is start-issue safe to install?
It mutates local git state and Marshroom JSON—review the Security Audits panel on this page and confirm state.json paths before granting shell and git access.
SKILL.md
READMESKILL.md - Start Issue
Start working on a Marshroom cart issue in the current repository. ## Critical Requirements - **state.json update is MANDATORY**. After creating the branch, you MUST update the issue status to `running` in `${MARSHROOM_STATE:-~/.config/marshroom/state.json}`. If this fails, stop and report the error — do NOT silently continue. - Use `marsh start` if available; otherwise fall back to direct `jq` atomic write (see step 10). ## Steps 1. Read `${MARSHROOM_STATE:-~/.config/marshroom/state.json}` and parse the JSON 2. Extract the `cart` array. If the cart is empty, tell the user to add issues in the Marshroom app 3. Run `git remote get-url origin` to get the current repo's remote URL 4. Extract `owner/repo` from the remote URL (handle both HTTPS and SSH formats) 5. Filter cart entries where `repoCloneURL` (HTTPS) or `repoSSHURL` (SSH) matches the current remote. Compare by extracting `owner/repo` from each 6. If no matching cart entries, tell the user this repo has no cart issues 7. If `$ARGUMENTS` contains an issue number, find that entry; otherwise if multiple matches, list them and ask the user to pick one 8. Run `git checkout main && git pull origin main` to ensure main is up to date 9. Create and checkout the branch: `git checkout -b {branchName}` The branch name should be `Feature/#N` or `HotFix/#N`. `N` is issue number. 10. **Update issue status (MANDATORY)**: - First try: `marsh start #{issueNumber}` - If `marsh` is not found in PATH, fall back to direct atomic update: ```bash STATE_FILE="${MARSHROOM_STATE:-~/.config/marshroom/state.json}" TMP="$(mktemp "${STATE_FILE}.XXXXXX")" jq --argjson n ISSUE_NUMBER '.cart |= map(if .issueNumber == $n then .status = "running" else . end)' \ "$STATE_FILE" > "$TMP" && mv -f "$TMP" "$STATE_FILE" ``` - Verify the update succeeded by reading state.json and confirming status is `running` 11. Inject issue context: - Read the `issueBody` field from the matched cart entry - If non-null, display it under a "## Issue Details" header - This gives the agent full context about what needs to be done 12. Confirm the branch was created and display: - Issue: #{issueNumber} {issueTitle} - Branch: {branchName} - Repository: {repoFullName} - Status: running 13. Ask the user permission to start planning to resolve issue. If the user allows it, starts planning using /plan mode.