---
name: gpt-factory
description: Use when launching a software task through Factory with ChatGPT Sol. Packages complete file-backed repository context, writes title-safe request, launches Pro-default factory-gpt, and watches the durable run without exploratory help turns.
argument-hint: "<job description|plan-path>"
---

# GPT Factory

Audience: AI coding agents first.

Launch Factory through `factory-gpt`. Supply complete initial context as files. Sol receives no implicit conversation, repository history, terminal state, plan, spec, or WIP knowledge. Pi may execute mediated host tools after launch; that does NOT replace complete initial file context.

## Non-negotiable semantics

1. First line of request file MUST be one plain-text, one-line job description. Factory uses it as title.
2. Request MUST name every attached context file by relative path and state why it matters.
3. Package current repository state, not remembered state: checkout path, `HEAD`, `origin/main`, merge-base, branch, status, tracked diff, staged diff, untracked manifest, plan/spec, rules, bounded source, bounded tests.
4. Launch from task-owned isolated worktree. NEVER launch against shared/default checkout.
5. Keep context files inside launch repository so Pi and Factory can read them. “Attached” means explicitly referenced file-backed context, not prose pasted into prompt.
6. NEVER send secrets, credentials, tokens, browser profiles, `.env`, private conversation registries, `.git`, dependency trees, caches, build output, or unrelated source.
7. Default effort is `pro`. Use `--effort medium|high|xhigh` only when owner/task contract requires it. NEVER downgrade on failure.
8. Use exact commands below. NEVER spend turns running `--help` or rediscovering invocation syntax.

## Inputs

Resolve before packaging:

- one-sentence job description;
- task-owned worktree absolute path;
- authoritative plan/spec paths;
- applicable `CLAUDE.md`, `AGENTS.md`, skill, policy, or runbook paths;
- bounded implementation source/tests/config required to perform task;
- preserved WIP that task must retain;
- acceptance commands and expected behavior;
- prohibited paths/behaviors.

Missing authoritative requirement → stop and locate it locally. Do not ask Sol to infer it.

## Create context package

Run from task-owned worktree root:

```bash
set -euo pipefail
slug='<short-kebab-task-slug>'
ctx=".factory/context/$slug"
mkdir -p "$ctx/repo" "$ctx/requirements" "$ctx/source"

git fetch origin
printf '%s\n' "$(pwd -P)" > "$ctx/repo/worktree.txt"
git rev-parse HEAD > "$ctx/repo/head.txt"
git rev-parse origin/main > "$ctx/repo/origin-main.txt"
git merge-base HEAD origin/main > "$ctx/repo/merge-base.txt"
git branch --show-current > "$ctx/repo/branch.txt"
git status --short --branch > "$ctx/repo/status.txt"
git diff --binary origin/main...HEAD > "$ctx/repo/committed.patch"
git diff --binary > "$ctx/repo/working.patch"
git diff --binary --cached > "$ctx/repo/staged.patch"
git ls-files --others --exclude-standard > "$ctx/repo/untracked.txt"
```

`git fetch origin` failure → stop. NEVER package stale `origin/main` as current.

Copy required files while preserving repository-relative paths:

```bash
copy_context() {
  local src=$1 dst="$ctx/source/$1"
  test -f "$src" || { printf 'missing context: %s\n' "$src" >&2; return 1; }
  mkdir -p "$(dirname "$dst")"
  cp -- "$src" "$dst"
}

copy_context CLAUDE.md
copy_context docs/plans/<authoritative-plan>.md
copy_context docs/specs/<authoritative-spec>.md
copy_context path/to/required/source
copy_context path/to/required/test
```

Add every applicable parent/project instruction file. If WIP depends on untracked files, copy each required untracked file explicitly; `untracked.txt` alone is not content.

DO NOT package whole repository. Pi operates in current worktree and can read files later; package only authoritative initial context and task-bounded implementation surface.

## Write request file

Create `.factory/requests/<slug>.md`:

