القائمة
How to write a natural language specification that Builder can implement without asking questions.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
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.
| name | nlspec-format |
| description | How to write a natural language specification that Builder can implement without asking questions. |
What this project/feature is and why it exists. Written for a human who might read this in 6 months.
What the system DOES, described as observable behaviors. Not implementation details. Format: "When [trigger], the system [behavior], resulting in [observable outcome]."
Every point where the system touches the outside world:
What the system must NOT do. Error cases. Security boundaries. Performance requirements. Be explicit about edge cases — these are where Builder most often goes wrong.
Explicitly state what this spec does NOT cover. This prevents Builder from gold-plating.
How Verifier should know this works. Not test cases (those are holdout scenarios), but observable properties: "A user should be able to [action] and see [result]."
When a spec has open questions that block promotion to specs/ready/, write them as structured entries. Each ambiguity must be tagged for the kernel's Decision Monitor to classify and route:
### 7.N {short-description}
- reversibility: high | low
- impact: governance | implementation | cosmetic
- status: open
**Options:**
- **(a)** {option description}
- **(b)** {option description}
**Recommendation:** {your recommendation, if any}
The kernel reads these tags after the spec run:
reversibility: high + impact: implementation|cosmetic → auto-resolved (soft gate)reversibility: low OR impact: governance → blocks for operator (hard gate)Do not write ambiguities as unstructured prose. The structured format is what makes the Decision Monitor work.
A spec is ready when you can hand it to a competent developer who has never heard of this project and they can build it without asking a single question. If they'd need to ask, the spec is underspecified.
Before speccing anything non-trivial, write a research request: "I need to spec a system that does X. What are the established approaches? What are the key design decisions?" Wait for the brief. Then spec with informed constraints.