feat: Claude Code native skill mode for agent-loop orchestration

SKILL.md

@@ -0,0 +1,227 @@
+# Agent Loop Skill — Claude Code Native Mode
+
+This skill lets you run the `coding-review-agent-loop` orchestration directly inside
+an interactive Claude Code session, without calling `claude -p` for Claude turns.
+
+Claude (you, the host) performs coder/plan turns using your active session context.
+External agents (Codex, Gemini) are invoked via their local CLIs as subprocesses.
+GitHub operations go through `gh`.
+
+## Prerequisites
+
+- `gh` authenticated and configured.
+- `codex` CLI installed (for Codex reviewer turns).
+- `gemini` CLI installed (for Gemini reviewer turns).
+- The `coding-review-agent-loop` package importable from `src/` (run from repo root).
+
+## How to start a plan loop for an issue
+
+Provide the following information:
+
+1. **Repository**: `OWNER/REPO`
+2. **Issue number**: e.g. `123`
+3. **Reviewers**: e.g. `codex`, `gemini`, or both
+
+Then follow the steps below.
+
+---
+
+## Orchestration steps
+
+### Step 1 — Check for an existing session
+
+```bash
+python -m helpers.state_manager build-resume \
+  --issue ISSUE --repo OWNER/REPO \
+  --reviewers codex gemini \
+  --flow plan
+```
+
+If `round_number` > 1 or `completed_reviewer_names` is non-empty, a prior round
+was found and you can skip already-completed reviewer turns.
+
+### Step 2 — Write the plan (Claude host turn)
+
+Write the implementation plan to a temp file, e.g.:
+
+```
+/tmp/agent-loop-skill/{session-id}/plan-{uuid}.md
+```
+
+The file must end with:
+
+```
+<!-- AGENT_PLAN_STATE: approved -->
+-- Anthropic Claude
+```
+
+### Step 3 — Validate the plan
+
+```bash
+python -m helpers.validate_response \
+  --file /tmp/agent-loop-skill/{session-id}/plan-{uuid}.md \
+  --kind plan_state
+```
+
+### Step 4 — Attach AGENT_LOOP_META to the plan comment
+
+The comment posted to GitHub must carry an `AGENT_LOOP_META` marker so that
+`build-resume` can reconstruct the round state in future sessions.  Use
+`attach-metadata` to produce a metadata-tagged version of the plan file:
+
+```bash
+python -m helpers.state_manager attach-metadata \
+  --body-file /tmp/agent-loop-skill/{session-id}/plan-{uuid}.md \
+  --output /tmp/agent-loop-skill/{session-id}/plan-tagged.md \
+  --flow plan --role coder --agent Claude \
+  --round-number {round_number} --state approved \
+  --subject-plan-file /tmp/agent-loop-skill/{session-id}/plan-{uuid}.md \
+  --canonical-plan-file /tmp/agent-loop-skill/{session-id}/plan-{uuid}.md \
+  [--prior-items-file /tmp/agent-loop-skill/{session-id}/prior_items.json]
+```
+
+`prior_items.json` is the `prior_items` array from the `build-resume` JSON
+output.  Omit the flag when `prior_items` is empty (round 1).
+
+### Step 5 — Save as pending comment and post
+
+```bash
+python -m helpers.state_manager write-pending-comment \
+  --issue ISSUE --repo OWNER/REPO \
+  --body /tmp/agent-loop-skill/{session-id}/plan-tagged.md
+```
+
+```bash
+python -m helpers.gh_ops post-issue-comment \
+  --issue ISSUE --file /tmp/agent-loop-skill/{session-id}/plan-tagged.md \
+  --repo OWNER/REPO
+```
+
+```bash
+python -m helpers.state_manager clear-pending-comment \
+  --issue ISSUE --repo OWNER/REPO
+```
+
+### Step 6 — Run each reviewer
+
+For each reviewer (e.g. Codex):
+
+```bash
+python -m helpers.run_external \
+  --agent codex \
+  --prompt-file /tmp/agent-loop-skill/{session-id}/reviewer-prompt.md \
+  --output /tmp/agent-loop-skill/{session-id}/codex-review.md \
+  --workdir /path/to/codex/checkout
+```
+
+Validate the reviewer response:
+
+```bash
+python -m helpers.validate_response \
+  --file /tmp/agent-loop-skill/{session-id}/codex-review.md \
+  --kind plan_review \
+  --context-file /tmp/agent-loop-skill/{session-id}/context.json
+```
+
+The `context.json` must contain:
+
+```json
+{
+  "reviewer": "Codex",
+  "prior_items": [...],
+  "current_round_items": [...]
+}
+```
+
+Attach AGENT_LOOP_META to the reviewer comment (subject must match the coder comment):
+
+```bash
+python -m helpers.state_manager attach-metadata \
+  --body-file /tmp/agent-loop-skill/{session-id}/codex-review.md \
+  --output /tmp/agent-loop-skill/{session-id}/codex-review-tagged.md \
+  --flow plan --role reviewer --agent Codex \
+  --round-number {round_number} --state approved \
+  --subject-plan-file /tmp/agent-loop-skill/{session-id}/plan-{uuid}.md \
+  [--prior-items-file /tmp/agent-loop-skill/{session-id}/prior_items.json] \
+  [--dispositions-file /tmp/agent-loop-skill/{session-id}/codex_dispositions.json]
+```
+
+Post the reviewer comment (with metadata):
+
+```bash
+python -m helpers.gh_ops post-issue-comment \
+  --issue ISSUE --file /tmp/agent-loop-skill/{session-id}/codex-review-tagged.md \
+  --repo OWNER/REPO
+```
+
+### Step 7 — Update session state
+
+```bash
+python -m helpers.state_manager write-session \
+  --issue ISSUE --repo OWNER/REPO \
+  --fields '{"last_completed_step": "post_review", "round_number": 1}'
+```
+
+### Step 8 — Decision
+
+- If all reviewers approved: implementation is complete.
+- If any reviewer blocked: perform a new plan revision and loop back to Step 2.
+- If clarification is needed: post an `<!-- AGENT_CLARIFY -->` comment and stop.
+
+---
+
+## PR review mode
+
+Use `--flow pr` with `build-resume` and pass `--pr PR_NUMBER` (or `--head-sha SHA`)
+to operate in PR-review mode. All other steps are the same, using `--kind pr_review`
+for validation.
+
+---
+
+## Billing and terms note
+
+This skill runs Claude turns inside your active interactive Claude Code session.
+Whether that counts as interactive or programmatic usage depends on Anthropic's
+current terms and product behavior at the time you run it.
+Do not use this skill to proxy one user's session to other users, to build
+unattended 24/7 automation, or in any way that violates Anthropic's usage policies.
+
+---
+
+## Session state location
+
+Session state is stored in:
+
+```
+~/.local/state/coding-review-agent-loop/skill-sessions/{owner-repo}/{issue}.json
+```
+
+This location is outside git checkouts, so it never dirties any working tree.
+
+---
+
+## Limitations
+
+- If Claude Code's session ends mid-loop, resume from the last posted GitHub comment
+  by re-running Step 1 with `build-resume`.
+- Long-running Codex/Gemini subprocess progress is not streamed; check the log
+  file in `/tmp/coding-review-agent-loop/skill-logs/` if a reviewer hangs.
+- The structured protocol (AGENT_LOOP_META markers, structured JSON responses)
+  must match the versions expected by the existing library in `src/`.
+
+---
+
+## Demo
+
+Run a minimal dry-run demo (no live GitHub or agent calls):
+
+```bash
+python -m helpers.demo_loop --issue 123 --repo demo/repo
+```
+
+Expected output includes:
+```
+validation passed: plan_state
+validation passed: plan_review
+demo_loop: all steps completed successfully
+```

