ai-meta-factory 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+AI META FACTORY NON-COMMERCIAL LICENSE
+Version 1.0 — 2026
+
+Copyright (c) 2026 Devendra Solanki
+
+1. Definitions
+
+“Software” means the ai-meta-factory source code, documentation,
+prompt files, templates, configuration, and other materials distributed
+with this license.
+
+“Commercial Use” means any use of the Software that is intended for or
+directly connected with commercial advantage, monetary compensation,
+revenue generation, business operations, paid services, or economic benefit.
+
+Commercial Use includes, without limitation:
+
+a. use by a company, business, agency, or other commercial organization;
+b. use in developing, testing, operating, or maintaining a commercial product;
+c. use for internal business, engineering, consulting, or client work;
+d. use in a paid service, hosted service, SaaS product, or managed service;
+e. use in work delivered to a paying customer;
+f. selling, sublicensing, leasing, renting, or redistributing the Software;
+g. embedding the Software into a commercial product or service;
+h. offering support, training, implementation, or other paid services
+   substantially based on the Software.
+
+“Non-Commercial Use” means personal, educational, academic, research,
+evaluation, or other use that is not Commercial Use.
+
+“Licensor” means Devendra Solanki.
+
+2. Permission for Non-Commercial Use
+
+Subject to the conditions in this license, the Licensor grants you a
+limited, worldwide, non-exclusive, non-transferable, non-sublicensable,
+royalty-free license to use, copy, modify, and distribute the Software
+solely for Non-Commercial Use.
+
+3. Commercial Use Requires Permission
+
+Commercial Use is not permitted under this license.
+
+You must obtain a separate written commercial license from the Licensor
+before undertaking any Commercial Use.
+
+Commercial licensing inquiries:
+
+Email: [YOUR-COMMERCIAL-LICENSE-EMAIL]
+Repository: https://github.com/devendra-solanki-work/ai-meta-factory
+
+4. Distribution Conditions
+
+For permitted Non-Commercial Use, you must:
+
+a. retain this license notice;
+b. retain the copyright notice;
+c. include a copy of this license with any distribution;
+d. clearly identify modifications made to the Software; and
+e. not represent modified Software as the original Software.
+
+You may not sell, sublicense, or commercially redistribute the Software
+or any derivative work under this license.
+
+5. Restrictions
+
+You may not:
+
+a. use the Software for Commercial Use;
+b. remove or alter copyright, license, or attribution notices;
+c. use the Licensor's name, trademarks, or branding to imply endorsement;
+d. circumvent the commercial licensing requirements of this license; or
+e. distribute the Software in a manner that suggests it is available
+   for unrestricted commercial use.
+
+6. No Trademark License
+
+This license does not grant permission to use the name, trademarks,
+logos, service marks, or branding of the Licensor or the project,
+except as reasonably necessary to identify the Software.
+
+7. No Warranty
+
+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.
+
+8. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSOR SHALL NOT
+BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF,
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+9. Termination
+
+This license terminates automatically if you breach its terms.
+
+Upon termination, you must stop using, copying, modifying, and distributing
+the Software, except that permissions granted to recipients who complied
+with this license before termination will not be revoked solely because
+of your breach.
+
+10. Reservation of Rights
+
+All rights not expressly granted under this license are reserved by the
+Licensor.
+
+This license is not an open-source license because it restricts Commercial
+Use.

package/README.md

