@deveonc/spec-to-code 1.0.0-beta.2

package/README.md

@@ -0,0 +1,123 @@
+# 🚀 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 🚀

package/bin/lib/agent-metadata.js

@@ -0,0 +1,57 @@
+import fs from "fs";
+import path from "path";
+
+const toTitle = (value) => value.charAt(0).toUpperCase() + value.slice(1);
+
+const parseFrontmatter = (lines) => {
+    if (lines.length === 0 || lines[0].trim() !== "---") {
+        return { metadata: {}, body: lines.join("\n") };
+    }
+
+    const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (endIndex === -1) {
+        return { metadata: {}, body: lines.join("\n") };
+    }
+
+    const metadataLines = lines.slice(1, endIndex);
+    const body = lines.slice(endIndex + 1).join("\n").replace(/^\n+/u, "");
+    const metadata = {};
+
+    for (const line of metadataLines) {
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex === -1) continue;
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (key) {
+            metadata[key] = value;
+        }
+    }
+
+    return { metadata, body };
+};
+
+const readAgentMetadata = (agentPath) => {
+    const content = fs.readFileSync(agentPath, "utf8");
+    const { metadata, body } = parseFrontmatter(content.split(/\r?\n/u));
+    const baseName = path.basename(agentPath, ".agent.md");
+
+    return {
+        name: metadata.name ?? baseName,
+        description: metadata.description ?? `Agent instructions for ${baseName}.`,
+        command: metadata.command ?? toTitle(baseName),
+        body,
+    };
+};
+
+const readAllAgentMetadata = (agentsDir) => {
+    if (!fs.existsSync(agentsDir)) {
+        return [];
+    }
+
+    return fs
+        .readdirSync(agentsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".agent.md"))
+        .map((entry) => readAgentMetadata(path.join(agentsDir, entry.name)));
+};
+
+export { readAgentMetadata, readAllAgentMetadata, toTitle };

package/bin/lib/checklist.js

@@ -0,0 +1,81 @@
+import readline from "readline";
+
+const askQuestion = (prompt) => new Promise((resolve) => {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    rl.question(prompt, (answer) => {
+        rl.close();
+        resolve(answer);
+    });
+});
+
+const renderChecklist = (title, items) => {
+    if (title) {
+        console.log(title);
+    }
+    items.forEach((item, index) => {
+        const marker = item.checked ? "[x]" : "[ ]";
+        console.log(` ${marker} ${index + 1}. ${item.label}`);
+    });
+};
+
+const parseToggleInput = (input) => new Set(
+    input
+        .split(/[\s,]+/u)
+        .map((value) => Number.parseInt(value.trim(), 10))
+        .filter((value) => Number.isInteger(value) && value > 0),
+);
+
+const promptChecklist = async ({ title, prompt, items }) => {
+    renderChecklist(title, items);
+
+    const answer = await askQuestion(prompt);
+    if (!answer.trim()) {
+        return items.map((item) => item.checked);
+    }
+
+    const toggles = parseToggleInput(answer);
+
+    return items.map((item, index) => {
+        if (toggles.has(index + 1)) {
+            return !item.checked;
+        }
+        return item.checked;
+    });
+};
+
+const ensureSelection = async ({
+    title,
+    prompt,
+    items,
+    selections,
+    fallbackSelections,
+}) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        if (selections.some(Boolean)) {
+            return selections;
+        }
+        if (fallbackSelections) {
+            console.warn("⚠️  No selection; using defaults.");
+            return fallbackSelections;
+        }
+        throw new Error("No selection provided.");
+    }
+
+    let current = selections;
+    while (!current.some(Boolean)) {
+        console.warn("⚠️  Select at least one option to continue.");
+        const nextItems = items.map((item, index) => ({
+            ...item,
+            checked: current[index],
+        }));
+        current = await promptChecklist({ title, prompt, items: nextItems });
+    }
+
+    return current;
+};
+
+export { ensureSelection, promptChecklist };

package/bin/lib/install-config.js

@@ -0,0 +1,26 @@
+import fs from "fs";
+
+const readInstallConfig = (configPath) => {
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+
+    const raw = fs.readFileSync(configPath, "utf8");
+    if (!raw.trim()) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(raw);
+    } catch (error) {
+        console.warn("⚠️  Skipped: .ai/config.json (invalid JSON)");
+        return null;
+    }
+};
+
+const writeInstallConfig = (configPath, config) => {
+    const content = `${JSON.stringify(config, null, 4)}\n`;
+    fs.writeFileSync(configPath, content, "utf8");
+};
+
+export { readInstallConfig, writeInstallConfig };