```markdown
<One-line job description; no prefix, heading marker, bullet, or newline inside title>

## Outcome
<Exact owner-visible result.>

## Repository snapshot
- Worktree: `.factory/context/<slug>/repo/worktree.txt`
- HEAD: `.factory/context/<slug>/repo/head.txt`
- origin/main: `.factory/context/<slug>/repo/origin-main.txt`
- Merge-base: `.factory/context/<slug>/repo/merge-base.txt`
- Branch/status: `.factory/context/<slug>/repo/branch.txt`, `.factory/context/<slug>/repo/status.txt`
- Committed delta: `.factory/context/<slug>/repo/committed.patch`
- Working delta: `.factory/context/<slug>/repo/working.patch`
- Staged delta: `.factory/context/<slug>/repo/staged.patch`
- Untracked manifest: `.factory/context/<slug>/repo/untracked.txt`

## Mandatory context
- `.factory/context/<slug>/source/CLAUDE.md` — repository rules
- `.factory/context/<slug>/source/docs/plans/<plan>.md` — authoritative request and acceptance
- `.factory/context/<slug>/source/docs/specs/<spec>.md` — architecture contract
- `.factory/context/<slug>/source/<source>` — current implementation seam
- `.factory/context/<slug>/source/<test>` — required regression contract

Read every listed file before planning or editing. Treat snapshot files as authoritative launch-time state. Use mediated Pi tools for current host operations. Preserve unrelated WIP. Never modify prohibited paths.

## Acceptance
- Run: `<exact focused command>`
- Expected: `<exact clean result>`
- Run: `<exact full gate>`
- Expected: clean exit 0 with no warnings

## Delivery
Build, test, review, correct, and produce Factory receipts. Do not claim land/deploy unless workflow actually performs and proves them.
```

DO NOT start first line with `#`, `Task:`, filename, ticket ID alone, or generic text such as “Implement changes.” Title must describe job in one line.

Good first line:

```text
Prevent duplicate invoice capture during concurrent payment retries
```

DO NOT:

```text
# Task
```

## Validate package before launch

```bash
set -euo pipefail
request=".factory/requests/$slug.md"
test -s "$request"
title=$(sed -n '1p' "$request")
test -n "$title"
test "$title" = "${title//$'\n'/}"
test "${title#\#}" = "$title"

test -s "$ctx/repo/worktree.txt"
test -s "$ctx/repo/head.txt"
test -s "$ctx/repo/origin-main.txt"
test -s "$ctx/repo/merge-base.txt"
test -s "$ctx/repo/status.txt"

test "$(<"$ctx/repo/head.txt")" = "$(git rev-parse HEAD)"
test "$(<"$ctx/repo/origin-main.txt")" = "$(git rev-parse origin/main)"

grep -Fq ".factory/context/$slug/" "$request"
if grep -RIlE '(BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY|api[_-]?key[=:]|password[=:]|bearer [A-Za-z0-9._-]{16,})' "$ctx"; then
  printf 'gpt-factory: possible secret in context package\n' >&2
  exit 1
fi
```

Review `status.txt`, patches, and `untracked.txt` manually. Ensure every task-relevant dirty/untracked file is copied or intentionally excluded in request.

## Launch

Default Pro:

```bash
factory-gpt adw_plan_build_test_quality ".factory/requests/$slug.md"
```

Explicit effort:

```bash
factory-gpt --effort high adw_plan_build_test_quality ".factory/requests/$slug.md"
```

`factory-gpt` validates preset, starts authenticated virtual `solwebd`, selects `gpt/sol-web-<effort>`, and launches Factory. It has no provider fallback.

Capture returned `adw_id` immediately in durable plan/ledger. A new launch always creates a new run. Nonzero wrapper exit does not authorize blind duplicate launch: inspect trace and provider state first.

## Observe and control

```bash
factory watch <adw_id> --since-start --follow
factory decisions --adw <adw_id> --json
factory answer <decision_id> --choice <value>
factory answer <decision_id> --text '<answer>'
factory stop <adw_id>
```

Watch owner-visible progress at Overdeck `/factory`. Use `factory watch <adw_id> --since-start` after compaction/handoff.

Do not rapid-poll. Tracked process completion or `--follow` owns waiting.

## Completion gate

1. Read Factory receipt and changed diff.
2. Verify exact `HEAD`/`origin/main` assumptions remain valid; refresh before integration.
3. Run deterministic local acceptance independently.
4. Address every warning/security signal.
5. Land/deploy/install only through repository procedure when workflow did not already prove it.
6. Verify installed owner-visible behavior.
7. Update durable plan with `adw_id`, request path, last phase, commit, deployment, and runtime proof.
8. Mark DONE only after owner can use result.

## Failure rules

| Signal | Required action |
|---|---|
| Missing plan/spec/source | Add file and request reference; do not ask Sol to guess |
| `origin/main` changed after packaging | Rebuild snapshot before launch |
| Context too large | Narrow source/test surface; NEVER drop rules or authoritative contracts |
| Provider capped/unavailable | Record typed failure; no fallback or effort downgrade |
| Factory asks decision | Answer through `factory answer`; preserve receipt |
| Run fails after edits | Inspect trace/diff, preserve WIP, correct deterministically; never duplicate blindly |
| Model prose suggests shell commands | Pi/Factory mediates tools; never execute prose as an unvalidated command channel |
| Worktree dirty from unrelated work | Preserve it; create task-owned worktree; never stash/clean shared checkout |