--- name: agents-md-wizard description: Interview-driven wizard that drafts AGENTS.md (the cross-platform agent-readable spec at https://agents.md) for any project. Type-branched question sets keep it project-neutral — works for business pitches, games, research, infra, side-hustles, personal tools, nonsense projects, and free-text "other". Use when registering a new project in GeneralStaff, when project scope is unclear, or when an existing AGENTS.md needs a refresh. Invoke as `/agents-md-wizard ` or `/agents-md-wizard --type ` to skip type detection. metadata: trigger: Drafting or refreshing AGENTS.md for a project outputs: AGENTS.md at project root, plus optional updates to existing AGENTS.md --- # AGENTS.md Wizard Interview the user about a project and write `AGENTS.md` at the project's root. The artifact is the cross-platform standard at https://agents.md (supported by Google, OpenAI, Cursor, Aider, Zed, et al). Project-neutral framing — this works for satire, nonsense, side-hustles, and personal tools, not just business pitches. ## When to invoke - After registering a new project (in GeneralStaff or any project tracker) - When an LLM agent keeps drifting from project intent because intent isn't captured anywhere agent-readable - When a project pivots and `AGENTS.md` needs to reflect the new direction ## Argument Required positional: project path (absolute path or relative to CWD). Optional flags: - `--type ` — skip the type-detection question; valid values: `business`, `game`, `research`, `infra`, `side-hustle`, `personal-tool`, `nonsense`, `other` - `--update` — refresh an existing AGENTS.md; appends a dated revision block instead of overwriting (Phase B feature; for Phase A, just overwrite with a warning) ## Operational pattern When invoked: 1. **Resolve project path.** If the argument is relative, resolve against user's CWD. Confirm the directory exists. If not, surface "Directory not found: " and stop. 2. **Determine project type.** - If `--type ` was passed, use it. - Else, ask the user: ``` What kind of project is this? 1. business — heavy interview (~12 questions, ~10 min) 2. game — heavy interview (~10 questions, ~8 min) 3. research — focused interview (~6 questions, ~5 min) 4. infra — focused interview (~5-7 questions, ~5 min) 5. side-hustle — light interview (~5-6 questions, ~4 min) 6. personal-tool — light interview (~4-5 questions, ~3 min) 7. nonsense — minimal (~3 questions, ~2 min) 8. other — free-text (you describe it however) 9. skip — write a stub AGENTS.md with TODO markers ``` - Wait for response. Accept either the number or the name. 3. **Load question set.** Read `/questions/.json`. The file is an array of `{id, prompt, required}`. For `other` (empty file), prompt the user for free-text and skip the structured interview. For `skip`, render the template with all placeholders → "[TODO]" and stop. 4. **Conduct the interview.** For each question: - Display the prompt with a question number ("[3/12]") - Wait for the user's response in chat - Store the response keyed by `id` - For required questions, if the user gives an empty / "skip" response, re-ask once with a brief hint that the question is load-bearing for downstream agent context. After two declines, accept "[not specified]" and move on. - Don't editorialize the user's answers. Capture them verbatim (light formatting only — preserve whatever phrasing they use). 5. **Render the template.** Read `/templates/agents-md.md`. The template has `{{placeholder}}` syntax with `||` fallback chains so a single template serves all types (a `nonsense` project produces a 3-section AGENTS.md because most placeholders fall through to "[not specified]" — which we then strip per the next rule). 6. **Light-type rendering rule.** For types `personal-tool` and `nonsense`, after rendering, REMOVE any sections whose body is exactly "[not specified]". Keep the section headings only when there's an actual answer. Other types render all 10 sections (with "[not specified]" placeholder for missing answers — surfaces the gap to the user). 7. **Write AGENTS.md.** Write the rendered content to `/AGENTS.md`. If the file already exists: - Without `--update`: warn "AGENTS.md exists. Overwrite? (y/n)" and wait for response. On `n`, stop without writing. - With `--update`: read the existing file, prepend its current content under a `## Previous version (replaced YYYY-MM-DD)` section, then write the new content above. (Phase A keeps update mode simple; Phase B will add proper section-by-section diffing.) 8. **Confirm.** Report: ``` Wrote: /AGENTS.md Type: Sections rendered: N of 10 Universals captured: 3 of 3 ``` ## Type-specific notes - **business** — ask all 12 in order. The 3 universals first, then the business-specific 9. Don't restate the user's answers in business jargon; preserve their voice. - **game** — same pattern, 10 questions. Genre + reference games is the most load-bearing for agent context downstream. - **research** — 6 questions. The hypothesis question often produces a vague answer; if so, gently prompt for "the actual question you want answered" rather than the abstract framing. - **infra** — 7 questions (3 universal + 4). Constraints question is load-bearing — push for specific budget/latency/compliance numbers if the user gives vague answers. - **side-hustle** — 6 questions. The "what would make you abandon this" question often produces the most useful answer for downstream scope-creep prevention. - **personal-tool** — 5 questions. Short. Don't pad. - **nonsense** — 3 questions only. The whole point of this type is to capture intent for projects that aren't supposed to be Real Business™. A satire project, an experimental art piece, a deliberate joke — all valid. Capture the actual intent in the user's voice. - **other** — free-text. Ask: "Describe this project in your own words — what it is, what it isn't, when it's done, anything else relevant." Render that single response as the entirety of section 1. ## Behavioral guardrails - **Don't restate the user's answers back to them.** They typed them, they know what they said. Move to the next question. - **Don't editorialize in AGENTS.md.** The user's voice is the right voice. Light formatting only (markdown bullet lists, paragraph breaks). - **Don't add sections the template doesn't have.** AGENTS.md is a standard format; don't invent custom sections. - **Don't run the interview if the user just wants to inspect.** If the argument is `--help` or no project path is given, print usage and stop. Don't accidentally start a 12-question interview because the user typed `/agents-md-wizard` to see what it does. ## What this skill does NOT do - Doesn't read the project's existing files to "infer" answers. The point is to capture what the USER wants the project to be — which may differ from what the code currently looks like. Inferring from code would just describe the past. - Doesn't ship to the AGENTS.md website or any external system. - Doesn't modify project files other than `AGENTS.md` itself. - Doesn't run tests, builds, or any verification on the target project. ## Phase A scope This is Phase A: register-time wizard, writes AGENTS.md, no reviewer integration. Phase B will wire AGENTS.md into the GeneralStaff reviewer as a soft alignment check (`verified_misaligned` verdict). Phase C+ adds proactive drift detection. None of those exist yet — Phase A's deliverable is just the artifact and the interview.