start-issue

vkehfdl1/marshroom

Start working on a Marshroom cart issue — creates branch, injects context, updates status to running

What is start-issue?

Automates the setup for working on a Marshroom cart issue by creating a feature/hotfix branch, updating the issue status to running, and injecting issue context. Use this when you're ready to begin work on a tracked issue in your Marshroom workflow.

Reads the Marshroom state file and filters cart entries matching the current repository
Creates and checks out a feature or hotfix branch with proper naming (Feature/#N or HotFix/#N)
Updates the issue status to 'running' in state.json (via `marsh start` or atomic jq write)
Injects issue body context so you have full details about what needs to be done
Ensures main branch is up to date before creating the working branch
Offers to start planning the issue resolution after setup completes

How to install start-issue

npx skills add https://github.com/vkehfdl1/marshroom --skill start-issue

Prerequisites

Marshroom installed and configured with a state.json file at ${MARSHROOM_STATE:-~/.config/marshroom/state.json}
Git repository with a remote URL configured
At least one issue in your Marshroom cart matching the current repository

Claude Code

Cursor

Windsurf

Cline

How to use start-issue

1.Ensure you are in the repository where you want to work on an issue
2.Run the skill with an optional issue number (e.g., `start-issue 42`) or without arguments to select from matching cart entries
3.The skill will create and checkout the appropriate branch (Feature/#N or HotFix/#N)
4.Review the injected issue details displayed under 'Issue Details'
5.Confirm the branch creation and status update, then approve to begin planning

Use cases

Good for

Begin work on a tracked issue from your Marshroom cart in the current repository
Automatically set up branch and context when switching between multiple cart issues
Ensure issue status stays synchronized across your workflow without manual updates
Quickly access issue details and requirements without switching to another tool

Who it's for

Developers using Marshroom for issue tracking and cart management
Teams coordinating work across multiple repositories with shared issue carts
Developers who want automated branch creation and status updates

start-issue FAQ

What if there are multiple issues in the cart for this repository?

The skill will list all matching issues and ask you to select which one to work on by number.

What if the `marsh` command is not available?

The skill falls back to using `jq` to atomically update the state.json file directly, ensuring the status is still set to 'running'.

Will this affect my current uncommitted changes?

The skill checks out main and creates a new branch, so ensure your current work is committed or stashed before running it.

What branch naming convention does this use?

Branches are named Feature/#N for regular issues or HotFix/#N for hotfixes, where N is the issue number.

Can I specify which issue to work on without being prompted?

Yes, pass the issue number as an argument (e.g., `start-issue 42`) to skip the selection prompt.

Full instructions (SKILL.md)

Source of truth, from vkehfdl1/marshroom.

name: start-issue description: Start working on a Marshroom cart issue — creates branch, injects context, updates status to running

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

Read ${MARSHROOM_STATE:-~/.config/marshroom/state.json} and parse the JSON
Extract the cart array. If the cart is empty, tell the user to add issues in the Marshroom app
Run git remote get-url origin to get the current repo's remote URL
Extract owner/repo from the remote URL (handle both HTTPS and SSH formats)
Filter cart entries where repoCloneURL (HTTPS) or repoSSHURL (SSH) matches the current remote. Compare by extracting owner/repo from each
If no matching cart entries, tell the user this repo has no cart issues
If $ARGUMENTS contains an issue number, find that entry; otherwise if multiple matches, list them and ask the user to pick one
Run git checkout main && git pull origin main to ensure main is up to date
Create and checkout the branch: git checkout -b {branchName} The branch name should be Feature/#N or HotFix/#N. N is issue number.

Update issue status (MANDATORY):

First try: marsh start #{issueNumber}

If marsh is not found in PATH, fall back to direct atomic update:

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

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
Confirm the branch was created and display:
- Issue: #{issueNumber} {issueTitle}
- Branch: {branchName}
- Repository: {repoFullName}
- Status: running
Ask the user permission to start planning to resolve issue. If the user allows it, starts planning using /plan mode.