@@ -0,0 +1,108 @@
+# ai-meta-factory
+
+**Build consistent repository context for AI agents.**
+
+A meta-factory that generates structured project context artifacts from repository scans. These artifacts empower AI agents with accurate, repository-specific guidance, eliminating guesswork and ensuring consistent responses.
+
+## What is this?
+
+`ai-meta-factory` is a system for generating and maintaining AI-friendly documentation artifacts. Instead of relying on AI agents to infer your project's structure, conventions, and constraints from raw code, this factory produces standardized, concise reference files that:
+
+- **Ground AI agents** in your project's actual architecture
+- **Enforce consistency** across all agent interactions
+- **Reduce hallucination** by providing authoritative facts
+- **Speed up onboarding** for new developers and AI assistants
+
+## How it works
+
+The factory operates in stages:
+
+1. **Scanner** (`meta/factory/scanner.prompt`)
+   - Analyzes repository structure, languages, frameworks, and conventions
+   - Produces `repo-context.yaml` — the master source of truth
+
+2. **Context Generator** (`meta/factory/000-context-generator.prompt`)
+   - Transforms scanner output into `.cursor/rules/000-project-context.mdc`
+   - Compact lookup table: stack, entry points, directories, constraints, naming conventions
+
+3. **Architecture Documenter** (`meta/factory/architecture.prompt`)
+   - Generates `.cursor/rules/200-architecture.mdc` — module boundaries and dependency rules
+   - Produces `docs/adr/ADR-000-initial-architecture.md` — architecture decisions
+
+4. **Standards & Tests** (`meta/factory/standards.prompt`, `tests.prompt`)
+   - Coding standards: `.cursor/rules/100-*-standards.mdc`
+   - Test conventions: `.cursor/rules/300-test-conventions.mdc`
+
+5. **Drift Check** (`meta/factory/drift-check.prompt`)
+   - Validates that actual codebase matches generated context
+   - Flags architectural violations and outdated documentation
+
+6. **Claude Markdown** (`meta/factory/claudemd.prompt`)
+   - Generates `.cursor/rules/900-claude-instructions.mdc`
+   - Custom behavioral rules and tone guidance for AI assistants
+
+## Output artifacts
+
+All generated files live in `.cursor/rules/` and `docs/` — optimized for AI context windows:
+
+| Artifact | Purpose | Lines |
+|----------|---------|-------|
+| `000-project-context.mdc` | Quick reference (stack, entry points, directories) | ≤50 |
+| `100-*-standards.mdc` | Coding standards & conventions | Modular |
+| `200-architecture.mdc` | Module map, dependency rules, constraints | ≤30 |
+| `300-test-conventions.mdc` | Testing patterns and requirements | Concise |
+| `900-claude-instructions.mdc` | Custom AI behavior and tone | Brief |
+| `docs/adr/ADR-*.md` | Architecture Decision Records | Linked |
+
+## Core principles
+
+1. **Terse over friendly** — Every token matters in an AI context window
+2. **Facts over prose** — Lookup tables, not essays
+3. **Observable evidence** — All patterns backed by real code
+4. **Sanctioned constraints** — Only document things that break if violated
+5. **Single source of truth** — Scanner output is canonical
+
+## Design philosophy
+
+This factory treats AI agents as first-class participants in development:
+
+- **Agents need context, not tutorials** — No "here's what TypeScript is"
+- **Agents need boundaries, not guidelines** — Hard rules, not best practices
+- **Agents need signals, not noise** — Facts compressed to essentials
+- **Agents need consistency** — One source of truth for all interactions
+
+## Who is this for?
+
+- **Teams using AI coding agents** (GitHub Copilot, Claude, etc.)
+- **Projects that want consistent AI-assisted development**
+- **Organizations scaling AI-driven workflows** across multiple repositories
+
+## Implementation
+
+See [`artifact-factory-team-runbook.docx`](artifact-factory-team-runbook.docx) for detailed implementation guides and team workflows.
+
+## Getting started
+
+1. Run the scanner prompt on your repository
+2. Generate initial artifacts using factory prompts
+3. Integrate `.cursor/rules/` into your Cursor/IDE configuration
+4. Run periodic drift checks to keep context fresh
+
+## License
+
+The project is available under the
+[AI Meta Factory Non-Commercial License](LICENSE).
+
+Personal, educational, academic, research, and evaluation use is permitted
+subject to the license terms.
+
+Commercial use requires a separate written commercial license.
+
+For commercial licensing inquiries, contact:
+
+`[devendra.solanki.work@gmail.com]`
+
+---
+
+**License:** See repository for license information  
+**Status:** Active development

package/dist/adapters.d.ts

@@ -0,0 +1,3 @@
+import type { RepoContext, RenderedFile, Target } from './types.js';
+export declare function render(context: RepoContext, target: Exclude<Target, 'all'>): RenderedFile[];
+export declare function targets(value: Target): Exclude<Target, 'all'>[];

