@rijalpermana/spec-forge 0.1.0 → 0.1.2

package/README.md

@@ -63,6 +63,7 @@ forge --version
 cd your-project
 forge init                        # scaffolds specs/ + AI bridge (defaults to Claude Code)
 forge scan                        # (optional) inventory existing code -> specs/CODEBASE.md
+forge rules                       # (optional) scaffold specs/RULES.md — project conventions
 forge smelt btn-fraud-check       # interactive Q&A -> brief.md + prd.md stub
 
 # draft prd.md by hand, or with your AI tool, using brief.md as grounding
@@ -127,6 +128,7 @@ the writing.
 | `forge init [--target <t>]` | — | `specs/`, `specs/INDEX.md`, AI bridge files | Yes — bridge files regenerate freely |
 | `forge bridge <target>` | — | AI bridge files for `<target>` | Yes — always regenerates |
 | `forge scan [--depth <n>]` | — | `specs/CODEBASE.md` (stack, file stats, existing schema/API files, directory tree) | Yes — refreshes on every run |
+| `forge rules` | — | `specs/RULES.md` (project conventions the AI grounds all drafting in) | Yes — refuses if `RULES.md` exists |
 | `forge smelt <feature>` | — | `brief.md`, `prd.md` (stub), `INDEX.md` entry (`draft`) | Yes — refuses if `brief.md` exists |
 | `forge schema <feature>` | `prd.md` | `schema.dbml` (stub) | Yes |
 | `forge contract <feature>` | `prd.md` | `api-contract.md` (stub) | Yes |
@@ -141,6 +143,7 @@ your-project/
 ├── specs/
 │   ├── INDEX.md                    # creation order, status, dependencies across all features
 │   ├── CODEBASE.md                 # (optional) forge scan output: existing project inventory
+│   ├── RULES.md                    # (optional) forge rules output: project conventions the AI follows
 │   └── <feature-name>/
 │       ├── brief.md           # smelt Q&A capture
 │       ├── prd.md              # goal, actors, user stories, business rules, out-of-scope

package/dist/cli.js

@@ -6821,6 +6821,7 @@ function featureDir(feature, cwd = process.cwd()) {
 }
 
 // src/lib/command-specs.ts
