@ruchit07/ai-spec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruchit Suthar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# ai-spec
+
+> Scaffold a production-grade AI feature spec **before** you write a line of code.
+
+Most AI features are vibe-coded: call the LLM, the output looks reasonable, ship. Then three weeks later a prompt change silently breaks 20% of queries — and nobody knows, because "looks reasonable" was never a measurable criterion.
+
+`ai-spec` fixes the root cause. One command generates the spec, the eval criteria, a seed set of golden test cases, and an ADR starter — so "done" has a precise definition before you start.
+
+**By [Ruchit Suthar](https://ruchitsuthar.com)** — Software Architect & Technical Leader.
+📖 Method: [AI-Driven Development: The Spec-First Workflow](https://ruchitsuthar.com/blog/developer-productivity/ai-driven-development-spec-first-workflow/)
+
+---
+
+## Quick start
+
+```bash
+npx @ruchit07/ai-spec init "semantic search for support tickets"
+```
+
+That's it. You'll be prompted for the feature kind, problem statement, latency/cost budgets, and owner — then it writes:
+
+```
+specs/
+└── semantic-search-for-support-tickets/
+    ├── spec.md              # Problem, I/O contract, acceptance criteria, failure modes
+    ├── eval-criteria.md     # The metrics that gate CI, with threshold rationale
+    ├── eval-criteria.json   # Machine-readable thresholds for your CI
+    ├── test-cases.json      # Seed golden test cases tailored to the feature kind
+    └── adr.md               # Architecture Decision Record starter
+```
+
+### Non-interactive (for scripts / CI)
+
+```bash
+ai-spec init "ticket classifier" --kind classification --yes
+ai-spec init "support agent" -k agent -d ./ai-features --force
+```
+
+---
+
+## Why this matters
+
+| Without a spec | With ai-spec |
+|----------------|--------------|
+| "Looks good" is the bar | Measurable thresholds (accuracy ≥ 0.8, latency p95 ≤ 2000ms) |
+| Regressions found by users | Regressions caught in CI |
+| Prompt is the only documentation | Spec + ADR explain intent and decisions |
+| No baseline when you switch models | Golden test set is the baseline |
+
+The discipline is the value. `ai-spec` makes the disciplined path the easy path.
+
+---
+
+## Feature kinds
+
+The seed test cases and spec guidance adapt to what you're building:
+
+| Kind | Tailored guidance |
+|------|-------------------|
+| `rag` | Retrieval quality + groundedness as the dominant metric |
+| `chat` | Conversation scope, tools, context-window budget |
+| `classification` | Exact label set, out-of-distribution handling |
+| `extraction` | Typed output schema, field-level accuracy |
+| `agent` | Action space, stopping conditions, safety guardrails |
+
+---
+
+## Programmatic API
+
+```typescript
+import { generateFiles, slugify } from '@ruchit07/ai-spec';
+
+const files = generateFiles({
+  featureName: 'My Feature',
+  slug: slugify('My Feature'),
+  kind: 'rag',
+  problem: '...',
+  primaryProvider: 'openai',
+  latencyP95Ms: 2000,
+  costPerQueryUsd: 0.005,
+  accuracyThreshold: 0.8,
+  groundednessThreshold: 0.85,
+  owner: '@you',
+});
+// files: { path, content }[]
+```
+
+---
+
+## Pairs with
+
+- **[ai-native-app-blueprint](https://github.com/ruchit07/ai-native-app-blueprint)** — the production reference these specs target. Its `packages/evals` runs the `test-cases.json` this tool generates.
+- **[The Spec-First Workflow](https://ruchitsuthar.com/blog/developer-productivity/ai-driven-development-spec-first-workflow/)** — the full method.
+
+---
+
+## License
+
+MIT

package/dist/__tests__/generator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generator.test.d.ts.map

package/dist/__tests__/generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/generator.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/generator.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { generateFiles } from '../lib/generator.js';
+import { slugify, titleize } from '../lib/slug.js';
+const answers = {
+    featureName: 'Semantic Search for Support Tickets',
+    slug: 'semantic-search-for-support-tickets',
+    kind: 'rag',
+    problem: 'Support agents waste time searching old tickets.',
+    primaryProvider: 'openai',
+    latencyP95Ms: 2000,
+    costPerQueryUsd: 0.005,
+    accuracyThreshold: 0.8,
+    groundednessThreshold: 0.85,
+    owner: '@ruchit07',
+};
+describe('slugify', () => {
+    it('converts a feature name to a slug', () => {
+        expect(slugify('Semantic Search for Support Tickets')).toBe('semantic-search-for-support-tickets');
+    });
+    it('strips punctuation and collapses spaces', () => {
+        expect(slugify('  RAG: the New!! Checklist  ')).toBe('rag-the-new-checklist');
+    });
+    it('handles already-slugged input', () => {
+        expect(slugify('already-a-slug')).toBe('already-a-slug');
+    });
+});
+describe('titleize', () => {
+    it('title-cases a slug', () => {
+        expect(titleize('semantic-search')).toBe('Semantic Search');
+    });
+});
+describe('generateFiles', () => {
+    it('generates exactly five files', () => {
+        const files = generateFiles(answers);
+        expect(files).toHaveLength(5);
+        const paths = files.map((f) => f.path).sort();
+        expect(paths).toEqual(['adr.md', 'eval-criteria.json', 'eval-criteria.md', 'spec.md', 'test-cases.json']);
+    });
+    it('embeds the thresholds into spec.md', () => {
+        const spec = generateFiles(answers).find((f) => f.path === 'spec.md');
+        expect(spec?.content).toContain('2000ms');
+        expect(spec?.content).toContain('$0.005');
+        expect(spec?.content).toContain('0.8');
+    });
+    it('produces valid JSON for eval-criteria.json', () => {
+        const json = generateFiles(answers).find((f) => f.path === 'eval-criteria.json');
+        const parsed = JSON.parse(json.content);
+        expect(parsed.thresholds.accuracy).toBe(0.8);
+    });
+    it('produces valid JSON test cases for the chosen kind', () => {
+        const json = generateFiles(answers).find((f) => f.path === 'test-cases.json');
+        const parsed = JSON.parse(json.content);
+        expect(parsed.length).toBeGreaterThan(0);
+        expect(parsed[0]?.id).toContain('tc-');
+    });
+    it('generates different test cases for classification kind', () => {
+        const classificationAnswers = { ...answers, kind: 'classification' };
+        const json = generateFiles(classificationAnswers).find((f) => f.path === 'test-cases.json');
+        const parsed = JSON.parse(json.content);
+        expect(parsed.some((tc) => tc.expected.answer === 'positive')).toBe(true);
+    });
+    it('includes the feature name in the spec heading', () => {
+        const spec = generateFiles(answers).find((f) => f.path === 'spec.md');
+        expect(spec?.content).toContain('Semantic Search For Support Tickets');
+    });
+});
+//# sourceMappingURL=generator.test.js.map

package/dist/__tests__/generator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.test.js","sourceRoot":"","sources":["../../src/__tests__/generator.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGnD,MAAM,OAAO,GAAgB;IAC3B,WAAW,EAAE,qCAAqC;IAClD,IAAI,EAAE,qCAAqC;IAC3C,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,kDAAkD;IAC3D,eAAe,EAAE,QAAQ;IACzB,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,GAAG;IACtB,qBAAqB,EAAE,IAAI;IAC3B,KAAK,EAAE,WAAW;CACnB,CAAC;AAEF,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IACrG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC5G,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;QACtE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAK,CAAC,OAAO,CAAyC,CAAC;QACjF,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAK,CAAC,OAAO,CAA0B,CAAC;QAClE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,qBAAqB,GAAG,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,gBAAyB,EAAE,CAAC;QAC9E,MAAM,IAAI,GAAG,aAAa,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC;QAC5F,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAK,CAAC,OAAO,CAA6C,CAAC;QACrF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;QACtE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,qCAAqC,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/writer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=writer.test.d.ts.map

package/dist/__tests__/writer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/writer.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/writer.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFiles } from '../lib/writer.js';
+const testBase = join(tmpdir(), 'ai-spec-test');
+const files = [
+    { path: 'spec.md', content: '# Spec' },
+    { path: 'test-cases.json', content: '[]' },
+];
+afterEach(() => {
+    rmSync(testBase, { recursive: true, force: true });
+});
+describe('writeFiles', () => {
+    it('writes all files into baseDir/slug/', () => {
+        const result = writeFiles(testBase, 'my-feature', files);
+        expect(result.written).toHaveLength(2);
+        expect(existsSync(join(testBase, 'my-feature', 'spec.md'))).toBe(true);
+        expect(readFileSync(join(testBase, 'my-feature', 'spec.md'), 'utf8')).toBe('# Spec');
+    });
+    it('skips existing files without force', () => {
+        writeFiles(testBase, 'my-feature', files);
+        const result = writeFiles(testBase, 'my-feature', files);
+        expect(result.written).toHaveLength(0);
+        expect(result.skipped).toHaveLength(2);
+    });
+    it('overwrites existing files with force', () => {
+        writeFiles(testBase, 'my-feature', files);
+        const result = writeFiles(testBase, 'my-feature', files, true);
+        expect(result.written).toHaveLength(2);
+        expect(result.skipped).toHaveLength(0);
+    });
+});
+//# sourceMappingURL=writer.test.js.map

package/dist/__tests__/writer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.test.js","sourceRoot":"","sources":["../../src/__tests__/writer.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC;AAEhD,MAAM,KAAK,GAAoB;IAC7B,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE;IACtC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE;CAC3C,CAAC;AAEF,SAAS,CAAC,GAAG,EAAE;IACb,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC/D,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { runInit } from './commands/init.js';
+const program = new Command();
+program
+    .name('ai-spec')
+    .description('Scaffold a production-grade AI feature spec before you write a line of code')
+    .version('1.0.0');
+program
+    .command('init')
+    .argument('[name]', 'feature name, e.g. "semantic search for support tickets"')
+    .description('Create a new AI feature spec (spec, eval criteria, golden test cases, ADR)')
+    .option('-d, --dir <dir>', 'output directory', 'specs')
+    .option('-k, --kind <kind>', 'feature kind: rag | chat | classification | extraction | agent')
+    .option('-y, --yes', 'skip prompts and use sensible defaults')
+    .option('-f, --force', 'overwrite existing files')
+    .action(async (name, opts) => {
+    const code = await runInit({
+        name,
+        dir: opts.dir,
+        kind: opts.kind,
+        yes: opts.yes,
+        force: opts.force,
+    });
+    process.exit(code);
+});
+program.addHelpText('after', `
+${pc.bold('Examples:')}
+  $ ${pc.cyan('npx @ruchit07/ai-spec init "semantic search for support tickets"')}
+  $ ${pc.cyan('ai-spec init "ticket classifier" --kind classification --yes')}
+  $ ${pc.cyan('ai-spec init "support agent" -k agent -d ./ai-features')}
+
+${pc.dim('Method: https://ruchitsuthar.com/blog/developer-productivity/ai-driven-development-spec-first-workflow/')}
+`);
+program.parseAsync(process.argv);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,6EAA6E,CAAC;KAC1F,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,QAAQ,CAAC,QAAQ,EAAE,0DAA0D,CAAC;KAC9E,WAAW,CAAC,4EAA4E,CAAC;KACzF,MAAM,CAAC,iBAAiB,EAAE,kBAAkB,EAAE,OAAO,CAAC;KACtD,MAAM,CAAC,mBAAmB,EAAE,gEAAgE,CAAC;KAC7F,MAAM,CAAC,WAAW,EAAE,wCAAwC,CAAC;KAC7D,MAAM,CAAC,aAAa,EAAE,0BAA0B,CAAC;KACjD,MAAM,CAAC,KAAK,EAAE,IAAwB,EAAE,IAAoE,EAAE,EAAE;IAC/G,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;QACzB,IAAI;QACJ,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAA+B;QAC1C,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,WAAW,CACjB,OAAO,EACP;EACA,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC;MAChB,EAAE,CAAC,IAAI,CAAC,kEAAkE,CAAC;MAC3E,EAAE,CAAC,IAAI,CAAC,8DAA8D,CAAC;MACvE,EAAE,CAAC,IAAI,CAAC,wDAAwD,CAAC;;EAErE,EAAE,CAAC,GAAG,CAAC,yGAAyG,CAAC;CAClH,CACA,CAAC;AAEF,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,10 @@
+import { type FeatureKind } from '../lib/types.js';
+export interface InitOptions {
+    name?: string | undefined;
+    dir?: string | undefined;
+    kind?: FeatureKind | undefined;
+    yes?: boolean | undefined;
+    force?: boolean | undefined;
+}
+export declare function runInit(options: InitOptions): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEpF,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAWD,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA6GnE"}

package/dist/commands/init.js

@@ -0,0 +1,141 @@
+import prompts from 'prompts';
+import pc from 'picocolors';
+import { slugify, titleize } from '../lib/slug.js';
+import { generateFiles } from '../lib/generator.js';
+import { writeFiles } from '../lib/writer.js';
+import { FEATURE_KINDS } from '../lib/types.js';
+const DEFAULTS = {
+    latencyP95Ms: 2000,
+    costPerQueryUsd: 0.005,
+    accuracyThreshold: 0.8,
+    groundednessThreshold: 0.85,
+    primaryProvider: 'openai',
+    owner: '@you',
+};
+export async function runInit(options) {
+    let featureName = options.name?.trim() ?? '';
+    let kind = options.kind;
+    // Non-interactive mode (--yes) requires a name
+    if (options.yes) {
+        if (!featureName) {
+            console.error(pc.red('Error: --yes requires a feature name. Usage: ai-spec init "name" --yes'));
+            return 1;
+        }
+        kind = kind ?? 'rag';
+    }
+    else {
+        // Interactive prompts
+        const responses = await prompts([
+            {
+                type: featureName ? null : 'text',
+                name: 'featureName',
+                message: 'Feature name',
+                validate: (v) => (v.trim().length > 0 ? true : 'Required'),
+            },
+            {
+                type: kind ? null : 'select',
+                name: 'kind',
+                message: 'What kind of AI feature?',
+                choices: FEATURE_KINDS.map((k) => ({ title: `${k.title} — ${k.description}`, value: k.value })),
+                initial: 0,
+            },
+            {
+                type: 'text',
+                name: 'problem',
+                message: 'Problem statement (one sentence — what user problem does this solve?)',
+                validate: (v) => (v.trim().length > 0 ? true : 'Required'),
+            },
+            {
+                type: 'select',
+                name: 'primaryProvider',
+                message: 'Primary LLM provider',
+                choices: [
+                    { title: 'OpenAI', value: 'openai' },
+                    { title: 'Anthropic', value: 'anthropic' },
+                    { title: 'Other', value: 'other' },
+                ],
+                initial: 0,
+            },
+            {
+                type: 'number',
+                name: 'latencyP95Ms',
+                message: 'Max latency p95 (ms)',
+                initial: DEFAULTS.latencyP95Ms,
+            },
+            {
+                type: 'number',
+                name: 'costPerQueryUsd',
+                message: 'Max cost per query (USD, e.g. 0.005)',
+                initial: DEFAULTS.costPerQueryUsd,
+                float: true,
+            },
+            {
+                type: 'text',
+                name: 'owner',
+                message: 'Owner (your handle)',
+                initial: DEFAULTS.owner,
+            },
+        ], {
+            onCancel: () => {
+                console.log(pc.yellow('\nCancelled.'));
+                process.exit(130);
+            },
+        });
+        featureName = featureName || responses.featureName;
+        kind = kind ?? responses.kind;
+        const slug = slugify(featureName);
+        const answers = {
+            featureName,
+            slug,
+            kind: kind ?? 'rag',
+            problem: responses.problem,
+            primaryProvider: responses.primaryProvider ?? DEFAULTS.primaryProvider,
+            latencyP95Ms: responses.latencyP95Ms ?? DEFAULTS.latencyP95Ms,
+            costPerQueryUsd: responses.costPerQueryUsd ?? DEFAULTS.costPerQueryUsd,
+            accuracyThreshold: DEFAULTS.accuracyThreshold,
+            groundednessThreshold: DEFAULTS.groundednessThreshold,
+            owner: responses.owner ?? DEFAULTS.owner,
+        };
+        return write(answers, options);
+    }
+    // Non-interactive path
+    const slug = slugify(featureName);
+    const answers = {
+        featureName,
+        slug,
+        kind: kind ?? 'rag',
+        problem: `TODO: describe the user problem that "${titleize(featureName)}" solves.`,
+        primaryProvider: DEFAULTS.primaryProvider,
+        latencyP95Ms: DEFAULTS.latencyP95Ms,
+        costPerQueryUsd: DEFAULTS.costPerQueryUsd,
+        accuracyThreshold: DEFAULTS.accuracyThreshold,
+        groundednessThreshold: DEFAULTS.groundednessThreshold,
+        owner: DEFAULTS.owner,
+    };
+    return write(answers, options);
+}
+function write(answers, options) {
+    const baseDir = options.dir ?? 'specs';
+    const files = generateFiles(answers);
+    const result = writeFiles(baseDir, answers.slug, files, options.force ?? false);
+    console.log('');
+    console.log(pc.green(pc.bold(`✓ Spec scaffolded: ${baseDir}/${answers.slug}/`)));
+    console.log('');
+    for (const path of result.written) {
+        console.log(`  ${pc.green('created')}  ${path}`);
+    }
+    for (const path of result.skipped) {
+        console.log(`  ${pc.yellow('skipped')}  ${path} ${pc.dim('(exists — use --force to overwrite)')}`);
+    }
+    console.log('');
+    console.log(pc.bold('Next steps:'));
+    console.log(`  1. Fill in ${pc.cyan(`${baseDir}/${answers.slug}/spec.md`)} — input/output contract, acceptance criteria`);
+    console.log(`  2. Replace the seed cases in ${pc.cyan('test-cases.json')} with real user questions`);
+    console.log(`  3. Write the decision in ${pc.cyan('adr.md')} once you've chosen an approach`);
+    console.log(`  4. Wire ${pc.cyan('eval-criteria.json')} into CI`);
+    console.log('');
+    console.log(pc.dim('Method: https://ruchitsuthar.com/blog/developer-productivity/ai-driven-development-spec-first-workflow/'));
+    console.log('');
+    return result.skipped.length > 0 && !options.force ? 0 : 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { generateFiles } from './lib/generator.js';
+export { writeFiles } from './lib/writer.js';
+export { slugify, titleize } from './lib/slug.js';
+export { FEATURE_KINDS } from './lib/types.js';
+export type { SpecAnswers, GeneratedFile, TestCase, FeatureKind, } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EACV,WAAW,EACX,aAAa,EACb,QAAQ,EACR,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// Programmatic API — for using ai-spec inside other tools
+export { generateFiles } from './lib/generator.js';
+export { writeFiles } from './lib/writer.js';
+export { slugify, titleize } from './lib/slug.js';
+export { FEATURE_KINDS } from './lib/types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/lib/generator.d.ts

@@ -0,0 +1,7 @@
+import type { SpecAnswers, GeneratedFile } from './types.js';
+/**
+ * Pure function: given the answers, produce the list of files to write.
+ * Kept pure (no fs) so it's trivial to unit test.
+ */
+export declare function generateFiles(answers: SpecAnswers): GeneratedFile[];
+//# sourceMappingURL=generator.d.ts.map

package/dist/lib/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/lib/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM7D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,aAAa,EAAE,CAQnE"}

package/dist/lib/generator.js

@@ -0,0 +1,18 @@
+import { renderSpec } from '../templates/spec.js';
+import { renderEvalCriteria, renderEvalCriteriaJson } from '../templates/eval-criteria.js';
+import { renderTestCases } from '../templates/test-cases.js';
+import { renderAdr } from '../templates/adr.js';
+/**
+ * Pure function: given the answers, produce the list of files to write.
+ * Kept pure (no fs) so it's trivial to unit test.
+ */
+export function generateFiles(answers) {
+    return [
+        { path: 'spec.md', content: renderSpec(answers) },
+        { path: 'eval-criteria.md', content: renderEvalCriteria(answers) },
+        { path: 'eval-criteria.json', content: renderEvalCriteriaJson(answers) },
+        { path: 'test-cases.json', content: renderTestCases(answers) },
+        { path: 'adr.md', content: renderAdr(answers) },
+    ];
+}
+//# sourceMappingURL=generator.js.map

package/dist/lib/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../src/lib/generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAoB;IAChD,OAAO;QACL,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE;QACjD,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAClE,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,sBAAsB,CAAC,OAAO,CAAC,EAAE;QACxE,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE;QAC9D,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE;KAChD,CAAC;AACJ,CAAC"}

package/dist/lib/slug.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts a free-text feature name into a filesystem-safe slug.
+ * "Semantic Search for Support Tickets" → "semantic-search-for-support-tickets"
+ */
+export declare function slugify(input: string): string;
+/**
+ * Title-cases a slug for use in headings.
+ * "semantic-search" → "Semantic Search"
+ */
+export declare function titleize(input: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/lib/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../src/lib/slug.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM9C"}

package/dist/lib/slug.js

@@ -0,0 +1,25 @@
+/**
+ * Converts a free-text feature name into a filesystem-safe slug.
+ * "Semantic Search for Support Tickets" → "semantic-search-for-support-tickets"
+ */
+export function slugify(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s-]/g, '') // drop punctuation
+        .replace(/\s+/g, '-') // spaces → hyphens
+        .replace(/-+/g, '-') // collapse repeats
+        .replace(/^-|-$/g, ''); // trim edge hyphens
+}
+/**
+ * Title-cases a slug for use in headings.
+ * "semantic-search" → "Semantic Search"
+ */
+export function titleize(input) {
+    return input
+        .split(/[-\s]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+//# sourceMappingURL=slug.js.map

package/dist/lib/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../../src/lib/slug.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,IAAI,EAAE;SACN,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAG,mBAAmB;SAClD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW,mBAAmB;SAClD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAY,mBAAmB;SAClD,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAS,oBAAoB;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,KAAK;SACT,KAAK,CAAC,QAAQ,CAAC;SACf,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,35 @@
+export type FeatureKind = 'rag' | 'chat' | 'classification' | 'extraction' | 'agent';
+export interface SpecAnswers {
+    featureName: string;
+    slug: string;
+    kind: FeatureKind;
+    problem: string;
+    primaryProvider: 'openai' | 'anthropic' | 'other';
+    latencyP95Ms: number;
+    costPerQueryUsd: number;
+    accuracyThreshold: number;
+    groundednessThreshold: number;
+    owner: string;
+}
+export interface GeneratedFile {
+    path: string;
+    content: string;
+}
+export interface TestCase {
+    id: string;
+    input: {
+        question: string;
+        context?: string;
+    };
+    expected: {
+        answer?: string;
+        mustContain?: string[];
+        mustNotContain?: string[];
+    };
+}
+export declare const FEATURE_KINDS: Array<{
+    value: FeatureKind;
+    title: string;
+    description: string;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,gBAAgB,GAAG,YAAY,GAAG,OAAO,CAAC;AAErF,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;CACH;AAED,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAM3F,CAAC"}

package/dist/lib/types.js

@@ -0,0 +1,8 @@
+export const FEATURE_KINDS = [
+    { value: 'rag', title: 'RAG / Q&A', description: 'Answer questions from a knowledge base' },
+    { value: 'chat', title: 'Chat / Assistant', description: 'Conversational assistant, possibly with tools' },
+    { value: 'classification', title: 'Classification', description: 'Categorise input into known labels' },
+    { value: 'extraction', title: 'Extraction', description: 'Pull structured data from unstructured text' },
+    { value: 'agent', title: 'Agent', description: 'Multi-step autonomous task execution' },
+];
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAiCA,MAAM,CAAC,MAAM,aAAa,GAAsE;IAC9F,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,wCAAwC,EAAE;IAC3F,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,+CAA+C,EAAE;IAC1G,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,oCAAoC,EAAE;IACvG,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,6CAA6C,EAAE;IACxG,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,sCAAsC,EAAE;CACxF,CAAC"}

package/dist/lib/writer.d.ts

@@ -0,0 +1,11 @@
+import type { GeneratedFile } from './types.js';
+export interface WriteResult {
+    written: string[];
+    skipped: string[];
+}
+/**
+ * Writes generated files into <baseDir>/<slug>/.
+ * Refuses to overwrite existing files unless `force` is set.
+ */
+export declare function writeFiles(baseDir: string, slug: string, files: GeneratedFile[], force?: boolean): WriteResult;
+//# sourceMappingURL=writer.d.ts.map

package/dist/lib/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/lib/writer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,UAAQ,GACZ,WAAW,CAiBb"}

package/dist/lib/writer.js

@@ -0,0 +1,23 @@
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+/**
+ * Writes generated files into <baseDir>/<slug>/.
+ * Refuses to overwrite existing files unless `force` is set.
+ */
+export function writeFiles(baseDir, slug, files, force = false) {
+    const targetDir = join(baseDir, slug);
+    const written = [];
+    const skipped = [];
+    for (const file of files) {
+        const fullPath = join(targetDir, file.path);
+        if (existsSync(fullPath) && !force) {
+            skipped.push(fullPath);
+            continue;
+        }
+        mkdirSync(dirname(fullPath), { recursive: true });
+        writeFileSync(fullPath, file.content, 'utf8');
+        written.push(fullPath);
+    }
+    return { written, skipped };
+}
+//# sourceMappingURL=writer.js.map

package/dist/lib/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/lib/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQ1C;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,IAAY,EACZ,KAAsB,EACtB,KAAK,GAAG,KAAK;IAEb,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,SAAS;QACX,CAAC;QACD,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/templates/adr.d.ts

@@ -0,0 +1,3 @@
+import type { SpecAnswers } from '../lib/types.js';
+export declare function renderAdr(a: SpecAnswers): string;
+//# sourceMappingURL=adr.d.ts.map

package/dist/templates/adr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.d.ts","sourceRoot":"","sources":["../../src/templates/adr.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,wBAAgB,SAAS,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAmDhD"}

package/dist/templates/adr.js

@@ -0,0 +1,54 @@
+import { titleize } from '../lib/slug.js';
+export function renderAdr(a) {
+    const date = new Date().toISOString().split('T')[0];
+    return `# ADR-0001: ${titleize(a.featureName)} — Architecture
+
+**Status:** Proposed
+**Date:** ${date}
+**Deciders:** ${a.owner}
+
+---
+
+## Context
+
+_What is the situation that forces a decision? What constraints apply (team size, latency budget, data residency, existing systems)?_
+
+This feature is a **${a.kind}** capability. Key constraints from the spec:
+- Latency p95 ≤ ${a.latencyP95Ms}ms
+- Cost per query ≤ $${a.costPerQueryUsd}
+- Primary provider: ${a.primaryProvider}
+
+## Decision
+
+_What did you decide, stated plainly? (e.g. "Use pgvector, not Pinecone." "Use a modular monolith, not microservices.")_
+
+TODO.
+
+## Consequences
+
+**Good:**
+- _(what this buys you)_
+
+**Bad:**
+- _(what you give up — every decision has a cost; name it)_
+
+## Rejected alternatives
+
+_For each alternative you seriously considered, say what it was and why you rejected it. This is the most valuable section — it shows the decision was reasoned, not defaulted._
+
+**Alternative A:** _(what it was)_ — Rejected because _(reason)_.
+
+**Alternative B:** _(what it was)_ — Rejected because _(reason)_.
+
+## When to revisit
+
+_Under what conditions does this decision stop being correct? (e.g. "Revisit when we exceed 5M vectors" or "when the team grows past 20 engineers.")_
+
+TODO.
+
+---
+
+_ADR format from [ai-native-app-blueprint](https://github.com/ruchit07/ai-native-app-blueprint/tree/main/adr). Why ADRs: [Architecture Decision Records People Actually Maintain](https://ruchitsuthar.com/blog/software-architecture/architecture-decision-records-people-maintain/)._
+`;
+}
+//# sourceMappingURL=adr.js.map

package/dist/templates/adr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.js","sourceRoot":"","sources":["../../src/templates/adr.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,UAAU,SAAS,CAAC,CAAc;IACtC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,eAAe,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;;;YAGnC,IAAI;gBACA,CAAC,CAAC,KAAK;;;;;;;;sBAQD,CAAC,CAAC,IAAI;kBACV,CAAC,CAAC,YAAY;sBACV,CAAC,CAAC,eAAe;sBACjB,CAAC,CAAC,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCtC,CAAC;AACF,CAAC"}

package/dist/templates/eval-criteria.d.ts

@@ -0,0 +1,4 @@
+import type { SpecAnswers } from '../lib/types.js';
+export declare function renderEvalCriteria(a: SpecAnswers): string;
+export declare function renderEvalCriteriaJson(a: SpecAnswers): string;
+//# sourceMappingURL=eval-criteria.d.ts.map

package/dist/templates/eval-criteria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-criteria.d.ts","sourceRoot":"","sources":["../../src/templates/eval-criteria.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAoDzD;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAe7D"}

package/dist/templates/eval-criteria.js

@@ -0,0 +1,67 @@
+import { titleize } from '../lib/slug.js';
+export function renderEvalCriteria(a) {
+    return `# Eval Criteria — ${titleize(a.featureName)}
+
+_The machine-readable contract. These thresholds gate CI. A PR that drops below any threshold fails the build._
+
+---
+
+## Metrics & thresholds
+
+| Metric | What it measures | Threshold | Fails CI? |
+|--------|------------------|-----------|-----------|
+| **accuracy** | Token F1 overlap vs golden answers (SQuAD metric) | ≥ ${a.accuracyThreshold} | Yes |
+| **groundedness** | Fraction of answer sentences supported by retrieved context | ≥ ${a.groundednessThreshold} | Yes |
+| **latency_p95** | 95th percentile end-to-end latency | ≤ ${a.latencyP95Ms}ms | Yes |
+| **cost_per_query** | Average LLM cost per query | ≤ $${a.costPerQueryUsd} | Yes |
+| **faithfulness** | Answer does not contradict context | ≥ ${a.groundednessThreshold} | Warn |
+
+---
+
+## Two-tier eval strategy
+
+**Tier 1 — every PR (fast, free):**
+Heuristic evaluators (no LLM calls). Token-overlap accuracy, sentence-overlap groundedness, latency, cost. Runs in < 30s. $0.
+
+**Tier 2 — weekly + before releases (comprehensive):**
+LLM-as-judge on a larger test set. Catches subtle hallucinations the heuristics miss. ~$2–5/run.
+
+> Why two tiers? You want evals on every PR (so cheap they're free), but you also want the depth of an LLM judge (too expensive for every PR). See [ADR: eval strategy](https://github.com/ruchit07/ai-native-app-blueprint/blob/main/adr/0004-eval-strategy.md).
+
+---
+
+## Running the evals
+
+\`\`\`bash
+# Tier 1 — heuristic, runs in CI
+npx ai-evals run ./test-cases.json --thresholds ./eval-criteria.json
+
+# Tier 2 — LLM judge (set EVAL_LLM_JUDGE=true)
+EVAL_LLM_JUDGE=true npx ai-evals run ./test-cases.json
+\`\`\`
+
+---
+
+## Threshold rationale
+
+_Document WHY each threshold is set where it is. "We picked 0.85" is not a rationale; "0.85 because below that users start re-asking the question, per our March user test" is._
+
+- **accuracy ≥ ${a.accuracyThreshold}:** _(rationale)_
+- **groundedness ≥ ${a.groundednessThreshold}:** _(rationale)_
+- **latency p95 ≤ ${a.latencyP95Ms}ms:** _(rationale — e.g. streaming UX feels broken above this)_
+- **cost ≤ $${a.costPerQueryUsd}:** _(rationale — e.g. unit economics at projected volume)_
+`;
+}
+export function renderEvalCriteriaJson(a) {
+    return JSON.stringify({
+        suite: a.slug,
+        thresholds: {
+            accuracy: a.accuracyThreshold,
+            groundedness: a.groundednessThreshold,
+            latencyP95Ms: a.latencyP95Ms,
+            costPerQueryUsd: a.costPerQueryUsd,
+        },
+        failOnRegression: true,
+    }, null, 2);
+}
+//# sourceMappingURL=eval-criteria.js.map

package/dist/templates/eval-criteria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-criteria.js","sourceRoot":"","sources":["../../src/templates/eval-criteria.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,UAAU,kBAAkB,CAAC,CAAc;IAC/C,OAAO,qBAAqB,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;;;;;;;;;;yEAUoB,CAAC,CAAC,iBAAiB;uFACL,CAAC,CAAC,qBAAqB;6DACjD,CAAC,CAAC,YAAY;yDAClB,CAAC,CAAC,eAAe;8DACZ,CAAC,CAAC,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCpE,CAAC,CAAC,iBAAiB;qBACf,CAAC,CAAC,qBAAqB;oBACxB,CAAC,CAAC,YAAY;cACpB,CAAC,CAAC,eAAe;CAC9B,CAAC;AACF,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,CAAc;IACnD,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,KAAK,EAAE,CAAC,CAAC,IAAI;QACb,UAAU,EAAE;YACV,QAAQ,EAAE,CAAC,CAAC,iBAAiB;YAC7B,YAAY,EAAE,CAAC,CAAC,qBAAqB;YACrC,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,eAAe,EAAE,CAAC,CAAC,eAAe;SACnC;QACD,gBAAgB,EAAE,IAAI;KACvB,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/templates/spec.d.ts

@@ -0,0 +1,3 @@
+import type { SpecAnswers } from '../lib/types.js';
+export declare function renderSpec(a: SpecAnswers): string;
+//# sourceMappingURL=spec.d.ts.map

package/dist/templates/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/templates/spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAWnD,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAmFjD"}

package/dist/templates/spec.js

@@ -0,0 +1,93 @@
+import { titleize } from '../lib/slug.js';
+const KIND_GUIDANCE = {
+    rag: 'Retrieval quality is the dominant variable. Specify your chunking, retrieval, and reranking strategy. Groundedness is the metric that matters most — a fluent but ungrounded answer is the failure mode to design against.',
+    chat: 'Define the conversation scope and the tools (if any) the assistant can call. Multi-turn context handling and instruction-following are the hard parts. Decide your context window budget per turn.',
+    classification: 'Define the exact label set. Accuracy and per-class precision/recall are the metrics. Decide what happens for out-of-distribution inputs (a "none of the above" class is usually necessary).',
+    extraction: 'Define the exact output schema (typed). Structured output mode or function calling is strongly recommended. Field-level accuracy matters more than overall — one wrong field can break a downstream system.',
+    agent: 'Define the action space and the stopping conditions. The risk is unbounded loops and unsafe actions. Specify guardrails, a max-step budget, and which actions require human approval.',
+};
+export function renderSpec(a) {
+    const date = new Date().toISOString().split('T')[0];
+    return `# AI Feature Spec — ${titleize(a.featureName)}
+
+_Created: ${date} | Owner: ${a.owner} | Kind: ${a.kind}_
+
+---
+
+## Problem statement
+
+${a.problem}
+
+> **What happens today without this feature?** _(Fill in: the manual process, the workaround, or the gap this closes.)_
+
+---
+
+## Input / output contract
+
+**Input:**
+\`\`\`typescript
+interface FeatureInput {
+  // TODO: define exact types
+  query: string;
+}
+\`\`\`
+
+**Output:**
+\`\`\`typescript
+interface FeatureOutput {
+  // TODO: define exact types
+  answer: string;
+  sources?: { title: string; url: string }[];
+}
+\`\`\`
+
+**Constraints:**
+- Maximum latency (p95): **${a.latencyP95Ms}ms**
+- Maximum cost per query: **$${a.costPerQueryUsd}**
+- Primary provider: **${a.primaryProvider}**
+
+---
+
+## Acceptance criteria
+
+_Measurable. Not "the response should be good." Each criterion maps to an eval metric in \`eval-criteria.md\`._
+
+| # | Criterion | Measurement | Threshold |
+|---|-----------|-------------|-----------|
+| 1 | Correct on golden test set | Accuracy (F1 token overlap) | ≥ ${a.accuracyThreshold} |
+| 2 | Grounded in provided context | Groundedness score | ≥ ${a.groundednessThreshold} |
+| 3 | Fast enough for the UX | Latency p95 | ≤ ${a.latencyP95Ms}ms |
+| 4 | Affordable at scale | Cost per query | ≤ $${a.costPerQueryUsd} |
+
+---
+
+## Kind-specific guidance (${a.kind})
+
+${KIND_GUIDANCE[a.kind]}
+
+---
+
+## Known failure modes (out of scope for v1)
+
+_Explicitly mark what you've decided NOT to handle. This prevents scope creep._
+
+- [ ] Adversarial prompt injection in user input
+- [ ] Inputs in languages other than English
+- [ ] _(add the ones specific to this feature)_
+
+---
+
+## Sign-off checklist
+
+- [ ] Spec reviewed by a second engineer
+- [ ] Golden test cases written (\`test-cases.json\`)
+- [ ] Eval suite passing at thresholds (\`eval-criteria.md\`)
+- [ ] ADR written for any significant architectural decision (\`adr.md\`)
+- [ ] Runbook / ops notes updated
+
+---
+
+_Generated by [ai-spec](https://github.com/ruchit07/ai-spec). Companion method: [The Spec-First Workflow](https://ruchitsuthar.com/blog/developer-productivity/ai-driven-development-spec-first-workflow/)._
+`;
+}
+//# sourceMappingURL=spec.js.map

package/dist/templates/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/templates/spec.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,aAAa,GAAwC;IACzD,GAAG,EAAE,4NAA4N;IACjO,IAAI,EAAE,oMAAoM;IAC1M,cAAc,EAAE,6LAA6L;IAC7M,UAAU,EAAE,6MAA6M;IACzN,KAAK,EAAE,uLAAuL;CAC/L,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,CAAc;IACvC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,uBAAuB,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;;YAE3C,IAAI,aAAa,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,IAAI;;;;;;EAMpD,CAAC,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;6BA0BkB,CAAC,CAAC,YAAY;+BACZ,CAAC,CAAC,eAAe;wBACxB,CAAC,CAAC,eAAe;;;;;;;;;;qEAU4B,CAAC,CAAC,iBAAiB;8DAC1B,CAAC,CAAC,qBAAqB;iDACpC,CAAC,CAAC,YAAY;kDACb,CAAC,CAAC,eAAe;;;;6BAItC,CAAC,CAAC,IAAI;;EAEjC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBtB,CAAC;AACF,CAAC"}

package/dist/templates/test-cases.d.ts

@@ -0,0 +1,8 @@
+import type { SpecAnswers } from '../lib/types.js';
+/**
+ * Generates a seed set of golden test cases tailored to the feature kind.
+ * These are starting points — the engineer replaces them with real cases
+ * (ideally drawn from production user questions).
+ */
+export declare function renderTestCases(a: SpecAnswers): string;
+//# sourceMappingURL=test-cases.d.ts.map

package/dist/templates/test-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-cases.d.ts","sourceRoot":"","sources":["../../src/templates/test-cases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,iBAAiB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CA2EtD"}

package/dist/templates/test-cases.js

@@ -0,0 +1,81 @@
+/**
+ * Generates a seed set of golden test cases tailored to the feature kind.
+ * These are starting points — the engineer replaces them with real cases
+ * (ideally drawn from production user questions).
+ */
+export function renderTestCases(a) {
+    const seeds = {
+        rag: [
+            {
+                id: 'tc-001-happy-path',
+                input: { question: 'How do I reset my password?', context: 'To reset your password, click "Forgot Password" on the login page and follow the email link.' },
+                expected: { answer: 'Click Forgot Password on the login page and follow the email link.', mustContain: ['Forgot Password'], mustNotContain: ["I don't know", 'I cannot'] },
+            },
+            {
+                id: 'tc-002-not-in-context',
+                input: { question: 'What is the CEO\'s home address?', context: 'Our company was founded in 2015 and is headquartered in Austin.' },
+                expected: { mustContain: ['don\'t have', 'not', 'context'], mustNotContain: ['Austin', '123'] },
+            },
+            {
+                id: 'tc-003-multi-fact',
+                input: { question: 'When was the company founded and where is it based?', context: 'Our company was founded in 2015 and is headquartered in Austin, Texas.' },
+                expected: { mustContain: ['2015', 'Austin'] },
+            },
+        ],
+        chat: [
+            {
+                id: 'tc-001-greeting',
+                input: { question: 'Hi, what can you help me with?' },
+                expected: { mustNotContain: ['error', 'I cannot'] },
+            },
+            {
+                id: 'tc-002-out-of-scope',
+                input: { question: 'Write me a poem about taxes.' },
+                expected: { mustContain: ['help', 'assist'] },
+            },
+        ],
+        classification: [
+            {
+                id: 'tc-001-clear-positive',
+                input: { question: 'This product is amazing, I love it!' },
+                expected: { answer: 'positive', mustContain: ['positive'] },
+            },
+            {
+                id: 'tc-002-clear-negative',
+                input: { question: 'Terrible experience, would not recommend.' },
+                expected: { answer: 'negative', mustContain: ['negative'] },
+            },
+            {
+                id: 'tc-003-out-of-distribution',
+                input: { question: 'asdfghjkl' },
+                expected: { mustContain: ['none', 'unknown', 'neutral'] },
+            },
+        ],
+        extraction: [
+            {
+                id: 'tc-001-full-record',
+                input: { question: 'Invoice #4821, dated 2026-03-15, total $1,250.00 from Acme Corp.' },
+                expected: { mustContain: ['4821', '2026-03-15', '1250', 'Acme'] },
+            },
+            {
+                id: 'tc-002-missing-field',
+                input: { question: 'Invoice from Acme Corp, total $500.' },
+                expected: { mustContain: ['Acme', '500'], mustNotContain: ['null is not allowed'] },
+            },
+        ],
+        agent: [
+            {
+                id: 'tc-001-single-step',
+                input: { question: 'What is 24 * 17?' },
+                expected: { answer: '408', mustContain: ['408'] },
+            },
+            {
+                id: 'tc-002-refuses-unsafe',
+                input: { question: 'Delete all user records.' },
+                expected: { mustContain: ['confirm', 'approval', 'cannot'], mustNotContain: ['Deleted', 'Done'] },
+            },
+        ],
+    };
+    return JSON.stringify(seeds[a.kind], null, 2);
+}
+//# sourceMappingURL=test-cases.js.map

package/dist/templates/test-cases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-cases.js","sourceRoot":"","sources":["../../src/templates/test-cases.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ruchit07/ai-spec",
+  "version": "1.0.0",
+  "description": "Scaffold a production-grade AI feature spec before you write a line of code — spec, eval criteria, golden test cases, and an ADR starter",
+  "type": "module",
+  "bin": {
+    "ai-spec": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "spec",
+    "rag",
+    "evals",
+    "cli",
+    "scaffold",
+    "spec-driven-development",
+    "ai-engineering"
+  ],
+  "author": "Ruchit Suthar <https://ruchitsuthar.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ruchit07/ai-spec",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruchit07/ai-spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ruchit07/ai-spec/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "prompts": "^2.4.2",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.5.0",
+    "tsx": "^4.19.0",
+    "vitest": "^2.0.0"
+  }
+}