overkill-factory

name	overkill-factory
description	Operate the Overkill Factory product-production line. Use when turning raw product papers into Product SOT, Product Experience OS/Product Face, security architecture, access readiness, Hermes Kanban cards, agent execution, Receipt Five evidence, human gates, pilots, Factory VNext methodology updates, or professional open-source GitHub stewardship for the public factory repository.

Overkill Factory

Overkill Factory is a gated product-production line for autonomous agents. Use Hermes Kanban as the primary runtime unless the user explicitly selects a different runtime.

First Move

1. Identify the current factory phase: source, SOT, architecture, Product Experience OS/Product Face, review, decomposition, execution, verification, promotion, pilot, VNext or public GitHub stewardship.
2. Separate source facts from inference and decisions.
3. If Hermes runtime state matters, use the hermes-kanban skill and inspect the real Hermes runtime/board before mutating anything.
4. Do not promote work from planning to execution without the matching gate.
5. For current deterministic-control-plane work, compile or inspect the workflow plan and validate the FactoryRun/command/event/decision/promotion contracts before trusting an agent's route choice.
6. For external research, check existing local artifacts/source ledgers before recapturing browser or social content.
7. Do not put raw study extraction, screenshots, private ledgers, local paths, private links or internal product names into the public factory repository.
8. If the work touches the public GitHub repository, treat GitHub as a product surface for an external operator with their own Hermes, not as an archive of this workspace.
9. Match the operator's language on every user-facing surface: chat, status, decision questions, owner-readable documents and Kanban card titles/summaries. Keep only internal machine surfaces such as schema keys, ids, step keys, worker ids and logs in English when useful.
10. Do not subscribe the operator directly to Kanban cards, worker completions, cron/watchdog messages or artifact dumps. The only human-facing voice is the selected manager profile, normally overkill-factory-gerente, which reports readable status and decision packages.

Factory Spine

Mandatory Factory Start

For a new product/project, a manager, bridge, or operator must not create a Hermes board or first phase card by hand. A new project only starts through the factory start path:

1. Create or point to a sealed factory_bridge_source_envelope.
2. Create a factory_bridge_start_request with project_mode=new_project.
3. Run the Hermes adapter:

python adapters/hermes/live_kanban_adapter.py materialize-bridge-start \
  --start-request <factory_bridge_start_request.json> \
  --source-envelope <factory_bridge_source_envelope.json>

This path creates the fresh Hermes board/card and writes the start-path metadata. Direct hermes kanban boards create, hermes kanban create, or agent-authored F1 cards are defects for new products, even when the card text looks correct.

After start, verify the runtime state before claiming the factory is active:

• the board was created by materialize-bridge-start;
• the root card metadata says factory_start_path=true or equivalent start-path proof;
• the source envelope and start request refs are present;
• the next route comes from the phase graph/reconciler, not from prose, memory, title, or agent judgement.

If any of those proofs are missing, stop the product flow and classify it as a factory integration defect. Do not continue by having an agent "act like" the factory.

Operating Mantra

Less mirabolante, more Kanban-native, more Hermes-native, more deterministic and easier to trust.

Use this as the default test for every autonomy, performance or routing fix: prefer durable Hermes Kanban graph state, explicit dependencies, typed blocks and native dispatch over sidecar loops, chat memory, agent interpretation or workers inventing the next phase. No-idle and watchdog code are integrity auditors and recovery paths, not the normal route authority.

Treat Hermes parent -> child links as execution dependencies, not visual nesting. When a phase creates required work-unit cards, attach those cards as native parents of the downstream phase/closure card before that downstream phase can promote. If required work is discovered late, link it while the downstream phase is still todo; if the downstream phase is already ready, running or done, that is a factory invariant violation.

Use the current V3 kernel control plane as the default factory spine:

F0 sealed source envelope -> F1 intake -> F2 source ledger
-> F3 understanding alignment -> F4 outcome/discovery
-> F5 Product SOT -> F6 full-scope coverage -> F7 Method Contract
-> F8 capability and Product Experience selection -> F9 architecture boundary
-> F10 security/access/budget -> F11 Product Creation Plan
-> F12 work units and packets -> F13 execution -> F15 verification/review
-> human gate event only when a real decision is required
-> Receipt Five -> release/block -> operations -> learnback

Use this legacy sequence only when handling existing Factory 10/11 cards or compatibility artifacts:

source intake -> source resolution -> Product SOT -> alignment questions
-> architecture -> Product Experience OS/Product Face -> specialist reviews -> onchain package
-> security scan plan -> human architecture gate -> documentation OS
-> decomposition -> Hermes cards -> execution -> verification
-> independent review -> human R3/R4 gate -> promotion -> monitoring
-> learning loop

Required Contracts

For the current V3 kernel, treat these as the control-plane contracts:

