contextos-agents 1.5.0

package/.agents/ctx.js

@@ -0,0 +1,370 @@
+/**
+ * .agents/ctx.js
+ * ContextOS — Main CLI Dispatcher and Context Engine
+ *
+ * Provides subcommands for:
+ *   - export: compiling skills for diverse agent formats (Gemini, Claude, Cursor, Copilot, Aider, Zed)
+ *   - profile: managing project profiles (list, show, apply, remove)
+ *   - resolve: dynamic on-demand skill resolution for prompts and file lists
+ *   - index: progressive skills index generation
+ *   - detect: tech stack detection
+ *   - validate / audit: skill source, frontmatter, and sync validation
+ *   - skill: plugin management (add, remove, list, search)
+ */
+
+const process = require('process');
+const path = require('path');
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  printHelp();
+  process.exit(1);
+}
+
+/**
+ * Prints usage instructions and supported CLI commands.
+ */
+function printHelp() {
+  console.log('Usage: node ctx.js <command> [args...]');
+  console.log('');
+  console.log('Commands:');
+  console.log('  export gemini [--profile <p>]   Compile skills for Gemini / Antigravity');
+  console.log('  export claude [--profile <p>]   Compile skills for Claude Code');
+  console.log('  export cursor [--profile <p>]   Compile skills → .cursorrules & .cursor/rules/*.mdc');
+  console.log('  export copilot [--profile <p>]  Compile skills → .github/copilot-instructions.md');
+  console.log('  export aider [--profile <p>]    Compile skills → .aider.conf.yml + CONVENTIONS.md');
+  console.log('  export zed [--profile <p>]      Compile skills → .zed/rules.md & .zed/prompts/*.md');
+  console.log('  export all [--profile <p>]      Compile skills for all supported agents');
+  console.log('  profile list                    List available project profiles');
+  console.log('  profile show <name>             Show profile configuration');
+  console.log('  profile apply <name>            Apply a profile (e.g. mvp, startup, enterprise, frontend)');
+  console.log('  profile remove                  Remove active profile filter');
+  console.log('  resolve <prompt>                Resolve minimal skills needed for a task');
+  console.log('  index                           Generate progressive skills-index.json');
+  console.log('  detect                          Auto-detect project tech stack');
+  console.log('  audit                           Alias for validate (check skills)');
+  console.log('  validate                        Validate skill sources, frontmatter, deps & sync');
+  console.log('  clean-worktrees                 Clean up lingering .swarm-worktrees and swarm/* branches');
+  console.log('  install-skill <ref>             Alias for skill add (install a plugin)');
+  console.log('  skill add   <ref>               Install a plugin skill (GitHub or npm)');
+  console.log('  skill remove <name>             Uninstall a plugin skill');
+  console.log('  skill list                      List installed skills (builtin + plugins)');
+  console.log('  skill search [query]            Search the community skill registry');
+  console.log('');
+  console.log('Plugin ref formats:');
+  console.log('  username/repo                    GitHub repo root SKILL.md');
+  console.log('  username/repo@commit             GitHub repo pinned to a commit');
+  console.log('  username/repo/path/to/skill      GitHub subpath skill');
+  console.log('  npm-package-name                 npm package');
+  console.log('  @scope/npm-package               scoped npm package');
+  console.log('');
+  console.log('Examples:');
+  console.log('  node .agents/ctx.js resolve "Build an accessible modal component"');
+  console.log('  node .agents/ctx.js profile list');
+  console.log('  node .agents/ctx.js profile apply mvp');
+  console.log('  node .agents/ctx.js detect');
+  console.log('  node .agents/ctx.js export all --profile frontend');
+  console.log('  node .agents/ctx.js skill add alice/my-cool-skill');
+}
+
+// ── Helper: parse checksum flag ─────────────────────────────────────────────
+function extractChecksum(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--checksum=')) {
+      return argv[i].split('=')[1];
+    }
+    if (argv[i] === '--checksum' && argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      return argv[i + 1];
+    }
+  }
+  return undefined;
+}
+
+const command = args[0];
+const target  = args[1];
+
+// ── export ────────────────────────────────────────────────────────────────────
+if (command === 'export') {
+  const profileFlagIdx = args.indexOf('--profile');
+  if (profileFlagIdx !== -1 && args[profileFlagIdx + 1]) {
+    const profiles = require('./profiles.js');
+    const profileName = args[profileFlagIdx + 1];
+    try {
+      profiles.applyProfile(profileName);
+      console.log(`[PROFILE] Applied profile '${profileName}' for this export.\n`);
+    } catch (err) {
+      console.error(`[ERROR] ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  const runGemini = () => {
+    const adapter = require('./adapters/gemini/export.js');
+    adapter.run();
+  };
+
+  const runClaude = () => {
+    const adapter = require('./adapters/claude/export.js');
+    adapter.run();
+  };
+
+  const runCursor = () => {
+    const adapter = require('./adapters/cursor/export.js');
+    adapter.run();
+  };
+
+  const runCopilot = () => {
+    const adapter = require('./adapters/copilot/export.js');
+    adapter.run();
+  };
+
+  const runAider = () => {
+    const adapter = require('./adapters/aider/export.js');
+    adapter.run();
+  };
+
+  const runZed = () => {
+    const adapter = require('./adapters/zed/export.js');
+    adapter.run();
+  };
+
+  if (target === 'gemini') {
+    runGemini();
+  } else if (target === 'claude') {
+    runClaude();
+  } else if (target === 'cursor') {
+    runCursor();
+  } else if (target === 'copilot') {
+    runCopilot();
+  } else if (target === 'aider') {
+    runAider();
+  } else if (target === 'zed') {
+    runZed();
+  } else if (target === 'all') {
+    console.log('Exporting skills for all agents...\n');
+    runGemini();
+    console.log('');
+    runClaude();
+    console.log('');
+    runCursor();
+    console.log('');
+    runCopilot();
+    console.log('');
+    runAider();
+    console.log('');
+    runZed();
+    console.log('\nAll exports complete.');
+  } else {
+    console.error(`Adapter for '${target}' not implemented yet.`);
+    console.error('Supported agents: gemini, claude, cursor, copilot, aider, zed, all');
+    process.exit(1);
+  }
+
+// ── profile ───────────────────────────────────────────────────────────────────
+} else if (command === 'profile') {
+  const subcommand = args[1] || 'list';
+  const profileName = args[2];
+  const profiles = require('./profiles.js');
+
+  if (subcommand === 'list') {
+    const list = profiles.listProfiles();
+    const active = profiles.getActiveProfile();
+    console.log('\nAvailable ContextOS Profiles:\n');
+    for (const p of list) {
+      const isActive = active && active.profile === p.id;
+      const marker = isActive ? '● [ACTIVE]' : '○';
+      console.log(`  ${marker} ${p.id.padEnd(12)} - ${p.name}: ${p.description}`);
+      if (p.exclude_skills && p.exclude_skills.length > 0) {
+        console.log(`      Excludes: ${p.exclude_skills.join(', ')}`);
+      }
+    }
+    console.log('\nApply a profile: node .agents/ctx.js profile apply <name>');
+    if (active) {
+      console.log(`Current active profile: ${active.profile} (${active.name})`);
+    }
+    console.log('');
+  } else if (subcommand === 'show') {
+    const name = profileName || (profiles.getActiveProfile() || {}).profile;
+    if (!name) {
+      console.error('[ERROR] Usage: node ctx.js profile show <name>');
+      process.exit(1);
+    }
+    const profile = profiles.getProfile(name);
+    if (!profile) {
+      console.error(`[ERROR] Profile '${name}' not found.`);
+      process.exit(1);
+    }
+    console.log(`\nProfile: ${profile.name} (${profile.id})`);
+    console.log(`Description: ${profile.description}`);
+    console.log(`Preferred Skills: ${(profile.prefer_skills || []).join(', ') || 'none'}`);
+    console.log(`Excluded Skills: ${(profile.exclude_skills || []).join(', ') || 'none'}\n`);
+  } else if (subcommand === 'apply') {
+    if (!profileName) {
+      console.error('[ERROR] Usage: node ctx.js profile apply <name>');
+      process.exit(1);
+    }
+    try {
+      const applied = profiles.applyProfile(profileName);
+      console.log(`\n✓ Profile '${applied.name}' successfully applied!`);
+      console.log(`  Excluded skills: ${(applied.exclude_skills || []).join(', ') || 'none'}`);
+      console.log('  Run: node .agents/ctx.js export all  (to rebuild exports with this profile)\n');
+    } catch (err) {
+      console.error(`[ERROR] ${err.message}`);
+      process.exit(1);
+    }
+  } else if (subcommand === 'remove' || subcommand === 'reset') {
+    const removed = profiles.removeActiveProfile();
+    if (removed) {
+      console.log('\n✓ Active profile filter removed. All skills will be included.\n');
+    } else {
+      console.log('\nNo active profile was set.\n');
+    }
+  } else {
+    console.error(`Unknown profile subcommand: ${subcommand}`);
+    console.error('Valid subcommands: list, show, apply, remove');
+    process.exit(1);
+  }
+
+// ── resolve ───────────────────────────────────────────────────────────────────
+} else if (command === 'resolve') {
+  const resolver = require('./resolver.js');
+  const promptArgs = args.slice(1).filter(a => !a.startsWith('-')).join(' ');
+  const filesIdx = args.indexOf('--files');
+  const files = filesIdx !== -1 && args[filesIdx + 1] ? args[filesIdx + 1].split(',') : [];
+  const phaseIdx = args.indexOf('--phase');
+  const phase = phaseIdx !== -1 && args[phaseIdx + 1] ? args[phaseIdx + 1] : 'Build';
+
+  const result = resolver.resolveSkills({ prompt: promptArgs, files, phase });
+  console.log('\n══════════════════════════════════════════');
+  console.log('  ContextOS — Dynamic Skill Resolution');
+  console.log('══════════════════════════════════════════');
+  console.log(resolver.formatDeclaration(result));
+  console.log('──────────────────────────────────────────\n');
+
+// ── index ─────────────────────────────────────────────────────────────────────
+} else if (command === 'index') {
+  const resolver = require('./resolver.js');
+  const index = resolver.buildSkillIndex(process.cwd());
+  const fs = require('fs');
+  const indexPath = path.join(process.cwd(), '.agents', 'skills-index.json');
+  fs.writeFileSync(indexPath, JSON.stringify({ version: '1.0.0', skills: index }, null, 2) + '\n');
+  console.log(`\nGenerated progressive skills index with ${index.length} skills → .agents/skills-index.json\n`);
+
+// ── detect ────────────────────────────────────────────────────────────────────
+} else if (command === 'detect') {
+  const profiles = require('./profiles.js');
+  const detection = profiles.detectStack(process.cwd());
+  console.log('\nContextOS — Tech Stack Detection\n');
+  if (detection.detected.length === 0) {
+    console.log('  Detected stack: Generic / Vanilla JavaScript');
+  } else {
+    console.log(`  Detected stack: ${detection.detected.join(', ')}`);
+  }
+  console.log(`  Recommended Profile: ${detection.recommendedProfile}`);
+  console.log(`  Recommended Skills: ${detection.recommendedSkills.join(', ')}`);
+  console.log(`\nApply recommended profile:\n  node .agents/ctx.js profile apply ${detection.recommendedProfile}\n`);
+
+// ── validate / audit ──────────────────────────────────────────────────────────
+} else if (command === 'validate' || command === 'audit') {
+  const validator = require('./validate.js');
+  validator.run();
+
+// ── install-skill ─────────────────────────────────────────────────────────────
+} else if (command === 'install-skill') {
+  const ref = args[1];
+  const dryRun = args.includes('--dry-run');
+  const checksum = extractChecksum(args);
+  const plugins = require('./plugins.js');
+  
+  if (!ref) {
+    console.error('[ERROR] Usage: ctx.js install-skill <ref> [--checksum <sha256>]');
+    process.exit(1);
+  }
+  
+  plugins.add(ref, { dryRun, checksum }).catch(err => {
+    console.error(`[ERROR] ${err.message}`);
+    process.exit(1);
+  });
+
+// ── skill ─────────────────────────────────────────────────────────────────────
+} else if (command === 'skill') {
+  const subcommand = args[1];
+  const ref        = args[2];
+  const dryRun     = args.includes('--dry-run');
+  const checksum   = extractChecksum(args);
+  const plugins    = require('./plugins.js');
+
+  if (!subcommand || subcommand === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (subcommand === 'add') {
+    plugins.add(ref, { dryRun, checksum }).catch(err => {
+      console.error(`[ERROR] ${err.message}`);
+      process.exit(1);
+    });
+  } else if (subcommand === 'remove') {
+    plugins.remove(ref);
+  } else if (subcommand === 'list') {
+    plugins.list();
+  } else if (subcommand === 'search') {
+    const query = args.slice(2).join(' ');
+    plugins.search(query).catch(err => {
+      console.error(`[ERROR] ${err.message}`);
+      process.exit(1);
+    });
+  } else {
+    console.error(`Unknown skill subcommand: ${subcommand}`);
+    console.error('Valid subcommands: add, remove, list, search');
+    process.exit(1);
+  }
+
+// ── clean-worktrees ──────────────────────────────────────────────────────────
+} else if (command === 'clean-worktrees' || command === 'clean') {
+  const { execSync } = require('child_process');
+  const fs = require('fs');
+  const path = require('path');
+  const rootDir = path.resolve(__dirname, '..');
+  const wtDir = path.join(rootDir, '.swarm-worktrees');
+  
+  console.log('Cleaning up ContextOS swarm worktrees and branches...');
+  try {
+    execSync('git worktree prune', { cwd: rootDir, stdio: 'pipe' });
+  } catch {}
+
+  let branchCount = 0;
+  try {
+    const branches = execSync('git branch --list "swarm/*"', { cwd: rootDir, encoding: 'utf-8' });
+    const list = branches.split('\n').map(b => b.replace(/^[*+\s]+/, '').trim()).filter(Boolean);
+    for (const b of list) {
+      try {
+        execSync(`git branch -D "${b}"`, { cwd: rootDir, stdio: 'pipe' });
+        branchCount++;
+      } catch {}
+    }
+  } catch {}
+
+  let dirCount = 0;
+  if (fs.existsSync(wtDir)) {
+    try {
+      const entries = fs.readdirSync(wtDir);
+      for (const e of entries) {
+        const full = path.join(wtDir, e);
+        try {
+          fs.rmSync(full, { recursive: true, force: true });
+          dirCount++;
+        } catch {}
+      }
+    } catch {}
+  }
+
+  console.log(`✓ Cleaned up ${dirCount} worktree directory(ies) and ${branchCount} swarm branch(es).`);
+
+// ── unknown ───────────────────────────────────────────────────────────────────
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run: node ctx.js (no args) to see help');
+  process.exit(1);
+}

package/.agents/generated/claude/skills/adapters/SKILL.md

@@ -0,0 +1,126 @@
+# agent-adapters
+
+## Overview
+
+Unified cross-agent configuration engine. Translates single ContextOS source rules into optimized native formats for Claude Code (CLAUDE.md), Gemini (.agents/skills), Cursor (.cursorrules, .cursor/rules/*.mdc), GitHub Copilot, Zed, Aider, and Continue.
+
+## When to Use
+
+Activate when configuring, synchronizing, or exporting agent rules and skills across multiple IDEs and AI programming assistants.
+
+## Rules & Patterns
+
+ContextOS is agent-agnostic. This skill generates the right config format for any AI agent.
+
+## Supported Agents
+
+| Agent | Config File | Format |
+| --- | --- | --- |
+| **Gemini** | `.agents/AGENTS.md` + `.agents/skills/` | Markdown + YAML skills |
+| **Claude Code** | `CLAUDE.md` | Single markdown file |
+| **GitHub Copilot / Codex** | `AGENTS.md` (root) | Markdown |
+| **Cursor** | `.cursorrules` | Plain text rules |
+| **Aider** | `.aider.conf.yml` | YAML config |
+| **Continue** | `.continuerules` | Markdown rules |
+| **OpenHands** | `openhands.json` | JSON config |
+| **Roo Code** | `.roo/` | Directory with rules |
+| **Windsurf** | `.windsurfrules` | Plain text rules |
+
+## Generation Command
+
+`ctx adapt [agent]` — Generate config for a specific agent.
+
+`ctx adapt all` — Generate configs for all supported agents.
+
+## Adapter Logic
+
+### For Claude Code (`CLAUDE.md`)
+
+Compile into a single markdown file:
+
+1. Project overview from `docs/PRD.md` (summary only)
+2. Architecture summary from `docs/ARCHITECTURE.md`
+3. Coding rules from loaded skills
+4. Active Decision Records
+5. Current tasks from `docs/TASKS.md`
+
+### For Gemini (`.agents/AGENTS.md`)
+
+Already native format. Just ensure:
+
+1. `AGENTS.md` references the skill directory
+2. Skills have proper SKILL.md with frontmatter
+3. Context Manager rules are in AGENTS.md
+
+### For Cursor (`.cursorrules`)
+
+Compile into a flat text file:
+
+1. Project context (condensed)
+2. Coding style rules
+3. Framework-specific instructions
+4. Anti-patterns to avoid
+
+### For Aider (`.aider.conf.yml`)
+
+```yaml
+read:
+  - docs/ARCHITECTURE.md
+  - docs/API.md
+  - docs/PROJECT_GRAPH.md
+conventions:
+  - {{coding rules from skills}}
+```
+
+## Sync Rules
+
+- Adapters read from the canonical ContextOS documents
+- Never edit adapter output files directly
+- Re-run `ctx adapt` after any document change
+- Each adapter file includes a header: `# Generated by ContextOS — do not edit directly`
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+# adapters Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Multi-Agent Configuration
+
+### Anti-pattern: Manually Syncing 6 Different Rule Files
+
+```text
+Editing .cursorrules, then forgetting to update CLAUDE.md, then editing copilot-instructions.md.
+Rules diverge across teammates using different IDEs.
+```
+
+### Best practice: ContextOS Standard (Single Source of Truth)
+
+```bash
+# Edit skills once in .agents/core/skills/
+# Compile to all agents with one command:
+node .agents/ctx.js export all
+# Automatically updates .cursorrules, CLAUDE.md, copilot-instructions.md, .aider, .zed
+```
+
+# adapters Troubleshooting & Common Mistakes
+
+## 1. Overwriting Custom Configs
+
+- **Symptom**: Custom non-ContextOS rules wiped out during export.
+- **Root Cause**: Running export with force flags over unmanaged files.
+- **Fix**: Keep custom project overrides in dedicated config files or use plugin skills.

package/.agents/generated/claude/skills/architecture-diagrams/SKILL.md

@@ -0,0 +1,101 @@
+# architecture-diagrams
+
+## Overview
+
+Visual architecture engineering skill inspired by [tt-a1i/archify](https://github.com/tt-a1i/archify). Replaces static ASCII art and rigid default diagrams with crisp, self-contained SVG and responsive HTML diagrams featuring modern dark-mode palettes, pulse animations for event flows, and strict C4-model component boundaries.
+
+## When to Use
+
+Activate whenever:
+
+- Designing or explaining distributed systems, microservices, or full-stack architectures.
+- Visualizing complex auth flows (OAuth2, PKCE), multi-step payment sagas, or CDC outbox data pipelines.
+- User requests an architecture diagram, flow chart, sequence diagram, or visual system design.
+
+## Rules & Patterns
+
+### 1. Diagram Types Supported
+
+1. **System Landscape / C4 Container Diagram**:
+   - Clients (Web, Mobile, Third-party) → API Gateway / CDN → Microservices / Serverless → Storage / Event Brokers.
+2. **Sequence Flow Diagram**:
+   - Step-by-step lifecycles with synchronous requests, asynchronous pub/sub events, and compensating transactions.
+3. **Data Pipeline & Event-Driven Topology**:
+   - Primary DB → Transactional Outbox → CDC (Debezium) → Kafka Topic → Consumers → Materialized Views.
+
+### 2. Aesthetic & Visual Invariants
+
+- **Dark Theme by Default**: Surface `#0B0F19`, containers `#1E293B`, borders `#334155`, text `#F8FAFC`.
+- **Semantic Component Accents**:
+  - Client / Frontend: Sky Blue (`#38BDF8`)
+  - API Gateway / Router: Indigo (`#818CF8`)
+  - Business Services: Emerald Green (`#34D399`)
+  - Databases / Storage: Amber / Orange (`#F59E0B`)
+  - Message Brokers / Event Buses: Purple (`#A855F7`)
+- **Active Data-Flow Motion**: Use subtle CSS `@keyframes` on SVG stroke dashes (`stroke-dasharray`, `stroke-dashoffset`) to show active direction of messages and data streams.
+
+---
+
+## Code Examples
+
+### Standalone Animated SVG Data-Flow Pattern
+
+```html
+<svg viewBox="0 0 800 200" xmlns="http://www.w3.org/2000/svg" class="bg-slate-950 rounded-xl p-4 w-full">
+  <defs>
+    <style>
+      .flow-line { stroke: #38BDF8; stroke-width: 2; stroke-dasharray: 6,6; animation: flow 1.5s linear infinite; }
+      @keyframes flow { to { stroke-dashoffset: -12; } }
+      .box { fill: #1E293B; stroke: #334155; stroke-width: 1.5; rx: 8; }
+      .text-title { fill: #F8FAFC; font-family: sans-serif; font-size: 14px; font-weight: 600; }
+      .text-sub { fill: #94A3B8; font-family: monospace; font-size: 11px; }
+    </style>
+  </defs>
+
+  <!-- Client Node -->
+  <rect x="30" y="70" width="160" height="60" class="box" />
+  <text x="110" y="96" text-anchor="middle" class="text-title">Next.js Client</text>
+  <text x="110" y="114" text-anchor="middle" class="text-sub">React 19 / RSC</text>
+
+  <!-- Data Flow -->
+  <line x1="190" y1="100" x2="330" y2="100" class="flow-line" />
+
+  <!-- API Gateway -->
+  <rect x="330" y="70" width="160" height="60" class="box" />
+  <text x="410" y="96" text-anchor="middle" class="text-title">API Gateway</text>
+  <text x="410" y="114" text-anchor="middle" class="text-sub">Auth & Rate Limiting</text>
+
+  <!-- Flow to Database -->
+  <line x1="490" y1="100" x2="630" y2="100" class="flow-line" />
+
+  <!-- Database -->
+  <rect x="630" y="70" width="140" height="60" class="box" />
+  <text x="700" y="96" text-anchor="middle" class="text-title">PostgreSQL</text>
+  <text x="700" y="114" text-anchor="middle" class="text-sub">Prisma / Outbox</text>
+</svg>
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Diagram clearly identifies all component boundaries, ports, and protocols.
+- [ ] Visual hierarchy is unambiguous (clients on left/top, storage on right/bottom).
+- [ ] Motion/animation is purposeful and lightweight (no heavy canvas frameworks).
+- [ ] Accessible: nodes include semantic labels and readable color contrast.
+
+---
+
+## Common Mistakes
+
+- **Messy cross-overs**: Laying out 20 boxes with overlapping lines instead of grouping into clean C4 layers.
+- **Unlabeled connections**: Lines without protocol (HTTPS, gRPC, WSS) or event payload descriptions.
+- **Overwhelming detail**: Drawing internal class diagrams when the user asked for a system-level overview.
+
+---
+
+## Integration Notes
+
+- Triggers during `system-design` and `microservices` planning phases.
+- Used to generate visual architecture artifacts in Markdown walkthroughs and specs.
+- Pairs with `ui-ux-pro` for consistent aesthetic styling.