code-factory-issue

name	code-factory-issue
description	Use when given a GitHub issue URL to autonomously implement — forks the repo, writes a spec if needed, decomposes into tasks, implements, and opens a PR

Code Factory

Autonomous end-to-end workflow: GitHub issue → spec → multi-file plan → implementation → PR on a fork.

Inputs

The following must be provided or derived from the issue URL:

• ISSUE_URL — full GitHub issue URL
• REPO_URL — repository URL
• REPO_OWNER — upstream repo owner
• REPO_NAME — upstream repo name
• ISSUE_NUMBER — issue number
• REQUESTER — GitHub username of the human who initiated this task

Script invocation

All shell snippets below that start with scripts/... refer to scripts inside this skill's own directory (the directory containing this SKILL.md). Invoke them with an absolute path so the working directory doesn't matter. For example, if this skill lives at <plugin-root>/skills/code-factory-issue/, invoke:

bash <plugin-root>/skills/code-factory-issue/scripts/read-issue.sh "$ISSUE_URL"

The scripts/ prefix in the examples below is shorthand for that absolute path.

Process

State-machine diagram: flow.md. Open it once for orientation if you need it.

Step 1: Read the Issue

scripts/read-issue.sh "$ISSUE_URL"

The script filters out comments from outside contributors (NONE, FIRST_TIMER) so the agent is not steered by untrusted input. Extract from the returned JSON: problem description, reproduction steps, acceptance criteria, any existing spec content, and trusted-contributor comments that add context.

Step 2: Fork & Branch

scripts/fork-and-branch.sh "$REPO_URL" "$REPO_NAME" "$ISSUE_NUMBER"

The script is idempotent: it skips fork creation if the fork already exists, skips adding the fork remote if already configured, and — if fix/issue-${ISSUE_NUMBER} already exists on the fork — checks it out and pulls the latest so a prior agent's work is preserved.

Step 3: Light Codebase Exploration (for classification + spec writing only)

Dispatch one or two Explore subagents to confirm what's needed for classifying the issue and writing the spec — nothing more. The decomposer agent in Step 6 will do its own deep codebase exploration in its own context; replicating it here just bloats the main context.

Scope:

• Files mentioned in the issue and their immediate vicinity (for bug reports: error paths and related tests)
• High-level project shape (language, framework, where the affected subsystem lives)
• Whether the issue's described behavior actually exists in the current code (for bugs)

Do NOT explore:

• Pattern files for new code (the decomposer handles this)
• Reusable helpers / utilities catalog (the decomposer handles this)
• CI command discovery (the decomposer handles this and writes it to standards.md)

Step 4: Classify Issue

After exploring the codebase, determine whether this issue describes a bug or a feature by analyzing the issue content.

Indicators of a bug:

• Describes broken or incorrect behavior ("X is happening when it shouldn't", "expected Y but got Z")
• References a regression ("this used to work", "broke after update/deploy")
• Includes error messages, stack traces, or unexpected output
• Describes a deviation from documented or previously working behavior

Indicators of a feature:

• Describes new capability ("add support for X", "implement Y")
• Requests behavioral change that never existed
• Proposes new API surface, configuration, or integration

Do NOT rely on issue labels — read the issue body and comments to make this determination.

First, check whether the issue body already contains a spec matching the writing-specs format (EARS requirements, system design, testing & validation sections). If so, post a short comment and use it directly:

gh issue comment "$ISSUE_URL" --body "Working on implementing the spec from this issue."

Step 5: Write Spec

If the issue is a bug: Use the bugfix skill to produce a 3-section spec (Current Behavior / Expected Behavior / Unchanged Behavior). Write it to docs/plans/YYYY-MM-DD-issue-${ISSUE_NUMBER}-design.md.

If the issue is a feature: Write a spec using the writing-specs format. Write it to docs/plans/YYYY-MM-DD-issue-${ISSUE_NUMBER}-design.md.

In both cases, post the spec as a comment on the issue:

gh issue comment "$ISSUE_URL" --body "<spec in markdown>"

