@hugo.bastidas/agent-foundation 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# agent-foundation
+
+CLI que instala convenciones personales de trabajo para agentes de IA
+(`AGENT_FOUNDATION.md`) en las instrucciones globales de Claude Code, Codex y
+OpenCode. Una sola fuente de verdad para convenciones de código, commits,
+estructura de proyectos y documentación — aplicada de forma idempotente en
+todos los hosts.
+
+## Uso
+
+```bash
+# instalar en todos los hosts
+npx -y @hugo.bastidas/agent-foundation install
+
+# instalar solo en hosts específicos
+npx -y @hugo.bastidas/agent-foundation install --host claude,codex
+
+# ver estado
+npx -y @hugo.bastidas/agent-foundation status
+
+# desinstalar
+npx -y @hugo.bastidas/agent-foundation remove
+```
+
+## Qué hace
+
+Por cada host seleccionado:
+
+1. Escribe `AGENT_FOUNDATION.md` (las convenciones) junto al archivo de
+   instrucciones globales del host.
+2. Inyecta un bloque gestionado con una `@referencia` al inicio de las
+   instrucciones globales, preservando el contenido existente.
+
+| Host | Instrucciones globales |
+|---|---|
+| Claude Code | `~/.claude/CLAUDE.md` |
+| Codex | `~/.codex/AGENTS.md` |
+| OpenCode | `~/.config/opencode/AGENTS.md` |
+
+La operación es idempotente: re-ejecutar `install` actualiza el bloque sin
+duplicarlo. `remove` elimina el bloque y el sidecar dejando intacto el resto
+del archivo.
+
+## Desarrollo
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Las convenciones viven en `AGENT_FOUNDATION_INSTRUCTIONS` en
+`src/foundation.ts` — edita ahí y re-ejecuta `install` para propagar.

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,70 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeAgentFoundation, removeAgentFoundation, agentFoundationPath } from './foundation.js';
+import { HOSTS, ALL_HOSTS, parseHosts } from './hosts.js';
+const USAGE = `agent-foundation — install personal agent conventions across AI coding hosts
+
+Usage:
+  agent-foundation install [--host <claude|codex|opencode|all>]
+  agent-foundation remove  [--host <claude|codex|opencode|all>]
+  agent-foundation status
+  agent-foundation --help
+
+Writes AGENT_FOUNDATION.md next to each host's global instructions file and
+injects a managed @reference block. "remove" deletes both. Default host: all.
+Hosts accept a comma-separated list (e.g. --host claude,codex).`;
+function getHostFlag(args) {
+    const index = args.indexOf('--host');
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+        throw new Error('--host requires a value');
+    return value;
+}
+async function install(hosts) {
+    for (const host of hosts) {
+        await writeAgentFoundation(HOSTS[host].instructions);
+        console.log(`Installed Agent Foundation reference in ${HOSTS[host].instructions}`);
+    }
+}
+async function remove(hosts) {
+    for (const host of hosts) {
+        await removeAgentFoundation(HOSTS[host].instructions);
+        console.log(`Removed Agent Foundation reference from ${HOSTS[host].instructions}`);
+    }
+}
+function status() {
+    console.table(ALL_HOSTS.map((host) => ({
+        Host: HOSTS[host].label,
+        Instructions: existsSync(HOSTS[host].instructions) ? 'yes' : 'no',
+        Foundation: existsSync(agentFoundationPath(HOSTS[host].instructions)) ? 'installed' : 'missing',
+    })));
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        console.log(USAGE);
+        return;
+    }
+    switch (command) {
+        case 'install':
+            await install(parseHosts(getHostFlag(args)));
+            break;
+        case 'remove':
+            await remove(parseHosts(getHostFlag(args)));
+            break;
+        case 'status':
+            status();
+            break;
+        default:
+            console.error(`Unknown command: ${command}\n`);
+            console.log(USAGE);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/foundation.d.ts

@@ -0,0 +1,8 @@
+export declare const AGENT_FOUNDATION_START = "<!-- >>> agent-foundation >>> -->";
+export declare const AGENT_FOUNDATION_END = "<!-- <<< agent-foundation <<< -->";
+export declare const AGENT_FOUNDATION_FILE = "AGENT_FOUNDATION.md";
+export declare const AGENT_FOUNDATION_INSTRUCTIONS: string;
+export declare function agentFoundationPath(globalInstructionsPath: string): string;
+export declare function writeAgentFoundation(filePath: string): Promise<void>;
+export declare function removeAgentFoundation(filePath: string): Promise<void>;
+//# sourceMappingURL=foundation.d.ts.map

package/dist/foundation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation.d.ts","sourceRoot":"","sources":["../src/foundation.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,sBAAsB,sCAAsC,CAAC;AAC1E,eAAO,MAAM,oBAAoB,sCAAsC,CAAC;AACxE,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D,eAAO,MAAM,6BAA6B,QA2J9B,CAAC;AA8Cb,wBAAgB,mBAAmB,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1E;AAED,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3E"}

package/dist/foundation.js

@@ -0,0 +1,227 @@
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+export const AGENT_FOUNDATION_START = '<!-- >>> agent-foundation >>> -->';
+export const AGENT_FOUNDATION_END = '<!-- <<< agent-foundation <<< -->';
+export const AGENT_FOUNDATION_FILE = 'AGENT_FOUNDATION.md';
+export const AGENT_FOUNDATION_INSTRUCTIONS = [
+    '## Agent Foundation',
+    '',
+    '### Code conventions',
+    '',
+    '| Element | Language |',
+    '|---|---|',
+    '| Variables, functions, constants | English |',
+    '| Classes and types | English |',
+    '| File names | English |',
+    '| Inline/block comments | Spanish |',
+    '| User-facing UI text | Spanish unless the project targets a specific locale |',
+    '',
+    'These conventions apply across TypeScript, JavaScript, Python, Astro, CSS, and other stacks.',
+    '',
+    '### Code quality and security',
+    '',
+    '- Write optimal code: avoid redundant logic, unnecessary loops, avoidable re-renders, N+1 queries, and preventable inefficiencies.',
+    '- Write secure code: prevent OWASP Top 10 issues, never hardcode secrets, and validate inputs at system boundaries.',
+    '- Boundary input validation and secret/security controls are required even when the user did not explicitly request them.',
+    '- Prefer simple, direct solutions over premature abstractions.',
+    '- Do not add error handling, validations, or features that were not explicitly requested unless they are necessary for boundary security, data integrity, or safe failure of the requested behavior.',
+    '',
+    '### Documentation lookups',
+    '',
+    '- When current library, framework, SDK, API, CLI, or cloud-service documentation is needed, use the available Context7 MCP/tooling first.',
+    '- If Context7 is unavailable or does not cover the requested technology, use the best available official documentation source.',
+    '- Do not rely on memory alone for version-sensitive syntax, setup, migration, or API behavior.',
+    '',
+    '### Required project structure',
+    '',
+    'Every new or existing project should have:',
+    '',
+    '1. `.env` — real environment variables, never committed.',
+    '2. `.env.example` — same keys without sensitive values, committed.',
+    '3. `.gitignore` — adjusted to the project stack.',
+    '4. Lock file — commit it (`package-lock.json`, `uv.lock`, `go.sum`, etc.). Never add lock files to `.gitignore`.',
+    '',
+    'The `.gitignore` should include at minimum:',
+    '',
+    '- Node/JS/TS: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.log`',
+    '- Python: `__pycache__/`, `*.pyc`, `.venv/`, `.env`, `dist/`, `*.egg-info/`',
+    '- Astro: Node entries plus `.astro/`',
+    '- General: `.DS_Store`, `Thumbs.db`, `.idea/`, `.vscode/` unless team settings are intentionally shared.',
+    '- AI tool artifacts: `.minimax/runs/`, `.minimax/cli-tests/`, `.minimax/multimodal-tests/`',
+    '',
+    'If these files are missing, tell the user and offer to create them.',
+    '',
+    '### Node.js workflow',
+    '',
+    'Use `npm` by default. Do not switch to yarn, pnpm, or bun unless the project already uses one of them (check for `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`). Commit `package-lock.json` — never gitignore it.',
+    '',
+    'Do not install a package to do something the runtime or an already-present dependency already handles.',
+    '',
+    '### Python workflow',
+    '',
+    'Always use `uv` for Python projects. Use `pyproject.toml` plus `uv.lock` as the default dependency contract, create/update dependencies with `uv add` or `uv remove`, install reproducibly with `uv sync --locked` (or `uv sync --frozen` when the project already standardizes on that flag), and run tools through `uv run` (for example `uv run pytest`, `uv run ruff check .`, `uv run mypy src`, or `uv run python -m package`). Do not introduce raw `pip`, manual `venv` setup, Poetry, Pipenv, or requirements-only workflows unless the user explicitly asks for compatibility with an existing project that already depends on them.',
+    '',
+    '### Testing',
+    '',
+    'Write tests only when explicitly requested or when the project already has a test suite and new code clearly belongs in it. Do not create a test suite from scratch unless asked.',
+    '',
+    'When writing tests:',
+    '- Test observable behavior, not implementation details.',
+    '- Follow the naming and placement convention already used in the project (e.g., `foo.test.ts` next to source, or a `/tests` directory at the project root).',
+    '- Prefer integration-level assertions over mocking internals.',
+    '',
+    '### Git repository initialization',
+    '',
+    'When starting or scaffolding any new project:',
+    '',
+    '1. Verify the directory is a git repository (`git status`). If not, run `git init` immediately before creating any project files.',
+    '2. Verify `.gitignore` exists and covers the project stack (see above). Create or update it before making any commit.',
+    '3. Make the initial commit only after `.gitignore`, `.env.example`, and the main documentation file (`AGENTS.md` or `README.md`) are in place.',
+    '',
+    'If any of these are missing when starting work on a new project, tell the user and offer to create them.',
+    '',
+    '### Git commit conventions',
+    '',
+    'When making commits in any project:',
+    '',
+    '- Use the Conventional Commits format: `type(scope): short description`',
+    '- Write commit title and body bullets in Spanish.',
+    '- Allowed types: `feat`, `fix`, `refactor`, `style`, `chore`, `docs`, `test`, `perf`, `ci`, `build`',
+    '- Keep the title concise (under 72 characters), lowercase, no trailing period.',
+    '- Add a body with bullet points when 3+ files change or changes clearly span different areas.',
+    '- Never include secrets, tokens, keys, or env variable values in commit messages.',
+    '- Always show the proposed message to the user and ask for confirmation before running `git commit`.',
+    '- After committing, ask the user whether to also run `git push`.',
+    '',
+    'Examples:',
+    '',
+    '```',
+    'fix(auth): corregir validación de token expirado',
+    '```',
+    '',
+    '```',
+    'feat(install): agregar componente de alias de shell y selección de hosts',
+    '',
+    '- agregar shell-alias.ts para generar alias mmx en bash/zsh',
+    '- ampliar el instalador con selección múltiple de hosts Claude',
+    '- expandir estadísticas de uso con desglose por herramienta',
+    '```',
+    '',
+    '### Required project documentation',
+    '',
+    'All local project documentation files (AGENTS.md, README.md, ARCHITECTURE.md, DESIGN.md) must be written in Spanish. Global sidecars (AGENT_FOUNDATION.md and any other host-level references you have installed) remain in English.',
+    '',
+    'Every new project must include these files at the repository root:',
+    '',
+    '1. `CLAUDE.md` — keep it free of project content; it only points the agent to `AGENTS.md`. Use a single line such as: "Always read and follow `AGENTS.md` for all project context and instructions."',
+    '2. `AGENTS.md` — the canonical project brief. It holds the most relevant information: project purpose, stack, run/build/test commands, project-specific constraints, and agent guidance. This is where the real instructions live.',
+    '3. `ARCHITECTURE.md` — a short, high-level map of the system (see below). Create it once the project has more than a couple of modules.',
+    '4. `DESIGN.md` — the design-system contract for the UI (see below). **Frontend projects only.**',
+    '',
+    'A project-local `AGENTS.md` must contain ONLY what is unique to that project. Never copy, paraphrase, or summarize sections already provided by global sidecars (`AGENT_FOUNDATION.md` or any other host-level references you have installed).',
+    '',
+    '**Never include in a local AGENTS.md:**',
+    '- Code conventions (variables, comments, file names, UI text language)',
+    '- Code quality or security rules',
+    '- Documentation lookup instructions (Context7, etc.)',
+    '- Required project structure (.env, .gitignore, lock file rules)',
+    '- Node.js or Python workflow rules',
+    '- Git repository initialization steps',
+    '- Git commit conventions or examples',
+    '- Any tool-specific routing or delegation policy (belongs in that tool\'s own sidecar)',
+    '- Any section that would be identical or near-identical across projects',
+    '',
+    '**A correct local AGENTS.md contains only:**',
+    '- What this project does (1–3 sentences)',
+    '- Stack and key dependencies',
+    '- How to build, test, and run the project',
+    '- Project-specific constraints or domain rules not covered globally',
+    '',
+    'When in doubt, omit the section. The global sidecars are always active — repeating them wastes tokens and creates drift when the global rule changes.',
+    '',
+    '#### ARCHITECTURE.md (keep it to ~1 page; point to code, do not duplicate it)',
+    '',
+    '- Overview: a few sentences on what the system does and its bird\'s-eye shape.',
+    '- Codemap: name the important modules, files, and types and what each is responsible for. Refer to them by name so symbol search can find them; avoid links that go stale.',
+    '- Invariants: rules that must always hold, especially "absence" rules (e.g. the model layer never imports the view layer).',
+    '- Boundaries: the seams between layers/systems and what each side may assume about the other.',
+    '- Cross-cutting concerns: logging, auth, error handling, configuration — anything that spans modules.',
+    '- Update it when the coarse structure changes, not on every edit.',
+    '',
+    '#### DESIGN.md (frontend only)',
+    '',
+    'A machine- and human-readable design-system spec so the UI stays consistent (format: github.com/google-labs-code/design.md):',
+    '',
+    '- YAML front matter with design tokens: colors (hex), typography (family, size, weight, line height), spacing scale, radius scale, and components that reference those tokens.',
+    '- Markdown body with the rationale: design philosophy and how/when to apply each token.',
+    '- Recommended sections, in order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do\'s and Don\'ts.',
+    '- Treat it as the source of truth for styling; generate framework tokens (e.g. Tailwind) from it instead of hardcoding values.',
+    '',
+    'If any required documentation file is missing when starting or scaffolding a project, tell the user and offer to create it.',
+].join('\n');
+const LEGACY_CLAUDE_SECTION_PATTERNS = [
+    /## Ruta del usuario\n[\s\S]*?(?=\n## Convenciones de código|\n## Calidad y seguridad del código|\n## Estructura obligatoria de proyectos|\n@RTK\.md|\n<!-- >>> minimax-plugin >>>|$)/g,
+    /## Convenciones de código \(aplican a todos los proyectos\)\n[\s\S]*?(?=\n## Calidad y seguridad del código|\n## Estructura obligatoria de proyectos|\n@RTK\.md|\n<!-- >>> minimax-plugin >>>|$)/g,
+    /## Calidad y seguridad del código\n[\s\S]*?(?=\n## Estructura obligatoria de proyectos|\n@RTK\.md|\n<!-- >>> minimax-plugin >>>|$)/g,
+    /## Estructura obligatoria de proyectos\n[\s\S]*?(?=\n@RTK\.md|\n<!-- >>> minimax-plugin >>>|$)/g,
+];
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// Normalizar CRLF a LF para que los regex funcionen igual en Windows/Mac/Linux.
+function normalizeLf(content) {
+    return content.replace(/\r\n/g, '\n');
+}
+function stripManagedAgentFoundation(content) {
+    return normalizeLf(content)
+        .replace(new RegExp(`${escapeRegExp(AGENT_FOUNDATION_START)}[\\s\\S]*?${escapeRegExp(AGENT_FOUNDATION_END)}`, 'g'), '')
+        .trim();
+}
+function stripLegacyClaudeSections(content) {
+    return LEGACY_CLAUDE_SECTION_PATTERNS.reduce((current, pattern) => current.replace(pattern, ''), normalizeLf(content))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function instructionReference(filePath) {
+    // Normalizar a forward slashes para que el @ reference funcione igual en Windows/Mac/Linux.
+    return `@${resolve(filePath).replace(/\\/g, '/')}`;
+}
+function managedReferenceBlock(targetPath) {
+    return [
+        AGENT_FOUNDATION_START,
+        instructionReference(targetPath),
+        AGENT_FOUNDATION_END,
+    ].join('\n');
+}
+export function agentFoundationPath(globalInstructionsPath) {
+    return join(dirname(globalInstructionsPath), AGENT_FOUNDATION_FILE);
+}
+export async function writeAgentFoundation(filePath) {
+    const targetPath = agentFoundationPath(filePath);
+    let existing = '';
+    try {
+        existing = await readFile(filePath, 'utf8');
+    }
+    catch { /* new file */ }
+    const stripped = stripLegacyClaudeSections(stripManagedAgentFoundation(existing));
+    const block = managedReferenceBlock(targetPath);
+    const updated = stripped ? `${block}\n\n${stripped}\n` : `${block}\n`;
+    await mkdir(dirname(filePath), { recursive: true });
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, `${AGENT_FOUNDATION_INSTRUCTIONS}\n`, 'utf8');
+    await writeFile(filePath, updated, 'utf8');
+}
+export async function removeAgentFoundation(filePath) {
+    let existing = '';
+    try {
+        existing = await readFile(filePath, 'utf8');
+    }
+    catch {
+        await rm(agentFoundationPath(filePath), { force: true });
+        return;
+    }
+    const stripped = stripManagedAgentFoundation(existing);
+    await writeFile(filePath, stripped ? `${stripped}\n` : '', 'utf8');
+    await rm(agentFoundationPath(filePath), { force: true });
+}
+//# sourceMappingURL=foundation.js.map

package/dist/foundation.js.map

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

package/dist/hosts.d.ts

@@ -0,0 +1,9 @@
+export type HostId = 'claude' | 'codex' | 'opencode';
+export interface HostInfo {
+    label: string;
+    instructions: string;
+}
+export declare const HOSTS: Record<HostId, HostInfo>;
+export declare const ALL_HOSTS: HostId[];
+export declare function parseHosts(value: string | undefined): HostId[];
+//# sourceMappingURL=hosts.d.ts.map

package/dist/hosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../src/hosts.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAI1C,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,EAAoC,CAAC;AAEnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAQ9D"}

package/dist/hosts.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const HOSTS = {
+    claude: { label: 'Claude Code', instructions: join(homedir(), '.claude', 'CLAUDE.md') },
+    codex: { label: 'Codex', instructions: join(homedir(), '.codex', 'AGENTS.md') },
+    opencode: { label: 'OpenCode', instructions: join(homedir(), '.config', 'opencode', 'AGENTS.md') },
+};
+export const ALL_HOSTS = ['claude', 'codex', 'opencode'];
+export function parseHosts(value) {
+    if (!value || value === 'all')
+        return ALL_HOSTS;
+    const requested = value.split(',').map((host) => host.trim().toLowerCase());
+    const invalid = requested.filter((host) => !(host in HOSTS));
+    if (invalid.length) {
+        throw new Error(`Unknown host(s): ${invalid.join(', ')}. Valid hosts: ${ALL_HOSTS.join(', ')}, all`);
+    }
+    return [...new Set(requested)];
+}
+//# sourceMappingURL=hosts.js.map

package/dist/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../src/hosts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAUjC,MAAM,CAAC,MAAM,KAAK,GAA6B;IAC7C,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE;IACvF,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE;IAC/E,QAAQ,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE;CACnG,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAEnE,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvG,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAa,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { writeAgentFoundation, removeAgentFoundation, agentFoundationPath, AGENT_FOUNDATION_FILE, AGENT_FOUNDATION_START, AGENT_FOUNDATION_END, AGENT_FOUNDATION_INSTRUCTIONS, } from './foundation.js';
+export { HOSTS, ALL_HOSTS, parseHosts } from './hosts.js';
+export type { HostId, HostInfo } from './hosts.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":"AAAA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { writeAgentFoundation, removeAgentFoundation, agentFoundationPath, AGENT_FOUNDATION_FILE, AGENT_FOUNDATION_START, AGENT_FOUNDATION_END, AGENT_FOUNDATION_INSTRUCTIONS, } from './foundation.js';
+export { HOSTS, ALL_HOSTS, parseHosts } from './hosts.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,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hugo.bastidas/agent-foundation",
+  "version": "0.1.0",
+  "description": "CLI to install personal agent conventions (AGENT_FOUNDATION.md) into Claude Code, Codex, and OpenCode global instructions",
+  "type": "module",
+  "bin": {
+    "agent-foundation": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "conventions",
+    "dotfiles"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/tools5290918/agent-foundations.git"
+  },
+  "homepage": "https://gitlab.com/tools5290918/agent-foundations",
+  "bugs": "https://gitlab.com/tools5290918/agent-foundations/-/issues",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}