docs/skill_mode.md

@@ -0,0 +1,137 @@
+# Claude Code Native Skill Mode
+
+## Overview
+
+`coding-review-agent-loop` includes a Claude Code skill that lets you run the
+multi-agent review loop directly inside an interactive Claude Code session
+instead of through `claude -p` subprocesses.
+
+| Aspect | Headless CLI mode | Skill mode |
+|--------|-------------------|------------|
+| Claude turns | `claude -p` subprocess (Agent SDK credits) | Active Claude Code session |
+| Codex turns | `codex exec` subprocess | Same `codex exec` subprocess |
+| Gemini turns | `gemini` subprocess | Same `gemini` subprocess |
+| GitHub ops | Python `gh` wrapper | Same `gh` wrapper |
+| Session resume | AGENT_LOOP_META in GitHub comments | Same markers + local session JSON |
+| Best for | Headless CI / unattended automation | Interactive development sessions |
+
+## Architecture
+
+```
+Claude Code (interactive session)
+│
+├── helpers/validate_response.py   ← validates structured protocol responses
+├── helpers/state_manager.py       ← session state + GitHub comment resume
+├── helpers/run_external.py        ← invokes codex/gemini CLIs
+├── helpers/gh_ops.py              ← GitHub issue/PR comment operations
+└── helpers/demo_loop.py           ← standalone dry-run demo
+```
+
+Claude performs coder/plan turns by writing files directly (using its Write
+tool or by producing structured JSON in its response).  External reviewers
+(Codex, Gemini) are still invoked as subprocesses via `run_external.py`.
+
+## Structured protocol compatibility
+
+The skill helpers reuse the same library entry points used by the headless CLI:
+
+- `_validate_plan_review_response` / `_validate_review_response` (unresolved_items)
+- `_resume_plan_round` / `_resume_pr_round` (round_state)
+- `parse_plan_state` / `validate_structured_plan_revision` (protocol)
+
+GitHub comment metadata markers (`AGENT_LOOP_META`) written by the skill are
+identical to those written by the headless CLI, so mixed-mode operation (start
+headless, resume in skill, or vice versa) is supported.
+
+## Session state
+
+Local session state is stored at:
+
+```
+~/.local/state/coding-review-agent-loop/skill-sessions/{owner-repo}/{issue}.json
+```
+
+This path is outside any git checkout so it never dirties a working tree.
+Fields written by `state_manager write-session`:
+
+| Field | Description |
+|-------|-------------|
+| `last_completed_step` | Most recently completed orchestration step |
+| `session_id` | Current skill session UUID prefix |
+| `round_number` | Current plan/PR round number |
+| `pending_comment_body` | Path to a comment body not yet posted |
+
+The `pending_comment_body` field provides crash recovery: if the session ends
+after writing the comment file but before posting it, the next `build-resume`
+call includes the path so Claude can re-post it.
+
+## Resume from existing round
+
+`state_manager build-resume` reads GitHub issue comments, extracts all
+`AGENT_LOOP_META` base64 blobs, calls `_resume_plan_round(comments,
+configured_reviewers=...)` or `_resume_pr_round(comments, head_sha=...,
+configured_reviewers=...)`, and outputs a JSON descriptor:
+
+```json
+{
+  "round_number": 2,
+  "prior_items": [...],
+  "compact_prior_summaries": [...],
+  "completed_reviewer_names": ["Codex"],
+  "pending_comment_body": null,
+  "current_plan": "..."
+}
+```
+
+The skill then skips already-completed reviewer turns and resumes from where
+the last session ended.
+
+**Important**: `--reviewers` must exactly match the configured reviewer list for
+the current invocation.  For PR-flow sessions, `--head-sha` or `--pr` is also
+required so `_resume_pr_round` can compare the current PR head SHA.
+
+## Billing and terms
+
+Running Claude turns inside an interactive Claude Code session may count
+differently toward billing than `claude -p` / Agent SDK invocations.  Whether
+this constitutes "interactive" or "programmatic" use depends on Anthropic's
+current terms and product behavior at the time of use.
+
+**Non-goals / constraints**:
+- Do not use this skill to proxy one user's session to other users.
+- Do not build unattended 24/7 automation that relies on pretending to be
+  interactive use.
+- Do not market this as free Claude access or billing bypass.
+- The existing headless `agent-loop` CLI path is unchanged and unaffected.
+
+## Install / setup for open-source users
+
+1. Clone the repository and install in development mode:
+   ```
+   pip install -e ".[dev]"
+   ```
+2. Copy or symlink `helpers/` and `SKILL.md` into your working directory
+   (or run from the repo root).
+3. Authenticate `gh` and install `codex` / `gemini` CLIs as needed.
+4. Run the demo to verify the install:
+   ```
+   python -m helpers.demo_loop --issue 123 --repo demo/repo
+   ```
+
+## Known limitations
+
+- Reviewer subprocess progress (Codex, Gemini) is not streamed to Claude's
+  terminal while the subprocess runs.  Check logs in
+  `/tmp/coding-review-agent-loop/skill-logs/`.
+- If the Claude Code session ends mid-loop, the next session must call
+  `build-resume` to reconstruct the round state from GitHub comments.
+- The structured protocol versions must match; update both the library and
+  the skill helpers together when the protocol evolves.
+- Future Antigravity CLI migration (#215) may require updates to
+  `run_external.py` when the `gemini` CLI name or interface changes.
+
+## Related
+
+- `SKILL.md` — step-by-step skill orchestration instructions for Claude.
+- Issue #216 — original exploration proposal.
+- Issue #215 — Antigravity CLI migration for Gemini CLI consumer users.

helpers/__init__.py

@@ -0,0 +1 @@
+# helpers package — Claude Code skill support scripts