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

package/bin/scripts/rules/configure-rules.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+import { ensureSelection, promptChecklist } from "../../lib/checklist.js";
+import { applyRules, listRuleFiles } from "../../lib/rules-manager.js";
+
+const parseArgs = (args) => {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === "--rules" && args[index + 1]) {
+            options.rulesDir = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (value === "--out" && args[index + 1]) {
+            options.targetDir = args[index + 1];
+            index += 1;
+        }
+    }
+    return options;
+};
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const resolvePath = (value) => path.resolve(process.cwd(), value);
+
+const MANDATORY_RULES = ["default.rules.md"];
+
+const normalizeSelectedRules = (initialSelected) => {
+    if (!initialSelected) {
+        return [];
+    }
+
+    const normalized = new Set(initialSelected);
+    if (normalized.has("general.rules.md")) {
+        normalized.add("default.rules.md");
+    }
+
+    return Array.from(normalized);
+};
+
+const buildItems = (ruleNames, selections) => ruleNames.map((name, index) => ({
+    label: name,
+    checked: selections ? selections[index] : true,
+}));
+
+const selectionsMatch = (left, right) => {
+    if (!left || !right || left.length !== right.length) {
+        return false;
+    }
+
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    if (leftSet.size !== rightSet.size) {
+        return false;
+    }
+
+    for (const value of leftSet) {
+        if (!rightSet.has(value)) {
+            return false;
+        }
+    }
+
+    return true;
+};
+
+const configureRules = async ({ rulesDir, targetDir, initialSelected, forceApply = false }) => {
+    const ruleNames = listRuleFiles(rulesDir);
+    if (ruleNames.length === 0) {
+        console.warn("⚠️  No rules found to configure.");
+        return { copied: [], removed: [], selected: [], changed: false };
+    }
+
+    const prompt = "Toggle selections with numbers (e.g. 1,2) or press Enter: ";
+    const title = "Rules to install:";
+    const normalizedSelected = normalizeSelectedRules(initialSelected);
+
+    const mandatoryRules = ruleNames.filter((name) => MANDATORY_RULES.includes(name));
+    const selectableRules = ruleNames.filter((name) => !MANDATORY_RULES.includes(name));
+    const missingMandatory = MANDATORY_RULES.filter((name) => !ruleNames.includes(name));
+
+    if (missingMandatory.length > 0) {
+        console.warn(`⚠️  Missing mandatory rules: ${missingMandatory.join(", ")}`);
+    }
+
+    const baseSelection = selectableRules.map((name) => {
+        if (!normalizedSelected.length) {
+            return true;
+        }
+        return normalizedSelected.includes(name);
+    });
+
+    let selections = baseSelection;
+    if (selectableRules.length > 0 && process.stdin.isTTY && process.stdout.isTTY) {
+        selections = await promptChecklist({
+            title,
+            prompt,
+            items: buildItems(selectableRules, selections),
+        });
+    }
+
+    if (selectableRules.length > 0) {
+        selections = await ensureSelection({
+            title,
+            prompt,
+            items: buildItems(selectableRules, selections),
+            selections,
+            fallbackSelections: selectableRules.map(() => true),
+        });
+    }
+
+    const selected = [
+        ...mandatoryRules,
+        ...selectableRules.filter((_, index) => selections[index]),
+    ];
+    const baseSelected = [
+        ...mandatoryRules,
+        ...selectableRules.filter((_, index) => baseSelection[index]),
+    ];
+    const changed = !selectionsMatch(selected, baseSelected);
+    const missingInTarget = mandatoryRules.filter((name) =>
+        !fs.existsSync(path.join(targetDir, name))
+    );
+    const shouldApply = forceApply || changed || missingInTarget.length > 0;
+
+    if (!shouldApply) {
+        return { copied: [], removed: [], selected, changed: false };
+    }
+
+    const results = applyRules({ sourceDir: rulesDir, targetDir, selected });
+
+    return { ...results, selected, changed: true };
+};
+
+const run = async () => {
+    const { rulesDir, targetDir } = parseArgs(process.argv.slice(2));
+    const defaultRulesDir = path.join(__dirname, "../../../templates/.ai/rules");
+    const resolvedRulesDir = resolvePath(rulesDir ?? defaultRulesDir);
+    const resolvedTargetDir = resolvePath(targetDir ?? path.join(".ai", "rules"));
+
+    const { copied, removed, selected } = await configureRules({
+        rulesDir: resolvedRulesDir,
+        targetDir: resolvedTargetDir,
+    });
+
+    console.log(`✅ Rules configured in ${resolvedTargetDir}`);
+    if (selected.length > 0) {
+        console.log(`✅ Selected: ${selected.join(", ")}`);
+    }
+    if (removed.length > 0) {
+        console.log(`🗑️  Removed: ${removed.join(", ")}`);
+    }
+    if (copied.length > 0) {
+        console.log(`✅ Copied: ${copied.join(", ")}`);
+    }
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        await run();
+    } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}
+
+export { configureRules };

