@ghl-ai/aw 0.1.0

package/integrate.mjs

@@ -0,0 +1,466 @@
+// integrate.mjs — Generate commands for all IDEs, instructions (CLAUDE.md, AGENTS.md)
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import * as fmt from './fmt.mjs';
+
+// AW CLI commands to generate
+const AW_COMMANDS = [
+  { name: 'pull',   description: 'Pull agents & skills from registry',           hint: '<path>' },
+  { name: 'push',   description: 'Push local changes to registry',               hint: '<path>' },
+  { name: 'status', description: 'Show workspace sync status',                   hint: '' },
+  { name: 'drop',   description: 'Stop syncing a path',                          hint: '<path>' },
+  { name: 'search', description: 'Search local and remote registry',             hint: '<query>' },
+  { name: 'nuke',   description: 'Remove entire .aw_registry/',            hint: '' },
+];
+
+/**
+ * Generate /aw:* commands directly into namespace commands/ dirs.
+ * Writes CLI commands + agent invoke commands alongside hand-written commands.
+ * link.mjs symlinks everything from commands/ → .claude/commands/aw/ for discovery.
+ *
+ * A .generated-manifest.json tracks which files were generated so they can be
+ * cleaned on rebuild without needing filename prefixes.
+ */
+export function generateCommands(cwd) {
+  const awDir = join(cwd, '.aw_registry');
+
+  // Clean old .generated-commands if it exists (migration)
+  const oldGenDir = join(awDir, '.generated-commands');
+  if (existsSync(oldGenDir)) rmSync(oldGenDir, { recursive: true, force: true });
+
+  let count = 0;
+  const namespaces = listNamespaceDirs(awDir);
+
+  for (const ns of namespaces) {
+    const commandsDir = join(awDir, ns, 'commands');
+    mkdirSync(commandsDir, { recursive: true });
+
+    // 1. CLI commands
+    for (const cmd of AW_COMMANDS) {
+      const fileName = `${cmd.name}.md`;
+      // Skip if a hand-written command with same name exists
+      if (existsSync(join(commandsDir, fileName))) continue;
+
+      const content = [
+        '---',
+        `name: aw:${cmd.name}`,
+        `description: ${cmd.description}`,
+        cmd.hint ? `argument-hint: "${cmd.hint}"` : null,
+        '---',
+        '',
+        'Run the following command:',
+        '',
+        '```',
+        `node bin/aw ${cmd.name} $ARGUMENTS`,
+        '```',
+        '',
+      ].filter(v => v !== null).join('\n');
+
+      writeFileSync(join(commandsDir, fileName), content);
+      count++;
+    }
+
+  }
+
+  // Codex skills — .agents/skills/<name>/SKILL.md
+  const agentsSkillsDir = join(cwd, '.agents/skills');
+  mkdirSync(agentsSkillsDir, { recursive: true });
+  for (const cmd of AW_COMMANDS) {
+    const skillDir = join(agentsSkillsDir, cmd.name);
+    mkdirSync(skillDir, { recursive: true });
+    const content = [
+      '---',
+      `name: ${cmd.name}`,
+      `description: ${cmd.description}`,
+      '---',
+      '',
+      `Run: \`node bin/aw ${cmd.name}\` followed by the user's arguments.`,
+      '',
+    ].join('\n');
+    writeFileSync(join(skillDir, 'SKILL.md'), content);
+  }
+
+  if (count > 0) {
+    fmt.logSuccess(`Generated ${count} aw commands`);
+  }
+
+  return count;
+}
+
+/**
+ * Copy CLAUDE.md and AGENTS.md to project root.
+ */
+export function copyInstructions(cwd, tempDir, namespace) {
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const dest = join(cwd, file);
+    if (existsSync(dest)) continue;
+
+    if (tempDir) {
+      const src = join(tempDir, 'registry', file);
+      if (existsSync(src)) {
+        let content = readFileSync(src, 'utf8');
+        if (namespace) {
+          content = content.replace(/\{\{TEAM\}\}/g, namespace);
+        }
+        writeFileSync(dest, content);
+        fmt.logSuccess(`Created ${file}`);
+        continue;
+      }
+    }
+
+    const content = file === 'CLAUDE.md'
+      ? generateClaudeMd(cwd, namespace)
+      : generateAgentsMd(cwd, namespace);
+    if (content) {
+      writeFileSync(dest, content);
+      fmt.logSuccess(`Created ${file}`);
+    }
+  }
+}
+
+function generateClaudeMd(cwd, namespace) {
+  const team = namespace || 'my-team';
+  return `# CLAUDE.md — ${team}
+
+Team: ${team} | Local-first orchestration via \`.aw_docs/\` | MCPs: \`memory/*\` (shared knowledge), \`git-jenkins\` (CI/CD), \`grafana\` (observability)
+
+## Routing Rule (ABSOLUTE)
+
+> **Every non-trivial task MUST call \`Skill(skill: "ghl-ai-task-router")\` BEFORE any response.**
+>
+> **Trivial** (do directly): typo fixes, single-line edits, git ops, file exploration, factual code questions.
+>
+> Everything else — including tasks phrased as questions, suggestions, or discussions — routes first.
+> **No conversational responses first. No planning first. Route first.**
+> **Execute, don't just recommend:** run the steps (tools, edits, workflows) instead of listing "next steps" for the user.
+
+## Architecture
+
+\`\`\`
+.aw_registry/
+├── ghl/                    # Platform layer (shared, read-only)
+│   ├── agents/             # 15 platform agents (reviewers, engineers, designer)
+│   ├── skills/             # 77 platform skills (SKILL.md files)
+│   ├── commands/           # Platform commands (health-check, help, discover)
+│   └── evals/              # Platform agent & skill quality tests
+│
+├── ${team}/                    # Team layer (from template, customizable)
+│   ├── agents/             # Team agents (developers, testers, PM, coordinator)
+│   ├── skills/             # Team-specific skills
+│   ├── commands/           # Workflow commands (ship, plan, review, deploy, etc.)
+│   ├── blueprints/         # Development workflow blueprints
+│   └── evals/              # Team agent quality tests
+│
+└── .sync-config.json       # Tracks synced paths and team namespace
+
+.aw_docs/                       # Local orchestration state
+├── STATE.md                    # Active run, recent history
+├── config.json                 # Sync settings
+├── runs/<run-id>/              # Per-run state
+│   ├── RUN.md                  # Run metadata + execution log
+│   ├── steps/<NN>-<name>.md   # Per-step state (YAML frontmatter)
+│   └── transparency/           # _transparency JSONs
+├── learnings/<agent>.md        # Accumulated learnings per agent
+├── learnings/_pending-sync.jsonl  # Sync queue → MCP memory/store
+└── tasks/BOARD.md              # Task board
+\`\`\`
+
+Symlinked to \`.claude/{agents,skills,commands/aw,blueprints,evals}\`.
+
+## Local-First Operations
+
+All orchestration is file-based. No MCP calls for orchestration.
+
+| Operation | How |
+|-----------|-----|
+| **Load agent** | Read \`.aw_registry/<ns>/agents/<slug>.md\` → skills list + identity |
+| **Load skill** | Read \`.aw_registry/<ns>/skills/<slug>/SKILL.md\` → full body |
+| **Create run** | Generate \`run-YYYYMMDDTHHMMSS\`, write \`.aw_docs/runs/<id>/RUN.md\` + step files |
+| **Step result** | Update step .md frontmatter + write transparency JSON |
+| **Close run** | Update RUN.md, append \`.aw_docs/learnings/\`, sync queue, eager \`memory/store\` |
+| **Track task** | Update \`.aw_docs/tasks/BOARD.md\` YAML frontmatter |
+| **Learn** | Append to \`.aw_docs/learnings/<agent>.md\` + \`_pending-sync.jsonl\` |
+| **Recall** | Read \`.aw_docs/learnings/<agent>.md\` + MCP \`memory/search\` |
+| **Discover agents** | Read \`.aw_registry/<ns>/\` or \`ls .claude/agents/\` |
+
+## MCP (Remote Only)
+
+Only these MCP calls are used:
+
+\`\`\`
+memory/search  → Search shared team knowledge base
+memory/store   → Push learnings to shared knowledge (eager sync after runs)
+memory/get     → Fetch specific memory by ID
+grafana/*      → External observability
+git-jenkins/*  → External CI/CD pipelines
+stitch/*       → External design generation
+\`\`\`
+
+## Symlink Naming
+
+All symlinks are prefixed with their namespace (\`ghl-\` or \`${team}-\`):
+- \`.aw_registry/ghl/agents/security-reviewer.md\` → \`.claude/agents/ghl-security-reviewer.md\`
+- \`.aw_registry/${team}/agents/frontend-developer.md\` → \`.claude/agents/${team}-frontend-developer.md\`
+- \`.aw_registry/${team}/commands/ship.md\` → \`.claude/commands/aw/${team}-ship.md\`
+
+## Dependency Rule
+
+- **ghl/ is self-contained** — platform agents reference only platform skills
+- **${team}/ can reference ghl/** — team agents use \`ghl-*\` prefixed skill names
+- **ghl/ never references ${team}/** — platform layer knows nothing about team-specific resources
+
+## How Agents Connect to Skills
+
+Agents declare skills in frontmatter \`skills:\` list:
+\`\`\`yaml
+# ghl/agents/security-reviewer.md — platform skills directly
+skills:
+  - security-review
+  - platform-services-authentication-authorization
+
+# ${team}/agents/frontend-developer.md — ghl- prefix for platform skills
+skills:
+  - ghl-vue-development                      # → ghl/skills/vue-development
+  - create-prd                                # → ${team}/skills/create-prd (local)
+\`\`\`
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Discover commands | Type \`/aw:\` and autocomplete |
+| List all agents | \`ls .claude/agents/\` |
+| List all skills | \`ls .claude/skills/\` |
+| Pull updates | \`aw pull\` |
+| Push changes | \`aw push <path>\` |
+| Workspace status | \`aw status\` |
+| Reset workspace | \`aw nuke\` |
+
+## Workflow: 11 Quality Gates
+
+\`\`\`
+Search → Intake → Architecture → Design → Implementation (Ralph Loop) →
+Testing → QA Validation → Code Review (5 parallel) → PR → Staging → Production
+\`\`\`
+
+Gates are shell scripts in \`scripts/gates/\` — CANNOT be bypassed by LLM judgment.
+
+## Cost Optimization Rules
+
+- **Commands**: Use parameterized single commands, not variant files
+- **Skills**: Link to \`platform-docs/content/...\`, max 60 lines inline
+- **Agents**: Definitions ≤5 KB, reference material in linked skills
+- **Local-first**: No MCP calls for orchestration — file reads are faster and always available
+`;
+}
+
+function generateAgentsMd(cwd, namespace) {
+  const team = namespace || 'my-team';
+  return `# AGENTS.md — ${team}
+
+## Agent System
+
+Two-layer agent system with local-first orchestration. Agents are loaded from \`.aw_registry/\` (symlinked to \`.claude/agents/\`).
+
+### How Agents Are Loaded (Local-First)
+
+Commands load agents entirely from local files — no MCP calls for agent/skill loading:
+
+\`\`\`
+1. Read .aw_registry/ghl/agents/<slug>.md       → Agent identity, skills[] list, capabilities
+   OR   .aw_registry/${team}/agents/<slug>.md
+
+2. For each skill in the agent's skills[] frontmatter:
+   Read .aw_registry/ghl/skills/<slug>/SKILL.md  → Full skill body (patterns, checklists)
+   OR   .aw_registry/${team}/skills/<slug>/SKILL.md
+
+3. Read .aw_docs/learnings/<slug>.md             → Prior learnings from past runs
+
+4. Call MCP memory/search({query: "..."})         → Recalled memories (only MCP call)
+\`\`\`
+
+### Platform Agents (ghl-)
+
+Shared infrastructure agents — always available, self-contained. Loaded from \`.aw_registry/ghl/agents/\`.
+
+| Agent | Role | Model Tier |
+|-------|------|------------|
+| \`ghl-architecture-reviewer\` | Architecture review, ADR compliance, coupling detection | Sonnet |
+| \`ghl-security-reviewer\` | Security review, auth patterns, tenant isolation | Sonnet |
+| \`ghl-performance-reviewer\` | Performance review, bundle analysis, N+1 detection | Sonnet |
+| \`ghl-frontend-engineer\` | MFA architecture, event-bus, shared packages | Sonnet |
+| \`ghl-services-engineer\` | Inter-service comms, workers, circuit breakers | Sonnet |
+| \`ghl-infra-engineer\` | Kubernetes, Terraform, Jenkins, deployment | Sonnet |
+| \`ghl-database-engineer\` | MongoDB, Redis, Elasticsearch, Firestore, migrations | Sonnet |
+| \`ghl-product-designer\` | HighRise design system, accessibility, typography | Sonnet |
+| \`ghl-frontend-core-reviewer\` | Vue 3 patterns, composables, Pinia stores | Sonnet |
+| \`ghl-frontend-i18n-reviewer\` | i18n compliance, translation keys | Haiku |
+| \`ghl-maintainability-reviewer\` | Code duplication, naming, complexity | Haiku |
+| \`ghl-reliability-reviewer\` | Error handling, null guards, SSR safety | Haiku |
+| \`ghl-sdet-engineer\` | Playwright POM, quality gates, performance testing | Haiku |
+| \`ghl-devops-automator\` | Docker, Jenkins pipelines, deployment strategies | Haiku |
+| \`ghl-data-engineer\` | CDC pipelines, ClickHouse, analytics data models | Haiku |
+
+### Team Agents (${team}-)
+
+Team-specific agents — customizable. Loaded from \`.aw_registry/${team}/agents/\`. Can reference platform skills via \`ghl-*\` prefix.
+
+| Agent | Role | Model Tier |
+|-------|------|------------|
+| \`${team}-coordinator\` | Task decomposition, quality gate enforcement, orchestration | Opus |
+| \`${team}-architect\` | ADR creation, data flow design, system architecture | Opus |
+| \`${team}-product-manager\` | PRDs, feature prioritization, sprint planning | Opus |
+| \`${team}-frontend-developer\` | Vue components, composables, TypeScript | Sonnet |
+| \`${team}-backend-developer\` | NestJS services, API endpoints, workers | Sonnet |
+| \`${team}-manager\` | Spec writing, user stories, team coordination | Sonnet |
+| \`${team}-unit-tester\` | Component tests, composable tests, BDD | Haiku |
+| \`${team}-e2e-tester\` | Cypress tests, Gherkin scenarios | Haiku |
+| \`${team}-mutation-tester\` | Stryker mutation analysis, test improvement | Haiku |
+| \`${team}-release-engineer\` | Release checklists, rollback plans, deploy | Sonnet |
+| \`${team}-design-reviewer\` | Design token audit, accessibility review | Haiku |
+| \`${team}-design-auditor\` | Dark mode audit, design token verification | Haiku |
+| \`${team}-technical-writer\` | API docs, migration guides | Haiku |
+| \`${team}-api-tester\` | API contract tests, auth flow tests | Haiku |
+| \`${team}-visual-tester\` | Screenshot comparison, visual test plans | Haiku |
+| \`${team}-responsive-tester\` | Breakpoint audit, touch target compliance | Haiku |
+| \`${team}-performance-benchmarker\` | Core Web Vitals, k6 scripts | Haiku |
+| \`${team}-stitch-designer\` | Multi-screen flows, screen prompts | Haiku |
+| \`${team}-animation-specialist\` | Transitions, reduced motion compliance | Haiku |
+| \`${team}-ux-researcher\` | Interview scripts, usability test plans | Haiku |
+| \`${team}-onboarding-optimizer\` | Empty state design, onboarding flow critique | Haiku |
+
+### Skill Resolution
+
+Agents declare skills in their frontmatter \`skills:\` list. Commands read SKILL.md files directly from disk:
+
+- **No prefix** → \`.aw_registry/${team}/skills/<name>/SKILL.md\`
+- **\`ghl-\` prefix** → \`.aw_registry/ghl/skills/<name-without-ghl->/SKILL.md\`
+
+\`\`\`yaml
+# .aw_registry/ghl/agents/security-reviewer.md — platform skills directly
+skills:
+  - security-review                                    # → .aw_registry/ghl/skills/security-review/SKILL.md
+  - platform-services-authentication-authorization     # → .aw_registry/ghl/skills/platform-services-.../SKILL.md
+
+# .aw_registry/${team}/agents/frontend-developer.md — ghl- prefix for platform skills
+skills:
+  - ghl-vue-development                                # → .aw_registry/ghl/skills/vue-development/SKILL.md
+  - create-prd                                         # → .aw_registry/${team}/skills/create-prd/SKILL.md
+\`\`\`
+
+### How to Invoke
+
+\`\`\`
+# Via workflow commands (recommended — orchestrates multiple agents with .aw_docs/ tracking)
+/aw:${team}-ship              # Full ship: research → spec → design → plan → implement → test → review → deploy
+/aw:${team}-work              # Implementation: 6 agents, parallel DB/frontend, quality review + test
+/aw:${team}-plan              # Architecture + PM planning
+/aw:${team}-review-all        # Parallel code review with 10 reviewers in 3 waves
+/aw:${team}-brainstorm        # Requirement exploration with architect + PM
+
+# Via Agent tool (direct invocation — no run tracking)
+Agent(subagent_type: "ghl:security-reviewer", prompt: "Review this PR for security issues")
+Agent(subagent_type: "${team}:frontend-developer", prompt: "Create a Vue component for...")
+\`\`\`
+
+### Learnings & Knowledge
+
+Agent knowledge accumulates across runs via \`.aw_docs/learnings/\`:
+
+\`\`\`
+.aw_docs/learnings/
+├── backend-developer.md        # Learnings from all runs where this agent worked
+├── frontend-developer.md       # Appended after each workflow close
+├── architecture-reviewer.md    # Prior learnings loaded before each run
+└── _pending-sync.jsonl         # Queue for eager sync to MCP memory/store
+\`\`\`
+
+Before each run, prior learnings are read from these files and injected into agent prompts. After each run, new learnings are appended. Optionally synced to shared MCP memory for cross-project recall.
+
+### Evals
+
+Each agent has quality test cases in \`.claude/evals/\`:
+\`\`\`
+.claude/evals/ghl-agents-security-reviewer/     # Platform agent evals
+.claude/evals/${team}-agents-frontend-developer/  # Team agent evals
+.claude/evals/ghl-skills-vue-development/        # Skill evals
+\`\`\`
+
+Run with: \`/ghl:eval agent:<slug>\` or \`/ghl:eval skill:<slug>\`
+`;
+}
+
+/**
+ * Initialize .aw_docs/ directory for local-first orchestration state.
+ * Creates run tracking, learnings, task board, and cache directories.
+ */
+export function initAwDocs(cwd) {
+  const awDocsDir = join(cwd, '.aw_docs');
+  if (existsSync(awDocsDir)) return; // Already initialized
+
+  const dirs = [
+    '.aw_docs/runs',
+    '.aw_docs/learnings',
+    '.aw_docs/tasks',
+    '.aw_docs/cache',
+  ];
+
+  for (const dir of dirs) {
+    mkdirSync(join(cwd, dir), { recursive: true });
+  }
+
+  // STATE.md — workspace state
+  writeFileSync(join(awDocsDir, 'STATE.md'), `---
+active_run: null
+last_run: null
+last_workflow: null
+last_agent: null
+updated_at: null
+pending_sync_count: 0
+---
+
+# Workspace State
+
+No active runs. Use \`/aw:<team>-<command>\` to start a workflow.
+`);
+
+  // config.json — registry paths, sync settings
+  writeFileSync(join(awDocsDir, 'config.json'), JSON.stringify({
+    sync: {
+      eager: true,
+      batch_threshold: 10,
+      mcp_memory_enabled: true,
+    },
+    paths: {
+      runs: '.aw_docs/runs',
+      learnings: '.aw_docs/learnings',
+      tasks: '.aw_docs/tasks',
+      cache: '.aw_docs/cache',
+    },
+  }, null, 2) + '\n');
+
+  // BOARD.md — task board
+  writeFileSync(join(awDocsDir, 'tasks', 'BOARD.md'), `---
+tasks: []
+updated_at: null
+---
+
+# Task Board
+
+No active tasks. Tasks are created during workflow execution.
+`);
+
+  // _pending-sync.jsonl — sync queue (empty)
+  writeFileSync(join(awDocsDir, 'learnings', '_pending-sync.jsonl'), '');
+
+  fmt.logSuccess('Created .aw_docs/ (local orchestration state)');
+}
+
+function listNamespaceDirs(awDir) {
+  if (!existsSync(awDir)) return [];
+  return readdirSync(awDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => d.name);
+}
+