• factory_workflow_compiled_plan
• factory_command
• factory_run_event
• factory_run
• factory_decision_outbox
• factory_promotion_packet
• factory_phase_graph
• v2_study_traceability
• v2_doc_implementation_obligations
• worker_authority_contract
• profile_compatibility_alias
• skill_provider_registry
• skill_ref_resolution_report
• product_experience_control_plane
• product_experience_evidence_stack
• capability_acquisition_contract
• capability_acquisition_run
• hermes_typed_block_policy
• hermes_reducer_mutation_proof
• hermes_blocked_first_protocol_receipt
• operator_delivery_receipt
• operator_notification_policy
• operator_channel_pack
• security_route_contract
• security_state_ledger
• capability_broker
• capability_lease
• security_profile
• factory_v2_readiness_claim

The agent may create artifacts. The route comes from the compiled workflow, phase engine, board reconciler, command reducer and Hermes runtime state.

For Factory 10 / Overkill V3.5 compatibility cards, require:

• factory_method_version
• phase
• surfaces
• risk_initial
• risk_effective
• authority_max
• owner_worker
• executor_identity
• reviewer_identity
• runtime_contract
• security_contract
• forbidden_actions
• done_definition
• kanban_transition_event_ref

Block or revise cards when:

• OVERKILL_VFINAL cards lack outcome_contract, method_contract, or loop_plan.
• Product-facing vFinal cards lack Product Experience routing, Product Face Packet, project design system / DESIGN.md contract, professional design process, or Product Face Result proof.
• Material vFinal execution lacks ready access_capability or autonomy_readiness_packet.
• R3/R4 or security-sensitive vFinal work lacks security_architecture_plan.
• Product-facing surfaces lack Product Experience routing, Product Face Packet, project design system / DESIGN.md contract, or Product Face Result proof.
• Onchain/Solana/Quasar work lacks an Onchain Work Package.
• R3/R4 onchain work lacks Auditor or human waiver.
• R3/R4/security/onchain work lacks a Codex Security/Cybersecurity scan packet.
• Executor and reviewer are the same identity.
• R4 lacks explicit human gate, rollback, risk owner, and security owner.
• Done lacks Receipt Five and transition-event metadata.
• Public artifacts contain private paths, internal names, raw source extraction or private workspace links.
• The public repository contains partial manual mirrors of generated contracts, historical evidence dumps, or folders that cannot justify their public purpose, first-use path, source of truth, and validation coverage.
• Public documentation changes touch registries, workers, phases, schemas, templates, method engines or public surfaces without updating docs/en/factory-manual.md, docs/en/technical-reference.md and the public surface validators when the claim changes.
• Hermes updates have not passed compatibility manifest, update runbook, disposable smoke and rollback planning.
• Hermes dispatch --dry-run and --initial-status blocked are not enough to prove no-spawn safety. No-spawn Hermes smoke cards need a verified blocked event in show --json, and dry-run should be used only on disposable boards.

References

Load only what is needed:

• references/factory-line.md for the full phase model and gates.
• references/hermes-adapter.md for Hermes/Kanban coupling and patch status.
• references/card-contract.md for card and Receipt Five field rules.
• references/automation.md for critical worker packets and factoryctl.py.
• references/documentation-standard.md for Area Manual quality, document types, and the "another agent can continue from this" documentation rule.
• references/open-source-github.md when assessing or changing the public GitHub repository, README, folder architecture, onboarding, examples, CI, release hygiene, public safety, or comparisons with other open-source repos.
• docs/en/technical-reference.md when working on deterministic state, phase jumps, command/event logs, decision outbox or promotion packets.
• docs/en/factory-manual.md and docs/en/technical-reference.md when checking the public factory explanation against workflow, worker, profile, OS, method, schema, template and public-surface contracts.
• agents/worker-registry.public.json, agents/worker-profiles.public.json and agents/hermes-profile-bindings.public.json before changing worker profiles or dispatch behavior.
• docs/en/factory-manual.md and docs/en/technical-reference.md when aligning public docs with the executable repo.

Scripts

When inside the overkill-factory repository, prefer the repo-level scripts/factoryctl.py:

