software-factory-scheduling

Software Factory Scheduling

Use this skill whenever you need to pick the next issue to work on in a software-factory target realm, or when you need to transition an issue's status as you start, finish, or get stuck on it. This is the loop control logic the orchestrator used to own; in the interactive Claude Code flow the agent owns it.

When you use this skill

The user pointed you at a target realm and asked you to work the factory backlog. You are about to:

• Search the realm for Issue cards.
• Decide which one to pick up next.
• Set its status to in_progress, work it (per the software-factory-bootstrap or software-factory-operations skill, depending on issueType), then mark it done or blocked.
• Repeat until no eligible issues remain.

First: verify boxel is installed

The user is expected to have @cardstack/boxel-cli installed (see the runbook prerequisites). Verify it before any boxel <cmd> invocation:

boxel --version
help_output="$(boxel --help)"
for cmd in lint parse test; do
  echo "$help_output" | grep -qE "^[[:space:]]+$cmd[[:space:]]" || {
    echo "boxel --help is missing the \`$cmd\` subcommand."
    echo "Ask the user to install or upgrade @cardstack/boxel-cli:"
    echo "  pnpm i -g @cardstack/boxel-cli"
    exit 1
  }
done

If verification fails, stop and report. Don't try to install boxel yourself.

Picking the next issue

1. Search the target realm for every Issue card. The Issue card-type is published by the source realm's darkfactory module. Construct the search query with the live tracker module URL (see "Discovering the tracker module URL" below):

   boxel search --realm <target-realm-url> --query '{
     "filter": {
       "type": { "module": "<tracker-module-url>", "name": "Issue" }
     }
   }' --json
   

2. Filter to eligible issues. An Issue is eligible if all of the following are true:

   • attributes.status is "backlog" or "in_progress".
   • Every Issue listed in relationships.blockedBy.*.links.self has attributes.status === "done". Resolve each blockedBy links.self against the parent issue's id (it's a relative path like ../Issues/foo); the resulting URL matches the blocker's id from the search index.
   • You haven't already tried this issue and exhausted your turn budget on it in the current run.