package/bin/spec-to-code.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { ensureSelection, promptChecklist } from "./lib/checklist.js";
+import { readAllAgentMetadata } from "./lib/agent-metadata.js";
+import { readInstallConfig, writeInstallConfig } from "./lib/install-config.js";
+import { configureRules } from "./scripts/rules/configure-rules.js";
+import { generateCommands } from "./scripts/opencode/generate-commands.js";
+import { generateOpencodeAgents } from "./scripts/opencode/generate-opencode-agents.js";
+import { generateSkills } from "./scripts/claude/generate-skills.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const srcAi = path.join(__dirname, "../templates/.ai");
+const dstAi = path.join(process.cwd(), ".ai");
+const opencodeDir = path.join(process.cwd(), ".opencode");
+const opencodeCommandsDir = path.join(opencodeDir, "commands");
+const claudeDir = path.join(process.cwd(), ".claude");
+const claudeSkillsDir = path.join(claudeDir, "skills");
+const agentsSrc = path.join(srcAi, "agents");
+
+const copied = [];
+const skipped = [];
+const removed = [];
+
+const getPackageVersion = () => {
+    const packagePath = path.join(__dirname, "../package.json");
+    const raw = fs.readFileSync(packagePath, "utf8");
+    const packageJson = JSON.parse(raw);
+
+    return packageJson.version ?? "0.0.0";
+};
+
+const clearAiDirectory = (directory, preserveFile) => {
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path.join(directory, entry.name);
+        if (entryPath === preserveFile) {
+            continue;
+        }
+        fs.rmSync(entryPath, { recursive: true, force: true });
+    }
+};
+
+const removeOpenCodeArtifacts = (opencodeRoot, agentMetadata) => {
+    const removedPaths = [];
+    for (const agent of agentMetadata) {
+        const commandPath = path.join(opencodeRoot, "commands", `${agent.command}.md`);
+        const agentPath = path.join(opencodeRoot, "agents", `${agent.name}.md`);
+
+        if (fs.existsSync(commandPath)) {
+            fs.rmSync(commandPath, { force: true });
+            removedPaths.push(path.join(".opencode", "commands", `${agent.command}.md`));
+        }
+        if (fs.existsSync(agentPath)) {
+            fs.rmSync(agentPath, { force: true });
+            removedPaths.push(path.join(".opencode", "agents", `${agent.name}.md`));
+        }
+    }
+
+    return removedPaths;
+};
+
+const removeClaudeArtifacts = (claudeRoot, agentMetadata) => {
+    const removedPaths = [];
+    for (const agent of agentMetadata) {
+        const skillPath = path.join(claudeRoot, "skills", agent.name);
+        if (fs.existsSync(skillPath)) {
+            fs.rmSync(skillPath, { recursive: true, force: true });
+            removedPaths.push(path.join(".claude", "skills", agent.name));
+        }
+    }
+
+    return removedPaths;
+};
+
+const run = async () => {
+    const configPath = path.join(dstAi, "config.json");
+    const packageVersion = getPackageVersion();
+    const existingConfig = readInstallConfig(configPath);
+    const hasConfig = Boolean(existingConfig);
+    const sameVersion = hasConfig && existingConfig.version === packageVersion;
+    const isUpdate = hasConfig && existingConfig.version !== packageVersion;
+
+    if (fs.existsSync(dstAi)) {
+        if (isUpdate) {
+            clearAiDirectory(dstAi, configPath);
+        } else if (!sameVersion) {
+            fs.rmSync(dstAi, { recursive: true, force: true });
+            skipped.push(".ai/ (removed)");
+        }
+    }
+
+    if (!sameVersion) {
+        fs.cpSync(srcAi, dstAi, { recursive: true });
+        copied.push(".ai/");
+    }
+
+    const agentMetadata = readAllAgentMetadata(agentsSrc);
+    const defaultIntegrations = {
+        opencode: existingConfig?.integrations?.opencode ?? fs.existsSync(opencodeDir),
+        claude: existingConfig?.integrations?.claude ?? fs.existsSync(claudeDir),
+    };
+
+    const integrations = [
+        {
+            key: "opencode",
+            label: "Install OpenCode commands (.opencode/commands)",
+            checked: defaultIntegrations.opencode,
+        },
+        {
+            key: "claude",
+            label: "Install Claude Code skills (.claude/skills)",
+            checked: defaultIntegrations.claude,
+        },
+    ];
+
+    let selections = integrations.map((item) => item.checked);
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        selections = await promptChecklist({
+            title: "Optional integrations:",
+            prompt: "Toggle selections with numbers (e.g. 1,2) or press Enter: ",
+            items: integrations,
+        });
+    }
+    selections = await ensureSelection({
+        title: "Optional integrations:",
+        prompt: "Toggle selections with numbers (e.g. 1,2) or press Enter: ",
+        items: integrations,
+        selections,
+        fallbackSelections: [true, false],
+    });
+
+    const [installOpenCode, installClaude] = selections;
+    const integrationChanged =
+        !hasConfig ||
+        installOpenCode !== defaultIntegrations.opencode ||
+        installClaude !== defaultIntegrations.claude;
+    const shouldApplyIntegrations = !sameVersion || integrationChanged;
+
+    if (shouldApplyIntegrations) {
+        if (installOpenCode) {
+            if (!fs.existsSync(agentsSrc)) {
+                console.warn("⚠️  Skipped: .opencode (agents missing)");
+            } else {
+                const { created, skipped: commandSkipped } = generateCommands({
+                    agentsDir: agentsSrc,
+                    commandsDir: opencodeCommandsDir,
+                });
+                const { created: agentCreated, skipped: agentSkipped } = generateOpencodeAgents({
+                    agentsDir: agentsSrc,
+                    outDir: path.join(opencodeDir, "agents"),
+                });
+
+                created.forEach((name) => {
+                    copied.push(path.join(".opencode", "commands", name));
+                });
+                commandSkipped.forEach((name) => {
+                    skipped.push(path.join(".opencode", "commands", name));
+                });
+                agentCreated.forEach((name) => {
+                    copied.push(path.join(".opencode", "agents", name));
+                });
+                agentSkipped.forEach((name) => {
+                    skipped.push(path.join(".opencode", "agents", name));
+                });
+            }
+        } else if (fs.existsSync(opencodeDir) && agentMetadata.length > 0) {
+            removed.push(...removeOpenCodeArtifacts(opencodeDir, agentMetadata));
+        }
+
+        if (installClaude) {
+            if (!fs.existsSync(agentsSrc)) {
+                console.warn("⚠️  Skipped: .claude/skills (agents missing)");
+            } else {
+                const { created, skipped: skillSkipped } = generateSkills({
+                    agentsDir: agentsSrc,
+                    skillsDir: claudeSkillsDir,
+                });
+                created.forEach((name) => {
+                    copied.push(path.join(".claude", "skills", name));
+                });
+                skillSkipped.forEach((name) => {
+                    skipped.push(path.join(".claude", "skills", name));
+                });
+            }
+        } else if (fs.existsSync(claudeDir) && agentMetadata.length > 0) {
+            removed.push(...removeClaudeArtifacts(claudeDir, agentMetadata));
+        }
+    } else if (fs.existsSync(opencodeDir) || fs.existsSync(claudeDir)) {
+        skipped.push("integrations (unchanged)");
+    }
+
+    const { selected: selectedRules, removed: removedRules, copied: copiedRules } =
+        await configureRules({
+            rulesDir: path.join(srcAi, "rules"),
+            targetDir: path.join(dstAi, "rules"),
+            initialSelected: existingConfig?.rules,
+            forceApply: !sameVersion,
+        });
+
+    copiedRules.forEach((rule) => {
+        copied.push(path.join(".ai", "rules", rule));
+    });
+    removedRules.forEach((rule) => {
+        removed.push(path.join(".ai", "rules", rule));
+    });
+
+    const now = new Date().toISOString();
+    const installConfig = {
+        version: packageVersion,
+        installedAt: existingConfig?.installedAt ?? now,
+        updatedAt: now,
+        integrations: {
+            opencode: installOpenCode,
+            claude: installClaude,
+        },
+        rules: selectedRules,
+    };
+    writeInstallConfig(configPath, installConfig);
+
+    console.log("✅ Spec-to-Code initialized");
+    if (copied.length > 0) {
+        console.log(`✅ Copied: ${copied.join(", ")}`);
+    }
+    if (skipped.length > 0) {
+        console.log(`⚠️  Skipped: ${skipped.join(", ")}`);
+    }
+    if (removed.length > 0) {
+        console.log(`🗑️  Removed: ${removed.join(", ")}`);
+    }
+    console.log(
+        `ℹ️  OpenCode commands: ${installOpenCode ? "installed" : "not installed"}`,
+    );
+    console.log(
+        `ℹ️  Claude Code skills: ${installClaude ? "installed" : "not installed"}`,
+    );
+    if (installOpenCode && installClaude) {
+        console.log(
+            "➡️ Open OpenCode and run: /Architect, or open Claude Code and use the architect skill.",
+        );
+    } else if (installOpenCode) {
+        console.log("➡️ Open OpenCode and run: /Architect");
+    } else if (installClaude) {
+        console.log("➡️ Open Claude Code and use the architect skill.");
+    } else {
+        console.log("➡️ No integration installed. Re-run to enable OpenCode or Claude Code.");
+    }
+};
+
+try {
+    await run();
+} catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deveonc/spec-to-code",
+  "version": "1.0.0-beta.2",
+  "description": "Spec-to-Code workflow bootstrap for OpenCode using agent-based LLM development",
+  "type": "module",
+  "scripts": {
+    "test": "node --test",
+    "test:single": "node --test",
+    "release": "semantic-release"
+  },
+  "bin": {
+    "spec-to-code": "./bin/spec-to-code.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "keywords": [
+    "opencode",
+    "llm",
+    "agents",
+    "spec-to-code"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "semantic-release": "^24.2.9"
+  }
+}

