madarauchiha-314/the-loop/handoff-to-the-loop

Hand a conversation to the-loop

A developer who has talked an idea through with Claude should not have to re-type it as a spec. This skill turns the conversation into the artifacts it supports, files them on a GitHub issue with a handoff record, and lets the-loop's poller start the work at the stage the developer reached instead of at the first phase.

The rule: draft, interview, confirm, then post. Nothing leaves this conversation

before the developer confirms the summary, and the furthest artifact is never approved

here — its approval gate on the ticket does that.

The spec behind this skill is the-loop's issue-517 (docs/specs/issue-517/).

When to use it, and when to refuse

Use it when the developer asks to hand the conversation, an idea, or a draft spec to the-loop, in any words, or runs /the-loop:handoff.

Refuse, and post nothing, when nobody is at the keyboard. A handoff is a developer-attended act. Stop and say "a handoff needs the developer present; run it from your own session" when any of these holds:

• the prompt carries the-loop's interaction mode: work-item directive;
• THE_LOOP_WORK_ITEM or THE_LOOP_INSTANCE is set in the environment (a

daemon-spawned session);

• the question tool (AskUserQuestion) is disallowed in this session.

Overview

flowchart LR
  d[1 Draft] --> t[2 Transport] --> i[3 Interview] --> c[4 Confirm]
  c -->|yes| iss[5a Issue] --> j[5b Jira copy] --> b[5c Branch + draft PR]
  b --> a[5d Spec-chain artifact] --> r[5e Handoff record] --> n[5f Next step]

Steps 5b to 5d run only when chosen or possible. The record is posted after everything it points at exists, so it never names something that failed.

1. Draft what the conversation supports

Draft only the artifacts the conversation actually settled, as a prefix of the spec chain: brainstorm.md → requirements.md (or bugfix.md for a defect) → design.md → testing-plan.md. Never invent a later artifact to fill the chain.

• Sources: this conversation, plus any docs/specs/draft-*/ files when a repository

is checked out. Read those before drafting, and build on them.

• Templates: use the-loop's templates when the plugin is installed

(${CLAUDE_PLUGIN_ROOT}/skills/the-loop/templates/<name>.md, the same path in Cursor). On a surface without them, keep these sections:

• The brainstorm keeps what was rejected. A chat that never ran /the-loop:brainstorm

still becomes a brainstorm.md; its Ideas & options lists every option the conversation weighed, the rejected ones struck through with the reason. A rejected option is a finding.

• Front-matter: status: draft and approvedBy: [] on every file, and

workItem: draft-<slug> until the issue exists. Never write status: approved; the the-loop gates and the import-handoff hook do that.

• Write for the reviewer. Follow the the-loop:writing skill when the plugin is

installed. A gated section stays even when it is empty, with one sentence saying why.

In a checkout, the drafts may be written to docs/specs/draft-<slug>/. Commit nothing yet. Elsewhere, keep them in the conversation.

2. Pick the transport

Every later step goes through the first of these that works, and the summary names it:

1. the-loop CLI, when the-loop --version runs.
2. A GitHub or Atlassian connector, on the Claude chat and desktop apps.
3. `gh`, when it is installed and authenticated.

With none of the three, stop: show the drafts and say what is missing.

3. The interview

Ask four questions, in this order, with the harness's question tool (AskUserQuestion in Claude Code). Each question has at most four options plus free text. Preselect every answer the conversation implies, and say why in the option's description. On a surface without a question tool, ask the same questions in one message, with the preselected answer marked, and wait for the reply.

The stage decides the artifacts carried (§ Stage table). If the drafts do not fit the stage picked, say so and ask again; for example, design settled needs a requirements.md and a design.md.

Validate free text as it is entered, and ask again on a bad value:

• the repository must match ^[\w.-]+/[\w.-]+$;
• the Jira project key must be listed by the-loop ticket projects. Without the CLI there

is no config to check against, so Jira is not offered, and the summary says so;

• an epic key must look like PROJ-123;
• an existing issue must exist and be open in that repository.

The next step means:

• Run now: add every arming label and post the-loop start (§ 5f).
• Continue in this session: register this session on the item and run

/the-loop:work-on <id> here. Offered only in a checkout with the CLI.

• Queue it: add the arming labels only. The item waits for a the-loop start.
• Just file it: the issue and the record, nothing else.

4. The confirmation summary

Show one summary and wait for an explicit yes. It lists everything the next step will do:

