skills/init-free-agent/SKILL.md

name, description

name

description

init-free-agent

End-to-end workflow for delivering a new feature where the implementation runs inside a sandboxed iso-claude container instead of a host subagent — clean tree → PRD → branch → PRD-only PR → pick iso-claude agent → iso-claude implements (commits + pushes from inside the container) → host reviews → user reviews the review → merge. Use when the user says "start a new feature in an iso-claude agent", "kick off the free-agent workflow", or invokes /init-free-agent. Variant of /init-work that swaps the host implementation subagent for an iso-claude container session via the iso-claude MCP server.

Agentic feature workflow (free-agent variant)

Same eight steps as /init-work, with two changes:

• Step 4.5 (new): ask the user which iso-claude agent to use, from the live list returned by mcp__iso-claude__list_agents.
• Step 5 (modified): delegate implementation to a sandboxed iso-claude container via start_session / send_message / end_session with cwd: true, instead of launching a host Agent.

Everything else (preflight, clean main, PRD, branch, PR open, review, human checkpoint, merge) stays on the host. Do not skip steps. Do not collapse Step 7 — the human review of the agent's review is the load-bearing checkpoint.

This skill orchestrates other tools: /init-prd for Step 2, the mcp__iso-claude__* tools for Step 5, and /review for Step 6. The skill itself should not implement the feature — delegate.

What the iso-claude variant trades off

The container has node, claude, and git but no PHP, no composer, no docker, no glab. The implementation agent inside therefore cannot run composer code-quality, composer phpunit-isolated, or any docker-based test suite. Quality gates run on the host at Step 6 / Step 7 instead.

If the feature requires running the project's quality gates during implementation (e.g. iterating against a failing test), prefer /init-work instead.

Step 0: Preflight

Before doing anything destructive, check the basics. Stop and ask the user if any check fails.

• git rev-parse --is-inside-work-tree → must be true.
• git remote get-url origin → must succeed. Save the URL; you'll need it for host detection.
• Detect host from the origin URL (same logic as /init-work):
  • github.com → GitHub, CLI is gh.
  • gitlab.com or any host with gitlab in the FQDN, or known self-hosted GitLab (e.g. labs.gauntletai.com for this repo) → GitLab, CLI is glab.
  • codeberg.org or hosts running Gitea → Gitea, CLI is tea.
  • Anything else → stop and ask the user which host this is.
• Verify the host CLI is installed (command -v <cli>). If missing, stop.
• Verify the iso-claude MCP server is reachable: call mcp__iso-claude__list_agents. If the call errors, stop and ask the user to check that the MCP server is registered and the iso-claude repo is built (cd ~/Code/iso-claude/mcp-server && npm install && npm run build).
• Identify the main branch: git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'. Fall back to master then main if that fails.

Step 1: Land on a clean main/master

Make the working tree match origin's main branch with no local clutter.

1. Capture the current branch (git rev-parse --abbrev-ref HEAD).
2. Stash dirty state. If git status --porcelain is non-empty, run:

   git stash push --include-untracked --message "init-free-agent preflight $(date -u +%FT%TZ)"
   

   Tell the user explicitly that you are about to stash and what files are in scope — quote git status first. Do not silently stash.
3. Switch and update. git checkout <main> then git pull --ff-only origin <main>. If the pull fails (non-FF), stop and ask — do not force.

If the user objects to stashing, abort the skill and let them resolve it manually first.

Step 2: Run the PRD skill

Invoke the init-prd skill via the Skill tool. That skill interrogates the user in three rounds and writes docs/prds/<NNNN>-<slug>.md. Do not pre-fill answers from prior conversation context — the interrogation is the point.

When /init-prd finishes, capture two values from the file it created:

• The PRD number <NNNN> (the 4-digit prefix on the new file).
• The slug <slug> (everything after the prefix, before .md).

You will use these in Steps 3, 4, and 5.

Step 3: Branch off main

git checkout -b prd-<NNNN>-<slug>

If the branch already exists locally or on the remote, stop and ask — never silently reset or rebase someone else's branch.

Stage and commit the new PRD file:

git add docs/prds/<NNNN>-<slug>.md
git commit -m "docs(prd): scaffold PRD <NNNN> — <Working Title>

Assisted-by: Claude Code"

Push with upstream tracking:

git push -u origin prd-<NNNN>-<slug>

The PRD file is the only thing in this commit. No code, no scaffolding stubs.

Step 4: Open a PR with only the PRD

Same as /init-work Step 4 — open the PR against <main> from the new branch. Title format: PRD <NNNN>: <Working Title>. Use the host's CLI (gh / glab / tea). Capture the URL.

If the CLI is missing or auth fails, stop. Don't fall back to a different host's CLI; don't silently skip the PR step.

Step 4.5: Pick an iso-claude agent

Call mcp__iso-claude__list_agents. Present the full list to the user with a one-line note for each (read from iso-claude.json if needed) and ask them to pick one. Recommend implementer (or any agent the user has configured to forward a push token) when the work needs to commit and push. Other agents may not have GITLAB_TOKEN (or equivalent) wired into their env and will fail at the push step.

Stop and ask if the list is empty or the call errors.

Step 5: Delegate implementation to an iso-claude session

Open a new session and drive it via the MCP tools.

mcp__iso-claude__start_session(agent="<chosen>", cwd=true)
  → returns { handle, agent, session_id, created_at }