+var GROUND_IN_RULES = "If specs/RULES.md exists, read it first and follow those project conventions — " + "they override any defaults described below. ";
 var COMMAND_SPECS = [
   {
     name: "scan",
@@ -6830,13 +6831,21 @@ var COMMAND_SPECS = [
     readOnly: true,
     instructions: "This command scans the existing project deterministically (no code is " + "interpreted) and writes specs/CODEBASE.md — a factual inventory of the detected " + "stack, file statistics, existing schema and API files, and the directory tree. " + "After it runs, read specs/CODEBASE.md and use it as grounding: when drafting " + "schemas, contracts, or tasks later, reuse the conventions, entities, and files " + "that already exist here instead of inventing new ones. Don't echo the whole file " + "back — just confirm the stack and the spec-relevant files you found."
   },
+  {
+    name: "rules",
+    argumentHint: "(no arguments — scaffolds specs/RULES.md)",
+    description: "Scaffold specs/RULES.md — project conventions the AI follows when drafting",
+    requiresPrd: false,
+    readOnly: false,
+    instructions: "This command scaffolds specs/RULES.md — a project-level conventions file " + "(tech stack, naming, module structure, API/response format, data, validation, " + "security, testing, docs, tooling). After it runs, help the user fill the [TODO] " + "sections: infer what you can from specs/CODEBASE.md and the existing code, and " + "ask about anything you can't. Keep each rule factual and enforceable. Once " + "filled, every other forge drafting command must obey these rules."
+  },
   {
     name: "smelt",
     argumentHint: "[feature-name]",
     description: "Extract raw requirements into a grounding brief, then draft the PRD",
     requiresPrd: false,
     readOnly: false,
-    instructions: "This command is interactive — it prompts for goal, actors, constraints, and " + "out-of-scope items in the terminal. Once it completes, read {{brief}} and " + "draft {{prd}} following the structure already stubbed there. Do not invent " + "scope, actors, or rules that aren't grounded in the brief — if something's " + "missing, ask what to clarify instead of guessing."
+    instructions: GROUND_IN_RULES + "This command has two input modes. Default: it prompts for goal, actors, " + "constraints, and out-of-scope items in the terminal. With --from <file>: it " + "stages an existing BRD/requirements document verbatim in the feature folder as " + "source-brd.<ext> (extension preserved — .md, .pdf, .docx, …) and leaves " + "'[TODO: extract from source-brd.<ext>]' markers in {{brief}}. If a source-brd.* " + "file exists, read it (if your tool can't open that format — e.g. .docx — say so " + "and ask the user to export it to Markdown or PDF) and replace each marker in " + "{{brief}} with the value extracted from the document, citing the BRD section it " + "came from so every requirement stays traceable. Then read {{brief}} and draft " + "{{prd}} following the structure already stubbed there. Do not invent scope, " + "actors, or rules that aren't grounded in the brief or the BRD — if something's " + "missing, ask what to clarify instead of guessing."
   },
   {
     name: "schema",
@@ -6844,7 +6853,7 @@ var COMMAND_SPECS = [
     description: "Scaffold schema.dbml, then draft it from prd.md",
     requiresPrd: true,
     readOnly: false,
-    instructions: "Read {{prd}} and fill {{schema}} with tables, columns, and relationships that " + "are directly traceable to entities, actors, or business rules in the PRD. " + "Follow existing DBML conventions in this repo (multi-tenant RLS pattern, " + "tenant_id scoping, Drizzle-compatible types) if a reference schema exists " + "elsewhere in the project."
+    instructions: GROUND_IN_RULES + "Read {{prd}} and fill {{schema}} with tables, columns, and relationships that " + "are directly traceable to entities, actors, or business rules in the PRD. " + "Follow existing DBML conventions in this repo (multi-tenant RLS pattern, " + "tenant_id scoping, Drizzle-compatible types) if a reference schema exists " + "elsewhere in the project."
   },
   {
     name: "contract",
@@ -6852,7 +6861,7 @@ var COMMAND_SPECS = [
     description: "Scaffold api-contract.md, then draft it from prd.md",
     requiresPrd: true,
     readOnly: false,
-    instructions: "Read {{prd}} and fill {{contract}}. Use exactly this format per endpoint, " + `one block per endpoint, no deviation:
+    instructions: GROUND_IN_RULES + "Read {{prd}} and fill {{contract}}. Use exactly this format per endpoint, " + `one block per endpoint, no deviation:
 
 ` + `Title: [short name]
 ` + `endpoint: [METHOD] [path]
@@ -6866,7 +6875,7 @@ var COMMAND_SPECS = [
     description: "Scaffold tasks.md, then draft it from prd.md",
     requiresPrd: true,
     readOnly: false,
-    instructions: "Read {{prd}} and {{schema}} (if present), then fill {{tasks}}. Sequence " + "strictly: data/schema tasks before logic tasks before UI tasks. Call out any " + "dependency inversion explicitly rather than silently reordering — if the PRD " + "implies model or logic work before its data source exists, flag it instead of " + "hiding it."
+    instructions: GROUND_IN_RULES + "Read {{prd}} and {{schema}} (if present), then fill {{tasks}}. Sequence " + "strictly: data/schema tasks before logic tasks before UI tasks. Call out any " + "dependency inversion explicitly rather than silently reordering — if the PRD " + "implies model or logic work before its data source exists, flag it instead of " + "hiding it."
   },
   {
     name: "testcase",
@@ -6874,7 +6883,7 @@ var COMMAND_SPECS = [
     description: "Scaffold testcases.md, then draft it from prd.md",
     requiresPrd: true,
     readOnly: false,
-    instructions: "Read {{prd}} and fill {{testcases}}. Use exactly this table format, one row " + `per scenario, do not change columns:
+    instructions: GROUND_IN_RULES + "Read {{prd}} and fill {{testcases}}. Use exactly this table format, one row " + `per scenario, do not change columns:
 
 ` + `| No | Test Scenario | Test Case | Test Type | Expected Result | Actual Result | Status | Remark |
 ` + `| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
@@ -7146,7 +7155,8 @@ Next: forge smelt <feature-name>`);
 
 // src/commands/smelt.ts
 var import_prompts = __toESM(require_prompts3(), 1);
-import { join as join8 } from "node:path";
+import { copyFileSync, mkdirSync as mkdirSync5 } from "node:fs";
+import { basename, extname, join as join8, resolve } from "node:path";
 
 // src/lib/template.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
@@ -7169,7 +7179,8 @@ function fileExists(path) {
 }
 
 // src/commands/smelt.ts
-async function smelt(feature) {
+var SOURCE_DOC_BASE = "source-brd";
+async function smelt(feature, opts = {}) {
   const cwd = process.cwd();
   const dir = featureDir(feature, cwd);
   const briefPath = join8(dir, SPEC_FILES.brief);
@@ -7186,36 +7197,20 @@ async function smelt(feature) {
     console.log(`Existing features: ${existingFeatures.join(", ")}
 `);
   }
-  const answers = await import_prompts.default([
-    { type: "text", name: "goal", message: "One-sentence goal — what must this feature deliver?" },
-    { type: "text", name: "actors", message: "Who are the actors/roles involved?" },
-    { type: "text", name: "constraints", message: "Key constraints (regulatory, technical, deadline)?" },
-    { type: "text", name: "outOfScope", message: "What's explicitly OUT of scope?" },
-    {
-      type: "text",
-      name: "dependsOn",
-      message: "Does this depend on another existing feature? (feature name, or leave blank)"
-    }
-  ]);
-  if (!answers.goal) {
-    console.log("Smelting cancelled.");
+  const briefVars = opts.from ? stageSourceDoc(opts.from, dir) : await runInteractive(feature);
+  if (!briefVars)
     return;
-  }
   const briefRaw = readTemplate(join8(templatesDir, SPEC_FILES.brief));
   const brief = renderTemplate(briefRaw, {
     feature,
     date: new Date().toISOString().slice(0, 10),
-    goal: answers.goal ?? "",
-    actors: answers.actors ?? "",
-    constraints: answers.constraints ?? "",
-    outOfScope: answers.outOfScope ?? ""
+    ...briefVars
   });
   writeIfAbsent(briefPath, brief);
   const prdRaw = readTemplate(join8(templatesDir, SPEC_FILES.prd));
   const prd = renderTemplate(prdRaw, { feature });
   const prdWritten = writeIfAbsent(prdPath, prd);
-  const dependsOn = answers.dependsOn?.trim() || "-";
-  upsertIndexEntry(cwd, feature, { status: "draft", dependsOn });
+  upsertIndexEntry(cwd, feature, { status: "draft", dependsOn: briefVars.dependsOn });
   console.log(`
 Wrote ${briefPath}`);
   if (prdWritten)
@@ -7224,6 +7219,55 @@ Wrote ${briefPath}`);
   console.log(`
 Next: open this project in your AI tool and draft prd.md from brief.md ` + `— use the /forge:smelt, /forge-smelt, or AGENTS.md instructions, depending ` + `on which bridge you initialized.`);
 }
+function stageSourceDoc(from, dir) {
+  const srcPath = resolve(process.cwd(), from);
+  if (!fileExists(srcPath)) {
+    console.log(`Source document not found: ${srcPath}`);
+    process.exitCode = 1;
+    return;
+  }
+  const docName = `${SOURCE_DOC_BASE}${extname(srcPath).toLowerCase()}`;
+  const destPath = join8(dir, docName);
+  if (fileExists(destPath)) {
+    console.log(`${destPath} already exists — leaving it in place.`);
+  } else {
+    mkdirSync5(dir, { recursive: true });
+    copyFileSync(srcPath, destPath);
+    console.log(`Staged ${basename(srcPath)} → ${destPath}`);
+  }
+  const marker = `[TODO: extract from ${docName}]`;
+  return {
+    goal: marker,
+    actors: marker,
+    constraints: marker,
+    outOfScope: marker,
+    dependsOn: "-"
+  };
+}
+async function runInteractive(feature) {
+  const answers = await import_prompts.default([
+    { type: "text", name: "goal", message: "One-sentence goal — what must this feature deliver?" },
+    { type: "text", name: "actors", message: "Who are the actors/roles involved?" },
+    { type: "text", name: "constraints", message: "Key constraints (regulatory, technical, deadline)?" },
+    { type: "text", name: "outOfScope", message: "What's explicitly OUT of scope?" },
+    {
+      type: "text",
+      name: "dependsOn",
+      message: "Does this depend on another existing feature? (feature name, or leave blank)"
+    }
+  ]);
+  if (!answers.goal) {
+    console.log("Smelting cancelled.");
+    return null;
+  }
+  return {
+    goal: answers.goal ?? "",
+    actors: answers.actors ?? "",
+    constraints: answers.constraints ?? "",
+    outOfScope: answers.outOfScope ?? "",
+    dependsOn: answers.dependsOn?.trim() || "-"
+  };
+}
 
 // src/commands/scaffold.ts
 import { join as join9 } from "node:path";
@@ -7290,8 +7334,8 @@ function verify(feature) {
 }
 
 // src/commands/scan.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join11, extname, relative, basename } from "node:path";
+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";
 var IGNORE_DIRS = new Set([
   "node_modules",
   ".git",
@@ -7331,7 +7375,7 @@ function scan(options = {}) {
     apis: pathListOrNone(apis),
     tree: renderTree(cwd, depth)
   });
-  mkdirSync5(specsDir(cwd), { recursive: true });
+  mkdirSync6(specsDir(cwd), { recursive: true });
   const outPath = join11(specsDir(cwd), "CODEBASE.md");
   writeFileSync5(outPath, rendered, "utf-8");
   console.log(`Wrote ${outPath}`);
@@ -7418,8 +7462,8 @@ function detectStack(root) {
   return found;
 }
 function isSchemaFile(f) {
-  const ext = extname(f).toLowerCase();
-  const base = basename(f).toLowerCase();
+  const ext = extname2(f).toLowerCase();
+  const base = basename2(f).toLowerCase();
   if (ext === ".dbml" || ext === ".prisma" || ext === ".sql")
     return true;
   if (/schema/.test(base) && [".ts", ".js", ".py", ".rb", ".go", ".json"].includes(ext))
@@ -7430,7 +7474,7 @@ function isSchemaFile(f) {
 }
 function isApiFile(f) {
   const p = f.toLowerCase();
-  const base = basename(p);
+  const base = basename2(p);
   if (/(openapi|swagger)\.(ya?ml|json)$/.test(base))
     return true;
   if (/\.(controller|route|router|resolver)\.(ts|js|py)$/.test(base))
@@ -7440,7 +7484,7 @@ function isApiFile(f) {
   return false;
 }
 function renderProject(root, fileCount) {
-  let name = basename(root);
+  let name = basename2(root);
   const pkgPath = join11(root, "package.json");
   if (existsSync4(pkgPath)) {
     try {
@@ -7471,7 +7515,7 @@ function renderProject(root, fileCount) {
 function fileStats(files) {
   const counts = new Map;
   for (const f of files) {
-    const ext = extname(f).toLowerCase() || "(no ext)";
+    const ext = extname2(f).toLowerCase() || "(no ext)";
     counts.set(ext, (counts.get(ext) ?? 0) + 1);
   }
   const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12);
@@ -7479,7 +7523,7 @@ function fileStats(files) {
 `);
 }
 function renderTree(root, maxDepth) {
-  const lines = [`${basename(root) || root}/`];
+  const lines = [`${basename2(root) || root}/`];
   walkTree(root, "", maxDepth, lines);
   return lines.join(`
 `);
@@ -7525,13 +7569,31 @@ function linesOrNone(items, emptyText) {
 `) : emptyText;
 }
 
+// src/commands/rules.ts
+import { join as join12 } from "node:path";
+function rules() {
+  const cwd = process.cwd();
+  const outPath = join12(specsDir(cwd), "RULES.md");
+  const raw = readTemplate(join12(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.`);
+    return;
+  }
+  console.log(`Wrote ${outPath}`);
+  console.log(`  Fill in the [TODO] sections with your project's conventions.`);
+  console.log(`
+Every forge drafting command (smelt, schema, contract, tasks, testcase) ` + `will ground the AI in these rules.`);
+}
+
 // src/cli.ts
 var program2 = new Command;
-program2.name("forge").description("Spec-driven development CLI — scaffolds specs, schemas, API contracts, tasks, and test cases.").version("0.1.0");
+program2.name("forge").description("Spec-driven development CLI — scaffolds specs, schemas, API contracts, tasks, and test cases.").version("0.1.2");
 program2.command("init").description("Scaffold specs/ folder and an AI-tool bridge in the current project").option("-t, --target <target>", "bridge target: claude, cursor, windsurf, or generic", "claude").action((options) => init({ target: options.target }));
 program2.command("bridge <target>").description("(Re)generate AI-tool bridge commands: claude, cursor, windsurf, or generic").action((target) => bridge(target));
 program2.command("scan").description("Inventory the existing project structure into specs/CODEBASE.md").option("-d, --depth <n>", "directory-tree depth to include in the report", "2").action((options) => scan({ depth: Number(options.depth) }));
-program2.command("smelt <feature>").description("Extract raw requirements into a grounding brief and stub the PRD").action(smelt);
+program2.command("rules").description("Scaffold specs/RULES.md — project conventions the AI follows when drafting").action(() => rules());
+program2.command("smelt <feature>").description("Extract raw requirements into a grounding brief and stub the PRD").option("-f, --from <file>", "extract from an existing BRD/requirements document instead of interactive Q&A").action((feature, options) => smelt(feature, { from: options.from }));
 program2.command("schema <feature>").description("Scaffold schema.dbml (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.schema, label: "schema" }));
 program2.command("contract <feature>").description("Scaffold api-contract.md (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.contract, label: "contract" }));
 program2.command("tasks <feature>").description("Scaffold tasks.md WBS (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.tasks, label: "tasks" }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rijalpermana/spec-forge",
-  "version": "0.1.0",
+  "version": "0.1.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

@@ -0,0 +1,71 @@
+# Project Rules & Conventions
+
+> Read by the AI before drafting any spec (schema, contract, tasks, testcases)
+> through `forge`. Rules here **override** forge's built-in defaults. Fill every
+> `[TODO]`, delete sections that don't apply, and keep entries factual and
+> enforceable — the AI follows this literally.
+
+## Tech stack
+
+- Language / runtime: [TODO]
+- Framework: [TODO]
+- Database / ORM: [TODO]
+- Other key libraries: [TODO]
+
+## Naming conventions
+
+- Folders & files: [TODO — e.g. kebab-case]
+- Classes / types: [TODO — e.g. PascalCase]
+- Variables & functions: [TODO — e.g. camelCase]
+- Database columns: [TODO — e.g. snake_case]
+- API endpoints / paths: [TODO — e.g. kebab-case, `/v1/...`]
+- Forbidden: [TODO — e.g. no underscores in file/folder names]
+
+## Project & module structure
+
+[TODO — describe the folder layout a new feature/module must follow, e.g.
+`dto/`, `entities/`, `*.controller.ts`, `*.service.ts`, `*.repository.ts`,
+`*.module.ts`. The AI should scaffold new work to match this.]
+
+## API design
+
+- Versioning: [TODO — e.g. URI versioning `/v1/`, `/v2/`]
+- Auth: [TODO — e.g. global guard, how to opt an endpoint out]
+- Response envelope: [TODO — paste the exact success shape the API returns]
+- Error shape & status: [TODO — how errors are formatted and what HTTP status is used]
+- Pagination: [TODO — shape of paginated responses]
+
+## Data & schema
+
+- Audit/base fields every entity carries: [TODO — e.g. created_by, created_date, ...]
+- Multi-tenancy / scoping: [TODO — or "n/a"]
+- Type conventions: [TODO]
+
+## Validation
+
+[TODO — e.g. all inputs validated with a schema/validator; every field documented with an example]
+
+## Security
+
+[TODO — e.g. secrets from env only; encryption standard; required headers; rate limiting]
+
+## Testing
+
+- Framework: [TODO]
+- Coverage threshold: [TODO — e.g. 80% branches/functions/lines/statements, build fails below]
+- Test file convention: [TODO — e.g. `*.spec.ts` beside the file under test]
+- Minimum per unit: [TODO — e.g. 1 success case + 1 error case]
+
+## Documentation
+
+[TODO — e.g. OpenAPI/Swagger required; every endpoint and DTO documented with examples]
+
+## Tooling
+
+- Lint: [TODO]
+- Format: [TODO]
+- Pre-commit checks: [TODO]
+
+## Out of bounds
+
+[TODO — anything the AI must never do in this codebase]