• the transport (CLI, connector or gh);
• the GitHub issue: new (title, loop:<phase> label) or the existing one attached to;
• the Jira copy, when chosen: project, issue type, epic, title, the the-loop-mirror

label;

• in a checkout: the files under docs/specs/<id>/, the branch the-loop/<id>-<slug>,

and the draft PR title;

• the spec-chain artifact, when chosen: its title and one tab per file;
• the handoff record: stage, starting step, artifacts, carrier, and which earlier

artifacts this confirmation approves (§ Approved in chat);

• the next step, with the exact arming labels.

Quote the developer's reply verbatim. It goes into the record as confirmation, and it is the paper trail for every artifact the handoff counts as approved. A reply that asks for changes is not a confirmation: revise and show the summary again.

5. Post, in this order

5a. The GitHub issue

• New issue: title from the furthest artifact's summary; the body is a short

statement of the problem plus what is carried, linking files rather than pasting them. Apply the stage's loop:<phase> label (§ Stage table) and no arming label yet.

• CLI: the-loop ticket create --repository OWNER/REPO --title "…" --body-file body.md --label loop:<phase>.
• Connector, or gh issue create --repo OWNER/REPO --title "…" --body-file body.md --label loop:<phase>.
• Attach to an existing issue: create nothing. Add the loop:<phase> label only when

the issue has none.

• The work item's id is issue-<N> and its ref github:OWNER/REPO#<N>. Without a

checkout, link no file path that no remote branch holds.

5b. The Jira copy (CLI only)

the-loop ticket create --project PROJ --issue-type Story [--parent PROJ-7] \
  --title "…" --body-file jira-body.md --label the-loop-mirror

The description opens with the GitHub issue URL. The copy carries the-loop-mirror and never an arming label, so no session ever starts from it. Note the jira:SITE/KEY-N ref the CLI prints; the record's mirror line names it on the GitHub issue. When the Jira create fails, say so, leave mirror out of the record, and carry on: GitHub is the tracker.

5c. In a checkout: branch and draft PR

1. Promote docs/specs/draft-<slug>/ to docs/specs/<id>/ (all files, the brainstorm

included) and set workItem: <id> in each file's front-matter. The front-matter edit happens before hashing.

1. Create the branch the-loop/<id>-<slug>, commit the files

(docs(<id>): hand off at <stage>), and push it.

1. Open the draft PR. pr create needs a registered session, so register first:

``bash the-loop sessions register --work-item github:OWNER/REPO#N --harness claude \ --harness-session-id "$CLAUDE_SESSION_ID" the-loop pr create --work-item github:OWNER/REPO#N --title "docs(<id>): <title>" \ --body-file pr-body.md --draft ``

Unless the next step is continue in this session, close the registration afterwards (the-loop sessions close --work-item …) so the poller spawns its own session. Without the CLI: gh pr create --draft --head the-loop/<id>-<slug>.

The record then says carried-by: branch the-loop/<id>-<slug> · PR #<n>.

5d. The spec-chain artifact (when chosen)

Publish one artifact titled <id>: <title>, one tab per carried file in chain order, mermaid rendered. Embed the files' exact text, so the session that imports the handoff can extract the bytes the record hashed:

<script type="application/json" id="the-loop-spec-files">
[{"name": "brainstorm.md", "md": "…exact file text…"},
 {"name": "requirements.md", "md": "…exact file text…"}]
</script>

• name is one of brainstorm.md, requirements.md, bugfix.md, design.md,

testing-plan.md. md is the file's text exactly as hashed, JSON-escaped, with every </ written as <\/ so the text cannot close the script tag.

• The record's spec-artifact line is <artifact URL> sha256:<hex>, where the hash is

over the JSON text between the script tags (LF line endings, UTF-8).

• On a harness without an artifact tool (Codex, Cursor), skip this step, carry the files

in the ticket, and say so in the record's from line, e.g. Cursor · 2026-10-21 · no artifact tool.

5e. The handoff record

Post it on the GitHub issue, last but for the arming (§ The handoff record).

• CLI: write the record as JSON and post it.

``bash the-loop handoff post --work-item github:OWNER/REPO#N --record record.json \ [--files <dir holding the carried files>] ``

--files is for carriedBy: "ticket" only; the CLI hashes every file against the record, renders the <details> blocks and any part comments, and posts them in order.

• Connector or gh: write the record by hand in the exact wire format below and post it

as a comment. A record you post is trusted because you are an authorized user; one malformed character makes the poller ignore it and start from the first phase.

5f. The next step