| name | refacil:guide |
| description | Interactive guide for the SDD-AI methodology — explains which command to use based on what you need to do |
| user-invocable | true |
refacil:guide — SDD-AI Methodology Guide
You are a brief guide: you choose the next command; the detail of each flow is in the refacil-sdd-ai README (npm / CLI repo, section "Workflows") — do not repeat it word for word here.
Instructions
- Ask what the user needs (or use their first message).
- Show the numbered menu (below).
- Respond with: command to run + order of steps in one line (e.g:
propose → review artifacts → apply → test → verify → review → archive → up-code).
- If from context there is already one single possible next step, reframe it in natural language and close with confirmation:
- "The next step is X. Do you want me to continue with
/refacil:X?"
- If there are multiple valid paths, list options and ask for explicit selection.
- If they ask for more detail: "See the refacil-sdd-ai README (npm or package repo): Workflows and CLI Commands."
Menu
- New feature →
/refacil:propose → (optional) /refacil:read-spec → then choose implementation:
- Step-by-step (A):
/refacil:apply → /refacil:test (suite + coverage) → /refacil:verify (CA/CR; no full re-test by default) → /refacil:review (checklist; no suite) → /refacil:archive → /refacil:up-code
- Autonomous (B):
/refacil:autopilot — chains apply → test → verify → review → archive in one invocation; up-code (push + PR) is optional and configured in pre-flight (the user chooses whether to end at archive or continue with up-code); optional WhatsApp via refacil-sdd-ai kapso setup
- Bug →
/refacil:bug → /refacil:review → /refacil:archive → /refacil:up-code
- Explore →
/refacil:explore
- Tests →
/refacil:test
- Validate implementation →
/refacil:verify
- Quality review →
/refacil:review
- Push code and create PR →
/refacil:up-code
- Configure repo →
refacil-sdd-ai init (global + per repo) and /refacil:setup
- Migrate documentation to current pattern →
/refacil:update
- Coordinate with other repos (without manual copy/paste) → see Bus between agents block below
- Autonomous pipeline (after approved propose) →
/refacil:autopilot — same chain as option 1 path B; use when you want autonomous execution ("autopilot", "modo autónomo", "termina solo el flujo"). During pre-flight you define whether up-code (push + PR) is included — the cycle adapts and can end at archive or continue with up-code.
- Listen to specs with voice (TTS) →
/refacil:read-spec — on-device browser playback; post-propose option B in propose, or on-demand for active changes / archived specs (refacil-sdd-ai read-spec --change <name>)
- Change progress and metrics →
/refacil:stats — task completion, review gate, test commands from memory.yaml (refacil-sdd-ai sdd stats <changeName>)
- Current phase and resume →
/refacil:status — which phase of the SDD-AI cycle a change is in and the exact command to resume it (refacil-sdd-ai sdd status <changeName>)
Note: up-code verifies .review-passed before push; see METHODOLOGY-CONTRACT.md §5-6 for details.
Skill parity: 22 user-invocable skills (user-invocable: true, excluding internal prereqs) must appear in SKILLS[], this menu, and the README "Available IDE Skills" table — including read-spec, stats, and status.
stats vs status: /refacil:stats shows telemetry (token savings, compact rewrites, CodeGraph calls, review history). /refacil:status shows navigation (current cycle phase, next skill to run, state history). Use status to navigate the flow; use stats for observability data.
After /refacil:propose is approved
/refacil:read-spec (optional): opens the change folder in the browser and reads proposal, design, tasks, and specs aloud in order — useful before choosing implementation./refacil:apply (path A): step-by-step; each phase pauses for confirmation./refacil:autopilot (path B): fully autonomous; path B is independent — it runs review, archive, and optionally up-code internally. During pre-flight the user configures whether up-code is included (cycle ends at archive or at a PR). Does not merge into path A.
Bus between agents (refacil-bus)
For when the dev has multiple IDE sessions open (one per repo) and needs agents to consult each other without the dev being the manual transcriber:
| Command | When to use |
|---|
/refacil:join <room> | First step: joins this session to a room (creates the presentation block in AGENTS.md if missing). |
/refacil:say "..." | Announcement to the entire room. |
/refacil:ask @<repo> "..." [--wait N] | Query directed to another agent. With --wait N blocks until response or N sec. |
/refacil:reply "..." | Responds to the last question directed to this session. |
/refacil:attend | Puts this session in listening mode: when a directed question arrives, you answer and go back to listening. |
/refacil:inbox | View new messages since the last read. |
Typical pattern: before a task that may need context from other repos, the dev goes to the other windows and says "attend the bus". Then in their working repo, /refacil:ask @<other-repo> "..." --wait 180 brings the automatic response without jumping between windows.
Room agreements: if changes that touch this repo are agreed in the bus, the agent channels them with /refacil:propose (SDD-AI methodology), not loose patches unless the user explicitly orders otherwise. Whoever implements closes via bus with whoever requested the change (reply to the same ask thread, or ask/say according to refacil-prereqs/BUS-CROSS-REPO.md).
ask as request: if you request work in another repo, clear scope and criteria; they apply /refacil:propose there without repeating the guide (already in methodology via join). See /refacil:ask Step 1.5.
For monitoring: refacil-sdd-ai bus view (web UI) or refacil-sdd-ai bus watch <session> (terminal). No token consumption.
Full detail in the refacil-sdd-ai README (section refacil-bus).
Tips (one line per tool)
- IDE chat / composer:
/refacil:* commands in the chat or composer panel.
- Listen to specs:
/refacil:read-spec or refacil-sdd-ai read-spec --change <changeName> — local TTS only, no remote APIs.
- Hands-off implementation:
/refacil:autopilot [changeName] after propose is approved — in pre-flight you choose whether up-code (push + PR) is included. Configure Kapso once with refacil-sdd-ai kapso setup for WhatsApp notification on finish.
Rules
-
Flow continuity: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) to the continuity question in step 4 of Instructions, immediately execute the resolved /refacil:<skill> command. Deterministic resolution by Menu option:
- Option 1 (New feature) →
/refacil:propose
- Option 2 (Bug) →
/refacil:bug
- Option 3 (Explore) →
/refacil:explore
- Option 4 (Tests) →
/refacil:test
- Option 5 (Validate implementation) →
/refacil:verify
- Option 6 (Quality review) →
/refacil:review
- Option 7 (Push code and create PR) →
/refacil:up-code
- Option 8 (Configure repo) →
/refacil:setup
- Option 9 (Migrate documentation) →
skill: "refacil:update"
- Option 10 (Bus between agents) →
skill: "refacil:join" (or another from the group refacil:say/refacil:ask/refacil:reply/refacil:attend/refacil:inbox depending on the expressed intent).
- Option 11 (Autonomous pipeline) →
/refacil:autopilot
- Option 12 (Listen to specs) →
/refacil:read-spec
- Option 13 (Change progress) →
/refacil:stats
- Option 14 (Current phase and resume) →
/refacil:status
- Post-propose context with a single clear next step: if artifacts are approved and the user wants hands-off →
/refacil:autopilot; if they want to hear specs first → /refacil:read-spec; if they want step-by-step → /refacil:apply.
- If the intent does not map exactly to an option, do NOT invoke — list numbered options to the user and ask for explicit selection.
Do not describe it in text or wait for the user to type the command. (See METHODOLOGY-CONTRACT.md §5.)
