docs(guide): claim quests with a draft PR, forks included

README.md

@@ -58,8 +58,9 @@ in Git history, beside the code that completed it.
 
 Work is taken through a live runner lock or an open change on the forge.
 kix.quest records each active job in its database and reassigns a job whose
-runner goes offline. On GitHub, a pushed quest
-branch claims the work. These states stay out of the plan file.
+runner goes offline. On GitHub, a draft PR
+opened from the quest's branch, including from a fork, claims the work. These
+states stay out of the plan file.
 
 ## Try it
 

assets/AGENTS.md

@@ -105,20 +105,28 @@ kix.quest records each active job in its database and reassigns a job whose
 runner goes offline. Check those locks and open changes before
 starting. These states stay out of the quest file.
 
-On GitHub, if you have push access, make an empty commit and push a branch to
-the remote.
-The remote branch claims the quest so other agents skip it.
-Check for its branch and any open PR before starting.
-If a branch looks stale (old, with no open PR), offer the user to take it over.
+On GitHub, a quest is claimed by an open PR whose head branch is the quest's
+branch, from the upstream repository or a fork
+(`gh pr list --repo <upstream> --head <quest-branch>`), or by that branch
+upstream while its PR is being opened.
+Check both against the upstream repository; in a fork's clone, `origin` is
+usually the fork.
+To claim a quest, push an empty commit to its branch, upstream if you have push
+access and otherwise on your fork, then open a draft PR from it right away.
+That PR becomes the quest's PR.
+Then recheck: the earliest open PR holds the claim, and a later one closes and
+stops.
+If an upstream branch looks stale (old, with no open PR), offer the user to take
+it over.
 
 A quest's branch is its path without `.md`.
 For example, `quest/m1/foo/bar.md` is branch `quest/m1/foo/bar`.
 
 Push claims and updates with an explicit refspec: `git push <remote> refs/heads/<quest-branch>:refs/heads/<quest-branch>`.
 A bare branch name can push to the base branch instead, for example under `push.default=upstream` when the quest branch tracks it.
 
-When a quest is complete with no open decisions, open its PR ready for review.
-Otherwise open a draft and list its open decisions, or what remains unfinished, in the body.
+When a quest is complete with no open decisions, mark its PR ready for review.
+Otherwise keep it a draft and list its open decisions, or what remains unfinished, in the body.
 A draft suggests `/quest-iterate`; a PR ready for review suggests `/quest-merge`.
 Include a summary of the changes made and suggest follow-up quests based on issues encountered.
 Add a closing keyword for every issue under `Closes`.

assets/skills/spawn.md

@@ -10,7 +10,7 @@ Run `quest unblocked --json` for ready candidates in milestone priority, descend
 The count is distinct transitive dependents; other prerequisites may still remain.
 Use that order when dispatching, and recompute after the quest tree changes.
 An explicit argument takes precedence: filter to the selected quests/epics and honor their requested order.
-Ranking does not establish that work is unclaimed: verify live locks, open changes, and remote branch claims before starting.
+Ranking does not establish that work is unclaimed: verify live locks, open changes (including PRs from forks), and remote branch claims before starting.
 For a quest waiting on an outside condition, check whether it has cleared before recommending.
 
 Start every quest you would recommend starting, without asking: well planned, with no blockers or conflicts with quests already started.
@@ -30,7 +30,7 @@ Each agent reports back only when done or blocked.
 Limit the number of active agents to the physical CPU core count.
 Other sessions share this machine: hold new agents while the load average exceeds the core count.
 
-When done, each agent opens a PR, a draft if decisions or unfinished work remain.
+When done, each agent's claim PR holds its work, still a draft if decisions or unfinished work remain.
 Its report lists every open decision and suggested follow-up with a recommendation.
 Report each sub-agent's final status, staying silent on interim notifications, but do not monitor their PRs.
 

assets/skills/start.md

@@ -10,12 +10,12 @@ The argument is the quest to work on.
 If you are unsure on the best course of action, ask the user for direction.
 
 Update your checkout, run `quest ready`, then confirm the quest is still ready and unclaimed.
-Check the forge for a live runner lock or an open change; on GitHub, check the quest's remote branch and open PRs.
+Check the forge for a live runner lock or an open change; on GitHub, check the quest's upstream branch and open PRs from any fork.
 Confirm you can write in your worktree; if you cannot, stop and report without claiming.
 Claim it as `quest guide` describes.
-Release work you cannot finish; on GitHub, delete its branch claim and your isolated worktree.
+Release work you cannot finish; on GitHub, close its claim PR, delete its branch, and remove your isolated worktree.
 
-Implement the quest until it is complete, or some blocker is hit, then create a PR.
+Implement the quest until it is complete, or some blocker is hit, then push to its PR and update the description.
 Never write to or clean up a directory other agents share, such as a session scratchpad.
 
 When done, explain the result in a few lines and summarize any issues encountered.

cloudflare/src/home.tsx

@@ -139,7 +139,11 @@ export function Home(props: { setup: string; board: Board }) {
 					</li>
 					<li>
 						<p class="state">Accepted by @agent</p>
-						<p>A live runner lock takes active work. On GitHub, pushing the quest's branch claims it.</p>
+						<p>
+							A live runner lock takes active work. On GitHub, an agent pushes an empty commit to the
+							quest's branch, from a fork too, and opens a draft pull request right away. The earliest
+							open pull request holds the claim.
+						</p>
 					</li>
 					<li>
 						<p class="state ql-turn-in">
@@ -148,7 +152,10 @@ export function Home(props: { setup: string; board: Board }) {
 							</span>
 							Ready to turn in
 						</p>
-						<p>The work arrives as a draft pull request, plan and code reviewed together.</p>
+						<p>
+							The work lands on that pull request, marked ready for review, plan and code reviewed
+							together.
+						</p>
 					</li>
 					<li>
 						<p class="state">Quest complete</p>

design/theme.md

@@ -56,7 +56,8 @@ blocked and `Required:`), with the markers and size colours.
 A quest shows its most advanced state: Ready to turn in, then Accepted by, then
 Available or Requires. Accepted by comes from a live runner lock: an active
 job in kix.quest's database, which moves when its runner goes offline; open changes
-carry Ready to turn in. GitHub uses the pushed quest branch to claim work.
+carry Ready to turn in. On GitHub, a draft PR from the quest branch, opened
+right away and from a fork too, claims work.
 None of these states adds a section to the quest file.
 
 Tokens are display only: a run's spend and donated tokens show with an amber

docs/getting-started.md

@@ -53,7 +53,8 @@ pull request; `/quest-spawn` sends several agents out in parallel when
 your session supports them. Use `$quest-start` and `$quest-spawn` in Codex.
 Check the forge for a live runner lock or an open change before starting.
 kix.quest records each active job in its database and reassigns a job whose
-runner goes offline. On GitHub, check the quest's remote branch and open PRs. `quest ready`
+runner goes offline. On GitHub, check the upstream repository for the quest's
+branch and for open PRs from it, including PRs from forks. `quest ready`
 reads dependencies in the quest tree; it does not look for these live states.
 
 You review each change: `/quest-ready` takes a draft to review, and