python scripts/factoryctl.py gate-report --card path/to/card.md
python scripts/factoryctl.py worker-packet --worker all --card path/to/card.md --out path/to/output-dir
python scripts/factoryctl.py compile-workflow --out .tmp/factory-workflow-compiled-plan.json
python scripts/factoryctl.py validate-factory-run templates/factory-run.json
python scripts/factoryctl.py validate-study-traceability templates/study-traceability.json
python scripts/factoryctl.py validate-doc-implementation-obligations templates/doc-implementation-obligations.json --traceability templates/study-traceability.json
python scripts/factoryctl.py validate-runtime-contracts
python scripts/factoryctl.py validate-agent-skill-boundaries
python scripts/factoryctl.py validate-reference-superiority
python scripts/factoryctl.py validate-worker-authority-contract templates/worker-authority-contract.json
python scripts/factoryctl.py validate-product-experience-control-plane templates/product-experience-control-plane.json
python scripts/factoryctl.py validate-capability-acquisition-contract templates/capability-acquisition-contract.json
python scripts/factoryctl.py capability-acquisition-run --capability-gap solana-ai-kit --surface solana --out .tmp/factory-runs/capability/skill-capability-acquisition-run.json
python scripts/factoryctl.py validate-capability-acquisition-run .tmp/factory-runs/capability/skill-capability-acquisition-run.json
python scripts/factoryctl.py validate-hermes-reducer-mutation-proof templates/hermes-reducer-mutation-proof.json
python scripts/factoryctl.py validate-factory-readiness-claim templates/factory-readiness-claim.json
python scripts/generate_factory_reference_docs.py --out ../.tmp/generated/factory-kernel-reference.md
python scripts/generate_factory_reference_docs.py --out ../.tmp/generated/factory-kernel-reference.md --check
python scripts/validate_worker_profiles.py

Use scripts/validate_factory_contract.py to sanity-check a card or receipt JSON file outside Hermes or outside the repo:

python scripts/validate_factory_contract.py path/to/card.json
python scripts/validate_factory_contract.py path/to/receipt.json --receipt

This script is a lightweight preflight. Hermes gates remain authoritative when running on the Hermes adapter.

Operating Rules

• Prefer one operational artifact over scattered notes.
• Every important factory area needs a simple, deep Area Manual. If another agent cannot continue the area from the document, the document is not done.
• Explain which registry or reducer rule selected a gate or worker, and which alternatives were rejected by contract.
• Do not let an agent identity select a phase, worker, gate or promotion path. It must point to workflow, phase-engine, board-reconciler, command, event-log, decision-outbox or promotion-packet evidence.
• Treat older methodology notes as evidence, not as truth by default.
• Planning may continue with missing access. Material execution must not start until indispensable access/capabilities are ready or explicitly blocked.
• Security Review does not replace Security Architecture. Material security risk needs security architecture before implementation.
• Keep final canonical documents free of doubts, backlog, raw study, and behind-the-scenes comparison. Put those in study, proposal, roadmap, or context-lock documents instead.
• When the factory methodology is still under blind-spot exploration, do not suggest pilots or live validation as the next step. First run or update the Blind Spot Audit and decide whether gaps become core, pack, gate, worker, template, checklist, or out of scope.
• For Solana/Quasar program work, prefer Quasar and require the Auditor path.
• For security-sensitive work, make Codex Security/Cybersecurity timing explicit.
• Security is a specialist matrix: AppSec/OWASP, agentic AI, cloud/IaC, secrets/keys, supply chain, detection/monitoring, privacy/data and Solana/Quasar all need the right worker.
• Missing capability does not go straight to a human blocker. Run the capability acquisition lane against skill providers, capability packs and reference sources; block only after search_completed=true and no safe candidate can activate.
• Use open specialists for exploration and closed specialists only after repetition, predictable input and verifiable output.
• AutoReview is pre-landing evidence, not approval.
• Handoff is a replayable state packet, not a pretty summary.
• Remote proof uses Crabbox/Testbox/container only when local proof is insufficient and must include TTL, cost, cleanup and artifact evidence.
• Worker packets must not leak local absolute paths. Repo-local source cards use relative paths; external/private cards use redacted external:<name> refs.
• Public GitHub work has a product bar: a newcomer must understand what the project is, install or run a first-value path, know which folders matter, and avoid private/internal context without needing this chat.
• Every public folder needs a burden-of-proof decision: keep, merge, relocate, generate, privatize, or delete. Do not preserve folders because they once helped internal validation.
• Do not add hand-written partial worker or contract guides. Summaries must either cover the full public source of truth or be generated from it.
• Worker packets must carry profile_binding so Hermes can dispatch to a real profile with skill refs, result schema and evidence policy.
• Do not treat a worker name as an agent configuration. Agent configuration lives in the worker profile and Hermes binding.
• Project design system / DESIGN.md is the project-level visual and interaction contract. Frontend and Product Face workers must consume it before product-facing implementation or proof.
• Product Face Packet is planning; product_face_result is proof. Product-facing completion needs screenshots, viewports, checked states, journeys, accessibility, overlap, performance note and evidence refs.
• Product Experience OS is the official layer for product experience across websites, web apps, mobile, desktop, CLI/TUI, extensions, agentic interfaces, design systems, docs and onboarding. Product Face is the packet/result inside that layer, not the whole layer.
• Auditor preflight is not a real Quasar code audit. Preflight must be marked as bounded evidence, not code-audit PASS.
• Keep R3/R4 human authority explicit; never fake approval records.
• Before saying "done", show evidence, tests, state, and remaining risk.