feat: PR review feedback helper (gh) and workflow docs

Made-with: Cursor

Author: amit221

.env.example

@@ -24,6 +24,9 @@ GITHUB_TOKEN=
 
 # Discovery, filters, and agent model are fixed in src/orchestrator.py (top-level constants).
 
+# Optional: output file for `python pr_review.py` when --output is omitted (PR review follow-up).
+# IYNX_PR_REVIEW_FEEDBACK_PATH=
+
 # Optional: append-only JSON Lines log for supervising agents (see README). Empty or 0 disables.
 # IYNX_PROGRESS_JSONL=.iynx-run-progress.jsonl
 

README.md

@@ -155,6 +155,30 @@ Use **`IYNX_PR_LABEL`** when running the agent so new PRs get the same label and
 
 **Exit codes:** `0` success; `1` config/usage; `2` GitHub HTTP/network error after retries.
 
+### PR review follow-up (GitHub)
+
+After maintainers comment on an open PR, dump review threads into a **local markdown file** for an agent (or you) to implement fixes. Uses **`gh` only** (no direct GitHub REST in this tool). Install and authenticate [GitHub CLI](https://cli.github.com/) on the host.
+
+**Default output:** `<contribution-repo>/.iynx/pr-review-feedback.md` — only if that path is **gitignored** in the target repo; otherwise pass **`--output`** or set **`IYNX_PR_REVIEW_FEEDBACK_PATH`**. **Do not commit** that file.
+
+```bash
+# From inside the contribution clone (branch can be set with gh pr checkout)
+cd workspace/owner-repo
+python ../pr_review.py https://github.com/owner/repo/pull/42
+
+# Or explicit repo + number (from any cwd; use --output if not in a git repo)
+python pr_review.py --repo owner/repo --pr 42 -o /tmp/pr-review-feedback.md
+
+# PowerShell example with explicit output
+python pr_review.py "https://github.com/owner/repo/pull/42" --output "$env:TEMP\pr-review-feedback.md"
+```
+
+**Clone / checkout (normalize first):** from the contribution repo, run `git fetch` and `gh pr checkout <N>` (same PR as your branch). If you have no clone yet, clone the **head** repository from `gh pr view <url> --json headRepository,baseRepository`, add `upstream` when the PR is from a fork, then `gh pr checkout`.
+
+**Exit codes:** `0` file written; `1` usage or local validation (e.g. default path not gitignored); `2` `gh`/GitHub error.
+
+See `skills/issue-fix-workflow.md` § PR review follow-up and `docs/superpowers/specs/2026-03-24-pr-review-followup-design.md`.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -166,6 +190,7 @@ Use **`IYNX_PR_LABEL`** when running the agent so new PRs get the same label and
 | `IYNX_STATS_NO_LABEL` | No | If `1`/`true`, same as `python stats.py --no-label` (author + branch only; no label in search) |
 | `IYNX_STATS_BRANCH_REGEX` | No | Override branch regex for `stats.py` (default matches `fix/issue-<n>`) |
 | `IYNX_STATS_AUTHOR` | No | GitHub login for `stats.py` (default: token’s user) |
+| `IYNX_PR_REVIEW_FEEDBACK_PATH` | No | Output path for `python pr_review.py` when `--output` is omitted (same effect as `--output`; use to write without a local clone). For the default `.iynx/pr-review-feedback.md` path, you still need a repo root and a gitignored target unless you set this to a path outside the repo |
 | `IYNX_PROGRESS_JSONL` | No | Path to JSONL progress file; empty/`0`/`false` disables the file |
 | `IYNX_DOCKER_TTY` | No | If `1` (default), `docker run -t` for streamed steps so Cursor CLI output is line-buffered to the host; set `0` if `-t` fails (e.g. some CI) |
 | `IYNX_DOCKER_TRACE` | No | If `1` (default), every Docker shell step prints `[iynx-docker]` timestamp lines (clone, bootstrap, `cursor-agent`, verify, PR) so `docker logs` / host `[docker]` lines show clear phases; set `0` to silence |
@@ -194,8 +219,10 @@ iynx/
 │   ├── bootstrap.py    # Generate .cursor-agent per repo
 │   ├── workflow_progress.py  # JSONL progress for agents
 │   ├── pr_stats.py     # GitHub PR stats CLI (label + branch filter)
+│   ├── pr_review_followup.py  # PR review → markdown (`gh` only)
 │   └── pr.py           # Fork + push + gh pr create
 ├── stats.py            # Entry: PR statistics (`python stats.py`)
+├── pr_review.py        # Entry: PR review feedback file (`python pr_review.py`)
 ├── skills/
 │   └── issue-fix-workflow.md
 ├── tests/               # pytest (discovery + GitHub checks)

pr_review.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+Write PR review feedback to markdown (gh CLI only).
+
+Usage:
+  python pr_review.py https://github.com/owner/repo/pull/42
+  python pr_review.py owner/repo#42
+  python pr_review.py --repo owner/repo --pr 42
+  python pr_review.py 42 --repo owner/repo
+"""
+
+import os
+import sys
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+
+def _ensure_src_on_path() -> None:
+    src = os.path.join(_ROOT, "src")
+    if src not in sys.path:
+        sys.path.insert(0, src)
+
+
+if __name__ == "__main__":
+    import run as run_module
+
+    run_module.load_dotenv_if_present(_ROOT)
+    _ensure_src_on_path()
+    from pr_review_followup import main
+
+    raise SystemExit(main())

skills/issue-fix-workflow.md

@@ -98,6 +98,68 @@ Check `CONTRIBUTING.md`, `README.md`, or CI config for the actual commands.
 - **Disclaimer**: Mention AI involvement if the repo asks for it
 - **Scope**: Use scopes the repo's PR lint allows (check `.github/workflows/` or contributing docs)
 
+## 6. PR review follow-up (address maintainer comments)
+
+Use this when an open PR already exists and reviewers left feedback. **Contribution repo** = the upstream project you fixed (not the Iynx `the-fixer` repo unless that is your target).
+
+### Default artifact (do not commit)
+
+- **Path:** `<contribution-repo-root>/.iynx/pr-review-feedback.md`
+- **Policy:** Never commit this file. It is local scratch for the agent.
+- **Gitignore:** The helper refuses the default path unless Git ignores it (`git check-ignore`). If the upstream repo does not ignore `.iynx/`, pass **`--output`** or set **`IYNX_PR_REVIEW_FEEDBACK_PATH`** to a path outside the repo (or add an ignore rule locally without committing it—prefer `--output`).
+
+### Phase 1 — Normalize (existing clone)
+
+From the contribution clone (e.g. `workspace/owner-repo/`):
+
+```bash
+git fetch --all --prune
+gh pr checkout <PR_NUMBER>
+```
+
+```powershell
+git fetch --all --prune
+gh pr checkout <PR_NUMBER>
+```
+
+### Phase 1 — Normalize (PR only, no clone yet)
+
+1. Inspect head vs base: `gh pr view <URL> --json headRepository,baseRepository`.
+2. If **head** equals **base** (same `nameWithOwner`): clone that repo, then `gh pr checkout <N>`.
+3. Else (fork PR): clone the **head** repo’s URL from JSON, add `upstream` to the **base** repo URL, then `gh pr checkout <N>` from that clone.
+
+### Phase 2 — Fetch review text into markdown
+
+From the **Iynx** project root (or any cwd if you use `--output` / env):
+
+```bash
+# Inside contribution clone; writes .iynx/pr-review-feedback.md if gitignored
+python pr_review.py https://github.com/owner/repo/pull/42
+
+python pr_review.py owner/repo#42
+python pr_review.py --repo owner/repo --pr 42
+python pr_review.py 42 --repo owner/repo
+```
+
+```powershell
+cd path\to\contribution-clone
+python path\to\the-fixer\pr_review.py "https://github.com/owner/repo/pull/42"
+
+python path\to\the-fixer\pr_review.py --repo owner/repo --pr 42 --output "$env:TEMP\pr-review-feedback.md"
+```
+
+Requires **`gh`** installed and authenticated. If **`--output`** is omitted, **`IYNX_PR_REVIEW_FEEDBACK_PATH`** is used when set; otherwise the default is `.iynx/pr-review-feedback.md` under the contribution repo (requires that path to be gitignored).
+
+### Phase 3 — Implement, verify, push
+
+1. Read the markdown file; address each review thread; ask on the PR if something is ambiguous.
+2. Run tests (and lint/format) using `.iynx/context.json` `test_command` / `lint_command` when present, else CONTRIBUTING.
+3. Commit (do not add `pr-review-feedback.md`); push to the **same branch** as the PR head.
+
+**Exit codes:** `0` = file written; `1` = usage or local validation; `2` = `gh`/GitHub error.
+
+**Spec:** `docs/superpowers/specs/2026-03-24-pr-review-followup-design.md`
+
 ## Adapting to a Repo
 
 Each repo has its own structure. Before starting: