skills/init-work/SKILL.md

---
name: init-work
description: End-to-end workflow for delivering a new feature with agent assistance — clean tree → PRD → branch → PRD-only PR → agent implements → agent reviews → user reviews the review → merge. Use when the user says "start a new feature", "kick off the agentic workflow", or invokes /init-work. Orchestrates: a clean checkout, the /init-prd skill, branching, PR creation, an implementation Agent, a review Agent, an interactive review-of-review session with the user, and merge with explicit confirmation. Detects host (GitHub/GitLab/Gitea) from the origin URL.
---

# Agentic feature workflow

Eight steps. Run them in order. Do not skip steps. Do not collapse Step 7 into "I'll just merge it" — the human review of the agent's review is the load-bearing checkpoint.

This skill orchestrates other tools: it invokes `/init-prd` for Step 2, launches `Agent` for Steps 5 and 6, and invokes `/review` (via the Skill tool) where appropriate. The skill itself should not implement the feature — delegate.

## 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:
  - `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 CLI is installed (`command -v <cli>`). If missing, stop and ask the user to install it (or to run Step 4's PR-open command themselves). For OpenEMR specifically, CLAUDE.md says GitLab CLI access is not yet configured in this fork — if `glab` is missing, surface that note and stop.
- 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`) — useful if anything goes sideways.
2. **Stash dirty state.** If `git status --porcelain` is non-empty, run:
   ```bash
   git stash push --include-untracked --message "init-work 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. The stash is recoverable via `git stash list` / `git stash pop`, but the user should know it happened.
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 (says they have in-progress work elsewhere), 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>
```

Branch naming is `prd-<NNNN>-<slug>` (e.g. `prd-0001-ai-agent-service`). If the branch already exists locally, stop and ask — never silently reset or rebase someone else's branch. If a branch with that name exists on the remote, also stop and ask.

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"
```

Then 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, no "placeholder for later" files.

## Step 4: Open a PR with only the PRD

Open the PR against `<main>` from the new branch. The PR body should contain a one-line summary plus a link/reference to the PRD path. Title format: `PRD <NNNN>: <Working Title>`.

Pick the right CLI based on Step 0's host detection:

- **GitHub** (`gh`):
  ```bash
  gh pr create --base <main> --head prd-<NNNN>-<slug> \
    --title "PRD <NNNN>: <Working Title>" \
    --body "$(cat <<'EOF'
  Tracking PR for [PRD <NNNN>](docs/prds/<NNNN>-<slug>.md). Implementation will follow on this branch.
  EOF
  )"
  ```
- **GitLab** (`glab`):
  ```bash
  glab mr create --target-branch <main> --source-branch prd-<NNNN>-<slug> \
    --title "PRD <NNNN>: <Working Title>" \
    --description "Tracking MR for [PRD <NNNN>](docs/prds/<NNNN>-<slug>.md). Implementation will follow on this branch."
  ```
- **Gitea** (`tea`):
  ```bash
  tea pr create --base <main> --head prd-<NNNN>-<slug> \
    --title "PRD <NNNN>: <Working Title>" \
    --description "Tracking PR for [PRD <NNNN>](docs/prds/<NNNN>-<slug>.md). Implementation will follow on this branch."
  ```

Capture the URL the CLI prints. You'll reference it in the final report.

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 5: Delegate implementation to an Agent

Launch `Agent` (subagent_type=`general-purpose`) 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 after every file, not all-at-once at the end). Examples of "semantically distinct": a new service stub + its first passing test; a migration + the model that uses it; the seeder + a smoke test that runs it. Use Conventional Commit messages, `Assisted-by: Claude Code` trailer.
- Tells it to honor `CLAUDE.md` (PSR coding standards, `composer code-quality`, the testing workflow under `docker/development-easy`).
- Tells it to **stop and report** at the end — 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.

Run the implementation agent in the foreground — Step 6 depends on its output.

When the agent finishes, verify on the host:

- `git status` → working tree clean (the agent should have committed everything it touched).
- `git log <main>..HEAD --oneline` → at least one commit beyond the PRD scaffold.
- `git rev-parse @{u}` and `git rev-parse HEAD` → equal (it pushed).

If any of those fail, prompt the agent (or the user) to reconcile before moving on.

## Step 6: Delegate review to an Agent

Invoke the `review` skill via the Skill tool — it is the project's documented PR-review entry point. If for some reason `review` is unavailable, fall back to launching `Agent` (subagent_type=`general-purpose`) 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 (strict types, dependency injection, no `$GLOBALS`, PSR-3 logging context, etc.), test coverage of in-scope items, and any security/PHI concerns flagged by the codebase's 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)

This is the human-in-the-loop checkpoint. Present the agent's review to the user in a readable form, then walk through it with them:

- 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), commit and push them on the same branch.
- 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

Merging is irrevocable on a shared branch. **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` (or `--merge` / `--rebase` if the user prefers — ask if unsure).
- **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.
- 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 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. If the user wants a second feature, start the skill again from Step 0.
- **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.