package/dist/adapters.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+const yaml = (context) => `repository:\n  name: ${context.repository.name}\n  primary_language: ${context.repository.primaryLanguage ?? 'null'}\n  languages: [${context.repository.languages.join(', ')}]\nstack:\n  runtime: ${context.stack.runtime ?? 'null'}\n  frameworks: [${context.stack.frameworks.join(', ')}]\nstructure:\n  directories: [${context.structure.directories.join(', ')}]\n  entry_points: [${context.structure.entryPoints.join(', ')}]\ncommands:\n  build: ${context.commands.build ?? 'null'}\n  test: ${context.commands.test ?? 'null'}\n  dev: ${context.commands.dev ?? 'null'}\nconstraints:\n${context.constraints.map((x) => `  - ${x}`).join('\n')}\n`;
+const json = (context) => JSON.stringify({
+    ...context,
+    systemPrompt: `You are an evidence-driven assistant for ${context.repository.name}. Follow the repository constraints and do not invent missing facts.`
+}, null, 2) + '\n';
+const marker = (context) => createHash('sha256').update(JSON.stringify(context)).digest('hex').slice(0, 12);
+export function render(context, target) {
+    const hash = marker(context);
+    const header = `<!-- Generated by ai-meta-factory; context ${hash}. Do not edit manually. -->\n`;
+    const summary = `# ${context.repository.name} — Project Context\n\n- Languages: ${context.repository.languages.join(', ') || 'unknown'}\n- Runtime: ${context.stack.runtime ?? 'unknown'}\n- Frameworks: ${context.stack.frameworks.join(', ') || 'none detected'}\n- Entry points: ${context.structure.entryPoints.join(', ') || 'none detected'}\n- Directories: ${context.structure.directories.join(', ') || 'none detected'}\n- Constraints: ${context.constraints.join(' ')}\n`;
+    switch (target) {
+        case 'cursor':
+            return [
+                {
+                    path: '.cursor/rules/000-project-context.mdc',
+                    content: `---\nalwaysApply: true\nname: "000-project-context"\ndescription: "Generated repository reference"\n---\n${header}${summary}`
+                },
+                { path: 'meta/factory/repo-context.yaml', content: yaml(context) }
+            ];
+        case 'github-copilot':
+            return [
+                {
+                    path: '.github/copilot-instructions.md',
+                    content: `${header}${summary}\nUse the existing project structure and commands. Do not infer undocumented architecture.`
+                },
+                { path: 'meta/factory/repo-context.yaml', content: yaml(context) }
+            ];
+        case 'claude':
+            return [
+                {
+                    path: 'CLAUDE.md',
+                    content: `${header}${summary}\n## Reasoning rules\nUse only observable repository evidence. Preserve architectural boundaries and ask before changing generated context.\n`
+                },
+                { path: 'meta/factory/repo-context.yaml', content: yaml(context) }
+            ];
+        case 'gemini':
+            return [
+                { path: 'gemini-context.json', content: json(context) },
+                { path: 'meta/factory/repo-context.yaml', content: yaml(context) }
+            ];
+        case 'generic':
+            return [
+                { path: '.ai-context/repo-context.json', content: json(context) },
+                { path: '.ai-context/README.md', content: `${header}This directory contains generated, tool-neutral repository context. Regenerate after structural changes.\n` }
+            ];
+    }
+}
+export function targets(value) {
+    return value === 'all' ? ['cursor', 'github-copilot', 'claude', 'gemini', 'generic'] : [value];
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { render, targets } from './adapters.js';
+import { scan } from './scanner.js';
+const args = process.argv.slice(2);
+const command = args[0] ?? 'init';
+const targetIndex = args.indexOf('--target');
+const target = (targetIndex >= 0 ? args[targetIndex + 1] : 'all');
+const pathIndex = args.indexOf('--path');
+const root = resolve(pathIndex >= 0 ? args[pathIndex + 1] : '.');
+const dryRun = args.includes('--dry-run');
+const force = args.includes('--force');
+if (!['init', 'generate', 'drift-check'].includes(command)) {
+    console.error('Usage: ai-meta-factory init|generate|drift-check [--target target] [--dry-run] [--force]');
+    process.exit(1);
+}
+const context = scan(root);
+if (command === 'drift-check') {
+    const generated = render(context, 'generic').find((file) => file.path === '.ai-context/repo-context.json');
+    const actualPath = join(root, '.ai-context/repo-context.json');
+    const drifted = !existsSync(actualPath) || readFileSync(actualPath, 'utf8') !== generated?.content;
+    console.log(drifted ? 'DRIFT: generated context is missing or outdated.' : 'OK: generated context matches the repository scan.');
+    process.exit(drifted ? 2 : 0);
+}
+for (const selected of targets(target)) {
+    for (const file of render(context, selected)) {
+        const destination = join(root, file.path);
+        const directory = destination.slice(0, destination.lastIndexOf('/'));
+        if (existsSync(destination) && !force) {
+            console.log(`SKIP ${file.path} (exists; use --force to replace)`);
+            continue;
+        }
+        if (dryRun) {
+            console.log(`WOULD WRITE ${file.path}`);
+            continue;
+        }
+        mkdirSync(directory, { recursive: true });
+        writeFileSync(destination, file.content);
+        console.log(`WRITE ${file.path}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { scan } from './scanner.js';
+export { render, targets } from './adapters.js';
+export type { RepoContext, RenderedFile, Target } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { scan } from './scanner.js';
+export { render, targets } from './adapters.js';

package/dist/scanner.d.ts

@@ -0,0 +1,2 @@
+import type { RepoContext } from './types.js';
+export declare function scan(root: string): RepoContext;

package/dist/scanner.js

@@ -0,0 +1,107 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const ignored = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.next', '.venv']);
+function packageJson(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function files(root, depth = 0) {
+    if (depth > 4)
+        return [];
+    const result = [];
+    for (const entry of readdirSync(root)) {
+        if (ignored.has(entry))
+            continue;
+        const absolute = join(root, entry);
+        const stat = statSync(absolute);
+        if (stat.isDirectory()) {
+            result.push(...files(absolute, depth + 1));
+        }
+        else {
+            result.push(relative(process.cwd(), absolute).replaceAll('\\', '/'));
+        }
+    }
+    return result;
+}
+function read(root, name) {
+    try {
+        return readFileSync(join(root, name), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function detectLanguage(paths) {
+    const map = {
+        '.ts': 'TypeScript',
+        '.tsx': 'TypeScript',
+        '.js': 'JavaScript',
+        '.jsx': 'JavaScript',
+        '.py': 'Python',
+        '.go': 'Go',
+        '.rs': 'Rust',
+        '.java': 'Java',
+        '.cs': 'C#',
+        '.rb': 'Ruby'
+    };
+    const result = new Set();
+    for (const path of paths) {
+        const ext = path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
+        const detected = map[ext];
+        if (detected)
+            result.add(detected);
+    }
+    return [...result].sort();
+}
+export function scan(root) {
+    const paths = files(root);
+    const pkg = packageJson(root);
+    const languages = detectLanguage(paths);
+    const dirs = [...new Set(paths.map((p) => p.split('/')[0]).filter((p) => !p.includes('.') && p.length > 0))].sort();
+    const entryPoints = paths.filter((p) => /(^|\/)(index|main|app|server)\.(ts|tsx|js|jsx|py|go|rs)$/.test(p)).slice(0, 10);
+    const scripts = pkg.scripts ?? {};
+    const frameworks = [
+        ...(pkg.dependencies ? Object.keys(pkg.dependencies).filter((name) => ['react', 'next', 'express', 'fastify', 'nestjs', 'vue', 'angular'].some((token) => name.includes(token))) : []),
+        ...(read(root, 'pyproject.toml')?.match(/(?:django|fastapi|flask|pytest)/gi) ?? [])
+    ];
+    const testFiles = paths.filter((p) => /(test|spec)\.(ts|tsx|js|jsx|py|go)$/.test(p));
+    const packageManager = pkg.packageManager ?? (read(root, 'package-lock.json') ? 'npm' :
+        read(root, 'pnpm-lock.yaml') ? 'pnpm' :
+            read(root, 'yarn.lock') ? 'yarn' :
+                null);
+    return {
+        repository: {
+            name: pkg.name ?? root.split('/').pop() ?? 'repository',
+            description: pkg.description ?? null,
+            primaryLanguage: languages[0] ?? null,
+            languages
+        },
+        stack: {
+            frameworks: [...new Set(frameworks)].sort(),
+            packageManager,
+            runtime: languages.includes('TypeScript') || languages.includes('JavaScript') ? 'Node.js' : null
+        },
+        structure: {
+            directories: dirs,
+            entryPoints
+        },
+        conventions: {
+            files: languages.length ? 'Observe existing file naming and preserve repository conventions.' : null,
+            tests: testFiles.length ? `${testFiles.length} test-like files detected.` : null
+        },
+        commands: {
+            build: scripts.build ?? null,
+            test: scripts.test ?? null,
+            dev: scripts.dev ?? scripts.start ?? null
+        },
+        constraints: [
+            'Generated artifacts must remain evidence-backed.',
+            'Do not overwrite user-authored files without explicit confirmation.'
+        ],
+        generatedAt: new Date().toISOString()
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export type Target = 'cursor' | 'github-copilot' | 'claude' | 'gemini' | 'generic' | 'all';
+export interface RepoContext {
+    repository: {
+        name: string;
+        description: string | null;
+        primaryLanguage: string | null;
+        languages: string[];
+    };
+    stack: {
+        frameworks: string[];
+        packageManager: string | null;
+        runtime: string | null;
+    };
+    structure: {
+        directories: string[];
+        entryPoints: string[];
+    };
+    conventions: {
+        files: string | null;
+        tests: string | null;
+    };
+    commands: {
+        build: string | null;
+        test: string | null;
+        dev: string | null;
+    };
+    constraints: string[];
+    generatedAt: string;
+}
+export interface RenderedFile {
+    path: string;
+    content: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ai-meta-factory",
+  "version": "0.1.0",
+  "description": "Repository-aware context generator for AI coding tools.",
+  "keywords": [
+    "ai",
+    "coding-agents",
+    "repository-context",
+    "developer-tools",
+    "artificial-intelligence"
+  ],
+  "author": "Devendra Solanki",
+  "homepage": "https://github.com/devendra-solanki-work/ai-meta-factory",
+  "type": "module",
+  "bin": {
+    "ai-meta-factory": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devendra-solanki-work/ai-meta-factory.git"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "check": "tsc --noEmit" 
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}