skills/init-free-agent/SKILL.md

---
name: init-free-agent
description: 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:
   ```bash
   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

```bash
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:

```bash
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:

```bash
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.

```text
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:

```bash
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:

```text
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.