trackfw 2.12.3 → 2.13.0

package/README.md

@@ -1,6 +1,6 @@
 # trackfw
 
-> The AI-native governance layer for software delivery — ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
+> AI governance CLI for software delivery teams — ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
 
 [![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)
 [![Go](https://img.shields.io/badge/go-1.25+-00ADD8?logo=go)](go.mod)
@@ -8,7 +8,9 @@
 [![PyPI](https://img.shields.io/pypi/v/trackfw?logo=python&color=3776AB)](https://pypi.org/project/trackfw/)
 [![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)
 
-**trackfw** is an open-source CLI that enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.
+**trackfw** is an open-source governance CLI for AI-native software delivery. It enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.
+
+It is designed for teams looking for an ADR / REQ / ROADMAP governance framework with native support for AI coding assistants such as Codex, Claude Code, Gemini CLI, Antigravity, Cursor, GitHub Copilot, Windsurf, Amazon Q, and Kiro.
 
 ```
 ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
@@ -91,8 +93,8 @@ npm install -g trackfw
 ```
 
 The npm package is pure Node.js — no compiled binary or postinstall download.
-It works wherever Node.js ≥ 18 is installed. Shared behavior and intentional
-Go-only integration installers follow the [CLI parity contract](docs/cli-parity.md).
+It works wherever Node.js ≥ 18 is installed. Shared behavior, including the AI
+integration lifecycle, follows the [CLI parity contract](docs/cli-parity.md).
 
 ### pip
 
@@ -151,15 +153,17 @@ trackfw status
 | `trackfw plugins list` | List installed plugins |
 | `trackfw plugins add <user/repo>` | Install a plugin from GitHub Releases |
 | `trackfw plugins remove <name>` | Remove an installed plugin |
-| `trackfw agents` | Install Claude Code subagents *(Go binary only)* |
-| `trackfw gemini` | Install Gemini CLI skills and commands *(Go binary only)* |
-| `trackfw cursor` | Install Cursor rules *(Go binary only)* |
-| `trackfw copilot` | Install GitHub Copilot instructions *(Go binary only)* |
-| `trackfw windsurf` | Install Windsurf rules and workflows *(Go binary only)* |
-| `trackfw amazonq` | Install Amazon Q Developer rules *(Go binary only)* |
+| `trackfw agents list` | List available agents and deployment state across AI CLIs |
+| `trackfw agents install` | Install selected specialist agents |
+| `trackfw agents update` | Safely update managed agents |
+| `trackfw agents uninstall` | Remove selected owned agent deployments |
+| `trackfw skills list` | List available governance skills and deployment state |
+| `trackfw skills install/update/uninstall` | Manage selected governance skills |
+| `trackfw gemini`, `cursor`, `copilot`, `windsurf`, `amazonq` | Historical aliases in the Go distribution only; use `agents`/`skills` |
 | `trackfw version` | Print version |
 
-> **Go binary only** commands (`agents`, `gemini`, `cursor`, `copilot`, `windsurf`, `amazonq`) are available when installed via brew, `install.sh`, or `go install`. When using the npm package, AI integrations are installed through `trackfw init`.
+The same lifecycle contract is available from the Go/Homebrew, npm, and PyPI
+distributions.
 
 ---
 
@@ -323,19 +327,41 @@ $ trackfw status
 
 ## AI assistant integration
 
-`trackfw init` asks which AI tools your team uses and installs native governance context for each. When using the Go binary (brew, `install.sh`, `go install`), each integration can also be run as a standalone command.
+`trackfw init` can install initial AI integrations. The `agents` and `skills`
+command families provide the complete lifecycle in every distribution.
 
-| Command | Installs | Format |
-|---|---|---|
-| `trackfw init --ai-tools codex` | `AGENTS.md`, 5 repository skills, 6 custom agents, Codex config and hooks | `.agents/skills/` + `.codex/` |
-| `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |
-| `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |
-| `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |
-| `trackfw copilot` | `copilot-instructions.md` + 10 instructions + 10 prompts | `.github/` |
-| `trackfw windsurf` | 10 rules + workflows in `.windsurf/` + global rules | Appends to `~/.codeium/windsurf/memories/` |
-| `trackfw amazonq` | 10 rules in `.amazonq/rules/` | Plain Markdown |
+| Target | Native/fallback representation |
+|---|---|
+| Claude Code | Subagent Markdown and Agent Skills |
+| Codex | Custom-agent TOML and Agent Skills |
+| Gemini CLI | Agent Markdown and skills |
+| Antigravity | Agent/skill directories; explicit `legacy-cli` surface available |
+| Cursor | Agent Markdown and skills |
+| GitHub Copilot | Custom agents and Agent Skills |
+| Windsurf | Specialist-skill fallback for agents and native skills |
+| Amazon Q | CLI agent JSON and workflow-rule fallback |
+| Kiro | Native IDE/CLI agents and Agent Skills |
+
+```bash
+# Inspect every deployment, including legacy surfaces
+trackfw agents list --json
+
+# Install selected items in the repository
+trackfw agents install --targets codex,claude --items architect,backend --scope project
+trackfw skills install --targets codex,antigravity --items governance,implement --scope project
+
+# Select an alternate surface explicitly
+trackfw agents install --targets kiro --surface kiro=cli
+trackfw agents list --targets antigravity --surface antigravity=legacy-cli
+```
 
-Each installer is idempotent — running it twice never overwrites your customizations.
+Without `--targets`, mutations open a numbered/checkbox selector in a TTY and
+fail with an actionable error in CI. The lifecycle reports `not-installed`,
+`current`, `outdated`, or `modified`. A manifest under `.trackfw/` records
+scope-specific ownership, version, SHA-256, and shared claims. Modified files
+are never replaced or removed unless `--force` is explicit, and unmanaged files
+are never removed. Known historical templates are adopted without overwriting;
+unknown unmanaged content cannot be adopted by `update`, even with `--force`.
 
 The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
 
@@ -350,7 +376,7 @@ The 10 roles installed for each tool: **architect · backend · frontend · qa
 ? Package manager?       npm / pnpm / yarn / bun
 ? Git hooks?             husky / lefthook / none
 ? CI system?             GitHub Actions / GitLab CI / none
-? Which AI assistants?   Claude Code / OpenAI Codex / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
+? Which AI assistants?   Claude / Codex / Gemini / Antigravity / Cursor / Copilot / Windsurf / Amazon Q / Kiro
 ```
 
 The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trackfw",
-  "version": "2.12.3",
-  "description": "Governance CLI for AI-native software delivery. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
+  "version": "2.13.0",
+  "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",
     "adr",
@@ -19,11 +19,22 @@
     "pre-commit",
     "developer-experience",
     "technical-debt",
+    "governance-cli",
+    "agents",
+    "agents-md",
+    "skills",
+    "subagents",
+    "hooks",
+    "ai-coding-assistant",
     "claude-code",
     "openai-codex",
+    "gemini-cli",
     "gemini",
+    "github-copilot",
     "cursor",
     "copilot",
+    "windsurf",
+    "amazon-q",
     "req",
     "trackfw"
   ],

package/src/commands/agents.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('./integrations').createLifecycleCommand('agents')

package/src/commands/index.js

@@ -27,6 +27,8 @@ function createProgram() {
   program.addCommand(require('./help'))
   program.addCommand(require('./configure'))
   program.addCommand(require('./version'))
+  program.addCommand(require('./agents'))
+  program.addCommand(require('./skills'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())

package/src/commands/init.js

@@ -4,7 +4,7 @@ const { t } = require('../i18n')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
-cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (codex,claude,gemini,cursor,copilot,windsurf,amazonq)', '')
+cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,kiro)', '')
 cmd.action(async (options) => {
   const path = require('path')
   const generators = require('../generators/init')
@@ -22,17 +22,10 @@ cmd.action(async (options) => {
     }
     await generators.scaffold(cfg)
     const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
+    const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'kiro'])
     for (const tool of aiTools) {
-      switch (tool) {
-        case 'codex':    require('../generators/codex').installCodex(process.cwd()); break
-        case 'claude':   await generators.installAgents();  break
-        case 'gemini':   await generators.installGemini();  break
-        case 'cursor':   await generators.installCursor();  break
-        case 'copilot':  await generators.installCopilot(); break
-        case 'windsurf': await generators.installWindsurf(); break
-        case 'amazonq':  await generators.installAmazonQ(); break
-        default: throw new Error(`Unsupported AI tool: ${tool}`)
-      }
+      if (!supported.has(tool)) throw new Error(`Unsupported AI tool: ${tool}`)
+      await generators.installIntegrationTarget(tool, process.cwd())
     }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -157,10 +150,12 @@ cmd.action(async (options) => {
         { name: 'Claude Code', value: 'claude' },
         { name: 'OpenAI Codex', value: 'codex' },
         { name: 'Gemini CLI', value: 'gemini' },
+        { name: 'Google Antigravity', value: 'antigravity' },
         { name: 'Cursor', value: 'cursor' },
         { name: 'GitHub Copilot', value: 'copilot' },
         { name: 'Windsurf', value: 'windsurf' },
         { name: 'Amazon Q Developer', value: 'amazonq' },
+        { name: 'Kiro', value: 'kiro' },
       ],
     })
   } catch (err) {
@@ -183,17 +178,7 @@ cmd.action(async (options) => {
   const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
   await generators.scaffold(cfg)
 
-  for (const tool of (aiTools || [])) {
-    switch (tool) {
-      case 'codex':    require('../generators/codex').installCodex(process.cwd()); break
-      case 'claude':   await generators.installAgents();  break
-      case 'gemini':   await generators.installGemini();  break
-      case 'cursor':   await generators.installCursor();  break
-      case 'copilot':  await generators.installCopilot(); break
-      case 'windsurf': await generators.installWindsurf(); break
-      case 'amazonq':  await generators.installAmazonQ(); break
-    }
-  }
+  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd())
 
   console.log(`\n${t('init.success')}`)
   require('../generators/init').printArchitectNextSteps(process.cwd())

package/src/commands/integrations.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const { Command } = require('commander')
+const { catalog, execute, parseSurfaces } = require('../integrations')
+
+const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
+const collect = (value, previous) => previous.concat(value)
+
+function human(result) {
+  const lines = [`Available ${result.kind} (catalog ${result.catalog_version}):`]
+  for (const item of result.items) lines.push(`  ${item.id.padEnd(14)} ${item.name} — ${item.description}`)
+  lines.push('', 'Deployments:')
+  for (const deployment of result.deployments) {
+    const managed = deployment.managed ? 'managed' : 'unmanaged'
+    lines.push(`  ${deployment.target.padEnd(12)} ${deployment.surface.padEnd(12)} ${deployment.item.padEnd(14)} ${deployment.state.padEnd(13)} ${deployment.destination} (${managed})`)
+  }
+  return lines.join('\n')
+}
+
+async function promptSelection(kind, options, prompts = require('@inquirer/prompts')) {
+  const { checkbox } = prompts
+  options.targets = await checkbox({ message: 'Target CLIs', choices: catalog.targets.map(target => ({ name: target.name, value: target.id })), required: true })
+  options.items = await checkbox({ message: `${kind} to manage`, choices: catalog[kind].map(item => ({ name: item.name, value: item.id })), required: true })
+}
+
+async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquirer/prompts')) {
+  const { select } = prompts
+  const selected = parseSurfaces(options.surfaces)
+  for (const targetID of options.targets || []) {
+    if (selected[targetID]) continue
+    const target = catalog.targets.find(entry => entry.id === targetID)
+    const eligible = target.surfaces.filter(surface => !['legacy', 'unsupported'].includes(surface.capabilities[kind].support_level))
+    if (eligible.length <= 1) continue
+    const surface = await select({ message: `Surface for ${target.name}`, choices: eligible.map(entry => ({ name: entry.name, value: entry.id })) })
+    options.surfaces.push(`${targetID}=${surface}`)
+  }
+}
+
+function createLifecycleCommand(kind) {
+  const root = new Command(kind).description(`Manage trackfw ${kind}`)
+  for (const operation of ['list', 'install', 'uninstall', 'update']) {
+    const command = new Command(operation)
+      .option('--targets <targets>', 'Comma-separated target CLIs', csv)
+      .option('--items <items>', `Comma-separated ${kind} IDs`, csv)
+      .option('--scope <scope>', 'Installation scope: project or global', 'project')
+      .option('--surface <target=surface>', 'Surface selection (repeatable)', collect, [])
+      .option('--json', 'Print deterministic JSON')
+      .option('--force', 'Replace or remove modified artifacts')
+    command.action(async options => {
+      options.surfaces = options.surface || []
+      if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
+      const mutation = operation !== 'list'
+      if (mutation && (!options.targets || !options.targets.length)) {
+        if (!process.stdin.isTTY) throw new Error(`${operation} requires --targets in non-interactive mode`)
+        await promptSelection(kind, options)
+      }
+      if (mutation && process.stdin.isTTY) await promptAmbiguousSurfaces(kind, options)
+      options.allSurfaces = operation === 'list'
+      const output = execute(kind, operation, options)
+      console.log(options.json ? JSON.stringify(output) : human(output))
+    })
+    root.addCommand(command)
+  }
+  return root
+}
+
+module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces }

package/src/commands/skills.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('./integrations').createLifecycleCommand('skills')

package/src/commands/update.js

@@ -73,7 +73,15 @@ cmd.action(() => {
   }
   if (fs.existsSync(path.join(cwd, 'AGENTS.md')) || fs.existsSync(path.join(cwd, '.codex'))) {
     try {
-      require('../generators/codex').installCodex(cwd);
+      const { buildPlans, IntegrationManager } = require('../integrations');
+      const roots = { projectRoot: cwd };
+      const manager = new IntegrationManager(roots);
+      for (const kind of ['agents', 'skills']) {
+        const plans = buildPlans(kind, { targets: ['codex'], scope: 'project' });
+        const statuses = manager.inspect(plans);
+        const existing = plans.filter((_, index) => statuses[index].state !== 'not-installed');
+        manager.update(existing);
+      }
     } catch (e) {
       console.warn(`  ⚠ Codex integration: ${e.message}`);
     }

package/src/generators/codex.js

@@ -81,13 +81,11 @@ Review the branch as an owner. Return findings first, ordered by severity, with
 `,
 }
 
-function writeManaged(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true })
-  fs.writeFileSync(filePath, content.trim() + '\n', 'utf8')
-}
-
 function installCodex(cwd) {
   const root = cwd || process.cwd()
+  const { execute } = require('../integrations')
+  execute('agents', 'install', { targets: ['codex'], scope: 'project' }, { projectRoot: root })
+  execute('skills', 'install', { targets: ['codex'], scope: 'project' }, { projectRoot: root })
   injectRulesForTool('codex', root)
 
   const configPath = path.join(root, '.codex', 'config.toml')
@@ -98,14 +96,8 @@ function installCodex(cwd) {
     fs.writeFileSync(configPath, config, 'utf8')
   }
 
-  for (const [name, content] of Object.entries(skills)) {
-    writeManaged(path.join(root, '.agents', 'skills', name, 'SKILL.md'), content)
-  }
-  for (const [name, content] of Object.entries(agents)) {
-    writeManaged(path.join(root, '.codex', 'agents', name), content)
-  }
   injectCodexHooks(root)
   console.log('  ✓ Codex: AGENTS.md, skills, custom agents and hooks')
 }
 
-module.exports = { installCodex }
+module.exports = { installCodex, legacyCodexFixtures: { skills, agents } }

package/src/generators/init.js

@@ -931,17 +931,13 @@ Oriente o usuário:
 // AI tool installers
 // ---------------------------------------------------------------------------
 
-/**
- * installAgents — instala agentes Claude Code em ~/.claude/agents/
- * O pacote npm não embute os templates binários do Go, por isso informa
- * ao usuário que esta operação requer o binário Go instalado.
- */
-async function installAgents() {
-  // CLAUDE.md já tratado por generateClaudeMD via injectOrUpdateRules
-  console.log('  ✓ claude (agentes — execute `trackfw install agents` com o binário Go para instalar os templates)')
+/** Compatibility entrypoint backed by the canonical integration engine. */
+async function installAgents(cwd = process.cwd()) {
+  await installIntegrationTarget('claude', cwd)
 }
 
 async function installGemini(cwd = process.cwd()) {
+  await installIntegrationTarget('gemini', cwd)
   try {
     injectRulesForTool('gemini', cwd)
     console.log('  ✓ trackfw rules → GEMINI.md')
@@ -951,6 +947,7 @@ async function installGemini(cwd = process.cwd()) {
 }
 
 async function installCursor(cwd = process.cwd()) {
+  await installIntegrationTarget('cursor', cwd)
   try {
     injectRulesForTool('cursor', cwd)
     console.log('  ✓ trackfw rules → .cursor/rules/trackfw.mdc')
@@ -960,6 +957,7 @@ async function installCursor(cwd = process.cwd()) {
 }
 
 async function installCopilot(cwd = process.cwd()) {
+  await installIntegrationTarget('copilot', cwd)
   try {
     injectRulesForTool('copilot', cwd)
     console.log('  ✓ trackfw rules → .github/copilot-instructions.md')
@@ -969,6 +967,7 @@ async function installCopilot(cwd = process.cwd()) {
 }
 
 async function installWindsurf(cwd = process.cwd()) {
+  await installIntegrationTarget('windsurf', cwd)
   try {
     injectRulesForTool('windsurf', cwd)
     console.log('  ✓ trackfw rules → .windsurfrules')
@@ -978,6 +977,7 @@ async function installWindsurf(cwd = process.cwd()) {
 }
 
 async function installAmazonQ(cwd = process.cwd()) {
+  await installIntegrationTarget('amazonq', cwd)
   try {
     injectRulesForTool('amazonq', cwd)
     console.log('  ✓ trackfw rules → .amazonq/developer/guidelines.md')
@@ -986,6 +986,15 @@ async function installAmazonQ(cwd = process.cwd()) {
   }
 }
 
+/** Install the canonical agents and skills for one AI target. */
+async function installIntegrationTarget(target, cwd = process.cwd()) {
+  const { execute } = require('../integrations')
+  const roots = { projectRoot: cwd }
+  execute('agents', 'install', { targets: [target], scope: 'project' }, roots)
+  execute('skills', 'install', { targets: [target], scope: 'project' }, roots)
+  console.log(`  ✓ ${target} agents and skills`)
+}
+
 /**
  * generateClaudeCommandsForce — re-gera todos os slash commands, sobrescrevendo arquivos existentes.
  */
@@ -1093,6 +1102,7 @@ module.exports = {
   installCopilot,
   installWindsurf,
   installAmazonQ,
+  installIntegrationTarget,
   injectRulesForTool,
   injectRulesDetected,
   trackfwRulesBlock,

package/src/integrations/assets/agents/architect.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-architect
+description: Principal software architect for system design, ADRs and governed multi-agent coordination.
+model: opus
+---
+
+# Architect
+
+Map the existing architecture and traceability chain before proposing changes. Record material decisions as ADRs, produce decision-complete plans, and delegate implementation to the appropriate specialist. Do not implement product code.

package/src/integrations/assets/agents/backend.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-backend
+description: Senior backend specialist for APIs, domain logic, integrations and data access.
+model: sonnet
+---
+
+# Backend
+
+Implement only the assigned backend scope. Preserve public contracts, Clean Architecture boundaries, observability and trackfw traceability. Run focused build and tests and report evidence and remaining risks.

package/src/integrations/assets/agents/code-quality.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-code-quality
+description: Code quality specialist for maintainability, static analysis, refactoring and quality gates.
+model: sonnet
+---
+
+# Code Quality
+
+Assess duplication, complexity, architecture fitness, coverage and code smells. Run the repository's linters and quality gates, then report actionable findings by impact without expanding the assigned scope.

package/src/integrations/assets/agents/data.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-data
+description: Data engineering and data science specialist for pipelines, quality, analytics and MLOps.
+model: sonnet
+---
+
+# Data
+
+Implement reliable, observable and idempotent data workflows. Validate schemas, lineage, quality expectations and cost before changes, and never substitute invented production data for real contracts.

package/src/integrations/assets/agents/dba.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-dba
+description: Database specialist for modeling, queries, indexes, migrations, backup and recovery.
+model: sonnet
+---
+
+# DBA
+
+Inspect schemas and execution plans before proposing changes. Favor safe, reversible migrations, validate backup and recovery constraints, and preserve data integrity and least-privilege access.

package/src/integrations/assets/agents/frontend.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-frontend
+description: Senior frontend specialist for accessible, localized and performant user interfaces.
+model: sonnet
+---
+
+# Frontend
+
+Implement only the assigned frontend scope. Preserve the design system, WCAG accessibility, localization and browser behavior. Validate the affected build and UI tests before completion.

package/src/integrations/assets/agents/infra.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-infra
+description: Infrastructure specialist for cloud, Kubernetes, GitOps, CI/CD, reliability and FinOps.
+model: sonnet
+---
+
+# Infrastructure
+
+Implement only the assigned infrastructure scope. Prefer declarative, least-privilege and reversible changes. Validate plans and manifests without applying to live environments unless explicitly authorized.

package/src/integrations/assets/agents/qa.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-qa
+description: Quality assurance specialist for unit, integration, contract and end-to-end testing.
+model: sonnet
+---
+
+# QA
+
+Trace critical flows against roadmap acceptance criteria. Create reproducible tests, investigate regressions and flaky behavior, and report concrete contract gaps with validation evidence.

package/src/integrations/assets/agents/security.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-security
+description: Security reviewer for trust boundaries, secrets, injection, permissions and supply-chain risk.
+model: sonnet
+---
+
+# Security
+
+Perform evidence-backed threat analysis. Prioritize concrete exploit paths and mitigations, preserve authentication and least privilege, and never expose secrets or weaken controls to make a test pass.

package/src/integrations/assets/agents/ux.md

@@ -0,0 +1,9 @@
+---
+name: trackfw-ux
+description: UX and UI specialist for research, interaction design, design systems and accessibility.
+model: sonnet
+---
+
+# UX
+
+Evaluate user journeys, interaction consistency and WCAG 2.2 AA accessibility. Ground recommendations in evidence and validate complex or uncertain flows visually before production implementation.

package/src/integrations/assets/catalog.json

@@ -0,0 +1,33 @@
+{
+  "version": "1.1.0",
+  "agents": [
+    {"id":"architect","name":"Architect","description":"Architecture, ADRs and governed coordination","asset":"assets/agents/architect.md"},
+    {"id":"backend","name":"Backend","description":"Backend APIs, domain logic and integrations","asset":"assets/agents/backend.md"},
+    {"id":"frontend","name":"Frontend","description":"Accessible and localized user interfaces","asset":"assets/agents/frontend.md"},
+    {"id":"qa","name":"QA","description":"Automated testing and acceptance coverage","asset":"assets/agents/qa.md"},
+    {"id":"infra","name":"Infrastructure","description":"Cloud, Kubernetes, delivery and reliability","asset":"assets/agents/infra.md"},
+    {"id":"security","name":"Security","description":"Threat analysis and DevSecOps controls","asset":"assets/agents/security.md"},
+    {"id":"code-quality","name":"Code Quality","description":"Maintainability and quality gates","asset":"assets/agents/code-quality.md"},
+    {"id":"dba","name":"DBA","description":"Database modeling, performance and recovery","asset":"assets/agents/dba.md"},
+    {"id":"ux","name":"UX","description":"User experience, design systems and accessibility","asset":"assets/agents/ux.md"},
+    {"id":"data","name":"Data","description":"Data pipelines, quality, analytics and MLOps","asset":"assets/agents/data.md"}
+  ],
+  "skills": [
+    {"id":"governance","name":"Governance","description":"Inspect and maintain the governance chain","asset":"assets/skills/governance.md"},
+    {"id":"plan","name":"Plan","description":"Plan a governed implementation","asset":"assets/skills/plan.md"},
+    {"id":"implement","name":"Implement","description":"Execute an approved roadmap","asset":"assets/skills/implement.md"},
+    {"id":"review","name":"Review","description":"Review correctness and traceability","asset":"assets/skills/review.md"},
+    {"id":"release","name":"Release","description":"Prepare and verify a release","asset":"assets/skills/release.md"}
+  ],
+  "targets": [
+    {"id":"claude","name":"Claude Code","surfaces":[{"id":"cli","name":"Claude Code CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"subagent"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.claude/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".claude/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.claude/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".claude/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"settings","surface":"cli","scope":"project","path":".claude/settings.json","purpose":"attention hooks","required":false}]},
+    {"id":"codex","name":"Codex CLI","surfaces":[{"id":"cli","name":"Codex CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"custom-agent-toml"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.codex/agents/trackfw-{{id}}.toml","extension":".toml"},{"scope":"project","path":".codex/agents/trackfw-{{id}}.toml","extension":".toml"}],"skills":[{"scope":"global","path":"~/.agents/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".agents/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"config","surface":"cli","scope":"project","path":".codex/config.toml","purpose":"custom agent configuration","required":false},{"id":"hooks","surface":"cli","scope":"project","path":".codex/hooks.json","purpose":"attention hooks","required":false}]},
+    {"id":"gemini","name":"Gemini CLI","surfaces":[{"id":"cli","name":"Gemini CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-markdown"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.gemini/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".gemini/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.gemini/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".gemini/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"context","surface":"cli","scope":"global","path":"~/.gemini/GEMINI.md","purpose":"global governance context","required":false},{"id":"settings","surface":"cli","scope":"project","path":".gemini/settings.json","purpose":"attention hooks","required":false}]},
+    {"id":"antigravity","name":"Google Antigravity","surfaces":[{"id":"current","name":"Antigravity IDE and CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-directory"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.gemini/config/agents/trackfw-{{id}}/agent.md","extension":".md"},{"scope":"project","path":".agents/agents/trackfw-{{id}}/agent.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.gemini/config/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".agents/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}},{"id":"legacy-cli","name":"Antigravity legacy CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"legacy","representation":"agent-json"},"skills":{"support_level":"legacy","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.gemini/antigravity-cli/agents/trackfw-{{id}}/agent.json","extension":".json"},{"scope":"project","path":".agents/agents/trackfw-{{id}}/agent.json","extension":".json"}],"skills":[{"scope":"global","path":"~/.gemini/antigravity-cli/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".agents/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"rules","surface":"current","scope":"project","path":".agents/rules/trackfw.md","purpose":"workspace governance rules","required":false},{"id":"workflows","surface":"current","scope":"project","path":".agents/workflows/trackfw.md","purpose":"workflow discovery","required":false}]},
+    {"id":"cursor","name":"Cursor","surfaces":[{"id":"ide","name":"Cursor IDE","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-markdown"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.cursor/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".cursor/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.cursor/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".cursor/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"hooks","surface":"ide","scope":"project","path":".cursor/hooks.json","purpose":"attention hooks","required":false}]},
+    {"id":"copilot","name":"GitHub Copilot","surfaces":[{"id":"ide","name":"GitHub Copilot","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"custom-agent"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.copilot/agents/trackfw-{{id}}.agent.md","extension":".agent.md"},{"scope":"project","path":".github/agents/trackfw-{{id}}.agent.md","extension":".agent.md"}],"skills":[{"scope":"global","path":"~/.copilot/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".github/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"instructions","surface":"ide","scope":"project","path":".github/copilot-instructions.md","purpose":"repository instructions","required":false},{"id":"hooks","surface":"ide","scope":"project","path":".github/hooks/trackfw-attention.json","purpose":"attention hooks","required":false}]},
+    {"id":"windsurf","name":"Windsurf","surfaces":[{"id":"ide","name":"Windsurf IDE","scopes":["global","project"],"capabilities":{"agents":{"support_level":"fallback","representation":"skill","fallback_representation":"specialist skill"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.codeium/windsurf/skills/trackfw-agent-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".windsurf/skills/trackfw-agent-{{id}}/SKILL.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.codeium/windsurf/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".windsurf/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"global-rules","surface":"ide","scope":"project","path":".windsurfrules","purpose":"governance rule discovery","required":false}]},
+    {"id":"amazonq","name":"Amazon Q Developer","surfaces":[{"id":"cli","name":"Amazon Q Developer CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"cli-agent-json"},"skills":{"support_level":"fallback","representation":"rule","fallback_representation":"workflow rule"}},"paths":{"agents":[{"scope":"global","path":"~/.aws/amazonq/cli-agents/trackfw-{{id}}.json","extension":".json"},{"scope":"project","path":".amazonq/cli-agents/trackfw-{{id}}.json","extension":".json"}],"skills":[{"scope":"global","path":"~/.aws/amazonq/rules/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".amazonq/rules/trackfw-{{id}}.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"guidelines","surface":"cli","scope":"project","path":".amazonq/developer/guidelines.md","purpose":"project governance guidelines","required":false}]},
+    {"id":"kiro","name":"Kiro","surfaces":[{"id":"ide","name":"Kiro IDE","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-markdown"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.kiro/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".kiro/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}},{"id":"cli","name":"Kiro CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-json"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.kiro/agents/trackfw-{{id}}.json","extension":".json"},{"scope":"project","path":".kiro/agents/trackfw-{{id}}.json","extension":".json"}],"skills":[{"scope":"global","path":"~/.kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"hooks","surface":"ide","scope":"project","path":".kiro/hooks/trackfw-attention.json","purpose":"attention hooks","required":false}]}
+  ]
+}

package/src/integrations/assets/skills/governance.md

@@ -0,0 +1,6 @@
+---
+name: trackfw-governance
+description: Inspect and maintain ADR, REQ, ROADMAP, traceability, lifecycle state and validation.
+---
+
+Run `trackfw context --format=json`, read the working context, preserve trace IDs and status-folder coherence, and run `trackfw validate --json` before reporting completion.

package/src/integrations/assets/skills/implement.md

@@ -0,0 +1,6 @@
+---
+name: trackfw-implement
+description: Implement work governed by an existing trackfw requirement and roadmap.
+---
+
+Identify the matching REQ and WIP roadmap before editing. Work one microbatch at a time, run focused project gates plus `trackfw validate --json`, and do not mark completion before acceptance criteria pass.

package/src/integrations/assets/skills/plan.md

@@ -0,0 +1,6 @@
+---
+name: trackfw-plan
+description: Plan governed changes with REQs, ADRs, roadmaps, microbatches and acceptance criteria.
+---
+
+Inspect existing governance artifacts, code and tests. Resolve material decisions in ADRs, create a linked REQ, and produce decision-complete parallelizable microbatches with exact validation commands.

package/src/integrations/assets/skills/release.md

@@ -0,0 +1,6 @@
+---
+name: trackfw-release
+description: Prepare and verify versioning, changelog, packaging, parity and publication gates.
+---
+
+Confirm traceability and completion, execute quality and package gates, derive SemVer from commits since the latest tag, and stop before publishing unless explicitly authorized.

package/src/integrations/assets/skills/review.md

@@ -0,0 +1,6 @@
+---
+name: trackfw-review
+description: Review changes for correctness, security, regression risk, tests and governance traceability.
+---
+
+Compare the branch with its base, verify the linked REQ and roadmap, and report evidence-backed findings by severity. Remain read-only unless fixes are explicitly requested.

package/src/integrations/catalog.js

@@ -0,0 +1,34 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const ASSET_ROOT = path.join(__dirname, 'assets')
+const catalog = Object.freeze(JSON.parse(fs.readFileSync(path.join(ASSET_ROOT, 'catalog.json'), 'utf8')))
+
+function items(kind) {
+  if (kind !== 'agents' && kind !== 'skills') throw new Error(`Unsupported integration kind: ${kind}`)
+  return catalog[kind]
+}
+
+function target(id) {
+  const found = catalog.targets.find(entry => entry.id === id)
+  if (!found) throw new Error(`Unsupported target: ${id}`)
+  return found
+}
+
+function surfaceFor(targetEntry, requested, kind = 'agents') {
+  const surfaces = targetEntry.surfaces || []
+  const found = requested
+    ? surfaces.find(entry => entry.id === requested)
+    : surfaces.find(entry => !['legacy', 'unsupported'].includes(entry.capabilities[kind].support_level)) || surfaces[0]
+  if (!found) throw new Error(`Unsupported surface ${requested} for target ${targetEntry.id}`)
+  return found
+}
+
+function readAsset(item) {
+  const relative = item.asset.replace(/^assets\//, '')
+  return fs.readFileSync(path.join(ASSET_ROOT, relative), 'utf8')
+}
+
+module.exports = { catalog, items, target, surfaceFor, readAsset }

package/src/integrations/index.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const { catalog, items, target, surfaceFor, readAsset } = require('./catalog')
+const { render } = require('./render')
+const { IntegrationManager } = require('./manager')
+const { legacyHashes } = require('./legacy')
+
+function parseSurfaces(values = []) {
+  const result = {}
+  for (const value of values) {
+    const [targetID, surfaceID, extra] = String(value).split('=')
+    if (!targetID || !surfaceID || extra !== undefined) throw new Error(`Invalid --surface ${value}: expected target=surface`)
+    if (result[targetID]) throw new Error(`Duplicate --surface for target ${targetID}`)
+    result[targetID] = surfaceID
+  }
+  return result
+}
+
+function selections(kind, options = {}) {
+  const selectedItems = options.items && options.items.length ? options.items : items(kind).map(item => item.id)
+  const itemEntries = selectedItems.map(id => {
+    const found = items(kind).find(item => item.id === id)
+    if (!found) throw new Error(`Unsupported ${kind} item: ${id}`)
+    return found
+  })
+  const targetValues = options.targets && options.targets.length ? options.targets : catalog.targets.map(entry => entry.id)
+  const surfaceSelections = parseSurfaces(options.surfaces)
+  const scopes = options.scope ? [options.scope] : ['project']
+  const targets = []
+  for (const targetID of targetValues) {
+    const targetEntry = target(targetID)
+    const selected = surfaceSelections[targetID]
+    const surfaces = options.allSurfaces && !selected
+      ? targetEntry.surfaces.filter(entry => entry.capabilities[kind].support_level !== 'unsupported')
+      : [surfaceFor(targetEntry, selected, kind)]
+    for (const surface of surfaces) targets.push({ target: targetEntry, surface })
+  }
+  return { itemEntries, targets, scopes }
+}
+
+function buildPlans(kind, options = {}) {
+  const selected = selections(kind, options)
+  const plans = []
+  for (const { target: targetEntry, surface } of selected.targets) {
+    const capability = surface.capabilities[kind]
+    if (capability.support_level === 'unsupported') continue
+    for (const scope of selected.scopes) {
+      if (!surface.scopes.includes(scope)) continue
+      const paths = surface.paths[kind].filter(entry => entry.scope === scope)
+      for (const item of selected.itemEntries) {
+        for (const installPath of paths) {
+          const destination = installPath.path.replace('{{id}}', item.id)
+          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination })
+          const claim = { target: targetEntry.id, surface: surface.id, scope, kind, item: item.id }
+          plans.push({
+            claim,
+            destination,
+            content,
+            catalogVersion: catalog.version,
+            supportLevel: capability.support_level,
+            representation: capability.representation,
+            legacyHashes: legacyHashes(claim),
+            item,
+          })
+        }
+      }
+    }
+  }
+  return plans.sort((a, b) => [a.claim.target, a.claim.surface, a.claim.scope, a.claim.item, a.destination].join('\0').localeCompare([b.claim.target, b.claim.surface, b.claim.scope, b.claim.item, b.destination].join('\0')))
+}
+
+function result(kind, plans, statuses) {
+  return {
+    kind,
+    catalog_version: catalog.version,
+    items: items(kind).map(({ id, name, description }) => ({ id, name, description })),
+    deployments: statuses.map((status, index) => ({
+      target: status.claim.target,
+      surface: status.claim.surface,
+      scope: status.claim.scope,
+      item: status.claim.item,
+      support_level: status.supportLevel,
+      representation: status.representation,
+      destination: plans[index].destination,
+      state: status.state,
+      managed: status.managed,
+    })),
+  }
+}
+
+function execute(kind, operation, options = {}, roots = {}) {
+  const plans = buildPlans(kind, options)
+  const manager = new IntegrationManager(roots)
+  let statuses
+  if (operation === 'list') statuses = manager.inspect(plans)
+  else if (operation === 'install') statuses = manager.install(plans, { force: options.force })
+  else if (operation === 'update') statuses = manager.update(plans, { force: options.force })
+  else if (operation === 'uninstall') statuses = manager.uninstall(plans, { force: options.force })
+  else throw new Error(`Unsupported integration operation: ${operation}`)
+  return result(kind, plans, statuses)
+}
+
+module.exports = { catalog, buildPlans, execute, IntegrationManager, parseSurfaces }

package/src/integrations/legacy.js

@@ -0,0 +1,35 @@
+'use strict'
+
+// SHA-256 values emitted by the pre-lifecycle installers. They are deliberately
+// static: only byte-identical historical templates may be adopted.
+const LEGACY_HASHES = Object.freeze({
+  // Go/Homebrew `trackfw agents` Claude templates.
+  'claude:cli:global:agents:architect': ['d28ae507d2ce9fd3fcd7cb1a0c1ffaaebc994dc9c45b219e5361b909dc6132ba'],
+  'claude:cli:global:agents:backend': ['587bf790907bc7451976c026b9c7dc5419541a5fdfb064586744198dcf8c0439'],
+  'claude:cli:global:agents:code-quality': ['8917909b55ed54cfa8bb66015a301428f4d924bb3658a9c4c5d443e14e60d399'],
+  'claude:cli:global:agents:data': ['3a402a85610cf3d463200d0f81fda61b5c6c02a0198d302a5d6da49e8e5ff688'],
+  'claude:cli:global:agents:dba': ['07aa92c09833a7c72c3d9b3e39ec1272a91e435deda2da5ddef321abed3702fa'],
+  'claude:cli:global:agents:frontend': ['7ae3940a0827b0047363cd984be5e96b66902098c5ea669d0975a234027ca39c'],
+  'claude:cli:global:agents:infra': ['9f5534c83c3d3b0a9e8c550bd7a3cbb861eb7c4d7671fe8783cd68ff5d5c1605'],
+  'claude:cli:global:agents:qa': ['384283eb46d5e3c5ee978fc87e1b5cd44009e3c62d57c8dcd5cf92189b79e291'],
+  'claude:cli:global:agents:security': ['10e02aa03fe502174174e376d9ec845c549f828af885059214af23854efb4c3f'],
+  'claude:cli:global:agents:ux': ['49b5bbcb8063075bda0b254d1040ae7d2b8d8c315f538cf05e39774ab8a2907b'],
+
+  // npm `installCodex`: five catalog agents and five workflow skills.
+  'codex:cli:project:agents:architect': ['c7e4b34984a8ba54753ecb9c0b2a1ad10b0d2083a15e03bcb19016012efa39e1', '38199d6edfc0fd7c5d6663996541a25a17203d87713709d0a0daad2ecc5d6be6', '94512bd3db605d5170841018adc2246ce314a57b3be07938fc61d0c41ef6126c'],
+  'codex:cli:project:agents:backend': ['0e2327ace2c719fcb0abe2f17dfdbad4a0d987824f888e6802a9f4a132163f64', '348c5ab0a57597f332c2a5b293f045a0d3980875a9c9083a06cad15f909e23a7', '43759e9a912bb236a997d58ad184dfcda2b45f6e00ed5a5edad93d83dd9c906d'],
+  'codex:cli:project:agents:frontend': ['1a377e6c9a51f1df549e475558897dac428f94ae50e6955a1ca99cb0b04b0648', '608c10cc0f910725ad813736a2548e1c66479abce28d32d4b8969707be1054f1', '5ebf3a404d300e17338538eeb8f50d63bda8fde5f5f0bf0b73767434233ae9c4'],
+  'codex:cli:project:agents:qa': ['aad7e86d59e511e6b1519e2e26bb4de376eb124725a44d82f704edf396989ac0', '3e8b3a5d04aa44c62ce6af801be9d907aa6458931c19676ca999776ac961254d', '33663bb0ee4bee4cd971a691283649b308ad093a01000762a70ec79481d10e52'],
+  'codex:cli:project:agents:security': ['b7743d40163066794941f37fab259f965bb78c54c9a8fe3cc7a0146d2552f016', 'cdd197001ebabf8cf63b8c1562d0eb89b226df8a2e5dcb1ce84e9a1ea6de782d', '1e3987835233bbdb0751e98a50ec7512dfc7855e293aa40d1ad77c80dde1945f'],
+  'codex:cli:project:skills:governance': ['54edf417d53e2a91f52651de5a31a9c1b80be8d0f7f1252c5b9f3b55630a9b96', 'c30786495105715ae707d374b414d21344b20a0cd354713f8173c5109d690fd9', 'be044d1a1f2af4835d476a3f4798b35e2067eeebdff8f30872353eee6b212736'],
+  'codex:cli:project:skills:implement': ['bb9bbe197244cd4537610579b324757e8c7f97755a78fdb01daab4638485bfc2', '898682d21e6ba938a2ef2fe4908f4047358e3f27ca291068a5585a47aca1426e', 'c5a53c5e9444810d3beeebe563798de792615c7703a0d99e954d578d068af4d4'],
+  'codex:cli:project:skills:plan': ['dc038a9f18bd0fee7e03d8c7816f058e9c95a4e729dddfb086d642a61bc676ba', '2ef36f3ac8c77eb46d13ba4cbe420e1c872f71edace9b7851d63cb50bc5f3708', 'b2cd10338db33369e78656a1e3877427a454f9eab6fa1ec948fd17730c66b46a'],
+  'codex:cli:project:skills:release': ['2db9c460046da9cb918acb7f716727a07fdb5b361f2a81a67c35b8fe09135fcd', '2450fd34b81a14d28c794abc0e9ac0213ba929a950d15b3226443c92419d42c9'],
+  'codex:cli:project:skills:review': ['bea0debcb3b8f5014a7c7ae0e93b9b8c4b318e14c8fc8ff6510594410a123783', 'b17fbc6d59bdfad64d2c1993cc588c0e6e9ae8e4b4a16669abf254d41cc40330', '8b3119641a0d06b99b451cf6437c15a2f7f58069fb0ebf855ab757f66b919b53'],
+})
+
+function legacyHashes(claim) {
+  return [...(LEGACY_HASHES[`${claim.target}:${claim.surface}:${claim.scope}:${claim.kind}:${claim.item}`] || [])]
+}
+
+module.exports = { LEGACY_HASHES, legacyHashes }

package/src/integrations/manager.js

@@ -0,0 +1,237 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const SCHEMA_VERSION = 1
+const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
+const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item].join('\u0000')
+const cleanClaim = claim => ({ target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item })
+
+class IntegrationManager {
+  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}) {
+    this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
+  }
+
+  manifestPath(scope) { return path.join(this.roots[scope], '.trackfw', 'integrations-manifest.json') }
+
+  resolve(scope, destination) {
+    const root = this.roots[scope]
+    if (!root) throw new Error(`Unsupported scope: ${scope}`)
+    if (typeof destination !== 'string' || destination.includes('\u0000') || destination.includes('\\')) throw new Error(`Unsafe destination: ${destination}`)
+    let resolved
+    if (destination.startsWith('~/')) {
+      if (scope !== 'global') throw new Error('Home destination requires global scope')
+      resolved = path.resolve(root, destination.slice(2))
+    } else if (path.isAbsolute(destination)) {
+      resolved = path.normalize(destination)
+    } else {
+      if (!destination || path.normalize(destination) !== destination || destination === '.' || destination.startsWith(`..${path.sep}`)) throw new Error(`Unsafe destination: ${destination}`)
+      resolved = path.resolve(root, destination)
+    }
+    const rel = path.relative(root, resolved)
+    if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`Destination is outside ${scope} root: ${destination}`)
+    this.assertNoSymlinks(root, resolved)
+    this.assertNoSymlinks(root, this.manifestPath(scope))
+    return resolved
+  }
+
+  assertNoSymlinks(root, destination) {
+    let current = destination
+    while (true) {
+      if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) throw new Error(`Symlink path is not allowed: ${current}`)
+      if (current === root) return
+      const parent = path.dirname(current)
+      const rel = path.relative(root, current)
+      if (parent === current || rel === '..' || rel.startsWith(`..${path.sep}`)) throw new Error(`Path escapes root: ${destination}`)
+      current = parent
+    }
+  }
+
+  loadManifest(scope) {
+    const file = this.manifestPath(scope)
+    this.assertNoSymlinks(this.roots[scope], file)
+    if (!fs.existsSync(file)) return { schema_version: SCHEMA_VERSION, artifacts: {} }
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (parsed.schema_version !== SCHEMA_VERSION || !parsed.artifacts || Array.isArray(parsed.artifacts)) throw new Error(`Unsupported integration manifest: ${file}`)
+    return parsed
+  }
+
+  atomicWrite(file, content, mode) {
+    const root = this.rootFor(file)
+    this.assertNoSymlinks(root, file)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`)
+    try {
+      fs.writeFileSync(tmp, content, { mode })
+      fs.chmodSync(tmp, mode)
+      fs.renameSync(tmp, file)
+      fs.chmodSync(file, mode)
+    } finally {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
+    }
+  }
+
+  rootFor(file) {
+    const found = Object.values(this.roots).find(root => {
+      const rel = path.relative(root, file)
+      return rel && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)
+    })
+    if (!found) throw new Error(`Path is outside integration roots: ${file}`)
+    return found
+  }
+
+  saveManifest(scope, manifest) {
+    const artifacts = {}
+    for (const destination of Object.keys(manifest.artifacts).sort()) {
+      const artifact = manifest.artifacts[destination]
+      artifact.claims = artifact.claims.map(cleanClaim).sort((a, b) => claimKey(a).localeCompare(claimKey(b)))
+      artifacts[destination] = artifact
+    }
+    this.atomicWrite(this.manifestPath(scope), `${JSON.stringify({ schema_version: SCHEMA_VERSION, artifacts }, null, 2)}\n`, 0o600)
+  }
+
+  inspect(plans) {
+    const manifests = new Map()
+    return plans.map(plan => {
+      const scope = plan.claim.scope
+      if (!manifests.has(scope)) manifests.set(scope, this.loadManifest(scope))
+      const file = this.resolve(scope, plan.destination)
+      const record = manifests.get(scope).artifacts[file]
+      const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
+      if (!fs.existsSync(file)) return { ...plan, destination: file, state: 'not-installed', managed }
+      const actual = sha256(fs.readFileSync(file))
+      const desired = sha256(plan.content)
+      let state
+      if (record) {
+        if (actual !== record.sha256) state = 'modified'
+        else if (actual !== desired || record.catalog_version !== plan.catalogVersion) state = 'outdated'
+        else state = 'current'
+      } else if (actual === desired) state = 'current'
+      else if ((plan.legacyHashes || []).includes(actual)) state = 'outdated'
+      else state = 'modified'
+      return { ...plan, destination: file, state, managed }
+    })
+  }
+
+  install(plans, { force = false } = {}) { return this.mutate('install', plans, force) }
+  update(plans, { force = false } = {}) { return this.mutate('update', plans, force) }
+  uninstall(plans, { force = false } = {}) { return this.mutate('uninstall', plans, force) }
+
+  mutate(operation, plans, force) {
+    const resolved = plans.map(plan => ({ plan, file: this.resolve(plan.claim.scope, plan.destination) }))
+    const manifests = new Map()
+    for (const { plan } of resolved) if (!manifests.has(plan.claim.scope)) manifests.set(plan.claim.scope, this.loadManifest(plan.claim.scope))
+    const desiredByFile = new Map()
+    for (const item of resolved) {
+      const desired = sha256(item.plan.content)
+      if (operation !== 'uninstall' && desiredByFile.has(item.file) && desiredByFile.get(item.file) !== desired) throw new Error(`Conflicting content planned for: ${item.file}`)
+      desiredByFile.set(item.file, desired)
+      this.preflight(operation, item, manifests.get(item.plan.claim.scope), force)
+    }
+    const snapshots = new Map()
+    for (const item of resolved) this.snapshot(snapshots, item.file)
+    for (const scope of manifests.keys()) this.snapshot(snapshots, this.manifestPath(scope))
+    try {
+      for (const item of resolved) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
+      for (const [scope, manifest] of [...manifests].sort(([a], [b]) => a.localeCompare(b))) this.saveManifest(scope, manifest)
+    } catch (error) {
+      this.rollback(snapshots)
+      throw error
+    }
+    return this.inspect(plans)
+  }
+
+  preflight(operation, { plan, file }, manifest, force) {
+    const status = this.inspectResolved(plan, file, manifest)
+    const record = manifest.artifacts[file]
+    const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
+    if (operation === 'install') {
+      if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
+      if (status.state === 'outdated' && owned && !force) throw new Error(`Artifact is outdated; use update: ${file}`)
+    } else if (operation === 'update') {
+      if (!owned && status.state === 'modified') throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+      if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
+    } else if (operation === 'uninstall' && owned && status.state === 'modified' && !force) {
+      throw new Error(`Artifact is modified; use --force: ${file}`)
+    }
+  }
+
+  inspectResolved(plan, file, manifest) {
+    const record = manifest.artifacts[file]
+    const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
+    if (!fs.existsSync(file)) return { state: 'not-installed', managed }
+    const actual = sha256(fs.readFileSync(file))
+    const desired = sha256(plan.content)
+    if (record) {
+      if (actual !== record.sha256) return { state: 'modified', managed }
+      return { state: actual === desired && record.catalog_version === plan.catalogVersion ? 'current' : 'outdated', managed }
+    }
+    if (actual === desired) return { state: 'current', managed: false }
+    if ((plan.legacyHashes || []).includes(actual)) return { state: 'outdated', managed: false }
+    return { state: 'modified', managed: false }
+  }
+
+  apply(operation, { plan, file }, manifest, force) {
+    let record = manifest.artifacts[file]
+    const key = claimKey(plan.claim)
+    const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === key))
+    if (operation === 'uninstall') {
+      if (!owned) return
+      record.claims = record.claims.filter(claim => claimKey(claim) !== key)
+      if (record.claims.length) return
+      if (fs.existsSync(file)) fs.unlinkSync(file)
+      delete manifest.artifacts[file]
+      this.cleanEmpty(path.dirname(file), this.roots[plan.claim.scope])
+      return
+    }
+
+    const exists = fs.existsSync(file)
+    let actual = exists ? sha256(fs.readFileSync(file)) : ''
+    const desired = sha256(plan.content)
+    const knownLegacy = (plan.legacyHashes || []).includes(actual)
+    let writeDesired = !exists
+    if (exists && !owned) writeDesired = (operation === 'update' && actual !== desired) || (force && actual !== desired)
+    else if (exists && owned) writeDesired = actual !== desired
+    if (!record) record = { destination: file, sha256: '', catalog_version: '', claims: [] }
+    if (writeDesired) {
+      this.atomicWrite(file, plan.content, 0o644)
+      actual = desired
+    } else if (exists && !owned && actual !== desired && !knownLegacy && !force) {
+      throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+    }
+    if (!record.claims.some(claim => claimKey(claim) === key)) record.claims.push(cleanClaim(plan.claim))
+    record.sha256 = actual
+    record.catalog_version = actual === desired ? plan.catalogVersion : 'legacy'
+    manifest.artifacts[file] = record
+  }
+
+  snapshot(snapshots, file) {
+    if (snapshots.has(file)) return
+    if (!fs.existsSync(file)) snapshots.set(file, null)
+    else snapshots.set(file, { content: fs.readFileSync(file), mode: fs.statSync(file).mode & 0o777 })
+  }
+
+  rollback(snapshots) {
+    for (const [file, snapshot] of [...snapshots].reverse()) {
+      try {
+        if (!snapshot) { if (fs.existsSync(file) && !fs.lstatSync(file).isDirectory()) fs.unlinkSync(file) }
+        else this.atomicWrite(file, snapshot.content, snapshot.mode)
+      } catch { /* preserve original error */ }
+    }
+  }
+
+  cleanEmpty(directory, root) {
+    while (directory !== root) {
+      const rel = path.relative(root, directory)
+      if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return
+      if (!fs.existsSync(directory) || fs.lstatSync(directory).isSymbolicLink() || fs.readdirSync(directory).length) return
+      fs.rmdirSync(directory)
+      directory = path.dirname(directory)
+    }
+  }
+}
+
+module.exports = { IntegrationManager, sha256, claimKey, SCHEMA_VERSION }

package/src/integrations/render.js

@@ -0,0 +1,42 @@
+'use strict'
+
+function normalize(content) {
+  return `${content.trim()}\n`
+}
+
+function markdownParts(content) {
+  const text = content.trim()
+  let name = 'trackfw-agent'
+  let description = 'trackfw specialist'
+  let body = text
+  if (text.startsWith('---\n')) {
+    const end = text.indexOf('\n---', 4)
+    if (end >= 0) {
+      const frontmatter = text.slice(4, end)
+      body = text.slice(end + 4).trim()
+      for (const line of frontmatter.split('\n')) {
+        const separator = line.indexOf(':')
+        if (separator < 0) continue
+        const key = line.slice(0, separator).trim()
+        const value = line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, '')
+        if (key === 'name') name = value
+        if (key === 'description') description = value
+      }
+    }
+  }
+  return { name, description, body }
+}
+
+function render({ kind, content, capability }) {
+  if (kind === 'skills') return normalize(content)
+  const parts = markdownParts(content)
+  if (capability.representation === 'custom-agent-toml') {
+    return `name = ${JSON.stringify(parts.name.replaceAll('-', '_'))}\ndescription = ${JSON.stringify(parts.description)}\ndeveloper_instructions = ${JSON.stringify(parts.body)}\n`
+  }
+  if (capability.representation === 'cli-agent-json' || capability.representation === 'agent-json') {
+    return `${JSON.stringify({ name: parts.name, description: parts.description, prompt: parts.body }, null, 2)}\n`
+  }
+  return normalize(content)
+}
+
+module.exports = { render, markdownParts }