package/templates/.ai/agents/architect.agent.md

@@ -0,0 +1,45 @@
+---
+name: architect
+description: Start the Architect specification workflow.
+command: Architect
+---
+
+You are a senior Product Strategist, UX Researcher, and Technical Analyst named Architect agent.
+
+Your goal is to help the user develop a complete, detailed, developer-ready specification for a new app idea.
+
+Working rules:
+1. If docs/specs.md does NOT exist, start the specification process immediately.
+2. If docs/specs.md already exists, review it briefly and ask whether to refine or proceed to planning.
+3. Ask strictly ONE question at a time. Never ask multiple questions in the same turn.
+4. Each question must build directly on the previous answer, refining or expanding the specification.
+5. Follow this structured path of exploration in order:
+    - Problem & pain points
+    - Target users & segments
+    - Core use cases
+    - Key features & functional scope
+    - User journey & UX flows
+    - Technical considerations (architecture, integrations, constraints, stack choices)
+    - Data model & edge cases
+    - Monetization strategy
+    - Risks, limitations, dependencies
+    - Final consolidated specification
+6. During technical considerations, ask explicitly for frontend/backend stack choices.
+7. Confirm the chosen stack with the user before moving forward (no assumptions).
+8. Do NOT propose features or assumptions unless you have explicitly asked about them first.
+9. Do NOT skip ahead in the structure — proceed logically, guided by my answers.
+10. If the user asks for new features after specs exist, direct them back to Planning to add tasks before any development.
+11. When exploration is complete, compile everything into docs/specs.md.
+   The document must include:
+    - Functional requirements
+    - Non-functional requirements
+    - High-level architecture choices
+    - Frontend/backend stack choices (confirmed)
+    - Data handling and edge cases
+    - Error handling strategy
+    - Testing strategy
+12. Once docs/specs.md is created, instruct the user to switch to the Planning agent with command /Planning.
+
+
+Start by asking the first question:
+“What is the core idea of your app in one or two sentences?”

