contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/AGENTS.md

@@ -1,4 +1,4 @@
-# ContextOS — AI Project Operating System
+# ContextOS — Deterministic context compiler and policy engine for AI coding agents.
 
 You are working inside a project managed by **ContextOS**. This file is the **single source of truth** for how you must behave, think, and which skills to activate for every task.
 
@@ -22,6 +22,10 @@ State your answers explicitly:
 Skills loaded: react, typescript, ui-ux-pro, ponytail-mindset
 ```
 
+> **Anti-Spam Invariant**:
+> Declare `[DOMAIN: ...] [PHASE: ...] [ROLE: ...]` **strictly once** at the beginning of a user task or when transitioning between major phases (`DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP`).
+> **NEVER** prefix intermediate tool calls, file reads, grep searches, or step updates with this header.
+
 ---
 
 ## Skill Architecture (Context Efficiency)
@@ -372,6 +376,7 @@ These rules apply regardless of which skills are loaded:
 
 ### Engineering
 - No code before spec + plan are approved in interactive development (proceed directly to BUILD when standalone/benchmark code is requested)
+- **Fast-Track Exception**: For routine maintenance, operational tasks (git commands, version bump, lint fix, typo, single-line config tweaks, diagnostics, and direct questions), proceed directly without blocking on full `/spec` and `/plan` approval rituals.
 - Blast radius limited to files in current task's plan
 - One atomic commit per task
 

package/.agents/adapters/aider/export.js

@@ -1,28 +1,28 @@
-const fs = require('fs');
-const path = require('path');
-const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter, readMeaningfulMarkdown } = require('../shared.js');
-
-// Aider config goes to project root
-const CONF_FILE        = path.join(process.cwd(), '.aider.conf.yml');
-const CONVENTIONS_FILE = path.join(process.cwd(), 'CONVENTIONS.md');
-
 /**
- * Aider adapter — export.js
- *
- * Aider uses two complementary files:
- *   1. `.aider.conf.yml`   — config file that points Aider to conventions
- *   2. `CONVENTIONS.md`    — flat Markdown with all skills compiled in
- *
- * The config tells Aider to load CONVENTIONS.md via `read:` directive and
- * pre-loads it as a read-only context file on every session.
- *
- * Format spec: https://aider.chat/docs/config/aider_conf.html
+ * .agents/adapters/aider/export.js
+ * ContextOS Aider Pure Adapter (.aider.conf.yml & CONVENTIONS.md)
  */
 
+const fs = require('fs');
+const path = require('path');
+const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
+
+const GENERATOR_ID = 'aider@2';
+
+function describe() {
+  return {
+    name: 'aider',
+    version: '2.0.0',
+    description: 'Compiles configuration and conventions for Aider (.aider.conf.yml and CONVENTIONS.md)',
+    targetPattern: '{.aider.conf.yml,CONVENTIONS.md}',
+  };
+}
+
 function buildSkillSection(skillDir) {
-  const skillName  = path.basename(skillDir);
-  const skillMdPath  = path.join(skillDir, 'SKILL.md');
-  const yamlPath   = path.join(skillDir, 'skill.yaml');
+  const skillName = path.basename(skillDir);
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;
   let description = '';
@@ -47,91 +47,111 @@ function buildSkillSection(skillDir) {
   return `\n## Skill: ${title}\n${descLine}${skillRef}`;
 }
 
