Skip to content
Back to search

pwn-it

SkillWorks with Claude CodeGitHub

Own a piece of development work in the current repository end to end. Takes GitHub issue(s) and/or documents, then runs a stateful, resumable workflow graph — intake, exploration, clarification, implementation in isolated worktrees with parallel subagents, a fresh-context review/fix loop that runs every configured review skill in parallel, a real before-vs-after demo video, push + PR + issue updates, and a work summary. Run from the root of the target repo. Invoke as `/pwn-it <issue-url | #number | doc-path>...` or `/pwn-it resume <RUN_ID> [what changed]`.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cahna--pwn-it/badge.svg)](/listings/cahna--pwn-it)

HTML

<a href="/listings/cahna--pwn-it"><img src="/api/listings/cahna--pwn-it/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone <this repo> ~/.claude/skills/pwn-it

Any skills directory works; the skill resolves its own location at runtime.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 469 lines
  1. ---
  2. name: pwn-it
  3. description: Own a piece of development work in the current repository end to end. Takes GitHub issue(s) and/or documents, then runs a stateful, resumable workflow graph — intake, exploration, clarification, implementation in isolated worktrees with parallel subagents, a fresh-context review/fix loop that runs every configured review skill in parallel, a real before-vs-after demo video, push + PR + issue updates, and a work summary. Run from the root of the target repo. Invoke as `/pwn-it <issue-url | #number | doc-path>...` or `/pwn-it resume <RUN_ID> [what changed]`.
  4. argument-hint: <issue-url | #number | doc-path>... | resume <RUN_ID> [what changed]
  5. disable-model-invocation: true
  6. ---
  7. # pwn-it: own a piece of work from start to finish
  8. Agentic harness for development work. You are the **orchestrator**: you own the outcome, keep
  9. the run state, make the decisions, and delegate bounded work to subagents.
  10. How to read this skill:
  11. - **The graph** (below) is the control flow. Every run is a walk through it.
  12. - **Node contracts** say, for each node, what to do, what must be true to leave it (the *exit
  13. gate*), and where to go next. Never leave a node without meeting its exit gate.
  14. - **The run state file** is your memory. The conversation can be compacted or the session
  15. restarted (e.g. to enable Chrome); the state file is what makes the run resumable. If it isn't
  16. in the state file, assume you'll forget it.
  17. - **References** in `references/` hold the detailed procedures. Read the one a node points to
  18. when you enter that node, not before.
  19. Skill directory (`$SKILL`): the directory holding this `SKILL.md`, i.e. the "Base directory for
  20. this skill" Claude Code shows when the skill loads. Use that absolute path; never assume where the
  21. skill is installed.
  22. Data directory (`$PWN_IT_HOME`): `$PWN_IT_HOME` if set in the environment, else `~/.claude/pwn-it/`.
  23. It holds everything pwn-it writes and keeps between runs; the skill directory is never written to.
  24. ```
  25. $PWN_IT_HOME/
  26. config.json # optional; review skills (see REVIEW)
  27. runs/<RUN_ID>/ # one per run (see Run state)
  28. repos/<repo>.md # repo profiles, from $SKILL/templates/repo-profile.md
  29. repos/<repo>.copy-ignored # extra gitignored paths setup-worktree.sh copies (one per line, # comments)
  30. LEARNINGS.md # friction with this skill, appended at REPORT
  31. ```
  32. Primary repo (`$REPO`): `git rev-parse --show-toplevel` from the directory the skill was invoked in.
  33. The skill is always run from the root of the target repo; don't search the disk for repos.
  34. "Ticket" in this skill means a GitHub issue. Its **key** is `<repo>-<number>` (e.g. `api-123`
  35. for `#123` in repo `api`), used wherever a filesystem- or branch-safe name is needed; refer to it
  36. as `#123` (or `owner/repo#123` across repos) in PRs, commits, and comments.
  37. ## Invocation and routing
  38. | Arguments | Route |
  39. | --- | --- |
  40. | Any mix of GitHub issue URLs/numbers (e.g. `#123`, `owner/repo#123`) and doc paths | New run, start at `PREFLIGHT`. All of them together are **one combined unit of work** (see below). Docs are either request or supporting material; work out which in `INTAKE` |
  41. | `resume <RUN_ID> [what changed]` | Re-read the run's `state.md`, then this file's contract for its `node`, then continue. If `what changed` is new feedback (PR comments, scope change), enter `FIX` or `PLAN` as appropriate |
  42. | Any ticket already listed in an existing run's `state.md` (search `$PWN_IT_HOME/runs/*/state.md`), without `resume` | Ask: resume that run (adding any new inputs to it), or start fresh as `<RUN_ID>-2` |
  43. | Nothing | Print the usage line and stop |
  44. `RUN_ID` is the primary ticket key (e.g. `api-123`), or `YYYYMMDD-short-slug` when there is no
  45. ticket. The run directory is `$PWN_IT_HOME/runs/<RUN_ID>/`.
  46. ### Multiple inputs: one combined unit of work
  47. Every argument in one invocation feeds a single run: one plan, one worktree and **one branch and
  48. PR per affected repo** containing the work for all of them. (Work that spans repos still needs one
  49. PR per repo; those PRs are cross-linked.)
  50. - **Primary ticket** = the first ticket argument. It names the `RUN_ID`, and the `RUN_ID` names
  51. the worktree directory and the branch (`<prefix>/<RUN_ID>/<slug>`), so a fresh run on the same
  52. ticket (`<RUN_ID>-2`) never shares either with the earlier run. If there are no tickets, use the date-slug.
  53. - **Every issue** is referenced in the PR description (`Closes #N` when fully addressed,
  54. `Refs #N` when partially), so GitHub links each one to the PR. Each commit names the issue(s)
  55. it addresses.
  56. - **Every issue** is marked in-progress at `INTAKE` and ready-for-review at `SHIP` where the repo
  57. supports it (see `references/ship.md` → Issues), and gets the PR comment.
  58. - **Acceptance criteria are merged** into one list, each tagged with its source (`[#1]`,
  59. `[doc: spec.md]`). Nothing gets dropped because another input covers something similar —
  60. deduplicate only exact overlaps, and note them.
  61. - **Conflicts between inputs** (two tickets asking for contradictory behavior, a doc that
  62. disagrees with a ticket) are open questions for `CLARIFY`, unless one source clearly
  63. supersedes the other (newer decision, stated priority) — then record which one wins and why.
  64. - Don't question the decision to combine. Note it in `PLAN` only if one input is clearly
  65. unrelated *and* would make the PR much harder to review; even then, recommend, don't split
  66. unasked.
  67. ## Global invariants — apply at every node
  68. 1. **Bias towards action.** Ask only when the answer changes what you do and you can't get it from
  69. the issue, the code, or a sensible default. Otherwise decide, record the
  70. assumption in the state file, and surface it in the PR and summary.
  71. 2. **No deferral of fixable work.** Don't create follow-ups for anything that can be fixed as part
  72. of this work. Follow-ups are only for (a) major changes well beyond the request, (b) massive
  73. security issues, or (c) work blocked by a dependency outside our control. Each one records why
  74. it isn't in this change and what happens next.
  75. 3. **State first.** On every node transition, append to the transition log and update `node:` in
  76. `state.md` before doing the new node's work. Record decisions, assumptions, answers, and
  77. artifacts as they happen.
  78. 4. **Commits:** Conventional Commits in the repo's existing style (check `git log`), defaulting
  79. to `type(scope): summary (#123)` (or `(#1, #2)` when a commit covers several). Never
  80. `--no-verify`; if a hook fails, fix the cause. Commit only after checking the test command's
  81. own exit status: a pipe (`jest | grep …`) hides a failure unless `set -o pipefail` is on.
  82. 5. **Isolation.** All code changes happen in the run's worktrees, never in the repo root checkout
  83. or another run's worktree. Services started for this run use the run's port slot and compose
  84. project name only.
  85. 6. **Real user data and secrets.** Treat any real user data (PII/PHI) as off-limits.
  86. Screenshots, videos, logs, PR text, issue comments, and the summary must contain **only local/dev seed or synthetic data** — never data
  87. from production or a shared environment with real users, and never secrets or tokens.
  88. Inspect every image before it leaves the machine.
  89. 7. **Authorized outward actions** (invoking this skill is the approval): mark this run's
  90. issues in-progress and ready-for-review (per `references/ship.md` → Issues); comment on
  91. them; push this run's branches; open PRs; upload demo artifacts to those PRs/issues; write the summary file.
  92. **Not authorized without asking:** merging, closing issues, pushing to a base
  93. branch, force-pushing anything except this run's own branch (and then only
  94. `--force-with-lease` after a rebase), commenting on other people's PRs/issues, messaging
  95. anyone, changing shared environments, running migrations against shared databases.
  96. 8. **Lean orchestrator context.** Delegate wide reads (multi-repo exploration, log trawls) to
  97. subagents and keep only their conclusions. After a compaction, re-read `state.md` and the
  98. contract for the current node before acting.
  99. ## Run state
  100. Create `$PWN_IT_HOME/runs/<RUN_ID>/` in `INTAKE` with:
  101. ```
  102. state.md # from $SKILL/templates/state.md — the single source of truth
  103. artifacts/before/ # baseline captures (stills, clips, API/test output)
  104. artifacts/after/ # same steps, after the change
  105. artifacts/demo.mp4 # edited before-vs-after video
  106. film/ # the video's sources: scenes, cards, edit list (built with $SKILL/film-kit)
  107. reviews/<repo>/round-N/<reviewer>.md # each reviewer's verbatim output (skill or CLI name)
  108. reviews/<repo>/round-N/merged.md # de-duplicated findings + your triage
  109. ```
  110. ## Workflow graph
  111. ```mermaid
  112. flowchart TD
  113. START(["/pwn-it args"]) --> ROUTE{"resume or<br/>existing run?"}
  114. ROUTE -- "resume" --> RESUME[["re-read state.md,<br/>jump to state.node"]]
  115. ROUTE -- "new" --> PREFLIGHT
  116. PREFLIGHT["PREFLIGHT<br/>capabilities + access"] --> INTAKE
  117. INTAKE["INTAKE<br/>read request + links,<br/>issue → in progress"] --> EXPLORE
  118. EXPLORE["EXPLORE<br/>map code,<br/>interdependencies"] --> PLAN
  119. PLAN["PLAN<br/>size, workstreams,<br/>tests, demo script"] --> G_CLEAR{"open questions,<br/>capability gaps,<br/>or size L?"}
  120. G_CLEAR -- "yes" --> CLARIFY["CLARIFY<br/>one batched ask"]
  121. CLARIFY --> PLAN
  122. G_CLEAR -- "no" --> SETUP
  123. SETUP["SETUP<br/>worktrees, config,<br/>ports, deps"] --> BASELINE
  124. BASELINE["BASELINE<br/>capture BEFORE,<br/>reproduce bug"] -- "can't reproduce /<br/>premise wrong" --> CLARIFY
  125. BASELINE --> BUILD
  126. BUILD["BUILD<br/>parallel workers,<br/>checkpoint commits"] --> VERIFY
  127. VERIFY{"VERIFY<br/>build, lint, types,<br/>tests, criteria"} -- "fail" --> BUILD
  128. VERIFY -- "pass" --> REVIEW
  129. REVIEW["REVIEW<br/>one fresh subagent<br/>per review skill"] --> RV1["reviewer:<br/>skill 1"] & RVN["reviewer:<br/>skill N"]
  130. RV1 & RVN --> MERGE["MERGE<br/>wait for all, de-dupe,<br/>triage"]
  131. MERGE --> G_REVIEW{"actionable<br/>findings?"}
  132. G_REVIEW -- "yes, converging" --> FIX["FIX<br/>address findings"]
  133. FIX --> VERIFY
  134. G_REVIEW -- "not converging" --> ESCALATE
  135. G_REVIEW -- "none" --> DEMO
  136. DEMO["DEMO<br/>capture AFTER,<br/>edit video"] --> SHIP
  137. DEMO -- "filming found a bug" --> FIX
  138. SHIP["SHIP<br/>rebase, push, PR,<br/>issue → review"] -- "rebase changed code" --> VERIFY
  139. SHIP --> REPORT
  140. REPORT["REPORT<br/>summary,<br/>handoff"] --> WATCH
  141. WATCH(["WATCH<br/>keep PR + summary<br/>in sync"]) -- "new feedback<br/>or scope change" --> FIX
  142. ESCALATE["ESCALATE<br/>ask user, wait"] -. "answer" .-> RETURN[["return to<br/>originating node"]]
  143. ```
  144. Any node may go to `ESCALATE` when it is blocked by something only the user can resolve. Loop
  145. bounds: `VERIFY → BUILD` at most 3 times for the same root cause; `REVIEW → FIX` at most 5 rounds
  146. per repo per review cycle. Exceeding a bound means `ESCALATE`, not another lap. A cycle starts at
  147. the first `REVIEW`; a user scope change, new human PR feedback (via `WATCH` or `resume`), or a
  148. fix for a bug found while filming in `DEMO` (new scope found by QA) starts a new cycle, which resets the round bound (round numbers keep counting up; effort escalation
  149. carries over).
  150. ## Node contracts
  151. ### PREFLIGHT — capabilities and access
  152. - **Do:** Check, in parallel, and record each as ok/missing in `state.md`:
  153. - Repo: `$REPO` is a git repo whose `origin` is on GitHub (`git remote get-url origin`).
  154. - GitHub: `gh auth status`, and `gh repo view` / `gh issue view` on the run's issues
  155. (see `references/ship.md` → Auth).
  156. - Browser: Claude in Chrome tools (`ToolSearch` for `claude-in-chrome`). Chrome DevTools MCP is
  157. the capture fallback.
  158. - `ffmpeg`, `docker`
  159. - Reviewers: load the list per `references/review-loop.md` → Configuration and check each
  160. review skill appears in your available skills, and each CLI reviewer is installed and logged in.
  161. - Film kit Playwright: `$SKILL/film-kit/setup-playwright.sh` (idempotent; installs the kit's own
  162. Playwright and headless Chromium if missing, then smoke-tests a launch). Never depend on the
  163. target repo's Playwright.
  164. - **Exit gate:** `$REPO` is a GitHub repo and issue access works (or there are no issues).
  165. Everything else that's missing is carried as a *capability gap* to `PLAN`, which decides if it matters. A configured reviewer (skill or CLI)
  166. that isn't available always matters: ask in `CLARIFY` whether to drop it or fix it first. With
  167. none available, `REVIEW` can't run.
  168. - **Next:** `INTAKE`. If either is broken, `ESCALATE` now — nothing else can start.
  169. ### INTAKE — understand the request
  170. - **Do:**
  171. 1. Create the run directory and `state.md`.
  172. 2. Read every issue in full (`gh issue view <n> --comments`): description, acceptance criteria,
  173. comments, attachments, linked/sub-issues, milestone. Follow links (other issues, docs, PRs) one hop,
  174. further when they're load-bearing.
  175. 3. Read every doc argument. Classify it as *request* or *supporting*. With several inputs,
  176. read them all before restating anything — later ones often reframe earlier ones.
  177. 4. Search for prior context: related issues and PRs (`gh search issues/prs` on the topic),
  178. and earlier pwn-it runs that touched the same area.
  179. 5. Mark each issue in progress (see `references/ship.md` → Issues).
  180. - **Exit gate:** `state.md` has a one-paragraph restatement of the combined request and one
  181. numbered list of acceptance criteria, each tagged with its source (plus implied ones marked
  182. *inferred*). Every input is accounted for; conflicts between inputs are listed as open
  183. questions or resolved with a recorded reason.
  184. - **Next:** `EXPLORE`.
  185. ### EXPLORE — map the code and its dependencies
  186. - **Do:**
  187. 1. The primary repo is `$REPO`. Read `$PWN_IT_HOME/repos/<repo>.md` if it exists, and the repo's
  188. `CLAUDE.md` and `.claude/` rules.
  189. 2. Locate the affected code, its callers, its tests, and any contracts with other services
  190. (APIs, events, shared schemas, client libs). For M/L work, fan out `Explore` subagents per
  191. area (in parallel).
  192. 3. If the work clearly needs changes in another repo, don't search for it: ask for its local
  193. path in `CLARIFY` and treat it as an additional affected repo. Decide the order
  194. (contract/producer before consumer).
  195. 4. Find how each affected repo is run, tested, and seeded locally, and how the change will be
  196. observable (UI screen, API call, job output).
  197. - **Exit gate:** `state.md` lists affected repos with the reason for each, the dependency order,
  198. and the verify commands per repo.
  199. - **Next:** `PLAN`.
  200. ### PLAN — decide how
  201. - **Do:** Write the plan into `state.md`:
  202. - **Size:** XS (one concern, one or two files) · S (one repo, a few files) · M (several modules
  203. or frontend + backend) · L (multi-repo, contract or schema change, or roughly a day or more of
  204. human work).
  205. - **Workstreams:** each with repo, the files/dirs it owns (disjoint across parallel streams),
  206. dependencies on other streams, and the worker model/effort (see Delegation). XS/S work is
  207. usually done by you directly.
  208. - **Test plan:** for bugs, the failing test that reproduces it; for features, what tests cover
  209. each acceptance criterion.
  210. - **Demo plan (edit plan):** the observable surface (`ui` | `api` | `cli` | `none`); one row
  211. per claim the PR makes, with how it is shown, the region to highlight, and the expected fact
  212. on each side; then numbered steps with captions. `BASELINE` and `DEMO` both follow this exact
  213. plan. See `references/demo-capture.md` → The edit plan.
  214. - **Open questions** and **capability gaps** that actually matter to this plan (e.g. a UI demo
  215. with no browser tools).
  216. - When a decision depends on real input size or shape, check a real sample's size (without
  217. reading its content) first; stripped or synthetic fixtures can be orders of magnitude smaller.
  218. - **Exit gate:** Every acceptance criterion maps to a workstream and a test. Every open question
  219. either has an answer or a recorded assumption.
  220. - **Next:** `CLARIFY` if there are open questions, gaps that matter, or the size is L (confirm the
  221. plan once). Otherwise `SETUP`.
  222. ### CLARIFY — one batched ask
  223. - **Do:** Ask everything outstanding in **one** `AskUserQuestion` call (up to 4 questions; put
  224. overflow in your message text). Each question stands on its own and offers your recommended
  225. option first. For size L, include the plan summary and ask for a go/adjust. When a large issue
  226. goes much deeper than its title suggests (common when an agent wrote it), lead with how deep it
  227. goes and offer scope tiers (A/B/C) in a plain table before the plan details.
  228. If a gap needs a restart (e.g. Chrome: "restart with `claude --chrome`, then run
  229. `/pwn-it resume <RUN_ID>`"), say so and set `status: waiting-on-user`.
  230. - **Exit gate:** Answers recorded in `state.md` → Questions & answers.
  231. - **Next:** `PLAN` (revise with the answers). The `PLAN ⇄ CLARIFY` loop repeats until nothing
  232. material is open; if a second round is needed, explain why the first didn't settle it.
  233. ### SETUP — isolated worktrees
  234. - **Do:** Follow `references/worktree-isolation.md`. In short, per affected repo:
  235. `$SKILL/scripts/setup-worktree.sh <repo-root> <RUN_ID> <slug>` creates
  236. `<repo-parent>/wt/<repo>/<RUN_ID>` (or under `$PWN_IT_WT_ROOT`) on branch `<prefix>/<RUN_ID>/<slug>`,
  237. copies gitignored local/dev config,
  238. and allocates a port slot. Then apply the port offset and compose project name to everything
  239. that binds a port, install dependencies, and start only the services the demo and tests need.
  240. - **Exit gate:** Each worktree builds, its services are up on its own ports with no collision
  241. with the root checkout or other worktrees, and `state.md` → Repos has the full row.
  242. - **Next:** `BASELINE`.
  243. ### BASELINE — capture BEFORE (and prove the problem)
  244. - **Do:** Before changing any code, run the demo script against the fresh worktree (still at the
  245. base commit) and capture into `artifacts/before/` per `references/demo-capture.md`. For bugs,
  246. this doubles as reproduction — and write the failing test now if you can. For features too:
  247. BEFORE captures double as exploratory QA, so record anything odd they surface.
  248. Set up for re-shoots now (`references/demo-capture.md` → Repeatable runs): snapshot the DB, and
  249. keep a runnable BEFORE build (a detached base worktree plus a compose variant) so `DEMO` can
  250. record both sides on the same stack later.
  251. - **Exit gate:** `artifacts/before/` holds the captures for every script step (or, for
  252. `surface: none`, the recorded reason).
  253. - **Next:** `BUILD`. If the bug won't reproduce or the request's premise looks wrong, record
  254. the evidence and go to `CLARIFY`.
  255. ### BUILD — implement
  256. - **Do:**
  257. - Execute the workstreams in dependency order; launch independent ones in parallel (several
  258. `Agent` calls in one message). Brief workers with `references/delegation.md` → Worker brief.
  259. - Contract first for multi-repo or multi-stream work: land the shared interface (types, API
  260. schema, event shape) before starting dependent streams.
  261. - Workers edit files only; **you** integrate and commit. Commit at logical checkpoints (a
  262. stream lands, a test goes green), not at the end in one lump.
  263. - Make each acceptance criterion true; don't gold-plate beyond it. Fix adjacent defects you
  264. touch (invariant 2).
  265. - **Exit gate:** All workstreams integrated and committed; nothing uncommitted except deliberate
  266. local config.
  267. - **Next:** `VERIFY`.
  268. ### VERIFY — prove it works
  269. - **Do:** In each worktree, run the repo's build, lint, type-check, and the relevant tests
  270. (affected module plus anything that consumes changed contracts), using the repo's documented
  271. commands. Walk the acceptance criteria one by one and record the evidence for each.
  272. - **Exit gate:** Everything green; every criterion has evidence in `state.md` → Verify.
  273. - **Next:** `REVIEW` on pass. On failure, `BUILD` with the failure output. Third failure from the
  274. same root cause: investigate (form hypotheses and test them, don't guess-and-patch), and if
  275. still stuck, `ESCALATE`.
  276. ### REVIEW — fresh eyes, one reviewer per review skill
  277. - **Do:** Load the review skills (`references/review-loop.md` → Configuration). For every affected
  278. repo × every review skill, launch a **fresh** `general-purpose` subagent (never a fork; model
  279. `opus`, the latest Opus; effort per `references/review-loop.md` → Effort escalation), all in
  280. **one message** so they run in parallel, each with `references/review-loop.md` → Reviewer brief.
  281. A `cli` reviewer gets the same kind of fresh subagent, briefed per `references/review-loop.md` →
  282. CLI reviewers (model `sonnet`; it runs the external CLI and converts the output).
  283. From round 2 on, every brief (except `fresh` CLI reviewers') includes the previous reviewed SHA and the merged prior findings
  284. with your response to each, so each reviewer does a proper re-review.
  285. - Wait until **every** reviewer has returned. Save each one's output verbatim to
  286. `reviews/<repo>/round-N/<reviewer>.md` as it arrives. On `resume`, relaunch only reviewers with no
  287. saved output for the current round.
  288. - **Exit gate:** every (repo, reviewer) pair has saved output for this round, or a recorded
  289. failure (a CLI reviewer whose outcome isn't `completed` for the current head SHA has failed,
  290. never passed with zero findings; a reviewer that errors is relaunched once; if it fails again, record it and continue
  291. only if at least one reviewer per repo succeeded, else `ESCALATE`).
  292. - **Next:** `MERGE`.
  293. ### MERGE — gather, de-duplicate, triage
  294. - **Do:** Per repo, merge all reviewers' findings for this round into one list in
  295. `reviews/<repo>/round-N/merged.md` per `references/review-loop.md` → Merge, then triage each
  296. merged finding per `references/review-loop.md` → Triage.
  297. - **Exit gate:** every reviewer finding maps to exactly one merged finding, and every merged
  298. finding has a triage outcome recorded.
  299. - **Next:** `FIX` if any finding is *fix* (and the loop is converging). `DEMO` if none are.
  300. `ESCALATE` if not converging (`references/review-loop.md` → Convergence): round 5 of the cycle
  301. reached, the merged actionable count didn't drop from the previous round, or a finding you
  302. marked fixed comes back.
  303. ### FIX — address findings
  304. - **Do:** Fix every *fix* finding (delegate in parallel when they're independent and touch
  305. disjoint files). Commit with meaningful messages — not "address review". Record your response
  306. per finding (fixed how / rejected with what evidence) for the next reviewer's brief. Also the
  307. entry point for human PR feedback and scope changes arriving via `WATCH` or `resume`.
  308. - **Exit gate:** Every *fix* finding is resolved in a commit or carries a rejection with evidence.
  309. - **Next:** `VERIFY` (and from there back to `REVIEW`). Fixes for bugs found while filming in
  310. `DEMO` take the same path, then re-shoot the affected chapters.
  311. ### DEMO — capture AFTER and edit the video
  312. - **Do:** Re-run the exact demo script against the worktree into `artifacts/after/`. Then make
  313. `artifacts/demo.mp4`: a chaptered explainer with one chapter per claim (BEFORE take, AFTER take,
  314. comparison card), recorded on both sides with `$SKILL/film-kit` and cut by you. It must make
  315. what changed visible, including what happens off screen (requests, API calls, server writes),
  316. and draw the eye to it: highlight it, caption it, and hold on it. Pick the stills for the PR.
  317. Follow `references/demo-capture.md` → Produce the video, including the real-user-data and secrets check.
  318. If filming exposes a bug, go to `FIX` (then `VERIFY` → `REVIEW`) before finishing the video.
  319. For new or changed user-facing UI, show the user the AFTER stills in one `AskUserQuestion`
  320. before `SHIP`. If they reject the look, build 2–3 real candidates and show them side by side
  321. instead of describing options.
  322. - **Exit gate:** every claim in the edit plan has a chapter and a comparison card; both sides'
  323. `facts.json` match the plan's expected facts; `demo.mp4` passes the QA in
  324. `references/demo-capture.md` (no blank or loading frames, native 1080p30, every key moment
  325. highlighted and captioned, captions true for their side). The PR stills are chosen, and no real user data
  326. or secrets are visible. For `surface: none`, before/after evidence text blocks
  327. exist instead and the reason is recorded.
  328. - **Next:** `SHIP`.
  329. ### SHIP — push, PR, issues
  330. - **Do:** Follow `references/ship.md`: fetch; rebase onto the latest base if it moved; push with
  331. upstream; open one PR per repo from `templates/pr-description.md` with before/after stills and
  332. the video; cross-link PRs and state merge order for multi-repo work; attach the video to the
  333. issues; mark issues ready for review and comment with PR links. Stop this run's services
  334. (keep volumes) to free the machine. Keep the BEFORE base worktree until the user accepts the
  335. video, then remove it.
  336. - **Exit gate:** PR URLs and issue updates recorded in `state.md`; images render in the PR
  337. (check the PR page).
  338. - **Next:** `REPORT`. If the rebase changed code (conflict resolution or a base change touching
  339. the same files), go back to `VERIFY` first, then re-review only if the resolution was
  340. non-trivial.
  341. ### REPORT — summary and handoff
  342. - **Do:**
  343. 1. Write the work summary from `templates/work-summary.md` to `<run_dir>/summary.md`.
  344. Markdown only; no real user data or secrets.
  345. 2. Update `$PWN_IT_HOME/repos/<repo>.md` (create it from `$SKILL/templates/repo-profile.md`)
  346. with durable, verified facts learned this run (how to run, ports, test commands, seed logins
  347. *location* — never the credentials — gotchas, which capture method worked).
  348. 3. Append friction with this skill itself to `$PWN_IT_HOME/LEARNINGS.md`, newest first, as
  349. `- YYYY-MM-DD <RUN_ID> [node]: what happened → suggested change`. If the file doesn't exist,
  350. start it with a `# pwn-it learnings` heading and that format line. It is for the human to
  351. fold into the skill; never edit `$SKILL` yourself.
  352. 4. Give the user a short handoff: PR links, issue status, video path, summary path, any
  353. follow-ups, and anything that needs them.
  354. - **Exit gate:** Summary written; `state.md` `status: shipped`.
  355. - **Next:** `WATCH`.
  356. ### WATCH — stay in sync for the rest of the session
  357. - **Do:** For as long as this session continues (or on `resume`), any change to the work —
  358. PR feedback addressed, scope change, rebase, issue changes — goes `FIX → VERIFY → REVIEW` as
  359. appropriate, then re-push, update the PR description, and **update the summary file** so it
  360. still matches reality. Note the update in the summary's changelog section.
  361. ### ESCALATE — blocked on the user
  362. - **Do:** Set `status: waiting-on-user` and record the originating node. Ask one batched
  363. `AskUserQuestion` with the evidence (what was tried, what happened, your recommendation
  364. first). For non-convergent review, show the findings that keep recurring and both positions.
  365. - **Next:** Back to the originating node with the answer recorded.
  366. ## Delegation and model routing
  367. Invoking this skill authorizes choosing `model` and `effort` per subagent. Match the worker to
  368. the work, not to the run's overall size:
  369. | Work | Agent type | Model | Effort |
  370. | --- | --- | --- | --- |
  371. | Locate code, map a repo, trace callers | `Explore` | `haiku` (`sonnet` for tangled code) | low–medium |
  372. | Mechanical edits: renames, config, boilerplate, fixtures, docs | `general-purpose` | `haiku` | low |
  373. | Standard feature/test work following existing patterns | `general-purpose` | `sonnet` | medium |
  374. | Cross-cutting design, concurrency, security, auth, migrations, hard debugging | `general-purpose` | `opus` | high |
  375. | Demo video edit | `general-purpose` | `opus` | high (orchestrator does final QA) |
  376. | Review (quality gate), one per review skill | fresh `general-purpose` | `opus` (latest) | high; **xhigh** from round 4 if rounds 1–3 all had findings |
  377. | Review, one per CLI reviewer (runs the CLI, converts its output) | fresh `general-purpose` | `sonnet` | medium |
  378. | A worker that already failed the same task once | escalate one tier | | +1 level |
  379. Rules:
  380. - Parallel workers must own disjoint files. Two workers never edit the same file concurrently.
  381. - Workers never run state-changing git commands (commit, checkout, rebase, stash, push). You do.
  382. - Workers in the same worktree don't start or stop services; they use the ones `SETUP` started.
  383. - Brief workers fully: they know only the brief. Use `references/delegation.md` → Worker brief.
  384. - If orchestration tooling for dynamic multi-agent workflows is available in the session, use it
  385. for M/L fan-out; otherwise parallel `Agent` calls are the mechanism.
  386. ## Tools and access
  387. - **Browser:** prefer the Claude in Chrome extension to drive web apps. If it's unavailable and
  388. the plan needs a browser, ask the user to make it available and restart with `claude --chrome`
  389. (then `/pwn-it resume <RUN_ID>`). Chrome DevTools MCP is acceptable for capture if the user
  390. says to proceed without the extension.
  391. - **GitHub:** the `gh` CLI for issues, PRs, CI, and API calls. Never print, log, or copy tokens.
  392. - **Processes:** with `pkill -f` / `pgrep -f`, bracket one character of the pattern
  393. (`pkill -f '[K]otlinCompileDaemon'`) so it can't match the shell running the command.
  394. - **Scripts:** `$SKILL/scripts/setup-worktree.sh` (run with `--help`), `$SKILL/scripts/scan-history.py`
  395. (`SHIP` private-data scan); run `$SKILL/scripts/selftest.sh` after changing either. For the video,
  396. `$SKILL/film-kit/` holds building blocks (overlay, recorder, clips, cards, assembly, contact
  397. sheets; see its `README.md`, and run `selftest/selftest.sh` after changing it). There is no
  398. end-to-end video script on purpose; see `references/demo-capture.md`.
README.md · README · 127 lines
  1. # pwn-it
  2. A Claude Code skill that owns a piece of
  3. development work end to end. Give it GitHub issues and/or docs; it plans the work, implements it
  4. in isolated git worktrees with parallel subagents, runs a review/fix loop with one or more review
  5. skills, records a before-vs-after demo video, then pushes, opens the PR, and updates the issues.
  6. Runs are stateful and resumable: everything lives in a state file, so a compaction or a restart
  7. doesn't lose the thread.
  8. ```
  9. /pwn-it #123 # one issue
  10. /pwn-it #123 #124 docs/spec.md # several inputs, one combined PR
  11. /pwn-it resume <RUN_ID> [what changed]
  12. ```
  13. Run it from the root of the target repo. `SKILL.md` has the full workflow graph and node
  14. contracts; `references/` holds the detailed procedures.
  15. ## What it does on its own (and what it won't)
  16. Invoking it authorizes: marking the run's issues in progress / ready for review, commenting on
  17. them, pushing the run's own branches, opening PRs, and uploading demo media to them.
  18. It asks first before: merging, closing issues, pushing to a base branch, force-pushing anything
  19. but its own branch, touching other people's PRs, or changing shared environments.
  20. ## Requirements
  21. - Claude Code, with a GitHub repo checked out locally (`origin` on GitHub)
  22. - [`gh`](https://cli.github.com/) logged in with the `repo` scope (`project` too if your issues
  23. live on a Projects board)
  24. - `git`, `node` (18+), `npm`, `ffmpeg`, `python3` (3.8+); `docker` if your app runs in compose
  25. - For UI demos: the Claude in Chrome extension (start Claude Code with `claude --chrome`).
  26. Uploading demo media to PRs needs it too: GitHub has no API for PR attachments, so pwn-it
  27. drives the PR page in your logged-in browser to upload them (`references/ship.md`). That is a
  28. workaround that depends on GitHub's page internals and may break when GitHub changes them.
  29. - The film kit installs its own pinned Playwright and headless Chromium on first use
  30. (`film-kit/setup-playwright.sh`); it never uses the target repo's.
  31. ## Install
  32. ```bash
  33. git clone <this repo> ~/.claude/skills/pwn-it
  34. ```
  35. Any skills directory works; the skill resolves its own location at runtime.
  36. ## Configuration
  37. pwn-it keeps its data in `~/.claude/pwn-it/` (override with `PWN_IT_HOME`), never in the skill
  38. directory:
  39. ```
  40. ~/.claude/pwn-it/
  41. config.json # optional, see below
  42. runs/<RUN_ID>/ # state, artifacts, reviews, summary per run
  43. repos/<repo>.md # per-repo profile pwn-it learns and reuses
  44. repos/<repo>.copy-ignored # extra gitignored paths to copy into worktrees
  45. LEARNINGS.md # friction with the skill, for you to fold back in
  46. ```
  47. ### Review skills
  48. The review step runs one fresh subagent per configured review skill, in parallel, then merges
  49. and de-duplicates their findings before fixing. Configure the list in
  50. `~/.claude/pwn-it/config.json`:
  51. ```json
  52. {
  53. "review_skills": [
  54. { "skill": "code-review", "args": "high {branch}" },
  55. { "skill": "my-team:review", "args": "the changes on branch {branch} compared with origin/{base}" }
  56. ]
  57. }
  58. ```
  59. A plain string is invoked with the branch name as its argument. Placeholders: `{branch}`,
  60. `{base}`, `{worktree}`, `{sha}`, `{effort}`. Without a config, pwn-it uses Claude Code's built-in
  61. `code-review` with args `high {branch}`. Any skill you list must be installed, and invocable by
  62. Claude (not `disable-model-invocation: true`), because each one runs inside a reviewer subagent.
  63. pwn-it checks at the start of each run.
  64. An entry can also be another AI CLI, run as one of the parallel reviewers. pwn-it runs the command
  65. (argv, no shell) from the worktree, and a subagent converts its output into the same findings
  66. format so it merges with the rest. `fresh: true` never shows it earlier rounds' findings:
  67. ```json
  68. { "cli": "codex", "name": "codex-ponytail",
  69. "command": ["codex", "exec", "--ephemeral", "-s", "read-only", "-C", "{worktree}", "{prompt}"],
  70. "prompt": "$ponytail:ponytail-review the changes on branch {branch} compared with origin/{base}\nPerform a clean-state review without reading or referencing any previous review findings, notes, or work logs.",
  71. "fresh": true, "timeout_min": 20 }
  72. ```
  73. pwn-it runs `command` as written, so put the CLI's sandbox and isolation flags there (for Codex,
  74. `-s read-only` doesn't restrict MCP servers; add `-c mcp_servers.<name>.enabled=false` per server
  75. if you want them off). pwn-it appends fixed rules to every CLI prompt (read-only, never post,
  76. review this exact commit, end with a `completed`/`blocked`/`failed` status line) and treats any
  77. run that doesn't report `completed` for the head commit as a failed reviewer, never a clean one. Reviews run before the PR exists, so refer
  78. to the branch, not a PR number. Details in `references/review-loop.md` → CLI reviewers.
  79. The CLI must be installed and logged in; pwn-it checks at the start of each run.
  80. ### Environment variables
  81. | Variable | Default | Purpose |
  82. | --- | --- | --- |
  83. | `PWN_IT_HOME` | `~/.claude/pwn-it` | Data directory |
  84. | `PWN_IT_WT_ROOT` | `<repo parent>/wt` | Where worktrees go |
  85. | `PWN_IT_BRANCH_PREFIX` | `$USER` | Branch names are `<prefix>/<RUN_ID>/<slug>` |
  86. | `PWN_IT_PLAYWRIGHT` | `~/.local/share/pwn-it/playwright` | Film kit's Playwright install |
  87. | `FILM_CHROMIUM`, `FILM_HEADLESS`, `FILM_PLAYWRIGHT_FROM` | | See `film-kit/README.md` |
  88. ## Layout
  89. | Path | What |
  90. | --- | --- |
  91. | `SKILL.md` | The workflow: graph, node contracts, invariants, delegation |
  92. | `references/` | Procedures for worktrees, demo capture, review loop, shipping, delegation |
  93. | `templates/` | Run state, PR description, work summary, repo profile |
  94. | `scripts/setup-worktree.sh` | Creates a worktree, copies gitignored local/dev config, allocates a port slot |
  95. | `scripts/scan-history.py` | Pre-push scan of every file version on the branch for known private values |
  96. | `scripts/selftest.sh` | Checks both scripts against a throwaway repo |
  97. | `film-kit/` | Building blocks for the demo video; `film-kit/selftest/selftest.sh` exercises them (for developing the kit; it writes to the gitignored `film-kit/selftest/out/`) |
  98. ## License
  99. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.