@rijalpermana/spec-forge 0.2.0 → 0.2.2

package/README.md

@@ -27,7 +27,8 @@ workflow into whichever AI coding tool you use.
   `prd.md`.
 - **Sequencing is enforced by guard rails, not convention.** `schema`,
   `contract`, `tasks`, and `testcase` all refuse to run until `prd.md`
-  exists, so nothing gets invented without a spec behind it.
+  exists, and `implement` refuses until `tasks.md` exists, so nothing gets
+  invented — or coded — without a spec behind it.
 - **One instruction source, many renderers.** Every AI-tool bridge is
   generated from `src/lib/command-specs.ts` — the instructions are written
   once and rendered into each tool's native format, so they can't drift out
@@ -74,6 +75,9 @@ forge mockup btn-fraud-check      # mockup.html (requires prd.md)
 forge tasks btn-fraud-check       # tasks.md (requires prd.md)
 forge testcase btn-fraud-check    # testcases.md (requires prd.md)
 forge verify btn-fraud-check      # reports missing files / unresolved [TODO]s
+
+forge implement btn-fraud-check   # checks tasks.md exists, reports grounding files
+                                   # -> your AI tool then writes the actual code
 ```
 
 ## Spec index
@@ -136,6 +140,7 @@ the writing.
 | `forge mockup <feature>` | `prd.md` | `mockup.html` (stub) | Yes |
 | `forge tasks <feature>` | `prd.md` | `tasks.md` (stub) | Yes |
 | `forge testcase <feature>` | `prd.md` | `testcases.md` (stub) | Yes |
+| `forge implement <feature>` | `tasks.md` | Console report of which grounding files exist; no spec file written | N/A — writes application code, not specs |
 | `forge verify <feature>` | — | Console report, `INDEX.md` status → `active` if complete | N/A (read-only on spec files) |
 
 ## Output structure
@@ -175,5 +180,6 @@ the templates and the AI-drafting instructions will drift out of sync.
 |---|---|---|
 | `forge: command not found` | `bun link` wasn't run, or shell hasn't reloaded | Re-run `bun link` in the `forge` package directory, restart your shell |
 | `No prd.md found for "<feature>"` | Tried `schema`/`contract`/`tasks`/`testcase` before `smelt` | Run `forge smelt <feature>` first |
+| `No tasks.md found for "<feature>"` | Tried `implement` before `tasks` | Run `forge tasks <feature>` first |
 | `<file> already exists — skipping` | The output spec file is already there | Edit it directly, or delete it to regenerate from the template |
 | `/forge:*` or `/forge-*` commands don't appear in your AI tool | `forge init`/`forge bridge` wasn't run for that target, or the tool needs a restart | Run `forge bridge <target>`, then restart the AI tool's session |

package/dist/cli.js

@@ -6901,6 +6901,15 @@ var COMMAND_SPECS = [
 
 ` + "Test Type must be exactly **Positive** or **Negative** (bolded). Actual Result " + "and Status stay as `-` until QA runs them manually."
   },