package/link.mjs

@@ -0,0 +1,209 @@
+// link.mjs — Create symlinks from IDE dirs → .aw_registry/
+
+import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+import * as fmt from './fmt.mjs';
+
+const IDE_DIRS = ['.claude', '.cursor', '.codex'];
+// Per-file symlink types
+const FILE_TYPES = ['agents', 'blueprints'];
+
+/**
+ * List namespace directories inside .aw_registry/ (skip dotfiles).
+ */
+function listNamespaceDirs(awDir) {
+  if (!existsSync(awDir)) return [];
+  return readdirSync(awDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => d.name);
+}
+
+/**
+ * List subdirectories (non-dot) in a directory.
+ */
+function listDirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => d.name);
+}
+
+/**
+ * Clean all symlinks from IDE type directories before re-linking.
+ */
+function cleanIdeSymlinks(cwd) {
+  for (const ide of IDE_DIRS) {
+    for (const type of [...FILE_TYPES, 'skills', 'evals']) {
+      const dir = join(cwd, ide, type);
+      if (!existsSync(dir)) continue;
+      for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        try {
+          if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
+        } catch { /* best effort */ }
+      }
+    }
+    // Clean command symlinks (both flat legacy and namespaced aw/)
+    const cmdDir = join(cwd, ide, 'commands');
+    if (!existsSync(cmdDir)) continue;
+    for (const entry of readdirSync(cmdDir)) {
+      const p = join(cmdDir, entry);
+      try {
+        if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
+      } catch { /* best effort */ }
+    }
+    // Clean inside commands/aw/ namespace dir
+    const awCmdDir = join(cmdDir, 'aw');
+    if (existsSync(awCmdDir)) {
+      for (const entry of readdirSync(awCmdDir)) {
+        const p = join(awCmdDir, entry);
+        try {
+          if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
+        } catch { /* best effort */ }
+      }
+    }
+  }
+}
+
+/**
+ * Compute flat IDE name: namespace-slug (always includes namespace).
+ */
+function flatName(ns, name) {
+  return `${ns}-${name}`;
+}
+
+/**
+ * Create/refresh all IDE symlinks.
+ *
+ * - agents, blueprints: per-file symlinks with flat names
+ * - skills: per-skill directory symlinks with flat names
+ * - commands: directory symlink per namespace → .claude/commands/<ns>/
+ *   (Claude Code needs a directory at .claude/commands/<ns>/ for /<ns>:* autocomplete)
+ */
+export function linkWorkspace(cwd) {
+  const awDir = join(cwd, '.aw_registry');
+  if (!existsSync(awDir)) return 0;
+
+  let created = 0;
+
+  // Clean old symlinks first
+  cleanIdeSymlinks(cwd);
+
+  const namespaces = listNamespaceDirs(awDir);
+
+  for (const ns of namespaces) {
+    // Per-file types: agents, blueprints
+    for (const type of FILE_TYPES) {
+      const typeDir = join(awDir, ns, type);
+      if (!existsSync(typeDir)) continue;
+
+      for (const file of readdirSync(typeDir).filter(f => f.endsWith('.md') && !f.startsWith('.'))) {
+        const flat = flatName(ns, file);
+
+        for (const ide of IDE_DIRS) {
+          const linkDir = join(cwd, ide, type);
+          mkdirSync(linkDir, { recursive: true });
+          const linkPath = join(linkDir, flat);
+          const targetPath = join(awDir, ns, type, file);
+          const relTarget = relative(linkDir, targetPath);
+          try {
+            execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
+            created++;
+          } catch { /* best effort */ }
+        }
+      }
+    }
+
+    // Skills: per-skill directory symlinks
+    const skillsDir = join(awDir, ns, 'skills');
+    if (!existsSync(skillsDir)) continue;
+    for (const skill of listDirs(skillsDir)) {
+      const flat = flatName(ns, skill);
+
+      for (const ide of IDE_DIRS) {
+        const linkDir = join(cwd, ide, 'skills');
+        mkdirSync(linkDir, { recursive: true });
+        const linkPath = join(linkDir, flat);
+        const targetPath = join(skillsDir, skill);
+        const relTarget = relative(linkDir, targetPath);
+        try {
+          execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
+          created++;
+        } catch { /* best effort */ }
+      }
+    }
+  }
+
+  // Evals: per-eval-dir symlinks (evals/agents/<name>/, evals/skills/<name>/)
+  for (const ns of namespaces) {
+    const evalsDir = join(awDir, ns, 'evals');
+    if (!existsSync(evalsDir)) continue;
+
+    for (const subType of listDirs(evalsDir)) {
+      const subDir = join(evalsDir, subType);
+      for (const evalName of listDirs(subDir)) {
+        const flat = `${ns}-${subType}-${evalName}`;
+
+        for (const ide of IDE_DIRS) {
+          const linkDir = join(cwd, ide, 'evals');
+          mkdirSync(linkDir, { recursive: true });
+          const linkPath = join(linkDir, flat);
+          const targetPath = join(subDir, evalName);
+          const relTarget = relative(linkDir, targetPath);
+          try {
+            execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
+            created++;
+          } catch { /* best effort */ }
+        }
+      }
+    }
+  }
+
+  // Codex per-skill symlinks: .agents/skills/<name>
+  const agentsSkillsDir = join(cwd, '.agents/skills');
+  for (const ns of namespaces) {
+    const skillsDir = join(awDir, ns, 'skills');
+    if (!existsSync(skillsDir)) continue;
+    mkdirSync(agentsSkillsDir, { recursive: true });
+    for (const skill of listDirs(skillsDir)) {
+      const flat = flatName(ns, skill);
+      const linkPath = join(agentsSkillsDir, flat);
+      const targetPath = join(skillsDir, skill);
+      const relTarget = relative(agentsSkillsDir, targetPath);
+      try {
+        execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
+        created++;
+      } catch { /* best effort */ }
+    }
+  }
+
+  // Commands: per-file symlinks from <ns>/commands/ → .claude/commands/aw/
+  // All commands (hand-written + generated) live in namespace/commands/ as single source of truth
+  for (const ns of namespaces) {
+    const commandsDir = join(awDir, ns, 'commands');
+    if (!existsSync(commandsDir)) continue;
+
+    for (const file of readdirSync(commandsDir).filter(f => f.endsWith('.md') && !f.startsWith('.'))) {
+      const cmdFileName = `${ns}-${file}`;
+
+      for (const ide of IDE_DIRS) {
+        const linkDir = join(cwd, ide, 'commands', 'aw');
+        mkdirSync(linkDir, { recursive: true });
+        const linkPath = join(linkDir, cmdFileName);
+        const targetPath = join(commandsDir, file);
+        const relTarget = relative(linkDir, targetPath);
+        try {
+          execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
+          created++;
+        } catch { /* best effort */ }
+      }
+    }
+  }
+
+  if (created > 0) {
+    fmt.logSuccess(`Linked ${created} IDE symlink${created > 1 ? 's' : ''}`);
+  }
+
+  return created;
+}