lopatin/snaketron/snaketron-skin-factory

Snaketron Skin Factory

This is the thin Hermes operator wrapper for specs/skin-factory-prd.md. The factory CLI owns the state machine, provider calls, persistence, gates, budgets, leases, and retries. Do not reimplement those responsibilities in the agent.

The scheduled Hermes cron runs the same CLI through a non-agent wrapper. This skill handles human status and recovery requests; it is not required to reason through routine production ticks. Installation and rollback are documented in skin-factory/docs/hermes-operations.md.

The factory is model-role based. Its versioned config selects the task worker, Gemini 3.7 Flash smart/judge roles, Gemini 3 Pro Image generation, and the image editor. Never substitute a model silently.

Scheduled run

Run exactly one resumable cycle:

factory run-once --config config/factory.yaml --env-file .factory.env --json

Read the structured result and report only:

• attempts created, resumed, completed, or rejected;
• items newly waiting for prototype review or final review;
• spend against caps;
• pause/halt reason and the action required;
• whether an optimization candidate was promoted.

The installed wrapper and smoke procedure run doctor checks, and run-once checks optimizer readiness. Each stage is idempotent. If Hermes is interrupted, invoke it again; the operation journal reconciles external calls and reports an unknown outcome instead of blindly repeating spend. Do not repair state files by hand.

Preflight failures

Stop and report the CLI's exact error when it identifies:

• another live lease;
• a missing or mismatched pinned provider/model;
• missing service credentials;
• a budget or WIP cap;
• unavailable database/object storage/browser renderer;
• corrupt state or a failed integrity check.

Do not source an interactive shell profile to discover credentials, print secrets, switch providers, clear a halt, or bypass a deterministic gate.

Human requests

Use the CLI rather than editing the database or repository directly:

factory status --config config/factory.yaml --json
factory label attempt_01 artifact_01 --kind prototype_label --outcome accept --actor human:reviewer --feedback-file feedback.txt --env-file operator.json --json
factory re-evaluate artifact_01 --actor human:reviewer --feedback-file feedback.txt --env-file operator.json --json
factory retry attempt_01 --from build --actor human:reviewer --feedback-file feedback.txt --env-file operator.json --json
factory resolve-operation operation_01 --actor human:reviewer --resolution-file resolution.json --env-file operator.json --json

Load the operator credential through --env-file; never place a secret in a command argument. These operator commands require an authenticated human credential. Prototype and final approvals are issued through authenticated review actions that bind an exact artifact or revision hash. The cron service identity has no permission to approve a prototype, resolve an unknown provider operation, publish, override blocking gates, or resume a human halt. Operation resolution requires evidence and records one of the PRD's immutable outcomes. Gates marked blocking: true in the shared manifest are never overrideable.

Blind labels require an explicit accept or reject outcome. Label each artifact independently; machine evaluations for another artifact remain hidden until that artifact receives its own label. Labels never imply approval.

Optimization

run-once automatically enqueues or advances eligible optimization work. Optimization is also available on demand to an operator; it is not an interactive-agent dependency or a second required schedule:

factory optimize --if-ready --target authoring-playbook --json

The command freezes its dataset, calls Gemini 3.7 Flash as GEPA reflection teacher, runs the configured task worker as student, evaluates candidates, and atomically promotes only an allowed playbook diff that passes the PRD's gates. Hermes reports the result; it does not edit the skill, rubric, direction, or tests itself.

Hard rules

1. Every concept and artifact is retained, including machine rejects.
2. Re-evaluation appends an evaluation; retry creates a child attempt.
3. Operational state belongs in the platform database/object store, never in

ad-hoc JSONL or per-tick git commits.

1. Behavioral artifacts are pinned for an attempt and change only between

attempts.

1. A machine may triage but may not start a build. Human prototype_approval

binds the exact build-reference artifact; a training label never authorizes execution.

1. Human publish_approval binds the reviewed revision/content hash and

publishes it immediately; shadow labels never publish.

1. The repository is canonical for direction, skills, rubrics, fixtures, and

config. Notion and agent transcripts are optional import sources only.

1. Workers never receive external side-effect credentials. Only the factory

driver may execute their structured requests through the operation journal.

1. The Hermes service JSON contains no review actor/token or Snaketron operator

token. Cron uses only --script --no-agent --workdir and one run-once job.