package/templates/.ai/agents/develop.agent.md

@@ -0,0 +1,88 @@
+---
+name: develop
+description: Implement a single task from docs/todo.md.
+command: Develop
+---
+
+You are a senior Software Engineer named Develop agent.
+
+Your goal is to implement the project incrementally by executing tasks from docs/todo.md and validate them by creating and executing test when possible.
+
+You operate ONE task at a time.
+
+------------------------------------------------------------
+EXECUTION RULES
+------------------------------------------------------------
+1. If no task is specified, pick the first unchecked task in docs/todo.md and ask for confirmation.
+   - Include the task ID and title in the confirmation message.
+   - Example: "Next available task is S3: Add user search filters. Proceed?"
+2. If any task is marked IN PROGRESS ([~]), warn the user and ask whether to resume it or start the next unchecked task.
+   - Example: "Task S2 is marked in progress. Resume S2 or start S3?"
+3. Implement EXACTLY ONE task from docs/todo.md.
+4. If the user asks for a new feature or change not in docs/todo.md, STOP and redirect them to the Planning workflow to add a new task.
+5. Do NOT modify docs/specs.md or docs/implementation_plan.md.
+6. Follow all rules in rules/*.rules.md.
+7. Preserve existing working code whenever possible.
+8. Integrate new code with existing modules (imports, wiring, configuration).
+
+
+------------------------------------------------------------
+TESTING (MANDATORY)
+------------------------------------------------------------
+7. After implementation, you MUST run the relevant test command(s):
+    - Examples: `npm test`, `mvn test`, `gradle test`, etc.
+8. If no tests exist:
+    - Create them.
+    - Then run the test suite.
+9. If tests fail:
+    - Fix the code or tests.
+    - Re-run tests until they pass.
+
+------------------------------------------------------------
+VALIDATION
+------------------------------------------------------------
+10. Summarize:
+    - Code changes
+    - Tests added or modified
+    - Test command(s) executed
+    - Test results (pass/fail)
+
+------------------------------------------------------------
+HANDOFF TO REVIEW
+------------------------------------------------------------
+11. Once tests pass:
+    - Automatically hand off to the Reviewer agent with /Reviewer.
+    - If multiple tasks are in progress, ask which task ID to review.
+    - Provide all context needed for review.
+
+
+------------------------------------------------------------
+POST-REVIEW BEHAVIOR
+------------------------------------------------------------
+12. If the Reviewer approves:
+    - Propose updating docs/todo.md by marking the task as completed.
+    - Ask whether to proceed with the next task.
+13. If approved and confirmed, suggest the next unchecked task.
+
+------------------------------------------------------------
+TASK LOCKING (MULTI-AGENT SAFETY)
+------------------------------------------------------------
+14. Before starting any task:
+    - Check docs/todo.md.
+    - If the task is marked [~] or [x], DO NOT start it.
+    - If the task is [ ], you must lock it by marking it [~].
+
+15. When starting a task:
+    - Update docs/todo.md by changing:
+      [ ] → [~] for the selected task.
+    - Clearly state that the task is now IN PROGRESS.
+
+16. If the task cannot be completed (blocked, unclear, failing tests):
+    - Keep the task marked as [~].
+    - Explain why it is blocked.
+
+17. Only after Reviewer approval:
+    - Propose updating the task from [~] → [x].
+
+Default execution format:
+“Implement task {{task_id}} from docs/todo.md.”