create-foundry-workspace 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Foundry Contributors
+
+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,170 @@
+# Foundry (`create-foundry-workspace`)
+
+> **Deterministic, local-first, zero-LLM CLI for initializing AI-ready software development workspaces.**
+
+[![CI](https://github.com/Harshitkant21/Foundry/actions/workflows/ci.yml/badge.svg)](https://github.com/Harshitkant21/Foundry/actions)
+[![npm version](https://img.shields.io/npm/v/create-foundry-workspace.svg?style=flat&color=CB3837)](https://www.npmjs.com/package/create-foundry-workspace)
+[![Node: >=18.0.0](https://img.shields.io/badge/Node->=18.0.0-green.svg)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Zero-LLM Runtime](https://img.shields.io/badge/Architecture-Deterministic%20Zero--LLM-8A2BE2.svg)](docs/ARCHITECTURE.md)
+
+---
+
+## What is Foundry?
+
+Modern developers increasingly rely on AI coding assistants such as **Cursor**, **Claude Code**, and **GitHub Copilot**. However, when starting a new project, developers are forced to manually author and repeatedly recreate AI instruction files, project rules, context files, and guardrails.
+
+**Foundry** is an open-source, deterministic developer tool distributed via npm as **`create-foundry-workspace`**. When starting a new project, running:
+
+```bash
+npx create-foundry-workspace
+# or: npm create foundry-workspace
+```
+
+asks a minimal set of meaningful project initialization questions and deterministically scaffolds an **AI-ready software workspace** based on predefined, versioned, and maintainable templates.
+
+---
+
+## What Foundry Does
+
+- **Establishes a Canonical Contract:** Generates a clean, machine-readable `ai-workspace.yaml` manifest.
+- **Generates Native Tool Adapters:** Renders native, complete instruction files for **Cursor** (`.cursor/rules/*.mdc`), **Claude Code** (`CLAUDE.md`), **GitHub Copilot** (`.github/copilot-instructions.md`), and the cross-tool open standard **`AGENTS.md`**.
+- **Generates Project README:** Creates a deterministic, human-facing `README.md` tailored to the selected project stack, commands, and AI tools.
+- **Enforces Architectural Guardrails:** Injects strict or standard code quality, security, and testing guardrails.
+- **Safeguards Existing Files:** Supports non-destructive safe-merges, overwrite protection, and dry-run execution.
+
+---
+
+## What Foundry Explicitly Does NOT Do
+
+Foundry is **NOT an AI agent** and does not use AI to generate workspaces:
+- ❌ **NO OpenAI, Anthropic, or Gemini API calls**
+- ❌ **NO local or remote LLM inference**
+- ❌ **NO network requests at runtime** (100% offline and local-first)
+- ❌ **NO hidden API keys or telemetry**
+- ❌ **NO autonomous code generation**
+
+Output is 100% deterministic: given the same inputs and version, the generated workspace is bit-for-bit identical every time.
+
+---
+
+## Quick Start
+
+Initialize an AI-ready workspace in your current directory:
+```bash
+npx create-foundry-workspace
+# or: npm create foundry-workspace
+```
+
+Or target a specific folder:
+```bash
+npx create-foundry-workspace ./my-new-project
+```
+
+### Non-Interactive (CI / Scripted) Usage
+```bash
+npx create-foundry-workspace ./my-new-service \
+  --name my-new-service \
+  --type api \
+  --lang python \
+  --strictness strict \
+  --ai cursor,claude,copilot,agents \
+  --yes
+```
+
+---
+
+## CLI Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `[directory]` | Target directory to initialize | `.` |
+| `-n, --name <string>` | Project name | Inferred from folder or `package.json` |
+| `-t, --type <type>` | `web` \| `api` \| `fullstack` \| `cli` \| `library` \| `data-ml` \| `mobile` \| `custom` | Inferred or `fullstack` |
+| `-l, --lang <lang>` | `typescript` \| `javascript` \| `python` \| `java` \| `go` \| `rust` \| `other` | Inferred or `typescript` |
+| `-r, --repo <repo>` | `github` \| `gitlab` \| `none` | `github` |
+| `-s, --strictness <level>` | `standard` \| `strict` | `standard` |
+| `-a, --ai <adapters>` | Comma-separated list of adapters (`claude,cursor,agents,copilot,codex,gemini,generic`) | `claude,cursor,agents` |
+| `--dry-run` | Preview files in terminal without writing to disk | `false` |
+| `-f, --force` | Overwrite conflicting files | `false` |
+| `-y, --yes` | Accept all defaults non-interactively | `false` |
+| `-v, --version` | Display version | |
+| `-h, --help` | Display help | |
+
+---
+
+## Generated Workspace Structure
+
+Foundry generates a deterministic, standardized workspace with zero bloat and zero hallucinations:
+
+```text
+my-project/
+├── ai-workspace.yaml               # Canonical machine contract
+├── README.md                       # Project documentation & stack guide
+├── AI_CONTEXT.md                   # System map and entrypoint for AI assistants
+├── PROJECT_GUARDRAILS.md           # Standalone architectural guardrails & testing rules
+├── CONTRIBUTING.md                 # Contribution workflow & guidelines
+├── .gitignore                      # Language-tailored ignore rules
+│
+├── .ai/                            # AI operational intelligence directory
+│   ├── context/project-context.md  # Detailed project domain background
+│   ├── rules/00-core-rules.md      # Core workspace rules & coding conventions
+│   ├── architecture/system-design.md # High-level architecture & layer boundaries
+│   ├── decisions/0001-project-init.md # Initial architecture decision record (ADR)
+│   └── tasks/task-backlog.md       # Operational scratchpad for AI agent task execution
+│
+├── docs/                           # Human-facing project documentation
+│   ├── README.md                   # Documentation index
+│   ├── ARCHITECTURE.md             # System architecture & component design
+│   ├── DEVELOPMENT.md              # Local setup, run, and test guides
+│   └── DECISIONS.md                # Architecture decision records index
+│
+└── [Tool Adapters]                 # Based on user selection:
+    ├── AGENTS.md                   # Multi-Agent open standard
+    ├── CLAUDE.md                   # Anthropic Claude Code CLI
+    ├── .cursor/rules/*.mdc         # Cursor IDE modular rules
+    ├── .github/copilot-instructions.md # GitHub Copilot context
+    ├── .codex/instructions.md      # OpenAI Codex context
+    ├── GEMINI.md                   # Google Antigravity & Gemini CLI
+    └── AI_INSTRUCTIONS.md          # Generic AI assistant instructions
+```
+
+---
+
+## Repository Architecture & Dogfooding
+
+Foundry strictly practices **dogfooding**. The Foundry repository itself is governed by the same `ai-workspace.yaml`, `AGENTS.md`, `CLAUDE.md`, `.cursor/`, and `.github/` files that it generates for users.
+
+For deeper architectural details, review the internal documentation:
+- [docs/SPECIFICATION.md](file:///d:/Extentions/Foundry/docs/SPECIFICATION.md) — Formal specification of the AI Workspace contract.
+- [docs/ARCHITECTURE.md](file:///d:/Extentions/Foundry/docs/ARCHITECTURE.md) — System architecture, module boundaries, and pure core pipeline.
+- [docs/ADAPTERS.md](file:///d:/Extentions/Foundry/docs/ADAPTERS.md) — Adapter interface specification and registry design.
+- [docs/DEVELOPMENT.md](file:///d:/Extentions/Foundry/docs/DEVELOPMENT.md) — Developer setup and testing guide.
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/Harshitkant21/Foundry.git
+cd Foundry
+
+# Install dependencies
+npm install
+
+# Run Vitest test suite
+npm test
+
+# Build TypeScript to dist/
+npm run build
+
+# Run local development CLI
+npx tsx src/bin.ts --dry-run
+```
+
+---
+
+## License
+
+MIT © Foundry Contributors

package/bin/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/bin.js';

package/dist/adapters/adapter.interface.d.ts

@@ -0,0 +1,13 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+export interface GeneratedFile {
+    readonly relativePath: string;
+    readonly content: string;
+}
+export interface WorkspaceAdapter {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly defaultSelected: boolean;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=adapter.interface.d.ts.map

package/dist/adapters/adapter.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.interface.js.map

package/dist/adapters/agents.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class AgentsAdapter implements WorkspaceAdapter {
+    readonly id = "agents";
+    readonly name = "AGENTS.md";
+    readonly description = "Open-standard root instructions for AI agents";
+    readonly defaultSelected = true;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=agents.adapter.d.ts.map

package/dist/adapters/agents.adapter.js

@@ -0,0 +1,16 @@
+import { renderAgentsDocument } from '../templates/agents.js';
+export class AgentsAdapter {
+    id = 'agents';
+    name = 'AGENTS.md';
+    description = 'Open-standard root instructions for AI agents';
+    defaultSelected = true;
+    render(context) {
+        return [
+            {
+                relativePath: 'AGENTS.md',
+                content: renderAgentsDocument(context),
+            },
+        ];
+    }
+}
+//# sourceMappingURL=agents.adapter.js.map

package/dist/adapters/claude.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class ClaudeAdapter implements WorkspaceAdapter {
+    readonly id = "claude";
+    readonly name = "Claude Code (CLAUDE.md)";
+    readonly description = "Compact CLI guidance and shell commands for Claude Code";
+    readonly defaultSelected = true;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=claude.adapter.d.ts.map

package/dist/adapters/claude.adapter.js

@@ -0,0 +1,30 @@
+export class ClaudeAdapter {
+    id = 'claude';
+    name = 'Claude Code (CLAUDE.md)';
+    description = 'Compact CLI guidance and shell commands for Claude Code';
+    defaultSelected = true;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules } = context;
+        const content = `# Claude Code Guidelines — ${config.project.name}
+
+## Key Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+- Dev:   \`${commands.dev}\`
+- Lint:  \`${commands.lint}\`
+
+## Project Guardrails
+${baseGuardrails}
+
+## Language Conventions
+${languageRules}
+`;
+        return [
+            {
+                relativePath: 'CLAUDE.md',
+                content,
+            },
+        ];
+    }
+}
+//# sourceMappingURL=claude.adapter.js.map

package/dist/adapters/codex.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class CodexAdapter implements WorkspaceAdapter {
+    readonly id = "codex";
+    readonly name = "Codex (CODEX.md)";
+    readonly description = "Instruction context for OpenAI Codex and IDE integrations";
+    readonly defaultSelected = false;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=codex.adapter.d.ts.map

package/dist/adapters/codex.adapter.js

@@ -0,0 +1,33 @@
+export class CodexAdapter {
+    id = 'codex';
+    name = 'Codex (CODEX.md)';
+    description = 'Instruction context for OpenAI Codex and IDE integrations';
+    defaultSelected = false;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules, appTypeRules } = context;
+        const content = `# OpenAI Codex Guidelines — ${config.project.name}
+
+## Project Profile
+- Application: ${config.project.name} (${config.project.type})
+- Language: ${config.project.language}
+- Strictness: ${config.strictness}
+
+## Standard Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+- Dev:   \`${commands.dev}\`
+- Lint:  \`${commands.lint}\`
+
+## Architecture
+${appTypeRules}
+
+## Language Conventions
+${languageRules}
+
+## Guardrails
+${baseGuardrails}
+`;
+        return [{ relativePath: 'CODEX.md', content }];
+    }
+}
+//# sourceMappingURL=codex.adapter.js.map

package/dist/adapters/copilot.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class CopilotAdapter implements WorkspaceAdapter {
+    readonly id = "copilot";
+    readonly name = "GitHub Copilot (.github/)";
+    readonly description = "Workspace prompt instruction block for GitHub Copilot";
+    readonly defaultSelected = true;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=copilot.adapter.d.ts.map

package/dist/adapters/copilot.adapter.js

@@ -0,0 +1,40 @@
+export class CopilotAdapter {
+    id = 'copilot';
+    name = 'GitHub Copilot (.github/)';
+    description = 'Workspace prompt instruction block for GitHub Copilot';
+    defaultSelected = true;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules, appTypeRules } = context;
+        const content = `# GitHub Copilot Workspace Instructions — ${config.project.name}
+
+This file provides system context for GitHub Copilot when assisting on this repository.
+
+## Project Metadata
+- Application Type: ${config.project.type}
+- Language: ${config.project.language}
+- Strictness Level: ${config.strictness}
+
+## Primary Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+- Dev:   \`${commands.dev}\`
+- Lint:  \`${commands.lint}\`
+
+## Architecture
+${appTypeRules}
+
+## Language Conventions
+${languageRules}
+
+## Safety & Quality Guardrails
+${baseGuardrails}
+`;
+        return [
+            {
+                relativePath: '.github/copilot-instructions.md',
+                content,
+            },
+        ];
+    }
+}
+//# sourceMappingURL=copilot.adapter.js.map

package/dist/adapters/cursor.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class CursorAdapter implements WorkspaceAdapter {
+    readonly id = "cursor";
+    readonly name = "Cursor (.cursor/rules/)";
+    readonly description = "Modular MDC rules with frontmatter for Cursor IDE";
+    readonly defaultSelected = true;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=cursor.adapter.d.ts.map

package/dist/adapters/cursor.adapter.js

@@ -0,0 +1,41 @@
+export class CursorAdapter {
+    id = 'cursor';
+    name = 'Cursor (.cursor/rules/)';
+    description = 'Modular MDC rules with frontmatter for Cursor IDE';
+    defaultSelected = true;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules, appTypeRules } = context;
+        const content = `---
+description: Core Architecture Rules for ${config.project.name}
+globs: *
+alwaysApply: true
+---
+# Cursor Core Rules — ${config.project.name}
+
+## Project Profile
+- Application: ${config.project.name} (${config.project.type})
+- Language: ${config.project.language}
+- Strictness: ${config.strictness}
+
+## Standard Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+
+## Architectural Guidelines
+${appTypeRules}
+
+## Language Conventions
+${languageRules}
+
+## Guardrails
+${baseGuardrails}
+`;
+        return [
+            {
+                relativePath: '.cursor/rules/00-core-rules.mdc',
+                content,
+            },
+        ];
+    }
+}
+//# sourceMappingURL=cursor.adapter.js.map

package/dist/adapters/gemini.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class GeminiAdapter implements WorkspaceAdapter {
+    readonly id = "gemini";
+    readonly name = "Gemini (GEMINI.md)";
+    readonly description = "Context guidelines for Google Antigravity & Gemini CLI";
+    readonly defaultSelected = false;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=gemini.adapter.d.ts.map

package/dist/adapters/gemini.adapter.js

@@ -0,0 +1,34 @@
+export class GeminiAdapter {
+    id = 'gemini';
+    name = 'Gemini (GEMINI.md)';
+    description = 'Context guidelines for Google Antigravity & Gemini CLI';
+    defaultSelected = false;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules, appTypeRules } = context;
+        const content = `# Gemini Guidelines — ${config.project.name}
+
+## Project Overview
+- Name: ${config.project.name}
+- Type: ${config.project.type}
+- Language: ${config.project.language}
+- Strictness: ${config.strictness}
+
+## Build & Test Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+- Dev:   \`${commands.dev}\`
+- Lint:  \`${commands.lint}\`
+
+## Architecture Conventions
+${appTypeRules}
+
+## Language Conventions
+${languageRules}
+
+## Architectural Guardrails
+${baseGuardrails}
+`;
+        return [{ relativePath: 'GEMINI.md', content }];
+    }
+}
+//# sourceMappingURL=gemini.adapter.js.map

package/dist/adapters/generic.adapter.d.ts

@@ -0,0 +1,10 @@
+import { ResolvedWorkspaceContext } from '../config/schema.js';
+import { GeneratedFile, WorkspaceAdapter } from './adapter.interface.js';
+export declare class GenericAdapter implements WorkspaceAdapter {
+    readonly id = "generic";
+    readonly name = "Generic (AI_INSTRUCTIONS.md)";
+    readonly description = "Tool-agnostic instruction file for any AI development environment";
+    readonly defaultSelected = false;
+    render(context: ResolvedWorkspaceContext): GeneratedFile[];
+}
+//# sourceMappingURL=generic.adapter.d.ts.map

package/dist/adapters/generic.adapter.js

@@ -0,0 +1,34 @@
+export class GenericAdapter {
+    id = 'generic';
+    name = 'Generic (AI_INSTRUCTIONS.md)';
+    description = 'Tool-agnostic instruction file for any AI development environment';
+    defaultSelected = false;
+    render(context) {
+        const { config, commands, baseGuardrails, languageRules, appTypeRules } = context;
+        const content = `# AI Development Instructions — ${config.project.name}
+
+## Project Profile
+- Application: ${config.project.name}
+- Type: ${config.project.type}
+- Language: ${config.project.language}
+- Guardrails Tier: ${config.strictness}
+
+## Standard Commands
+- Build: \`${commands.build}\`
+- Test:  \`${commands.test}\`
+- Dev:   \`${commands.dev}\`
+- Lint:  \`${commands.lint}\`
+
+## Architecture
+${appTypeRules}
+
+## Language Conventions
+${languageRules}
+
+## Guardrails
+${baseGuardrails}
+`;
+        return [{ relativePath: 'AI_INSTRUCTIONS.md', content }];
+    }
+}
+//# sourceMappingURL=generic.adapter.js.map

package/dist/adapters/registry.d.ts

@@ -0,0 +1,12 @@
+import { WorkspaceAdapter } from './adapter.interface.js';
+export declare class AdapterRegistry {
+    private adapters;
+    constructor();
+    register(adapter: WorkspaceAdapter): void;
+    get(id: string): WorkspaceAdapter | undefined;
+    getAll(): WorkspaceAdapter[];
+    getDefaultIds(): string[];
+    has(id: string): boolean;
+}
+export declare const defaultRegistry: AdapterRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/adapters/registry.js

@@ -0,0 +1,38 @@
+import { AgentsAdapter } from './agents.adapter.js';
+import { ClaudeAdapter } from './claude.adapter.js';
+import { CodexAdapter } from './codex.adapter.js';
+import { CopilotAdapter } from './copilot.adapter.js';
+import { CursorAdapter } from './cursor.adapter.js';
+import { GeminiAdapter } from './gemini.adapter.js';
+import { GenericAdapter } from './generic.adapter.js';
+export class AdapterRegistry {
+    adapters = new Map();
+    constructor() {
+        this.register(new AgentsAdapter());
+        this.register(new CursorAdapter());
+        this.register(new ClaudeAdapter());
+        this.register(new CopilotAdapter());
+        this.register(new CodexAdapter());
+        this.register(new GeminiAdapter());
+        this.register(new GenericAdapter());
+    }
+    register(adapter) {
+        this.adapters.set(adapter.id, adapter);
+    }
+    get(id) {
+        return this.adapters.get(id);
+    }
+    getAll() {
+        return Array.from(this.adapters.values());
+    }
+    getDefaultIds() {
+        return this.getAll()
+            .filter((a) => a.defaultSelected)
+            .map((a) => a.id);
+    }
+    has(id) {
+        return this.adapters.has(id);
+    }
+}
+export const defaultRegistry = new AdapterRegistry();
+//# sourceMappingURL=registry.js.map

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from './cli/command.js';
+runCli().catch((err) => {
+    console.error('\n[Foundry Error]:', err.message || err);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/cli/command.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(argv?: string[]): Promise<void>;
+//# sourceMappingURL=command.d.ts.map