refacil-sdd-ai

SDD-AI (Specification-Driven Development with AI) packaged as a CLI.

Installs skills and sub-agents for Claude Code, Cursor, OpenCode, and Codex that guide the developer through a structured AI-assisted development workflow, using refacil-sdd/ as the specification store, plus a local bus so agents across different repos can communicate with each other.

---

npm: refacil-sdd-ai | GitHub: Erikole21/refacil-sdd-ai

Requirements

• Node.js >= 20.0.0
• One or more supported IDEs: Claude Code >= 2.1.89, Cursor, OpenCode, or Codex

refacil-sdd-ai init checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but compact-bash will have no effect (Claude Code only — Cursor, OpenCode, and Codex have their own hook delivery mechanisms).

---

Installation

Step 1 — Install the package globally

npm install -g refacil-sdd-ai

Step 2 — Run init to install skills into your IDEs

refacil-sdd-ai init

init installs skills, sub-agents, and hooks into your IDE’s global user directories (~/.claude/, ~/.cursor/, ~/.config/opencode/). Skills are available in all your repos from this point — no need to re-run init when you open a new repo.

• Interactive IDE selector (Claude Code / Cursor / OpenCode / Codex) — pre-selects installed IDEs.
  Use --all to install for all four without prompting.
• Your IDE selection is saved to ~/.refacil-sdd-ai/selected-ides.json and reused on every update.
• Also prompts for global branch config (baseBranch, protectedBranches, artifactLanguage)
  stored in ~/.refacil-sdd-ai/config.yaml. Skip with --yes or --defaults.

Re-run init if you install a new IDE or want to change which IDEs have the methodology.

After init, restart your IDE session — new skills are not detected until you restart.

Step 3 — Configure each repo with /refacil:setup

In each repo where you want to use the methodology, open the IDE and run:

/refacil:setup

/refacil:setup:

1. Scaffolds AGENTS.md, .agents/, refacil-sdd/changes/, and project branch configuration (everything the methodology needs for this codebase).
2. Runs refacil-sdd-ai sync-repo-ide from the repository root so per-repo stubs and excludes match your IDE selection from init (~/.refacil-sdd-ai/selected-ides.json): CLAUDE.md, .cursorrules, .claudeignore, .cursorignore, .opencodeignore, plus compact-guidance / testing-policy markers when AGENTS.md / .agents/testing.md exist (same logic as init / update for those files).