🚀 spec-to-code

✨ A lightweight npm package that bootstraps a Spec-to-Code workflow, from any project folder, whether you're starting a new app or adding features/tests, using LLM agents 🤖 and rules 📜.

Inspired by Mattia D'Argenio’s Spec-to-Code methodology and the bmad-method approach to agent-based development.

🧠 Why spec-to-code?

Building software with LLMs works only if it’s structured.

This project helps you move from a vague idea 💡 to production-ready code 🏗️ by organizing LLM interactions into clear, reproducible steps:

➡️ Specification → Planning → Execution → Review

No prompt spaghetti.
No magic.
Just explicit workflows and clearly defined responsibilities.

⚡ Quick start

In a new project, run once:

npx @deveonc/spec-to-code

Then, in your agent tool:

/Architect

🧭 The Architect agent will automatically guide you through the specification process, one question at a time.

📦 What gets installed

.ai/
├── agents/        🤖 Architect, Planning, Develop, Reviewer agents
└── rules/         📜 Coding & architectural rules

Everything is local, versioned, and auditable.

If a .opencode/ folder exists, the installer generates OpenCode commands + agents from .ai/agents into .opencode/commands and .opencode/agents.

If a .claude/ folder exists, the installer generates Agent Skills from .ai/agents into .claude/skills (compatible with Claude Code).

Installer state is stored in .ai/config.json (version, date, selected integrations, selected rules).

You can regenerate commands, agents, and skills manually:

node bin/scripts/opencode/generate-commands.js --agents .ai/agents --out .opencode/commands
node bin/scripts/opencode/generate-opencode-agents.js --agents .ai/agents --out .opencode/agents
node bin/scripts/claude/generate-skills.js --agents .ai/agents --out .claude/skills

Script layout (by tool):

• bin/scripts/opencode/ - OpenCode commands + agents
• bin/scripts/claude/ - Claude Code skills (Agent Skills format)
• bin/scripts/rules/ - Rules selection and updates
• bin/lib/ - Shared utilities

During installation, a checklist is shown for OpenCode/Claude Code integration. Existing folders are pre-selected, and you can enable or disable each integration before the files are copied. After that, you choose which rules to install. Finish by running /Architect.

On rerun:

• If the version changed, .ai is refreshed (config preserved).
• If the version is the same, no files are copied unless you change integrations or rules.

You can also choose which rules are installed. default.rules.md is always included. To reconfigure later:

node bin/scripts/rules/configure-rules.js --out .ai/rules

🎯 Designed for

• 🧑‍💻 OpenCode users
• 🤖 Agent-based LLM workflows
• 🏗️ Developers who want structure, not vibes
• 🕰️ Long-lived, maintainable projects
• 🧠 Compatibility with Claude Code and OpenCode

Works for:

• creating a brand new application from scratch
• extending an existing codebase with new features or tests

When you request new features after the initial spec, route them through Planning to add tasks to docs/todo.md before any implementation.

🧩 Philosophy

LLMs are powerful — but only when constrained.

spec-to-code treats prompts as contracts,
agents as roles,
and development as a workflow, not a conversation.

Happy building 🚀