cwd: true causes the iso-claude launcher to copy the host's current project into /home/node/workspace inside the container and docker cp the host's .git directory in at run time. The agent inside therefore sees the current branch (prd-<NNNN>-<slug>), the PRD file, and the full history.

Send one send_message with a self-contained prompt that:

• Names the PRD file path (docs/prds/<NNNN>-<slug>.md) and the branch (prd-<NNNN>-<slug>) it must commit to.
• States that it is implementing this PRD's in-scope items only — open questions stay open, non-goals stay out.
• Tells it to commit and push as it works, once each semantically-distinct chunk of work is done (not per-file, not all-at-once at the end). Conventional Commit messages, Assisted-by: Claude Code trailer.
• Tells it to honor the workspace's CLAUDE.md for coding standards. Note that it cannot run the project's quality gates (composer code-quality, composer phpunit-isolated, the docker test suites, npm run lint:js) because PHP, composer, docker, and the project's node deps are not installed in the iso-claude image — those will run on the host at Step 6. The agent should still write code that would pass the gates.
• Tells it to push using GITLAB_TOKEN (or whatever the chosen agent has wired) without echoing or interpolating the token value. The recipe — git config --global credential.helper store plus ~/.git-credentials written via a here-doc / printf so the value never lands on argv — is in the agent profile's prompt.
• Tells it to stop and report when done — not to open or merge the PR, not to request review, not to bump versions. The skill drives those steps.
• Tells it to surface any blockers (open questions resurfacing, missing fixtures, ambiguous PRD wording) rather than guessing.

send_message returns a single SendResult after the agent emits its result event for the turn. There is no streaming visibility — the call blocks until the agent declares the turn finished. For real features this can take many minutes. Do not poll, do not retry, do not call again until the first call returns.

When send_message returns, do not end the session yet. First, on the host:

git fetch origin prd-<NNNN>-<slug>
git log HEAD..origin/prd-<NNNN>-<slug> --oneline   # verify the agent pushed something
git pull --ff-only origin prd-<NNNN>-<slug>        # bring the agent's commits to the host

If the fetch shows no new commits beyond the PRD scaffold, the agent didn't push. Send a follow-up send_message asking it to push (or to surface the error if push failed). Don't proceed until the host has the agent's commits.

Once the host is in sync:

mcp__iso-claude__end_session(handle="<handle>")

The container is removed.

Step 6: Delegate review to the host /review skill

Invoke the review skill via the Skill tool — it is the project's documented PR-review entry point. The host now has the agent's commits locally (Step 5 pulled them) and can run the project's quality gates that the iso-claude container could not.

If /review is unavailable, fall back to launching Agent (subagent_type=general-purpose) on the host with a prompt that:

• References the PR URL from Step 4 and the PRD file.
• Asks for a structured review: correctness vs. PRD, adherence to CLAUDE.md, test coverage of in-scope items, any security/PHI concerns flagged by project conventions.
• Is told not to push commits, not to fix issues, and not to merge — review only, written output only.

Capture the review output. Save it for Step 7.

Step 7: Review the review with the user (interactive)

Same as /init-work Step 7 — non-negotiable human-in-the-loop checkpoint.

Present the agent's review to the user in a readable form, then walk through it:

• For each finding, ask: accept (fix it), reject (false positive — explain why), or defer (file as a follow-up).
• Apply accepted fixes directly (or delegate small ones to a fresh Agent call on the host), commit and push them on the same branch. Fixes at this stage run on the host, not in a fresh iso-claude session — the goal is for the user to see the same commits the reviewer did.
• Reject false positives with a one-line note in your reply so the user can see the reasoning.
• Defer items get added to the PR description as a "Follow-ups" checklist (use the host's CLI to edit the PR body).

Do not move on to Step 8 until the user explicitly says "ship it" / "merge it" / "looks good". Open questions or ambiguity → stop and ask.

Step 8: Merge

Same as /init-work Step 8. Require explicit user confirmation in this turn. A "go ahead" from earlier in the conversation does not count.

Once confirmed, merge using the host's CLI:

• GitHub: gh pr merge --squash --delete-branch.
• GitLab: glab mr merge --squash --remove-source-branch.
• Gitea: tea pr merge --style squash --delete-branch.

Default to squash unless the user has expressed a different preference for this repo. After merge, return to <main> and git pull --ff-only.

If there is a stash from Step 1, remind the user it's still in git stash list and offer to git stash pop it.

Final report

One short paragraph naming:

• The merged PR URL.
• The PRD path.
• The iso-claude agent that did the implementation.
• Any deferred follow-ups recorded on the PR.
• The state of the Step 1 stash (popped, still pending, or none).

Hard rules

• Never skip Step 7. The human review of the agent review is non-negotiable. If the user wants to skip it, that's a different workflow — point them at it and stop.
• Never merge without explicit in-turn confirmation. Earlier "yes" answers don't carry across the implementation/review steps.
• Never silently stash. Always show git status and tell the user what's about to be stashed.
• Never end the iso-claude session before verifying the host has the agent's commits. If push didn't happen, the work is trapped in the container and lost when it's torn down.
• Never skip cwd: true on start_session. Without it the agent has no workspace and no git context.
• Never let the implementation agent open or merge the PR. Those are skill-driven steps, not agent-driven.
• Never fall back to a different host's CLI. If glab is missing on a GitLab repo, stop — do not use gh instead.
• Never collapse multiple PRDs into one branch. One PRD per invocation.
• Honor CLAUDE.md and existing skill outputs. The PRD that /init-prd produces is the source of truth for Step 5; don't rewrite it during implementation.