+  {
+    name: "implement",
+    argumentHint: "[feature-name]",
+    description: "Work through tasks.md and write the actual code for the feature",
+    requiresPrd: true,
+    readOnly: false,
+    writesCode: true,
+    instructions: GROUND_IN_RULES + "This command doesn't scaffold a spec file — it checks that {{tasks}} exists " + "and reports which grounding files (prd, schema, contract, tasks, testcases, " + "mockup, RULES.md) are present. Read all of them, then implement the feature: " + "follow {{tasks}}'s sequencing literally (data/schema before logic before UI, " + "don't reorder around a missing dependency — flag it instead), match {{schema}} " + "for the data layer and {{contract}} exactly for endpoint shapes, use {{mockup}} " + "only as a layout/flow reference (not final markup), and don't invent scope, " + "fields, or endpoints that aren't traceable to {{prd}}. Once implemented, run " + "through {{testcases}} manually and report which rows pass so the user can fill " + "in Actual Result / Status."
+  },
   {
     name: "verify",
     argumentHint: "[feature-name]",
@@ -6947,7 +6956,7 @@ function writeCommandFiles(dir, specs, fileName, render) {
 
 // src/lib/bridges/claude.ts
 function renderClaude(spec) {
-  const allowedTools = spec.readOnly ? `Bash(forge ${spec.name}:*), Read` : `Bash(forge ${spec.name}:*), Read, Edit`;
+  const allowedTools = spec.readOnly ? `Bash(forge ${spec.name}:*), Read` : spec.writesCode ? `Bash(forge ${spec.name}:*), Read, Write, Edit` : `Bash(forge ${spec.name}:*), Read, Edit`;
   const body = substitutePaths(spec.instructions, (file) => `specs/$ARGUMENTS/${file}`);
   return `---
 allowed-tools: ${allowedTools}
@@ -7305,9 +7314,33 @@ function makeScaffoldCommand({ file, label }) {
   };
 }
 
+// src/commands/implement.ts
+import { join as join10 } from "node:path";
+function implement(feature) {
+  const cwd = process.cwd();
+  const dir = featureDir(feature, cwd);
+  const tasksPath = join10(dir, SPEC_FILES.tasks);
+  if (!fileExists(tasksPath)) {
+    console.error(`No tasks.md found for "${feature}". Run "forge tasks ${feature}" first ` + `so implementation follows a sequenced plan instead of ad-hoc scope.`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Implementing: ${feature}
+`);
+  console.log(`Grounding files:`);
+  for (const file of SPEC_FILE_NAMES) {
+    const path = join10(dir, file);
+    console.log(`  ${fileExists(path) ? "[OK] " : "[--] "} specs/${feature}/${file}`);
+  }
+  const rulesPath = join10(specsDir(cwd), "RULES.md");
+  console.log(`  ${fileExists(rulesPath) ? "[OK] " : "[--] "} specs/RULES.md`);
+  console.log(`
+Next: work through specs/${feature}/tasks.md in order — data/schema tasks, ` + `then logic, then UI. Ground every change in schema.dbml, api-contract.md, and ` + `specs/RULES.md (if present); don't invent scope beyond prd.md. Once done, run ` + `through testcases.md manually and fill in Actual Result / Status.`);
+}
+
 // src/commands/verify.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function verify(feature) {
   const cwd = process.cwd();
   const dir = featureDir(feature, cwd);
@@ -7316,7 +7349,7 @@ function verify(feature) {
   let missing = 0;
   let withTodo = 0;
   for (const file of SPEC_FILE_NAMES) {
-    const path = join10(dir, file);
+    const path = join11(dir, file);
     if (!fileExists(path)) {
       console.log(`  [MISSING]  ${file}`);
       missing++;
@@ -7347,7 +7380,7 @@ function verify(feature) {
 
 // src/commands/scan.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync, mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join11, extname as extname2, relative, basename as basename2 } from "node:path";
+import { join as join12, extname as extname2, relative, basename as basename2 } from "node:path";
 var IGNORE_DIRS = new Set([
   "node_modules",
   ".git",
@@ -7376,7 +7409,7 @@ function scan(options = {}) {
   const files = collectFiles(cwd);
   const schemas = files.filter(isSchemaFile);
   const apis = files.filter(isApiFile);
-  const raw = readTemplate(join11(templatesDir, "codebase.md"));
+  const raw = readTemplate(join12(templatesDir, "codebase.md"));
   const rendered = renderTemplate(raw, {
     generatedAt: new Date().toISOString().slice(0, 10),
     depth: String(depth),
@@ -7388,7 +7421,7 @@ function scan(options = {}) {
     tree: renderTree(cwd, depth)
   });
   mkdirSync6(specsDir(cwd), { recursive: true });
-  const outPath = join11(specsDir(cwd), "CODEBASE.md");
+  const outPath = join12(specsDir(cwd), "CODEBASE.md");
   writeFileSync5(outPath, rendered, "utf-8");
   console.log(`Wrote ${outPath}`);
   console.log(`  ${files.length} files scanned — ${schemas.length} schema-ish, ${apis.length} API-ish`);
@@ -7409,9 +7442,9 @@ function collectFiles(root) {
     for (const e of entries) {
       if (e.isDirectory()) {
         if (!IGNORE_DIRS.has(e.name))
-          dirs.push(join11(dir, e.name));
+          dirs.push(join12(dir, e.name));
       } else if (e.isFile()) {
-        out.push(relative(root, join11(dir, e.name)));
+        out.push(relative(root, join12(dir, e.name)));
         if (out.length >= MAX_FILES)
           break;
       }
@@ -7421,7 +7454,7 @@ function collectFiles(root) {
 }
 function detectStack(root) {
   const found = [];
-  const pkgPath = join11(root, "package.json");
+  const pkgPath = join12(root, "package.json");
   if (existsSync4(pkgPath)) {
     let pkg = {};
     try {
@@ -7429,7 +7462,7 @@ function detectStack(root) {
     } catch {}
     const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
     const has = (n) => Object.prototype.hasOwnProperty.call(deps, n);
-    const isTs = has("typescript") || existsSync4(join11(root, "tsconfig.json"));
+    const isTs = has("typescript") || existsSync4(join12(root, "tsconfig.json"));
     found.push(`Node.js${isTs ? " / TypeScript" : ""} (package.json)`);
     const frameworks = [
       ["next", "Next.js"],
@@ -7469,7 +7502,7 @@ function detectStack(root) {
     ["Dockerfile", "Docker (Dockerfile)"]
   ];
   for (const [file, label] of manifests)
-    if (existsSync4(join11(root, file)))
+    if (existsSync4(join12(root, file)))
       found.push(label);
   return found;
 }
@@ -7497,7 +7530,7 @@ function isApiFile(f) {
 }
 function renderProject(root, fileCount) {
   let name = basename2(root);
-  const pkgPath = join11(root, "package.json");
+  const pkgPath = join12(root, "package.json");
   if (existsSync4(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
@@ -7515,7 +7548,7 @@ function renderProject(root, fileCount) {
     "Gemfile",
     "composer.json",
     "pom.xml"
-  ].filter((m) => existsSync4(join11(root, m)));
+  ].filter((m) => existsSync4(join12(root, m)));
   return [
     `- **Name:** ${name}`,
     `- **Root:** ${root}`,
@@ -7560,7 +7593,7 @@ function walkTree(dir, prefix, depthLeft, lines) {
     const isLast = i === shown.length - 1 && filtered.length <= CAP;
     lines.push(`${prefix}${isLast ? "└── " : "├── "}${e.name}${e.isDirectory() ? "/" : ""}`);
     if (e.isDirectory()) {
-      walkTree(join11(dir, e.name), prefix + (isLast ? "    " : "│   "), depthLeft - 1, lines);
+      walkTree(join12(dir, e.name), prefix + (isLast ? "    " : "│   "), depthLeft - 1, lines);
     }
   });
   if (filtered.length > CAP) {
@@ -7582,11 +7615,11 @@ function linesOrNone(items, emptyText) {
 }
 
 // src/commands/rules.ts
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function rules() {
   const cwd = process.cwd();
-  const outPath = join12(specsDir(cwd), "RULES.md");
-  const raw = readTemplate(join12(templatesDir, "rules.md"));
+  const outPath = join13(specsDir(cwd), "RULES.md");
+  const raw = readTemplate(join13(templatesDir, "rules.md"));
   const written = writeIfAbsent(outPath, raw);
   if (!written) {
     console.log(`${outPath} already exists — edit it directly, or delete it to regenerate the template.`);
@@ -7613,5 +7646,6 @@ program2.command("contract <feature>").description("Scaffold api-contract.md (re
 program2.command("mockup <feature>").description("Scaffold mockup.html (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.mockup, label: "mockup" }));
 program2.command("tasks <feature>").description("Scaffold tasks.md WBS (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.tasks, label: "tasks" }));
 program2.command("testcase <feature>").description("Scaffold testcases.md (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.testcases, label: "testcase" }));
+program2.command("implement <feature>").description("Check the spec set is ready for coding, and report which grounding files exist (requires tasks.md)").action(implement);
 program2.command("verify <feature>").description("Check that all spec files exist and have no unresolved [TODO] markers").action(verify);
 program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rijalpermana/spec-forge",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Spec-driven development CLI: scaffolds specs, schemas, API contracts, task lists, and test cases; bridges into Claude Code as slash commands.",
   "type": "module",
   "license": "MIT",

package/templates/rules.md

@@ -27,6 +27,31 @@
 `dto/`, `entities/`, `*.controller.ts`, `*.service.ts`, `*.repository.ts`,
 `*.module.ts`. The AI should scaffold new work to match this.]
 
+## Code design principles
+
+- **SOLID:**
+  - Single Responsibility — each module, class, or function has one reason
+    to change; separate data-fetching, business logic, and presentation.
+  - Open/Closed — extend behavior through new code (props, composition,
+    new implementations of an interface), not by editing working, tested
+    code to bolt on a special case.
+  - Liskov Substitution — a derived/extended type must work anywhere its
+    base type is accepted, without the caller needing to know the
+    difference or handle extra edge cases.
+  - Interface Segregation — depend only on the fields/methods actually
+    used; don't pass a whole object through when one field is needed, and
+    don't force implementers to satisfy methods they don't need.
+  - Dependency Inversion — depend on abstractions (interfaces, hooks,
+    an injected client), not concrete implementations, so the
+    implementation can be swapped or mocked without touching the caller.
+- **KISS:** prefer the simplest design that satisfies the requirement.
+  No speculative abstraction, config options, or generalization for
+  needs that don't exist yet.
+- **DRY:** don't duplicate logic — extract it once a second real
+  duplicate appears, not preemptively on the first occurrence. Two
+  similar-looking blocks that change for different reasons are not
+  duplication; don't force them into one abstraction.
+
 ## API design
 
 - Versioning: [TODO — e.g. URI versioning `/v1/`, `/v2/`]
@@ -40,6 +65,11 @@
 - Audit/base fields every entity carries: [TODO — e.g. created_by, created_date, ...]
 - Multi-tenancy / scoping: [TODO — or "n/a"]
 - Type conventions: [TODO]
+- Enums: don't use DBML's `enum {}` type. Model fixed-value fields as
+  `varchar`/`text` with a `note:` documenting the allowed values, or as a
+  proper lookup/reference table if the values carry their own metadata
+  (label, order, active flag) or are managed at runtime. This avoids a
+  schema migration every time a value is added or removed.
 
 ## Validation