agentleFS
ChristopherAlphonseChristopherAlphonse/calphonse-skills/factory/SKILL.md

factory

Skill1 starsChanged yesterdayMITView on GitHub

Take a feature from idea to a reviewed local commit by chaining the other skills in this repo as stages (shape, spec, build, review, polish, prove, ship), with a kanban board, a scripted state machine, and a headless tick. Picks skills for the codebase automatically (TypeScript and React get typescript-strict-style and vercel-react-best-practices, C# gets dotnet, Python gets python). Built and measured for Claude Code. Use when the user wants a whole feature driven end to end, a software factory, a pipeline, or the board. Never commits without the user's click and never pushes or opens a PR or MR. To review an existing branch, use factory-review instead.

  • Reads credentials
  • Sends data out
  • Commits and pushes

22 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use status and implement.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AnthropicSkill

    status

    Case status summary by audience — client-facing (plain language), internal (for the professor), or court-ready (formal caption format per local rules). Same facts, different framing and depth. Use when a student needs to update the client, brief the professor, or prepare a court status report.

    Also in 3 projects that use this

  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Audit: Every state change is one line in .planning/factory/audit.log.

    line 37
  2. Very specific:

    Keep skill frontmatter to name and description, with name equal to the folder name.

    line 67
  3. Very specific:

    After an agent returns, call JOB advance <id> <next> with the target the file justifies.

    line 116

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Factory

You are the orchestrator. You do no stage work yourself. For each stage you spawn a fresh subagent, with your harness's own mechanism, that runs the skill that owns the stage. Then you move the job with bin/job.

JOB means this skill's bin/job. TICK means bin/tick. Run both from the target project root. State lives in .planning/factory/ and worktrees in .worktrees/, both in the target project, never in this repo. Gitignore both there.

First action

Before any other tool call, including JOB create and JOB queue, run JOB board. It starts the read-only board if none is running and prints its link as 127.0.0.1:PORT/?c=CODE. Then write that link to the user as a message of its own, with the http scheme added and the code included, so it is clickable, and only then continue. The point is that the user watches the work happen, so the link must reach them before the first stage starts, never in the final report. Do not spawn a subagent, read the repo, or plan first. Repeat the link in every report that ends a pass. The board keeps running between passes and the link stays the same while it does. If JOB board refuses, say so in that first message and give JOB watch as the fallback. Do not use JOB serve: only the user starts that.

Waiting on the user

Whenever a job waits on the user (spec approval, Commit locally, Unblock), end the message with the command that opens the board with the buttons, in its own code block, with absolute paths and without being asked: cd <project root> && <absolute path of JOB> serve. JOB advance, JOB create, and JOB queue print it on stderr as well; copy it from there. Say that the read-only link has no buttons and this board does. Never run the command yourself: serve prints its one-time link in the user's terminal.

Then do not end your turn. Run JOB wait (90 seconds by default, JOB wait 110 to choose). It prints RESUME: <ids> ... the moment the user clicks, and then you run JOB queue and carry on. It prints STILL WAITING and exits 3 on timeout: run it again, and keep going until it prints RESUME, the user answers in chat, or the user says to stop. The board cannot message you, so this is how a click reaches you. A scheduled TICK pass picks the click up the same way on its next run.

Workflows

This skill runs the build workflow: a feature idea becomes a local commit and a PR body. JOB create <id> "<title>" makes a build job.

To review an existing branch or PR, use the factory-review skill. It is a separate skill with its own engine, board, and state folder (.planning/factory-review/), and it never writes code.

Enterprise policy

These hold in every harness and are enforced by structure, not by this text.

  • Baseline shell rules. policy.yaml is the human-in-the-loop baseline for every harness (Claude Code, Kiro, OpenCode). It denies git push, aws s3 rm, and curl -X POST, asks before every git verb that changes a repository, and allows a list of read-only commands. Deny beats ask, and ask beats allow. A command no rule names is not allowed, so it waits for a human. TICK turns the file into each harness's format and refuses a headless pass until the project's policy covers it. The factory's own denies below are stricter, never looser.
  • No commit, push, PR, or MR without the user. Agents leave changes uncommitted in the job's worktree. The only commit is JOB commit, which the user triggers from the board. It runs the repo's own hooks and refuses unless the tree matches the one that passed the gate.
  • Never run git commit, git push, git merge, git rebase, git config, git -c, git -C, gh, glab, curl, or wget. Never use the network.
  • Never try to run approve, commit, or unblock, or to start JOB serve. They belong to the user, and the CLI refuses them. JOB watch is the exception: it is a read-only board with no key and no action routes, and you may start it so the user can follow along.
  • Protected paths (CI config, CODEOWNERS, .env, factory config, plus any in config.json) fail the gate when touched.
  • Audit. Every state change is one line in .planning/factory/audit.log.
  • Board. The user starts JOB serve in their own terminal. It binds to localhost, redeems a one-time code for a session cookie, and holds the approval key in memory. The user's clicks are the only approvals.

How each layer is enforced, and how far to trust it:

LayerWhat it doesStrength
Harness rules, generated by TICK from policy.yaml and one deny liststop the agent running commit, push, merge, rebase, cherry-pick, revert, am, commit-tree, update-ref, config, git global options (-c, -C), gh, glab, curl, wget, sh -cMeasured on Claude Code: 24 of 24 attack spellings blocked, each one succeeding in a no-policy control. A command wrapper the list does not name, such as a script that shells out, is still not covered
Integrity checks in JOB (branch tip, hook config and files, remote refs, job.json against the audit log)detect a commit, push, or edited state that got past the other layers, and park the job on the userDetection only. An agent that shares your file permissions can still edit files and run git. It cannot do so silently
Per-worktree git hooks (pre-commit, pre-push, reference-transaction)refuse commits and pushes without the board's key, and chain to the repo's own hooksA speed bump. git -c core.hooksPath=/dev/null, unsetting the hooks path, --no-verify on push, and writing refs directly all defeat them. Do not rely on them alone
Board key and sessionapprove, commit, and unblock only run inside JOB serve, which needs a terminal, a one-time code, and a key held in the server's memoryStops an agent using the CLI. It does not stop a process running as you from opening its own terminal
TICKrefuses a headless run unless the harness's policy is installedHard, for runs it starts
Your remote's protected branches and MR rulesthe only layer an agent on your machine cannot editThe real guarantee. Turn it on for any repo the factory touches

Harnesses

Kiro, Claude Code and OpenCode get the same policy and the same guard. tick install <harness> writes the harness's own rules, plus bin/guard as a tool-call hook (a Kiro PreToolUse hook, a Claude Code PreToolUse hook, an OpenCode tool.execute.before plugin). The hook exists because each harness has a mode that skips its own prompts (Kiro --trust-all-tools, Claude Code bypass mode) and none of them can say "everything except". A hook still runs. The guard applies deny, then ask, then allow to every shell segment of a command, treats a command no rule names as blocked, checks redirect targets and file-tool writes against the protected paths, and exits 2 on any input it cannot read. tick check <harness> fails if the hook or its rules file differ from tick print <harness>. What is measured: on Kiro (v3 engine, kiro-cli 3.3.0) every conclusive attack in tests/probe_harness.py was blocked under --trust-all-tools, each succeeding in a control with no policy. Claude Code's deny rules were measured earlier (24 of 24), but its hook and the OpenCode plugin were not run against the real CLIs, since neither is installed where this was built. Their guard logic is unit-tested with each harness's tool names, and the OpenCode plugin is loaded under Node, so run tests/probe_harness.py claude and tests/probe_harness.py opencode before trusting either. Not covered on any harness: an allowed program that writes files by itself (a build tool), and sub-agents, whose hooks were not tested. The JOB integrity checks catch those. TICK passes no trust or bypass flag.

Claude CodeOpenCodeKiro
Skills dir.claude/skills.agents/skills.kiro/skills
Headless passclaude -popencode runkiro-cli chat --v3 --no-interactive --agent factory
Policy.claude/settings.json, .claude/hooks/opencode.jsonc, .opencode/plugins/, .opencode/guard/.kiro/agents/factory.json, .kiro/hooks/

TICK install <harness> writes the policy (deny, ask, and allow rules, plus the file-write limits) into the project and never overwrites, and TICK print <harness> prints them to merge by hand. TICK check <harness> exits non-zero when any blocked command is not denied, and TICK list shows the list. TICK <harness> checks, then runs one pass.

tests/probe_harness.py <harness> runs every attack with and without the policy in a scratch repo and reports BLOCKED, GAP, or INCONCLUSIVE. On Claude Code, 24 of 24 attacks were blocked, each succeeding in the no-policy control. On OpenCode only 4 attacks had a valid control, and all 4 were blocked. The probe refuses to attack until a canary shows the harness is inside the scratch repo.

Tests, linters, formatters in check mode, type checkers, and code-quality tools run unattended. policy.yaml allows them for JavaScript and TypeScript, Python, .NET, Go, Rust, Java, Ruby, shell, Terraform, Docker, YAML, Markdown, and make test, make lint, make check, and make verify. TICK install also allows the project's checks command and any patterns in the allow list of .planning/factory/config.json. Installs, publishes, deploys, and uploads are not on any list. Formatters and fixers that rewrite files (prettier --write, black, ruff format, gofmt -w, cargo fmt, dotnet format, terraform fmt, npm run format) are in policy.build.yaml, which only this skill loads. Any other command that no rule names waits for a human. A builder that needs a command no rule names stops and writes STATUS: BLOCKED. The project's allow list can never override a deny or an ask, and the agent cannot edit config.json.

Keep skill frontmatter to name and description, with name equal to the folder name. Kiro requires that.

Rules

  • JOB is the only writer of job.json. Never edit it. JOB advance checks the files that justify a move and refuses the rest.
  • Builders write code and leave it uncommitted. Reviewers never edit. Fixes go back to a builder.
  • A gate passes on a command's output, never on an agent saying "done". JOB gate runs checks from .planning/factory/config.json. If checks is empty, stop and ask the user.
  • Each subagent starts fresh. Its prompt gives the job id, the job folder, the worktree and branch, and the stage's one-line brief. It replies with one line.
  • Spawn stage agents in parallel where the stage allows, then wait for all of them before the pass ends. A headless pass ends the process, so nothing may be left running.
  • A job gets max_rounds build rounds (default 3). The next failure moves it to needs-human on its own.
  • Concurrency comes from config.json (default 1).

Build workflow

Each stage's agent writes the file named here with the status line first. JOB advance reads that line.

StageSkillWritesAdvance when
shapelets-talk-about-it, plus spike only if the shape rests on an unknownshape.md with STATUS: READY, or rejection.mdto spec, or rejected
specprd-mode, then its task listspec.md, tasks file under .planning/tasks/user approves on the board, then to build (this creates the local worktree and branch)
buildswe plus stack skills, one task at a time, no commitsbuild.md with STATUS: READY or BLOCKED. Run JOB progress <id> <done> <total> after each taskto gate, or needs-human when blocked
gateJOB gate <id> (a script, not an agent)round-N/checks.md with GATE: PASS or FAILto review on pass, build on fail
reviewsee Reviewersround-N/review-<name>.md with VERDICT: PASS or CHANGES, then reconcile.md from reconcile-reviews when anything is CHANGESto polish when all pass, else build
polishcomment-sicko, then unslop on prose touchedpolish.md with STATUS: DONE or REWORK. No committo gate when done (the gate reruns), build when comment-sicko condemns workaround code that needs a real fix
gate againJOB gate <id>round-N/checks.mdto prove on pass
proveprove-it-worksuat.md with STATUS: PASS or FAILto ship on pass, build on fail
shippr-body-style (+ demo-script optional)pr-body.md, and commit.md holding the commit messageuser clicks Commit locally on the board, then to ready

Stack skills are chosen by bin/job, not by you. It reads the file names and writes the result to job.json and to the queue hint (stack skills: ...). JOB stack <id> refreshes it after the build adds files.

If the files includeUse
.ts, .tsx, .js, .jsx and variantstypescript-strict-style
.tsx, .jsx, or next.config.*vercel-react-best-practices
proxy.ts, proxy.js, middleware.ts, middleware.jsnextjs-proxy-csp-hardening
.cs, .csproj, .sln, .cshtml, .razordotnet
.py, .pyi, pyproject.toml, uv.lockpython
.tf, cdk.json, serverless.yml, samconfig.tomlaws

For a build job the files are the whole repo. Review jobs (see factory-review) use only the files in the diff. If .planning/ has no codebase map, run whats-going-on before Shape.

Reviewers

code-review-frontend, qa-review, and test-review always. Add security-review when the diff touches auth, input handling, secrets, or headers, and architecture-review when it crosses service or module boundaries. Register the extras with JOB route <id> security,architecture before spawning. Review names on disk are code, qa, test, security, architecture.

Run

  1. JOB queue. Each row is action id stage hint. Act only on run rows. hold means the job waits on the user. wait means over the concurrency cap. done is finished.
  2. For each run row, spawn the stage's subagent with the hint as its brief. When the stage's file is already on disk, call JOB advance instead of spawning.
  3. After an agent returns, call JOB advance <id> <next> with the target the file justifies. If it refuses, read the message, send the stage back once with the problem named, and after a second refusal have the builder write STATUS: BLOCKED. While working a job, run JOB note <id> "<what you are doing>" when you start a stage and at each meaningful step (a short phrase, under 200 characters). The board shows the latest note on the card, which is the only live view of work between stage changes.
  4. Report the rows touched, any hold rows and what they wait on, and the board address.

Loop

A pass finds nothing to run, or only hold rows, and ends. To continue automatically after the user's click, the user starts TICK loop <harness> [seconds] in a terminal (default 15 seconds). It reads JOB queue and runs a pass whenever a row says run, so approving a spec, committing, or unblocking starts the next pass with no chat message. It never approves anything, runs one loop per project, and stops retrying a state that changed no job file in two passes (stalled, visible on the board). --once does a single check. Alternatively schedule TICK <harness> with cron or launchd every few minutes. In Claude Code, /loop 5m /factory run does the same interactively. Everything is files, so any pass resumes every job from its stage, in any harness.

Board

JOB board starts the read-only view if needed and prints its link (see First action); JOB watch [port] (default 8766) runs it in the foreground. It needs no terminal, holds no key, and answers no approve, commit, or unblock request. Its link stays valid until the process stops and can open in several tabs. Anyone, including an agent, may start it. JOB serve [port] serves the kanban on 127.0.0.1 and prints an address with a one-time code. It only starts in an interactive terminal. The board reads .planning/factory/jobs/*/job.json every 2 seconds. Columns: Shape, Spec, Build (build and gate), Review, Polish, Prove, Ship, Needs you, Ready to land. Cards show round, gate, one chip per reviewer, task progress, and the local commit. A card waiting on the user is outlined. Approve spec, Commit locally, and Unblock are the only buttons, and the only way those moves happen. Click a card to read every file in its folder. The board looks and behaves the same whichever harness ran the pass.

Out of scope

The factory never pushes, opens a PR or MR, merges, or deploys. ready means a local commit exists and a PR body is written. The user pushes and opens the MR by their own process.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.