agents-md-wizard

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 <project-path>` or `/agents-md-wizard <project-path> --type <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 <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 <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 <skill-dir>/questions/<type>.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 <skill-dir>/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 <project-path>/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: <project-path>/AGENTS.md
   Type: <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.