Running Issues

import { Aside } from ‘@astrojs/starlight/components’;

cspace can process GitHub issues in batch — hand a list of issue numbers (or all issues labeled ready) to the coordinator, and it spins up isolated containers, resolves dependencies, and ships PRs.

There are two entry points: /run-issues for an explicit list, and /run-ready for label-based automation.

Run specific issues

The /run-issues skill takes a list of issue numbers and hands them to the coordinator.

Step 1: Parse the issue list

Extract issue numbers from your message and confirm with a one-line summary per issue:

for n in 281 282 283; do
  gh issue view $n --json number,title,state \
    --jq '"#\(.number) \(.title) [\(.state)]"'
done

If any issues are already closed, they’re surfaced so you can decide whether to skip them.

Step 2: Feature branch decision

• Default: no feature branch. Each issue creates its own PR targeting main.
• Feature branch — only if you request it, the issues share a milestone, or they have inter-dependencies.

Don't worry about scanning for dependencies yourself — the coordinator reads each issue body and builds a dependency graph as Phase 0 of its playbook.

Step 3: Launch the coordinator

Write the instruction prompt to a file (never inline — see prompt gotchas) and launch:

cat > /tmp/coord-issues.txt <<'PROMPT'
Work on these GitHub issues, each independently targeting main:
#281, #282, #283

Each issue gets its own container and PR. Merge order does not matter.
PROMPT

cspace coordinate --prompt-file /tmp/coord-issues.txt

The instruction prompt should include:

• The list of issue numbers
• The base branch (main, or a feature branch)
• Anything not self-evident from the issues (e.g., “skip E2E for these”, “merge into feature/foo”, “stop if #281 fails”)

Example with a feature branch and sequencing hint:

cat > /tmp/coord-issues.txt <<'PROMPT'
Work on these issues targeting feature/interview-improvements:
#535, #540

Follow the coordinator playbook. If you discover #540 needs
#535's changes, sequence them yourself.
PROMPT

cspace coordinate --prompt-file /tmp/coord-issues.txt

Run in the background with a 60-minute timeout.

Step 4: Monitor and report

When the coordinator completes, read its output and review the final summary. If it failed, the coordinator is resumable — re-running with the same --name picks up where it left off.

Run ready-labeled issues

The /run-ready skill automatically fetches all open issues with the ready label and hands them to the coordinator.

Step 1: Fetch ready issues

The label name comes from your .cspace.json configuration (agent.issue_label, default: "ready"):

LABEL=$(jq -r '.agent.issue_label // "ready"' .cspace.json 2>/dev/null || echo "ready")

gh issue list --label "$LABEL" --state open \
  --json number,title,labels,milestone \
  --jq '.[] | "#\(.number) \(.title) [\(.labels | map(.name) | join(", "))]"'

If no issues are found, the workflow stops.

Steps 2–4: Branch, launch, and monitor

The remaining steps follow the same process as /run-issues above — feature branch decision, launch the coordinator with the ready issue numbers, and monitor the results.

Step 5: Clean up labels

After all PRs are created, remove the ready label from processed issues:

gh issue edit 538 --remove-label "ready"
gh issue edit 537 --remove-label "ready"

Configuring the issue label

The label used by /run-ready defaults to "ready" but can be changed via the agent.issue_label key in .cspace.json. See Configuration Reference for details.

Comparison

Feature	/run-issues	/run-ready
Input	Explicit list of issue numbers	All open issues with configured label
Label required	No	Yes (agent.issue_label, default "ready")
Label cleanup	No	Yes — offers to remove label after PR creation
Coordinator	Same coordinator playbook	Same coordinator playbook
Resumable	Yes	Yes

Both workflows use the same coordinator under the hood. The only difference is how issues are selected — explicit list vs. label query.