fac

Complete reference for the factory CLI — all commands, arguments, options, and usage. Use when an agent needs to invoke factory commands, check correct syntax, or understand available options.

When and how to write a human-action-needed entry to memory/{agent}/needs.md. Agents write these entries when they hit blockers that only a human can resolve.

When you encounter a failure, correction, or new pattern, write a learning and optionally propose a skill.

How the factory workspace is organized and what each directory means.

What to examine during a reflection pass and how to write observations to memory/{agent}/needs.md.

When and how to write scenario holdouts for factory verification.

How to integrate scenario evaluation into verification reports.

How to review proposed skills, curate shared memory, and detect patterns.

Send WhatsApp messages through NanoClaw's IPC. Use when an agent needs to notify the human via WhatsApp about completed work, failures, decisions needed, or status updates.

Ship working, build changeable. When implementing decisions made under ambiguity, build seams so the decision can be changed without rewriting.

When blocked by ambiguity, choose the best reversible option, document the debt, and ship. Do not wait for perfect information. Do not build the minimal hack.

How to write a natural language specification that Builder can implement without asking questions.

The reviewer agent's structured process for identifying factory improvement opportunities and generating evidence-backed intents.

How to know when you're done. Run tests, check the spec. If both pass, stop. If the same issue persists after 3 iterations, write a failure note and stop.

How to use the filesystem, shell, and git. Builder's tool vocabulary and conventions for interacting with the development environment.

How to keep memory clean. Archive stale daily logs. Promote important findings to long-term memory. Remove contradictions.

How to spot recurring patterns across projects. If Builder hits the same snag in multiple projects, that's a pattern worth writing a skill for.

How to set up and maintain CI/CD per stack. GitHub Actions patterns, testing configurations, deployment scripts.

How to audit, update, and manage dependencies. When to update vs. pin. How to evaluate whether an update is safe.

How to check if deployed projects are healthy. What "healthy" means per project type.

How to deliver research findings as a decision-ready brief. Not a research paper — an actionable answer with trade-offs surfaced.

How to judge whether information is reliable. Applies a source hierarchy before incorporating any finding into a research brief.

How to interview the human to extract what they actually want. What questions to ask and when to stop asking.

Skeleton NLSpec structures for common project types. Use these as starting frames, not rigid templates.

How to write a useful failure report. Not "it's wrong" — what's wrong, why it matters, what the spec says, what the code does, and a path forward.

The probabilistic satisfaction metric. Not pass/fail — a judgment about the fraction of users who would be satisfied with this output.

How to evaluate implementation against holdout scenarios. Run each scenario and assess whether the system behaves as expected.

How Verifier writes failure reports, including the mandatory Generalizable Learning section that the runtime extracts to learnings/failures/.

How to go from spec to working code.

Git conventions for the factory workspace and project repos.

How to research a question and deliver a decision-ready recommendation.

How to manage your context window. Load only what you need. Write to disk before you forget.

When and how to spawn subagents for parallel work. Any root agent can decompose.