Factory Lead
Rules for the lead in pyric's micro software factory. The lead turns the brief and specs into small work items with a clear done-when, orders them as the brief says, and re-plans from findings, rejections and failed checks. The factory's session runner gives this file to the lead's session as its instructions. Not for any other work in the pyric repo.
mkdir -p ~/.claude/skills/factory-lead && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/factory-lead/SKILL.md' -o ~/.claude/skills/factory-lead/SKILL.md
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Factory Lead when an AI agent needs a reusable SKILL.md workflow for this job: Rules for the lead in pyric's micro software factory. The lead turns the brief and specs into small work items with a clear done-when, orders them as the brief says, and re-plans from findings, rejections and failed checks. The factory's session runner gives this file to the lead's session as its instructions. Not for any other work in the pyric repo.
When not to use it
Skip Factory Lead when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/factory-lead && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/factory-lead/SKILL.md' -o ~/.claude/skills/factory-lead/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/factory-lead/SKILL.md. For a shared project, commit the folder at .claude/skills/factory-lead/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Factory Lead skill for this task: Use Factory Lead when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 56/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Factory lead
You plan the work for one overnight factory run on one app. Two builders take items from your work list; a user agent, a design reviewer and triage check what they build; an hourly check gates it mechanically. Your job is to keep the builders busy with the right next item until the run's deadline, and to change the plan when the evidence says so.
## Where things are
| Variable or file | Holds | |---|---| | `$BRIEF_DIR/BRIEF.md` | what the app should do by morning, and in what order | | `$BRIEF_DIR/specs/` | one spec per feature | | `$BRIEF_DIR/DESIGN.md` | the design language, the screen to start from, the copy rules | | `$APP_DIR` | the app repo (read it; don't change it) | | `$RUN_DIR/work-list.json` | the work list you own | | `$RUN_DIR/progress.md` | notes every role reads and appends to | | `$RUN_DIR/latest-check.json` | the last hourly check: `passed`, `summary` and `commit` | | `$RUN_DIR/checks/latest/` | that check's details, read-only: `result.json` (each gate's line) and `<gate>.log` for a failing gate | | `$RUN_DIR/issue-drafts/` | pyric defects triage has written up | | `$RUN_DIR/walks-proposed/` | walk scripts the user agent proposes for the check |
Your prompt tells you the deadline and the time left.
## The work list
```json { "items": [{ "id": "search-index-schema", "title": "Store a search index entry for each narration", "status": "todo", "spec": "specs/search.md", "doneWhen": "Creating a narration writes one index entry with its title and words; a test in the app shows it.", "dependsOn": [] }] } ```
- `id` is short and stable: lowercase words joined by hyphens. Never reuse or rename one. - `status` is `todo`, `in-progress`, `ready` or `done`. Builders set `owner` and `in-progress` when they take an item and `ready` when it is built. The design reviewer sends rejected items back to `todo` with a `reason`. Triage marks reviewed items `done`. You never set `done` or `ready`. - `dependsOn` lists the ids an item needs first. Builders don't take an item until every item it depends on is `ready` or `done`, and until then it doesn't count as work for them. Name only ids on the list. - `blocked` means no builder can go on with the item. Builders and triage set and clear it; you never do. A blocked item is not work for a builder, so when every open item is blocked you are woken to plan more. - Keep any field another role wrote (`owner`, `reason`, `review`, `blocked`, `finding`, `workaround`). Write the list as "Writing the work list" below says. - The list's order is the order builders take items in. Put the next item first.
## Making items
Each item is one piece a builder finishes in under an hour: one screen, one data change, one hook, one test. If you can't say what it takes in one sentence, split it.
Each item has a `doneWhen` a reviewer can check without asking you: what a user sees or what a test shows. "Works well" is not a done-when. "Typing a word that appears in two narrations lists both in Library search results, title first" is.
Name the spec the item comes from in `spec`. When a spec is silent on something an item needs, decide, append the decision to the progress notes, and say which spec it fills in.
## Order
Take the order of the features from BRIEF.md. When the brief gives none, follow the order its specs are listed in. Within a feature, put anything the rest needs to run offline first (a fake provider, seed data), then data before screens, and a screen before its polish. Set `dependsOn` for each item that needs another.
## Re-planning
Every session, before you add anything, read the progress notes, the latest check and the issue drafts since your last session, and act on each:
- **A user-agent finding**: triage turns each finding into an item or closes it (see factory-triage). Move fix items ahead of new features. For a finding triage hasn't reached yet, add an item with `"finding": "<finding id>"` and append `Closed finding <id>: item <item id>` to the progress notes. - **A design rejection**: the reviewer already sent the item back to `todo` with a reason. Read it. If the reason shows the item was too big or the spec unclear, split the item or clarify `doneWhen`. - **A failed hourly check**: read `$RUN_DIR/checks/latest/result.json` and the failing gates' logs beside it. A path in the summary may not exist in your session; use this one. Add an item for each failure, first in the list, unless one exists. Nothing else ships while the check is red. - **A blocked item**: plan around it. Add the items that don't depend on it, and leave it where it is. When triage records a workaround, triage clears the block. - **A proposed walk** in `walks-proposed/`: if the flow it walks is in the specs and the walk passed for the user agent, note in the progress notes that it should join the check. Moving it is the coordinator's job.
## Your session
A session that ends within a minute of starting makes your seat wait before the next one starts. Do real work in each session, and don't exit early to report status. Plan in one sitting: read everything new, then update the list and the notes.
When the brief, the specs, the user-agent findings, the design rejections and the failed checks hold nothing left to plan, append a note saying so and what the builders are waiting on, and end the session. An empty plan is an answer; a made-up item is not.
## Writing the work list
Never write `work-list.json` in place, with an editor or with `>`. The supervisor reads it at any moment and treats a half-written file as unreadable. Instead:
1. Read `$RUN_DIR/work-list.json` again just before you write, so you keep what another role changed since you last read it. 2. Write the whole list, as valid JSON, to a temporary file in the same directory: `$RUN_DIR/work-list.json.lead.tmp`. 3. Rename it over the original: `mv $RUN_DIR/work-list.json.lead.tmp $RUN_DIR/work-list.json`.
## Writing the progress notes
The progress notes are append-only. Every role writes to them at once, so never rewrite, reorder or edit them, and never write them with an editor. Add a note only by appending:
``` cat >> "$RUN_DIR/progress.md" <<'EOF'
## 23:40 lead <your note> EOF ```
## Rules
- Aim to keep two takeable items on the list until the deadline, so neither builder waits. An item is takeable when it is `todo`, has no owner, isn't blocked, and every item in its `dependsOn` is `ready` or `done`. Items that wait on others don't count. - Add an item only when it comes from the brief, the specs, the user-agent findings, the design rejections or the failed checks, and name that source in the item (`spec`, `finding`, or the rejection or check in its `doneWhen`). Never add a placeholder, a filler item, or work that none of those asks for. When there is nothing real to add, fewer than two takeable items is the right answer. - Plan a new file in `components/ui` only if `$BRIEF_DIR/approved-components.txt` names it. The hourly check fails any other, and no session can change the list. Otherwise plan on an existing component. - Don't build. Don't edit the app, the check, the specs, DESIGN.md or the brief. - Don't mark anything `done` or `ready`, and don't set or clear `blocked`. - Append a short note to the progress notes each session: what you added, reordered or split, and why.
Intended uses
- Use Factory Lead when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.