Build Your Own
AI Software Factory

---
name: factory-spec
description: Factory stage 1 — turn a feature idea into a build-ready spec through structured questioning, then file it as a Linear issue in the factory queue (team YOUR_TEAM_NAME, state Todo, label Factory Queue). Use when the user wants to spec out a feature, fix, or task. Produces a Linear issue only; never writes code.
---

# /factory-spec — Stage 1: specification

Your only deliverable is a filed Linear issue containing a build-ready spec.
You never write code in this stage.

## Factory constants
- Linear team: **YOUR_TEAM_NAME**
- Queue label: **Factory Queue** (how /factory-build and /factory-review find work)
- Filed state: **Todo**
- Conveyor: `Todo` (specced) → `In Progress` (building) → `In Review` (awaiting QA) → `Done` (set ONLY by review)

## Procedure

### 1. Understand the ask
The skill arguments are the raw feature idea. If empty, ask.
Interrogate the user in batches of at most 4 focused questions until you could
defend every section of the spec template without inventing anything: the
problem and who has it, success criteria, scope boundaries, technical
constraints, verification. If the working directory is the target repo, ground
the Technical approach in real file paths — read the repo's docs and the files
the feature touches. Stop asking when further answers wouldn't change the build.

### 2. Draft the spec
Fill in every section of `spec-template.md` (in this skill's folder). Rules:
- No placeholders, no "TBD". Can't fill a section → back to step 1.
- Acceptance criteria must be independently testable by someone who didn't build it.
- Work honestly larger than ~8 points → split into multiple linked issues.

### 3. One approval pass
Show the user the draft, ask a single go/no-go, accept edits, then file.

### 4. File to Linear
- Duplicate-check first (search open issues by title keywords).
- Create the issue: team YOUR_TEAM_NAME, state Todo, label ["Factory Queue"],
  imperative title, description = the full spec, priority (default Medium),
  estimate in points.
- The repo path MUST be in the spec's **Repo:** header — /factory-build
  cannot work without it.

### 5. Report
Output the issue identifier and URL, then stop. Building is /factory-build's job.

## Guardrails
- Never file a spec with unresolved questions.
- One feature per issue.
- This is the expensive-model stage — depth here pays for itself downstream.
  A vague spec wastes three sessions instead of one.

# <Imperative feature title>

**Repo:** <absolute path or git URL> | **Priority:** <Urgent/High/Medium/Low> | **Estimate:** <points>

## Problem
What's broken or missing, for whom, and why it matters now. One tight paragraph.

## Goals
- Concrete outcomes that define success. Each one observable after shipping.

## Non-goals
- Explicitly out of scope. This section protects the build stage from scope
  creep — be generous here.

## User flow
Step-by-step of what the user sees and does once this ships. Number the steps.

## Technical approach
- **Entry points / affected files:** real paths verified against the repo
- **Data model:** tables/fields added or changed; migrations needed?
- **APIs / interfaces:** endpoints, params, auth requirements
- **Key decisions:** chosen approach and why; alternatives rejected
- **Dependencies:** libraries, env vars, external services

## Acceptance criteria
- [ ] Each criterion independently testable by a reviewer who didn't build it
- [ ] Prefer "user can X and sees Y" over "code does Z"
- [ ] Include at least one failure/edge case criterion

## Test plan
Exact commands to run and expected results — how build proves it works and
review re-proves it independently. Cover happy path, edge, and failure cases.

## Build notes
- Branch: use the Linear-generated branch name for this issue.
- Secrets go in .env / env vars — never hardcoded (checked at review).
- Match repo conventions: read the repo's own docs before writing code.
- <anything environment-specific: ports, services, test data>

---
name: factory-build
description: Factory stage 2 — pull the highest-priority Todo issue labeled Factory Queue from Linear (team YOUR_TEAM_NAME), implement it on a feature branch per its spec, verify it, and move it to In Review with a build report. One issue per invocation. Designed for looped runs (/loop 5m /factory-build) on a cheaper model.
---

# /factory-build — Stage 2: execution

Take ONE specced issue from the queue, implement it exactly to spec, prove it
works, hand it to review.

## Factory constants
- Linear team: **YOUR_TEAM_NAME** • Queue label: **Factory Queue**
- You consume state **Todo**; you produce **In Review**.
- `Done` is set ONLY by /factory-review — never by you.
- Reports open with `**Agent:** <platform / model>`.

## Procedure

### 1. Pick up work
- List issues: team YOUR_TEAM_NAME, state Todo, label Factory Queue.
- Lane filter: if invoked with an argument (e.g. `/factory-build webapp`), only
  consider issues whose Linear project name or labels contain it.
- Pick highest priority, oldest first on ties. Skip:
  - issues whose most recent comment starts `BLOCKED:` (they need a human),
  - issues with unresolved blocking relations,
  - issues whose **Repo:** path is unreachable from THIS session's environment —
    skip these SILENTLY (no comment, no state change); another session will
    take them.
- Queue empty → say "Factory queue: nothing buildable" and stop cleanly.

### 2. Claim it
Set state In Progress, assignee me. Read the FULL spec and ALL comments —
a prior REVIEW REPORT (FAIL) defect list is your primary work order.

### 3. Locate the repo
The spec's **Repo:** header names the working directory. Verify it exists and
is a git repo. Header missing/ambiguous (a spec defect) → comment
`BLOCKED: <what's unclear>`, set state back to Todo, stop.

### 4. Branch
Work on the issue's Linear-generated branch name. Never commit to main/master.

### 5. Implement — with guardrails
- Read the repo's own agent docs (CLAUDE.md / AGENTS.md) first; match conventions.
- Build exactly what the spec describes. NO scope creep — tangents go in your
  report as "suggest /factory-spec", not built.
- Secrets in env vars, never hardcoded — review checks this.
- Spec ambiguous on a load-bearing decision → `BLOCKED: <questions>` comment,
  state back to Todo, stop. Do not guess.

### 6. Verify
Execute the spec's Test plan literally. Every acceptance criterion needs
evidence from RUNNING code — "the code looks right" is not verification.

### 7. Commit
Descriptive messages; record SHAs. Review the staged file list first: never
commit build artifacts (__pycache__/, node_modules/, dist/, logs); add
.gitignore entries as needed.

### 8. Hand off
Post a comment:

**BUILD REPORT**
- **Agent:** <platform / model>
- **Implemented:** <what was built, per spec section>
- **Verified:** <exact commands run and results, per criterion>
- **Branch / commits:** <branch> @ <SHAs>
- **Deviations from spec:** <none, or what and why>
- **Notes for review:** <what the reviewer should check first>

Then set state In Review.

### 9. Stop
One issue per invocation. The loop handles cadence.

---
name: factory-review
description: Factory stage 3 — QA the oldest Linear factory issue in In Review (team YOUR_TEAM_NAME, label Factory Queue) against its spec's acceptance criteria by actually running the code. Fix minor defects directly; pass to Done, or send major defects back to Todo with a defect report. The ONLY stage allowed to set Done. One issue per invocation. Designed for looped runs (/loop 5m /factory-review).
---

# /factory-review — Stage 3: quality assurance

You are the only stage allowed to mark an issue Done. Default posture:
skeptical. The build report is a claim, not a fact, until you reproduce it.

## Factory constants
- Linear team: **YOUR_TEAM_NAME** • Queue label: **Factory Queue**
- You consume **In Review**; you produce **Done** (pass) or **Todo** (fail → rework).
- Reports open with `**Agent:** <platform / model>`. Prefer reviewing work
  built by a DIFFERENT agent/model than yourself when possible.

## Procedure

### 1. Pick up work
- List issues: team YOUR_TEAM_NAME, state In Review, label Factory Queue,
  oldest first. Lane filter: same as build (argument matches project/labels).
- Skip (silently) issues whose **Repo:** path is unreachable from this session.
- Nothing there → "Factory queue: nothing awaiting review", stop cleanly.

### 2. Gather the evidence
Read the full spec, every comment (especially the latest BUILD REPORT), and
the actual diff: check out the branch named in the build report and read
git log / git diff against the default branch.

### 3. Verify by execution, not inspection
- Re-run the spec's Test plan yourself, FROM SCRATCH. Do not trust the build
  report's claimed results — reproduce them.
- Walk EVERY acceptance criterion: pass/fail with observed evidence.
- Baseline checks regardless of spec: no hardcoded secrets or tokens, no debug
  leftovers, input validation on new endpoints/forms, error paths don't crash,
  no unrelated files in the diff.

### 4. Verdict — three outcomes

**PASS** — every criterion verified, baseline clean:
tick the spec's acceptance checkboxes, post the report, set state Done.

**PASS WITH FIXES** — only minor defects (low-risk, no design change, all
fixable in ~15 minutes total): fix on the same branch, commit, re-verify,
list fixes with SHAs in the report, tick checkboxes, set Done.

**FAIL** — any major defect (criterion unmet, design deviation, security
issue, unreproducible verification): do NOT rework it yourself. Post a
numbered defect list (what's wrong → how to reproduce → expected vs actual),
set state Todo — the build stage treats your list as its work order.

Report format (comment on the issue):

**REVIEW REPORT — <PASS | PASS WITH FIXES | FAIL>**
- **Agent:** <platform / model>
- **Criteria:** <n>/<total> verified — one line per criterion: pass/fail + evidence
- **Test plan reproduced:** <commands run, results>
- **Baseline checks:** <clean or findings>
- **Fixes applied:** <none, or list with SHAs>
- **Defects:** <none, or numbered list>
- **Suggestions (out of scope):** <ideas for a future /factory-spec>

### 5. Stop
One issue per invocation. Improvement ideas go in Suggestions — never into
the code during a PASS.