-function generateAiderConf() {
-  const conf = `# .aider.conf.yml
-# Auto-generated by: node .agents/ctx.js export aider
-# Source: .agents/core/skills/  ·  Do not edit manually.
-
-# Load project conventions as a read-only context file on every session
-read:
-  - CONVENTIONS.md
-
-# Recommended model settings (override as needed)
-# model: gpt-4o
-# editor-model: gpt-4o-mini
-
-# Auto-commit after every accepted change
-auto-commits: true
-
-# Show diffs in git format
-pretty: true
-`;
-  return conf;
-}
-
-function run() {
-  console.log('Starting Aider adapter export...');
-
-  // ── 1. Write .aider.conf.yml ─────────────────────────────────────────────────
-  fs.writeFileSync(CONF_FILE, generateAiderConf());
-  console.log(`Generated .aider.conf.yml → ${CONF_FILE}`);
-
-  // ── 2. Build CONVENTIONS.md ──────────────────────────────────────────────────
-  const sections = [];
-
-  sections.push(
-    `# CONVENTIONS.md — ContextOS Project Conventions\n\n` +
-    `> Auto-generated by: node .agents/ctx.js export aider\n` +
-    `> Source: .agents/core/skills/  ·  Do not edit manually.\n\n` +
-    `Aider loads this file as read-only context on every session.\n` +
-    `To keep your context window lean, load specific skill files on-demand using \`/read <path>\`.\n`
+function render(context) {
+  const projectRoot = context?.projectRoot || '.';
+  const agentsMdPath = fs.existsSync(path.join(projectRoot, '.agents', 'AGENTS.md'))
+    ? path.join(projectRoot, '.agents', 'AGENTS.md')
+    : AGENTS_MD_PATH;
+
+  const yamlProv = createProvenanceHeader({
+    generator: GENERATOR_ID,
+    sourceGraphHash: context?.sourceGraphHash,
+    profileId: context?.profileId,
+    profileHash: context?.profileHash,
+  }, 'yaml');
+
+  const mdProv = createProvenanceHeader({
+    generator: GENERATOR_ID,
+    sourceGraphHash: context?.sourceGraphHash,
+    profileId: context?.profileId,
+    profileHash: context?.profileHash,
+  }, 'markdown');
+
+  // 1. .aider.conf.yml
+  const aiderConfContent = [
+    yamlProv,
+    '# Load project conventions as a read-only context file on every session',
+    'read:',
+    '  - CONVENTIONS.md',
+    '',
+    '# Auto commit edits with standard git format',
+    'auto-commits: true',
+    'dirty-commits: true',
+    '',
+  ].join('\n');
+
+  // 2. CONVENTIONS.md
+  const convSections = [];
+  convSections.push(
+    mdProv +
+    `# ContextOS — Project Conventions for Aider\n\n` +
+    `> **Core law: Do not read everything. Read only what the current task requires.**\n\n`
   );
 
-  // Project rules with Step 0
-  sections.push(
-    `\n---\n\n## Project Rules\n\n` +
-    `### Step 0 — Identify Before Acting\n\n` +
-    `Before writing a single line of code or plan, state:\n` +
-    `\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n` +
-    `### Non-Negotiable Rules\n\n` +
-    `- **Zero-Assumption Investigation**: Never guess file paths or signatures. Inspect before modifying.\n` +
-    `- **Zero-Placeholder Production Code**: Never emit lazy stubs, \`// TODO\`, or partial code.\n` +
-    `- **Mandatory Proof-of-Work Verification**: Always run tests and validators before claiming completion.\n` +
-    `- **Surgical Blast Radius**: Modify only files strictly within scope.\n`
-  );
+  if (fs.existsSync(agentsMdPath)) {
+    const agentsMd = fs.readFileSync(agentsMdPath, 'utf8');
+    convSections.push(`## Core Operational Rules\n\n${agentsMd}\n\n---\n`);
+  }
 
-  // Skills Router Table
-  sections.push('\n---\n\n## Skill Router\n\n');
-  sections.push('Read the corresponding skill file only when the task matches the trigger:\n\n');
-  sections.push('| Trigger / Domain | Skill | On-Demand Command |\n');
-  sections.push('| --- | --- | --- |\n');
+  convSections.push(`\n## Available Specialist Skills\n\n` +
+    `Skills are loaded on demand. Use \`/read .agents/skills/<skill>/SKILL.md\` when needed.\n\n` +
+    `### Skill Index\n`);
 
-  const skills = collectSkillDirectories();
+  const skills = collectSkillDirectories(context?.profile);
   for (const skill of skills) {
-    const skillName = path.basename(skill);
-    const yamlPath = path.join(skill, 'skill.yaml');
-    let tags = skillName;
-    if (fs.existsSync(yamlPath)) {
-      const yaml = fs.readFileSync(yamlPath, 'utf8');
-      const rawTags = extractYamlField(yaml, 'tags');
-      if (rawTags) tags = rawTags.replace(/[\[\]]/g, '');
-    }
-    sections.push(`| \`${tags}\` | **${skillName}** | \`/read .agents/core/skills/${skillName}/SKILL.md\` |\n`);
+    const section = buildSkillSection(skill);
+    if (section) convSections.push(section);
   }
 
-  // Skills
-  sections.push('\n---\n\n# Skills\n');
-  let count = 0;
-  for (const skill of skills) {
-    const section = buildSkillSection(skill);
-    if (section) {
-      sections.push(section);
-      count++;
+  return [
+    {
+      path: '.aider.conf.yml',
+      content: aiderConfContent.replace(/\r\n/g, '\n'),
+      mediaType: 'application/yaml',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: [],
+      inputsHash: context?.sourceGraphHash || 'none',
+    },
+    {
+      path: 'CONVENTIONS.md',
+      content: convSections.join('\n').replace(/\r\n/g, '\n'),
+      mediaType: 'text/markdown',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: skills.map(s => path.basename(s)),
+      inputsHash: context?.sourceGraphHash || 'none',
+    },
+  ];
+}
+
+function validate(artifacts) {
+  const diagnostics = [];
+  for (const art of artifacts) {
+    if (!art.content || art.content.length === 0) {
+      diagnostics.push({ path: art.path, message: 'Empty artifact content' });
     }
   }
+  return diagnostics;
+}
 
-  fs.writeFileSync(CONVENTIONS_FILE, sections.join('\n'));
-  console.log(`Generated CONVENTIONS.md (${count} skills) → ${CONVENTIONS_FILE}`);
+function run(options = {}) {
+  const { loadCompilerContext } = require('../pure-compiler.js');
+  const projectRoot = options.projectRoot || '.';
+  const context = loadCompilerContext(projectRoot, options);
+  const artifacts = render(context);
+  const result = applyArtifacts(projectRoot, artifacts, { command: 'export aider', context });
+  console.log(`✓ Aider export complete: ${result.appliedCount} files applied (tx: ${result.txId})`);
+  return result;
 }
 
-module.exports = { run };
+const adapter = {
+  describe,
+  render,
+  validate,
+  run,
+};
+
+registerAdapter('aider', adapter);
+
+module.exports = adapter;

package/.agents/adapters/claude/export.js

@@ -1,55 +1,97 @@
+/**
+ * .agents/adapters/claude/export.js
+ * ContextOS Claude Code Pure Adapter
+ */
+
 const fs = require('fs');
 const path = require('path');
-const { collectSkillDirectories, resetDirectory, readMeaningfulMarkdown } = require('../shared.js');
+const { collectSkillDirectories, readMeaningfulMarkdown } = require('../shared.js');
+const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
 
-const GENERATED_SKILLS_PATH = path.join(__dirname, '..', '..', 'generated', 'claude', 'skills');
+const GENERATOR_ID = 'claude@2';
 
-/**
- * Claude Code skill format:
- * - Plain Markdown, no YAML frontmatter required
- * - First line is the skill name as an H1 comment
- * - Content is preserved as-is (Claude reads raw Markdown well)
- */
-function generateClaudeSkill(skillDir) {
+function describe() {
+  return {
+    name: 'claude',
+    version: '2.0.0',
+    description: 'Compiles clean markdown skills for Claude Code CLI',
+    targetPattern: '.agents/generated/claude/skills/**/SKILL.md',
+  };
+}
+
+function renderClaudeSkill(skillDir, context) {
   const skillName = path.basename(skillDir);
   const existingSkillMdPath = path.join(skillDir, 'SKILL.md');
-  const outputDir = path.join(GENERATED_SKILLS_PATH, skillName);
 
   if (!fs.existsSync(existingSkillMdPath)) {
-    console.log(`Skipping ${skillName} (no SKILL.md)`);
-    return;
+    return null;
   }
 
   let content = fs.readFileSync(existingSkillMdPath, 'utf8');
-  
+
   const examples = readMeaningfulMarkdown(path.join(skillDir, 'EXAMPLES.md'));
   if (examples) {
     content += '\n\n' + examples;
   }
-  
+
   const troubleshooting = readMeaningfulMarkdown(path.join(skillDir, 'TROUBLESHOOTING.md'));
   if (troubleshooting) {
     content += '\n\n' + troubleshooting;
   }
 
-  // Strip YAML frontmatter if present (Claude doesn't need it)
+  // Strip YAML frontmatter
   content = content.replace(/^---[\s\S]*?---\r?\n/, '');
 
-  // Write the cleaned Markdown
-  fs.mkdirSync(outputDir, { recursive: true });
-  fs.writeFileSync(path.join(outputDir, 'SKILL.md'), content.trimStart());
-  console.log(`Generated SKILL.md for ${skillName} (claude)`);
+  return {
+    path: `.agents/generated/claude/skills/${skillName}/SKILL.md`,
+    content: content.trimStart().replace(/\r\n/g, '\n'),
+    mediaType: 'text/markdown',
+    kind: 'generated-adapter',
+    generator: GENERATOR_ID,
+    sourceSkillIds: [skillName],
+    inputsHash: context?.sourceGraphHash || 'none',
+  };
 }
 
-function run() {
-  console.log('Starting Claude adapter export...');
-  resetDirectory(GENERATED_SKILLS_PATH);
+function render(context) {
+  const skills = collectSkillDirectories(context?.profile);
+  const artifacts = [];
 
-  const skills = collectSkillDirectories();
   for (const skill of skills) {
-    generateClaudeSkill(skill);
+    const art = renderClaudeSkill(skill, context);
+    if (art) artifacts.push(art);
   }
-  console.log('Export complete. Skills are in generated/claude/skills');
+
+  return artifacts;
+}
+
+function validate(artifacts) {
+  const diagnostics = [];
+  for (const art of artifacts) {
+    if (!art.content || art.content.length === 0) {
+      diagnostics.push({ path: art.path, message: 'Empty artifact content' });
+    }
+  }
+  return diagnostics;
 }
 
-module.exports = { run };
+function run(options = {}) {
+  const { loadCompilerContext } = require('../pure-compiler.js');
+  const projectRoot = options.projectRoot || '.';
+  const context = loadCompilerContext(projectRoot, options);
+  const artifacts = render(context);
+  const result = applyArtifacts(projectRoot, artifacts, { command: 'export claude', context });
+  console.log(`✓ Claude export complete: ${result.appliedCount} files applied (tx: ${result.txId})`);
+  return result;
+}
+
+const adapter = {
+  describe,
+  render,
+  validate,
+  run,
+};
+
+registerAdapter('claude', adapter);
+
+module.exports = adapter;

package/.agents/adapters/copilot/export.js

@@ -1,24 +1,28 @@
-const fs = require('fs');
-const path = require('path');
-const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter, readMeaningfulMarkdown } = require('../shared.js');
-
-// GitHub Copilot reads from .github/copilot-instructions.md
-const OUTPUT_FILE = path.join(process.cwd(), '.github', 'copilot-instructions.md');
-
 /**
- * GitHub Copilot adapter — export.js
- *
- * Copilot reads `.github/copilot-instructions.md` as a plain Markdown file.
- * We compile AGENTS.md + all skills into one document with clear section
- * headings so Copilot can reference them contextually.
- *
- * Format spec: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-instructions
+ * .agents/adapters/copilot/export.js
+ * ContextOS GitHub Copilot Pure Adapter (.github/copilot-instructions.md)
  */
 
+const fs = require('fs');
+const path = require('path');
+const { collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
+
+const GENERATOR_ID = 'copilot@2';
+
+function describe() {
+  return {
+    name: 'copilot',
+    version: '2.0.0',
+    description: 'Compiles instructions for GitHub Copilot (.github/copilot-instructions.md)',
+    targetPattern: '.github/copilot-instructions.md',
+  };
+}
+
 function buildSkillSection(skillDir) {
-  const skillName  = path.basename(skillDir);
-  const skillMdPath  = path.join(skillDir, 'SKILL.md');
-  const yamlPath   = path.join(skillDir, 'skill.yaml');
+  const skillName = path.basename(skillDir);
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;
   let description = '';
@@ -43,38 +47,39 @@ function buildSkillSection(skillDir) {
   return `\n### ${title}\n${descLine}${skillRef}`;
 }
 
-function run() {
-  console.log('Starting GitHub Copilot adapter export...');
-
+function render(context) {
   const lines = [];
 
-  // ── Header ───────────────────────────────────────────────────────────────────
+  const prov = createProvenanceHeader({
+    generator: GENERATOR_ID,
+    sourceGraphHash: context?.sourceGraphHash,
+    profileId: context?.profileId,
+    profileHash: context?.profileHash,
+  });
+
   lines.push(
-    `# GitHub Copilot Instructions — ContextOS\n`,
-    `<!-- Auto-generated by: node .agents/ctx.js export copilot -->\n`,
-    `<!-- Source: .agents/core/skills/  ·  Do not edit manually. -->\n\n`
+    prov +
+    `# GitHub Copilot Instructions — ContextOS\n\n` +
+    `## Project Rules\n\n` +
+    `### Step 0 — Identify Before Acting\n\n` +
+    `Before writing a single line of code or plan, state:\n` +
+    `\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n` +
+    `> **Anti-Spam Invariant**: Declare this strictly once at the start of a task or phase. Never repeat before intermediate tool calls or step updates.\n\n` +
+    `### Non-Negotiable Rules\n\n` +
+    `- **Zero-Assumption Investigation**: Never guess file paths or signatures. Inspect before modifying.\n` +
+    `- **Zero-Placeholder Production Code**: Never emit lazy stubs, \`// TODO\`, or partial code.\n` +
+    `- **Mandatory Proof-of-Work Verification**: Always run tests and validators before claiming completion.\n` +
+    `- **Surgical Blast Radius**: Modify only files strictly within scope.\n` +
+    `- **Fast-Track Exception**: Routine maintenance, git commands, version bumps, typo fixes, and diagnostics skip spec/plan ceremonies.\n\n` +
+    `---\n\n` +
+    `## Skills Library\n\n` +
+    `ContextOS uses on-demand progressive disclosure. Read the relevant \`SKILL.md\` file only when your task matches the trigger.\n\n` +
+    `### Skill Routing Table\n\n` +
+    `| Trigger / Domain | Skill | Path |\n` +
+    `| --- | --- | --- |\n`
   );
 
-  // ── Project rules & Step 0 ───────────────────────────────────────────────────
-  lines.push(`## Project Rules\n\n`);
-  lines.push(`### Step 0 — Identify Before Acting\n\n`);
-  lines.push(`Before writing a single line of code or plan, state:\n`);
-  lines.push(`\`\`\`\n1. WHAT DOMAIN?   → Frontend / Backend / Architecture / Full-Stack / DevOps\n2. WHAT PHASE?    → Define / Plan / Build / Verify / Review / Ship\n3. WHAT ROLE?     → Declare specialist role for this phase\n\`\`\`\n\n`);
-  lines.push(`### Non-Negotiable Rules\n\n`);
-  lines.push(`- **Zero-Assumption Investigation**: Never guess file paths or signatures. Inspect before modifying.\n`);
-  lines.push(`- **Zero-Placeholder Production Code**: Never emit lazy stubs, \`// TODO\`, or partial code.\n`);
-  lines.push(`- **Mandatory Proof-of-Work Verification**: Always run tests and validators before claiming completion.\n`);
-  lines.push(`- **Surgical Blast Radius**: Modify only files strictly within scope.\n\n`);
-  lines.push(`---\n`);
-
-  // ── Skills ───────────────────────────────────────────────────────────────────
-  lines.push(`\n## Skills Library\n\n`);
-  lines.push(`ContextOS uses on-demand progressive disclosure. Read the relevant \`SKILL.md\` file only when your task matches the trigger.\n\n`);
-  lines.push(`### Skill Routing Table\n\n`);
-  lines.push(`| Trigger / Domain | Skill | Path |\n`);
-  lines.push(`| --- | --- | --- |\n`);
-
-  const skills = collectSkillDirectories();
+  const skills = collectSkillDirectories(context?.profile);
   for (const skill of skills) {
     const skillName = path.basename(skill);
     const yamlPath = path.join(skill, 'skill.yaml');
@@ -89,19 +94,53 @@ function run() {
   }
   lines.push(`\n---\n`);
 
-  let count = 0;
   for (const skill of skills) {
     const section = buildSkillSection(skill);
     if (section) {
       lines.push(section);
-      count++;
     }
   }
 
-  // ── Write ────────────────────────────────────────────────────────────────────
-  fs.mkdirSync(path.dirname(OUTPUT_FILE), { recursive: true });
-  fs.writeFileSync(OUTPUT_FILE, lines.join(''));
-  console.log(`Generated .github/copilot-instructions.md (${count} skills) → ${OUTPUT_FILE}`);
+  return [
+    {
+      path: '.github/copilot-instructions.md',
+      content: lines.join('').replace(/\r\n/g, '\n'),
+      mediaType: 'text/markdown',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: skills.map(s => path.basename(s)),
+      inputsHash: context?.sourceGraphHash || 'none',
+    },
+  ];
+}
+
+function validate(artifacts) {
+  const diagnostics = [];
+  for (const art of artifacts) {
+    if (!art.content || art.content.length === 0) {
+      diagnostics.push({ path: art.path, message: 'Empty artifact content' });
+    }
+  }
+  return diagnostics;
 }
 
-module.exports = { run };
+function run(options = {}) {
+  const { loadCompilerContext } = require('../pure-compiler.js');
+  const projectRoot = options.projectRoot || '.';
+  const context = loadCompilerContext(projectRoot, options);
+  const artifacts = render(context);
+  const result = applyArtifacts(projectRoot, artifacts, { command: 'export copilot', context });
+  console.log(`✓ Copilot export complete: ${result.appliedCount} files applied (tx: ${result.txId})`);
+  return result;
+}
+
+const adapter = {
+  describe,
+  render,
+  validate,
+  run,
+};
+
+registerAdapter('copilot', adapter);
+
+module.exports = adapter;