package/bin/lib/rules-manager.js

@@ -0,0 +1,42 @@
+import fs from "fs";
+import path from "path";
+
+const listRuleFiles = (sourceDir) => {
+    if (!fs.existsSync(sourceDir)) {
+        return [];
+    }
+
+    return fs
+        .readdirSync(sourceDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+};
+
+const applyRules = ({ sourceDir, targetDir, selected }) => {
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    const available = listRuleFiles(sourceDir);
+    const selectedSet = new Set(selected);
+    const results = { copied: [], removed: [] };
+
+    for (const ruleName of available) {
+        const srcFile = path.join(sourceDir, ruleName);
+        const dstFile = path.join(targetDir, ruleName);
+
+        if (selectedSet.has(ruleName)) {
+            fs.copyFileSync(srcFile, dstFile);
+            results.copied.push(ruleName);
+            continue;
+        }
+
+        if (fs.existsSync(dstFile)) {
+            fs.unlinkSync(dstFile);
+            results.removed.push(ruleName);
+        }
+    }
+
+    return results;
+};
+
+export { applyRules, listRuleFiles };

package/bin/scripts/claude/generate-skills.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+import { readAgentMetadata, toTitle } from "../../lib/agent-metadata.js";
+
+const buildSkillContent = (name, description, agentContent) => {
+    const title = toTitle(name);
+    const trimmed = agentContent.trimEnd();
+
+    return [
+        "---",
+        `name: ${name}`,
+        `description: ${description}`,
+        "---",
+        "",
+        `# ${title}`,
+        "",
+        trimmed,
+        "",
+    ].join("\n");
+};
+
+const parseArgs = (args) => {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--agents" && args[index + 1]) {
+            options.agentsDir = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--out" && args[index + 1]) {
+            options.skillsDir = args[index + 1];
+            index += 1;
+        }
+    }
+    return options;
+};
+
+const resolvePath = (value) => path.resolve(process.cwd(), value);
+
+const generateSkills = ({ agentsDir, skillsDir }) => {
+    if (!fs.existsSync(agentsDir)) {
+        throw new Error(`Missing agents directory: ${agentsDir}`);
+    }
+
+    fs.mkdirSync(skillsDir, { recursive: true });
+
+    const results = { created: [], skipped: [] };
+    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".agent.md")) continue;
+
+        const agentPath = path.join(agentsDir, entry.name);
+        const metadata = readAgentMetadata(agentPath);
+        const skillPath = path.join(skillsDir, metadata.name, "SKILL.md");
+
+        if (fs.existsSync(skillPath)) {
+            results.skipped.push(metadata.name);
+            continue;
+        }
+
+        const skillContent = buildSkillContent(
+            metadata.name,
+            metadata.description,
+            metadata.body,
+        );
+
+        fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+        fs.writeFileSync(skillPath, skillContent, "utf8");
+        results.created.push(metadata.name);
+    }
+
+    return results;
+};
+
+const run = () => {
+    const { agentsDir, skillsDir } = parseArgs(process.argv.slice(2));
+    const resolvedAgentsDir = resolvePath(
+        agentsDir ?? path.join(process.cwd(), ".ai", "agents"),
+    );
+    const resolvedSkillsDir = resolvePath(
+        skillsDir ?? path.join(process.cwd(), ".claude", "skills"),
+    );
+
+    const { created, skipped } = generateSkills({
+        agentsDir: resolvedAgentsDir,
+        skillsDir: resolvedSkillsDir,
+    });
+
+    console.log(`✅ Skills generated in ${resolvedSkillsDir}`);
+    if (created.length > 0) {
+        console.log(`✅ Created: ${created.join(", ")}`);
+    }
+    if (skipped.length > 0) {
+        console.log(`⚠️  Skipped: ${skipped.join(", ")}`);
+    }
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        run();
+    } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}
+
+export { generateSkills };

