@rijalpermana/spec-forge 0.1.0 → 0.1.1

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 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."
   },
   {
     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 |
 ` + `| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
@@ -7525,12 +7534,30 @@ 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.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("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").action(smelt);
 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" }));

package/package.json

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