Clarification markers: If the spec contains [NEEDS CLARIFICATION] markers, post them as a separate issue comment listing each question and the assumed answer. Then proceed immediately — do not wait for a response.

gh issue comment "$ISSUE_URL" --body "## Open Questions

While writing the spec, I made the following assumptions. Please correct me if any are wrong:

1. [question] — I assumed [answer]
2. [question] — I assumed [answer]

I'm proceeding with these assumptions. If you respond with corrections, I'll update the spec and adjust the implementation."

Do not wait for user approval — proceed to decomposition. If the user later comments with corrections, invoke the receiving-feedback skill.

Step 6: Decompose

Use the decomposing-specs skill to break the spec into a multi-file phased task plan. Output: directory docs/plans/YYYY-MM-DD-issue-${ISSUE_NUMBER}/ containing plan.md, standards.md, and phases/NN-<name>.md files (Phase 1 + Verification fully elaborated; intermediate phases as sketches that the executor elaborates just-in-time).

Step 7: Execute

Use the executing-plans skill to implement the plan. Pass it the plan directory path (docs/plans/YYYY-MM-DD-issue-${ISSUE_NUMBER}/), not individual files. This handles:

• On-demand phase loading (only plan.md + standards.md at startup; phase files load one at a time)
• Just-in-time phase elaboration via phase-elaborator for sketched phases (so Phase N is fleshed out against the post-Phase-N-1 codebase)
• Batched / sequential / parallel implementer dispatch
• Size-scaled phase-boundary reviews (Tier A defer for tiny phases, Tier B focused for risky tiny phases, Tier C full suite for ≥3-task phases) with severity-gated re-review
• Final CI verification + full spec review
• Remediation + auto-debug escalation

Step 8: Push & PR

Once execution completes and final validation passes:

scripts/push-and-pr.sh "$TITLE" "$BODY" "$REPO_OWNER" "$REPO_NAME" "$ISSUE_NUMBER" "$REQUESTER"

The script pushes the branch to the fork, opens a draft PR with $REQUESTER as reviewer, prepends Resolves <ISSUE_URL> to the body, and validates all arguments (title length, identifier format, numeric issue number). Do not include Resolves ... in $BODY — the script adds it.

Failure Path

If the issue cannot be resolved after executing-plans exhausts its remediation cycles, do not create a PR. Instead, comment on the issue explaining what was attempted and where it failed:

gh issue comment "$ISSUE_URL" --body "<explanation of what was tried and why it failed>"

Receiving Comments

If new non-outside-contributor comments arrive on the issue during Steps 6–8 (or after), invoke the receiving-feedback skill. It classifies each comment as either a trivial inline change (implement and move on) or a meaningful EARS-requirement change (update spec, re-run decomposing-specs, resume executing-plans).

Autonomy Rule

This workflow never blocks on human input. Three places where questions arise, all handled the same way — post to the GitHub issue and continue:

1. Clarification markers (from writing-specs or bugfix) → post assumptions to issue, proceed with assumed answers
2. NEEDS_HUMAN verdict (from auto-debugger during executing-plans) → post root-cause analysis to issue, treat as BLOCK_TASK, continue with unblocked work
3. Unresolvable failure (executing-plans exhausts all remediation including auto-debugger) → post explanation of what was attempted to the issue, create draft PR with partial work if any tasks completed successfully, or skip PR if nothing is shippable

In all three cases, the PR description (or issue comment if no PR) should include a "Needs Human Input" section listing each unresolved question or blocker with the context needed to make a decision.

Rules

• Always work on a fork — you do not have push access to the upstream repo
• Do not create a PR until final validation passes — All verifications pass + spec compliance confirmed. Exception: create a draft PR with partial work if some tasks completed successfully but others are blocked.
• Link the issue — push-and-pr.sh prepends Resolves ${ISSUE_URL} to the body automatically
• Reviewer — push-and-pr.sh always adds REQUESTER as a reviewer on the PR
• Comment on failure — if you can't resolve it, explain what you tried
• Never wait for human input — post questions to the issue and proceed with best-effort assumptions