package/bin/scripts/opencode/generate-commands.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+import { readAgentMetadata } from "../../lib/agent-metadata.js";
+
+const parseArgs = (args) => {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--agents" && args[index + 1]) {
+            options.agentsDir = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--out" && args[index + 1]) {
+            options.commandsDir = args[index + 1];
+            index += 1;
+        }
+    }
+    return options;
+};
+
+const resolvePath = (value) => path.resolve(process.cwd(), value);
+
+const buildCommandContent = (description, agentFileName) => [
+    "---",
+    `description: ${description}`,
+    "---",
+    `@.ai/agents/${agentFileName}`,
+    "",
+].join("\n");
+
+const generateCommands = ({ agentsDir, commandsDir }) => {
+    if (!fs.existsSync(agentsDir)) {
+        throw new Error(`Missing agents directory: ${agentsDir}`);
+    }
+
+    fs.mkdirSync(commandsDir, { recursive: true });
+
+    const results = { created: [], skipped: [] };
+    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".agent.md")) continue;
+
+        const agentPath = path.join(agentsDir, entry.name);
+        const metadata = readAgentMetadata(agentPath);
+        const commandFileName = `${metadata.command}.md`;
+        const commandPath = path.join(commandsDir, commandFileName);
+
+        if (fs.existsSync(commandPath)) {
+            results.skipped.push(metadata.command);
+            continue;
+        }
+
+        const commandContent = buildCommandContent(metadata.description, entry.name);
+        fs.writeFileSync(commandPath, commandContent, "utf8");
+        results.created.push(metadata.command);
+    }
+
+    return results;
+};
+
+const run = () => {
+    const { agentsDir, commandsDir } = parseArgs(process.argv.slice(2));
+    const resolvedAgentsDir = resolvePath(
+        agentsDir ?? path.join(process.cwd(), ".ai", "agents"),
+    );
+    const resolvedCommandsDir = resolvePath(
+        commandsDir ?? path.join(process.cwd(), ".opencode", "commands"),
+    );
+
+    const { created, skipped } = generateCommands({
+        agentsDir: resolvedAgentsDir,
+        commandsDir: resolvedCommandsDir,
+    });
+
+    console.log(`✅ Commands generated in ${resolvedCommandsDir}`);
+    if (created.length > 0) {
+        console.log(`✅ Created: ${created.join(", ")}`);
+    }
+    if (skipped.length > 0) {
+        console.log(`⚠️  Skipped: ${skipped.join(", ")}`);
+    }
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        run();
+    } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}
+
+export { generateCommands };

package/bin/scripts/opencode/generate-opencode-agents.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+import { readAgentMetadata } from "../../lib/agent-metadata.js";
+
+const parseArgs = (args) => {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--agents" && args[index + 1]) {
+            options.agentsDir = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--out" && args[index + 1]) {
+            options.outDir = args[index + 1];
+            index += 1;
+        }
+    }
+    return options;
+};
+
+const resolvePath = (value) => path.resolve(process.cwd(), value);
+
+const buildAgentContent = (description, body) => [
+    "---",
+    `description: ${description}`,
+    "---",
+    body.trimEnd(),
+    "",
+].join("\n");
+
+const generateOpencodeAgents = ({ agentsDir, outDir }) => {
+    if (!fs.existsSync(agentsDir)) {
+        throw new Error(`Missing agents directory: ${agentsDir}`);
+    }
+
+    fs.mkdirSync(outDir, { recursive: true });
+
+    const results = { created: [], skipped: [] };
+    const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".agent.md")) continue;
+
+        const agentPath = path.join(agentsDir, entry.name);
+        const metadata = readAgentMetadata(agentPath);
+        const outPath = path.join(outDir, `${metadata.name}.md`);
+
+        if (fs.existsSync(outPath)) {
+            results.skipped.push(metadata.name);
+            continue;
+        }
+
+        const content = buildAgentContent(metadata.description, metadata.body);
+        fs.writeFileSync(outPath, content, "utf8");
+        results.created.push(metadata.name);
+    }
+
+    return results;
+};
+
+const run = () => {
+    const { agentsDir, outDir } = parseArgs(process.argv.slice(2));
+    const resolvedAgentsDir = resolvePath(
+        agentsDir ?? path.join(process.cwd(), ".ai", "agents"),
+    );
+    const resolvedOutDir = resolvePath(
+        outDir ?? path.join(process.cwd(), ".opencode", "agents"),
+    );
+
+    const { created, skipped } = generateOpencodeAgents({
+        agentsDir: resolvedAgentsDir,
+        outDir: resolvedOutDir,
+    });
+
+    console.log(`✅ OpenCode agents generated in ${resolvedOutDir}`);
+    if (created.length > 0) {
+        console.log(`✅ Created: ${created.join(", ")}`);
+    }
+    if (skipped.length > 0) {
+        console.log(`⚠️  Skipped: ${skipped.join(", ")}`);
+    }
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        run();
+    } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}
+
+export { generateOpencodeAgents };