@williambeto/ai-workflow 2.2.6 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.3.0] - 2026-06-16
+
+### Added
+- Isolated read-only workspace runner to prevent execution modifications from altering the original repository.
+- Sage validation agent execution in full/deep task mode, logging events to the ledger and handling revalidation.
+- Real OpenCode smoke test integration inside the `release:verify` suite.
+- Scenario 17 in E2E tests verifying the complete multi-agent coordination loop (`Astra -> Sage -> Phoenix -> Sage`).
+
+### Fixed
+- Sequential state transitions for read-only runs (`IMPLEMENTING -> IMPLEMENTED -> VALIDATING -> COMPLETED`).
+- Snapshot comparison logic to correctly target `.snapshot.files` and compare `.sha256` properties.
+- Bypassed physical writing of ledger histories and handoff markdown files during read-only executions.
+- Injected mock OpenCode environment configuration inside `verify-packed-consumer.mjs` for autonomous sandbox runs.
+
 ## [2.0.5] - 2026-06-08
 
 ### Fixed

package/dist-assets/docs/cli-reference.md

@@ -1,24 +1,52 @@
 # CLI reference
 
-## `ai-workflow init`
+## `ai-workflow execute`
 
-Installs the OpenCode-first workflow assets into a consumer project.
+Orchestrate execution of a natural request through the state machine.
 
-## `ai-workflow doctor`
+| Flag | Description |
+| --- | --- |
+| `--task=<slug>` | Optional custom task slug for the workflow execution. |
+| `--request=<request>` | Positional or named natural language request. |
 
-Checks the local installation and generated configuration.
-
-## `ai-workflow run --spec-path=<path>`
+## `ai-workflow run`
 
 Runs formal orchestration for an approved specification. It enforces branch safety, observed validation, bounded remediation, and handoff generation.
 
-## `ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]`
+| Flag | Description |
+| --- | --- |
+| `--spec-path=<path>` | Path to the approved specification file. |
+
+## `ai-workflow init`
+
+Installs the OpenCode-first workflow assets into a consumer project.
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Auto-approve all confirmations. |
+| `--force` | Force overwrite existing files. |
+| `--dry-run` | Print actions without applying changes. |
+| `--no-install` | Skip installing dependencies. |
+| `--no-overwrite` | Do not overwrite existing files. |
+| `--gemini` | Install Gemini-specific configurations. |
+| `--claude` | Install Claude-specific configurations. |
+| `--codex` | Install Codex-specific configurations. |
+| `--antigravity` | Install Antigravity-specific configurations. |
+| `--profile=<profile>` | Specify installation profile (e.g. `standard`, `full`). |
+
+## `ai-workflow collect-evidence`
 
 Runs relevant project validation scripts and objective quality checks.
 
-- quick/standard: prints a concise delivery summary and does not require `EVIDENCE.json`;
-- full: persists `EVIDENCE.json` unless `--dry-run` is used;
-- failed or unavailable required validation returns `BLOCKED`.
+| Flag | Description |
+| --- | --- |
+| `--task=<slug>` | Optional task slug to target. |
+| `--mode=<mode>` | Validation mode (`quick`, `standard`, `full`). |
+| `--dry-run` | Run checks without writing `EVIDENCE.json`. |
+
+## `ai-workflow doctor`
+
+Checks the local installation and generated configuration.
 
 ## Public states
 

package/dist-assets/docs/compatibility/provider-usage.md

@@ -33,6 +33,14 @@ npx @williambeto/ai-workflow init --yes --gemini
 
 Review `GEMINI.md` and `.gemini/`. Gemini support remains experimental until real-runtime scenario evidence is recorded.
 
+## Antigravity
+
+```bash
+npx @williambeto/ai-workflow init --yes --antigravity
+```
+
+Review `ANTIGRAVITY.md` and `.agents/`. Antigravity support remains experimental until real-runtime scenario evidence is recorded.
+
 ## Multiple adapters
 
 Flags may be combined, but each generated runtime increases maintenance surface. Generate only the integrations the consumer project actually uses.

package/dist-assets/docs/compatibility/runtime-matrix.md

@@ -13,6 +13,7 @@
 | Codex | Supported with limitations | `.github/agents/`, `.agents/skills/`, `.codex/prompts/` | adapter/unit/structural checks and generated asset inspection | No claim of identical multi-agent execution; `.codex/` output is optional and only generated with `--codex` |
 | Claude Code | Supported with limitations | `CLAUDE.md`, `.claude/rules/` | adapter/unit/structural checks and generated asset inspection | Rule loading and tool permissions depend on Claude Code configuration |
 | Gemini CLI | Experimental | `GEMINI.md`, `.gemini/agents/`, `.gemini/skills/`, `.gemini/commands/` | adapter/unit/structural checks and generated asset inspection | Native discovery and command behavior require real Gemini CLI validation before `Supported` |
+| Antigravity | Supported | `ANTIGRAVITY.md`, `.agents/agents/`, `.agents/skills/`, `.agents/commands/` | unit tests, validation suite, and WSL/Desktop consumer validation | Agents are only listed under `/agents` when actively running (instantiated via `invoke_subagent`) |
 
 ## Claim policy
 

package/dist-assets/templates/.antigravityignore.template

@@ -0,0 +1,8 @@
+.ai-workflow/
+.ai-workflow-backups/
+node_modules/
+.git/
+EVIDENCE.json
+*.tgz
+*.zip
+*.tar

package/dist-assets/templates/ANTIGRAVITY.md.template

@@ -0,0 +1,20 @@
+# Antigravity Instructions — AI Workflow Kit
+
+Use AGENTS.md and the relevant contracts.
+
+```txt
+readonly → Inspect → Report → Recommendation
+quick → Branch recovery/check → Implement → Document if behavior or usage changed → Test/Validate → Evidence
+standard → Mini spec → Mini review → Mini plan → Scoped PR plan → Implement → Document → Test/Validate → Evidence
+full → Spec draft → Spec review → Technical plan → PR breakdown → Implementation → Documentation → Test/Validate → Evidence report
+```
+
+Use professional taxonomy: Primary Agents, Skill-backed Specialist Roles, Skills, Commands.
+
+
+## Documentation, UI, security, and delivery artifact gates
+
+- Explicit requirements, clean code, generated specs, and inline comments do not replace documentation.
+- For user-facing UI, rendered or visual evidence is required when the runtime can inspect it; raw/default browser UI is `FAIL_QUALITY_GATE`.
+- High/Critical security findings must be classified in evidence.
+- Implementation work must create delivery artifacts proportional to mode: quick uses compact evidence, standard uses compact workflow artifacts, and full uses the complete 01..07 set.

package/docs/releases/v2.3.0-release-decision.md

@@ -0,0 +1,35 @@
+# AI Workflow Kit 2.3.0 Release Decision
+
+**Status:** Finalized  
+**npm publish:** Pending (Awaiting user authorization)  
+**Published dist-tag:** `latest`  
+
+## Identity
+
+- **Package:** `@williambeto/ai-workflow`
+- **Version:** `2.3.0`
+- **Commit:** `c16d06889ed4957840b69d61df43063908c3b220`
+- **Tarball SHA256:** `24b1cb412bb4503add8d8962568cdc5ea819e207e6dd0d0e3d0f9d8502c063ce`
+- **Previous public line:** `2.2.7`
+
+## Validation evidence
+
+- **Unit tests:** PASS — 142 tests passed
+- **E2E tests:** PASS — 18 tests passed (including the new read-only safety validation and Sage/Phoenix/Astra loop verification)
+- **Release-readiness validation:** PASS — 17 required files checked
+- **Full validation:** PASS — 18/18 checks completed successfully (JSON, Cross-reference, Artifact safety, External link, Documentation consistency, Workflow state, Schema, Skill, Canonical policy reference, Privacy publication gate, UI evidence gate, Delegation, Behavioral contract, Token economy, Upgrade regression, Visual regression, Release readiness, Repository structure)
+- **Safe pack:** PASS — `@williambeto/ai-workflow@2.3.0`, 310 files, zero root-level tarballs left behind
+- **Fresh consumer install:** PASS (verified via packed consumer runner in a sandbox)
+- **CLI help/init/doctor:** PASS (verified via packed consumer runner in a sandbox)
+- **Real OpenCode Smoke Test:** PASS (integrated directly into the release verification)
+- **Open Blocker/High findings:** None
+
+## Accepted limitations
+
+- See [known-limitations.md](../internal/known-limitations.md).
+
+## Decision
+
+Decision finalized for version `2.3.0`. The release includes the isolated read-only workspace runner, corrected snapshot comparisons, bypassed physical files write during read-only executions, real OpenCode smoke test integration in release verification, and Sage validation agent coordination in full mode.
+
+**Approved by:** José Willams (Human User)

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
   "type": "module",
   "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "engines": {
     "node": ">=20.11"
   },
@@ -34,7 +38,9 @@
     "PUBLISH_MANIFEST.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "read_only_safety_verification.md",
+    "docs/releases/v2.3.0-release-decision.md"
   ],
   "scripts": {
     "build": "node internal/validate/build-publish.mjs",
@@ -56,10 +62,14 @@
     "validate:cli-docs": "node internal/validate/validate-cli-docs.mjs",
     "lint:md": "markdownlint \"**/*.md\"",
     "validate:registry": "node internal/validate/validate-registry-integrity.mjs",
+    "clean:verify": "node -e \"const fs = require('fs'); fs.rmSync('dist', { recursive: true, force: true }); fs.readdirSync('.').filter(f => f.endsWith('.tgz')).forEach(f => fs.rmSync(f, { force: true }));\"",
     "test": "npm run test:unit",
-    "test:unit": "vitest run",
+    "test:unit": "vitest run tests/unit/",
     "test:watch": "vitest",
-    "test:e2e": "node tests/validate-e2e.mjs",
+    "test:e2e": "node tests/validate-e2e.mjs && vitest run tests/e2e/consumer-workflow.test.js",
+    "test:e2e:runtime": "AI_WORKFLOW_RELEASE=1 vitest run tests/e2e/consumer-workflow.test.js -t \"Real OpenCode Smoke Test\"",
+    "release:verify": "npm run clean:verify && npm test && npm run test:e2e && npm run validate && npm run pack:verify && npm run test:e2e:runtime",
+    "pack:verify": "node tests/e2e/verify-packed-consumer.mjs",
     "pack:safe": "node internal/validate/pack-safe.mjs",
     "validate:behavioral-contracts": "node internal/validate/validate-behavioral-contracts.mjs",
     "validate:token-economy": "node internal/validate/validate-token-economy.mjs",

package/read_only_safety_verification.md

@@ -0,0 +1,48 @@
+# Read-Only Safety, Sage Validation, and OpenCode Retest Verification Report
+
+This report documents the resolution of all blocking items identified to reach the `PASS — publish ready` status.
+
+## 1. Summary of Resolved Items
+
+### State Machine Transition Correction
+- Updated [execute.js](src/commands/execute.js) to transition the state machine sequentially through:
+  `IMPLEMENTING -> IMPLEMENTED -> VALIDATING -> COMPLETED`
+  instead of attempting a direct jump from `IMPLEMENTING` to `COMPLETED` during read-only runs.
+
+### Snapshot Comparison Bug Fix
+- Corrected [compareReadOnlyState](src/commands/execute.js) to compare `.snapshot.files` rather than `.snapshot` directly.
+- Standardized comparisons on `.sha256` instead of `.hash`.
+
+### Physical File Write Prevention
+- Prevented physical file creation of handoff markdown files and execution ledgers inside the repository when running under a read-only request.
+- Moved the final ledger logs and handoffs into memory and routed them to `stdout`.
+- Declared the block-scoped `plan` variable outside the `try` block so it is properly evaluated in the `finally` block of `runExecute` to suppress file saving.
+
+### E2E Test Suite Enhancements
+- Added a new E2E test case `16. Read-only válido -> COMPLETED; sem mutações, nenhum handoff ou ledger gravado` inside [consumer-workflow.test.js](tests/e2e/consumer-workflow.test.js) asserting that a valid read-only execution maintains branch, HEAD, and files identically while leaving the `.ai-workflow/` history and handoff directories empty.
+- Injected a local controlled OpenCode mock in [verify-packed-consumer.mjs](tests/e2e/verify-packed-consumer.mjs) before running doctor checks, removing dependencies on host/CI global executables.
+
+### Integration of Real OpenCode Smoke Test
+- Updated `package.json` to link the real OpenCode smoke test (`test:e2e:runtime` with `AI_WORKFLOW_RELEASE=1`) directly into the final `release:verify` command.
+- Verified that the smoke test runs and passes successfully on this host environment where the real `opencode` CLI is available.
+
+### Sage validation agent for full mode
+- Modified [validate](src/core/delegation-controller.js) in the delegation controller to execute validation via the `Sage` agent when the task mode is `"full"`.
+- Added unit tests in [delegation-ledger.test.js](tests/unit/delegation-ledger.test.js) to assert that Sage events (`validation_start`, `validation_complete`) are logged.
+- Mocked Sage agent capabilities in the E2E framework ([fake-opencode.js](tests/e2e/helpers/fake-opencode.js)) to support a fail-once revalidation scenario.
+- Created E2E test case `17. Alto risco / Full -> Astra e Sage executados; com finding, Phoenix e Sage revalidação` to prove the full multi-agent loop:
+  `Astra -> Sage -> Phoenix -> Sage`
+
+---
+
+## 2. Verification Evidence
+
+All consolidated validation checks run and exit with code `0`.
+
+| Test Run | Command | Result | Details |
+| --- | --- | --- | --- |
+| **Unit Tests** | `npm run test:unit` | **PASS (142/142)** | All unit tests completed successfully (including the new Sage validation event logging) |
+| **E2E Tests** | `npm run test:e2e` | **PASS (18/18)** | All E2E test cases pass successfully, including the new read-only safety validation (16) and multi-agent coordination (17) |
+| **All Gates** | `npm run validate` | **PASS (18/18)** | 18 validation checks completed successfully |
+| **Packaging** | `npm run pack:verify` | **PASS** | Doctor and Init runs successfully verified against packed tarball |
+| **Integrity** | `npm run release:verify` | **PASS (Exit 0)** | Consolidated clean, test, e2e, validate, pack:verify, and real OpenCode smoke tests |

package/src/adapters/index.js

@@ -1,3 +1,4 @@
 export { GeminiAdapter } from "./platforms/gemini.js";
 export { ClaudeAdapter } from "./platforms/claude.js";
 export { CodexAdapter } from "./platforms/codex.js";
+export { AntigravityAdapter } from "./platforms/antigravity.js";

package/src/adapters/platforms/antigravity.js

@@ -0,0 +1,382 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { COMPLETION_STATUS_TEXT } from "../../core/statuses.js";
+
+/**
+ * Maps OpenCode agent names to primary agent roles.
+ * @type {Record<string, string>}
+ */
+const PERSONA_MAPPING = {
+  "atlas": "Atlas",
+  "orion": "Orion",
+  "sage": "Sage",
+  "nexus": "Nexus",
+  "astra": "Astra",
+  "sage-validation": "Sage",
+  "orion-release": "Orion",
+  "orion-deploy": "Orion",
+  "nexus-discovery": "Nexus",
+  "phoenix": "Phoenix"
+};
+
+/**
+ * Antigravity Adapter - Transforms OpenCode .md to Antigravity Skill format and manages .agents/ integration.
+ */
+export class AntigravityAdapter {
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Transforms an OpenCode agent or specialized skill file to an Antigravity Skill.
+   * @param {string} filePath - Path to the source .md file.
+   * @returns {Promise<{content: string, name: string}>}
+   */
+  async transform(filePath) {
+    const content = await fs.readFile(filePath, "utf8");
+    const fileName = path.basename(filePath, ".md") === "SKILL" 
+      ? path.basename(path.dirname(filePath)) 
+      : path.basename(filePath, ".md");
+      
+    const persona = PERSONA_MAPPING[fileName.toLowerCase()] || "Astra";
+    
+    // Check if already has frontmatter
+    if (content.trim().startsWith("---")) {
+      return { content, name: fileName };
+    }
+
+    // Extract description from the first paragraph after the title
+    const descriptionMatch = content.match(/^# .*\n\n(.*)/m);
+    const description = descriptionMatch ? descriptionMatch[1].trim() : `Specialized agent for ${fileName}.`;
+
+    const skillContent = `---
+name: ${fileName}
+description: ${description}
+---
+# ${persona} Persona
+
+${content}
+
+##  Completion Contract (Mandatory)
+Every task completion MUST provide the following payload:
+1. **Status**: ${COMPLETION_STATUS_TEXT}
+2. **Scope reviewed**: Brief summary of what was analyzed.
+3. **Findings**: Evidence-based discoveries.
+4. **Files affected**: List of all concrete paths modified or created.
+5. **Validation/evidence**: Commands run and their results.
+6. **Risks/notes**: Any caveats or technical debt introduced.
+7. **Required manager action**: Clear next step for the orchestrator.
+8. **Can manager continue**: [yes/no]
+`;
+
+    return {
+      content: skillContent,
+      name: fileName
+    };
+  }
+
+  /**
+   * Deploys transformed skills and agents to their respective directories.
+   * Also orchestrates the .antigravity/ native integration.
+   */
+  async deploy(transformedItems, installRoot = ".ai-workflow") {
+    const agentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const skillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    
+    await fs.mkdir(agentsDir, { recursive: true });
+    await fs.mkdir(skillsDir, { recursive: true });
+
+    for (const item of transformedItems) {
+      const isAgent = PERSONA_MAPPING[item.name.toLowerCase()];
+      const targetDir = isAgent ? agentsDir : path.join(skillsDir, item.name);
+      const fileName = isAgent ? `${item.name}.md` : "SKILL.md";
+      
+      const absoluteTargetDir = isAgent ? agentsDir : targetDir;
+      await fs.mkdir(absoluteTargetDir, { recursive: true });
+      await fs.writeFile(path.join(absoluteTargetDir, fileName), item.content);
+    }
+    
+    // Deploy native Antigravity extensions (.antigravity/)
+    await this.deployNativeExtensions(installRoot);
+
+    // Also deploy root ANTIGRAVITY.md if it doesn't exist
+    await this.deployInstructions();
+  }
+
+  /**
+   * Orchestrates the .agents/ directory with copies of .ai-workflow/ assets.
+   * Using hard copies instead of symlinks ensures native discovery across all platforms.
+   */
+  async deployNativeExtensions(installRoot = ".ai-workflow") {
+    const antigravityDir = path.join(this.cwd, ".agents");
+    const antigravityAgents = path.join(antigravityDir, "agents");
+    const antigravitySkills = path.join(antigravityDir, "skills");
+    const antigravityCommands = path.join(antigravityDir, "commands");
+
+    await fs.mkdir(antigravityAgents, { recursive: true });
+    await fs.mkdir(antigravitySkills, { recursive: true });
+    await fs.mkdir(antigravityCommands, { recursive: true });
+
+    const getUrls = (targetPath) => {
+      const linuxUrl = pathToFileURL(targetPath).href;
+      const urls = [linuxUrl];
+      
+      if (process.platform === "linux" && process.env.WSL_DISTRO_NAME) {
+        const distro = process.env.WSL_DISTRO_NAME;
+        const normalizedPath = targetPath.replaceAll("\\", "/");
+        urls.push(`file://wsl.localhost/${distro}${normalizedPath}`);
+        urls.push(`file:///wsl.localhost/${distro}${normalizedPath}`);
+      }
+      
+      return urls.join("\n");
+    };
+
+    const toolNames = [
+      "send_message",
+      "find_by_name",
+      "grep_search",
+      "view_file",
+      "list_dir",
+      "read_url_content",
+      "search_web",
+      "schedule",
+      "multi_replace_file_content",
+      "replace_file_content",
+      "write_to_file",
+      "run_command",
+      "manage_task",
+      "define_subagent",
+      "invoke_subagent",
+      "manage_subagents",
+      "call_mcp_tool"
+    ];
+
+    const systemPromptConfig = {
+      "includeSections": [
+        "user_information",
+        "mcp_servers",
+        "skills",
+        "subagent_reminder",
+        "messaging",
+        "artifacts",
+        "user_rules"
+      ]
+    };
+
+    // 1. Deploy Primary Agents to .agents/agents/{agent_name}/
+    const sourceAgentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const agentFiles = await fs.readdir(sourceAgentsDir).catch(() => []);
+
+    const AGENTS_INFO = {
+      "atlas": { name: "Atlas", description: "Router and workflow coordinator for AI Workflow Kit" },
+      "nexus": { name: "Nexus", description: "Discovery, requirement, scope, and specification owner" },
+      "orion": { name: "Orion", description: "Planning, PR sequencing, release, and deployment strategy owner" },
+      "astra": { name: "Astra", description: "Implementation owner for incremental, scoped changes" },
+      "sage": { name: "Sage", description: "Audit, validation, evidence, and quality gate owner" },
+      "phoenix": { name: "Phoenix", description: "Remediation and regression recovery owner" }
+    };
+
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const lowercaseName = path.basename(file, ".md").toLowerCase();
+      const info = AGENTS_INFO[lowercaseName];
+      if (!info) continue;
+
+      const agentFolder = path.join(antigravityAgents, lowercaseName);
+      await fs.mkdir(agentFolder, { recursive: true });
+
+      // Copy Markdown file to the agent's folder
+      const content = await fs.readFile(path.join(sourceAgentsDir, file), "utf8");
+      const mdTarget = path.join(agentFolder, `${lowercaseName}.md`);
+      await fs.writeFile(mdTarget, content);
+
+      // Generate agent.json
+      const agentJson = {
+        name: lowercaseName,
+        description: info.description,
+        hidden: false,
+        config: {
+          customAgent: {
+            systemPromptSections: [
+              {
+                title: "Agent System Instructions",
+                content: `You are ${info.name}, the ${lowercaseName === "astra" ? "implementation" : lowercaseName} owner.\n\nFollow the contract instructions in:\n${getUrls(mdTarget)}`
+              }
+            ],
+            toolNames,
+            systemPromptConfig
+          }
+        }
+      };
+      await fs.writeFile(path.join(agentFolder, "agent.json"), JSON.stringify(agentJson, null, 2));
+    }
+
+    // 2. Deploy Subagents to .agents/agents/{subagent_name}/
+    const SUBAGENTS_INFO = {
+      "Architecture-Specialist": { description: "Select the simplest architecture that safely satisfies current requirements", skill: "architecture" },
+      "Backend-Engineer": { description: "Support safe PHP/Node/Python backend changes for APIs and persistence", skill: "backend-development" },
+      "Deployment-Specialist": { description: "Plan, review, or validate deployment, release, and production-readiness", skill: "deployment" },
+      "Design-Specialist": { description: "Apply practical design principles to keep solutions simple and maintainable", skill: "design-principles" },
+      "Docs-Engineer": { description: "Write or improve project documentation, READMEs, guides, and prompts", skill: "documentation" },
+      "Frontend-Engineer": { description: "Implement or review frontend changes involving UI, state, routing, and accessibility", skill: "frontend-development" },
+      "Full-Stack-Engineer": { description: "Coordinate frontend and backend changes as one coherent, testable increment", skill: "full-stack-development" },
+      "Token-Economist": { description: "Reduce context size while preserving information required for safe execution", skill: "optimize-tokens" },
+      "PR-Manager": { description: "Plan, implement, review, or validate small pull requests while preserving scope", skill: "pr-workflow" },
+      "Discovery-Analyst": { description: "Clarify ambiguous requests into actionable problem statements and success outcomes", skill: "product-discovery" },
+      "Product-Planner": { description: "Turn clarified needs into scoped requirements with acceptance-ready outcomes", skill: "product-planning" },
+      "Memory-Guardian": { description: "Manage discoverable project memory for durable decisions and recurring corrections", skill: "project-memory" },
+      "Prompt-Engineer": { description: "Expert in creating and refining prompts for AI agents and workflows", skill: "prompt-engineer" },
+      "QA-Engineer": { description: "Design, review, or improve tests, acceptance criteria, and validation evidence", skill: "qa-workflow" },
+      "Refactoring-Specialist": { description: "Improve code/document structure safely while preserving behavior", skill: "refactoring" },
+      "Release-Specialist": { description: "Prepare release readiness decisions with explicit gates and evidence", skill: "release-workflow" },
+      "SDD-Specialist": { description: "Convert approved requirements into explicit, testable specification artifacts", skill: "spec-driven-development" },
+      "Technical-Leader": { description: "Make technical decisions, review architecture, and identify trade-offs", skill: "technical-leadership" },
+      "UI-UX-Engineer": { description: "Improve usability and interface clarity without introducing unnecessary complexity", skill: "ui-ux-design" }
+    };
+
+    for (const [name, subInfo] of Object.entries(SUBAGENTS_INFO)) {
+      const lowercaseSubagentName = name.toLowerCase();
+      const subagentFolder = path.join(antigravityAgents, lowercaseSubagentName);
+      await fs.mkdir(subagentFolder, { recursive: true });
+
+      const skillPath = path.join(antigravitySkills, subInfo.skill, "SKILL.md");
+
+      const subagentJson = {
+        name: lowercaseSubagentName,
+        description: subInfo.description,
+        hidden: false,
+        config: {
+          customAgent: {
+            systemPromptSections: [
+              {
+                title: "Agent System Instructions",
+                content: `You are ${name}.\n\nFollow the contract instructions in:\n${getUrls(skillPath)}`
+              }
+            ],
+            toolNames,
+            systemPromptConfig
+          }
+        }
+      };
+      await fs.writeFile(path.join(subagentFolder, "agent.json"), JSON.stringify(subagentJson, null, 2));
+    }
+
+    // 3. Copy Skills
+    const sourceSkillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    const skillFolders = await fs.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        await fs.mkdir(path.join(antigravitySkills, folder), { recursive: true });
+        const content = await fs.readFile(skillSource, "utf8");
+        await fs.writeFile(path.join(antigravitySkills, folder, "SKILL.md"), content);
+      }
+    }
+
+    // 4. Copy Commands (from dist-assets/commands)
+    const sourceCommandsDir = path.join(this.cwd, installRoot, "opencode/commands");
+    if (await this.exists(sourceCommandsDir)) {
+      const commandFiles = await fs.readdir(sourceCommandsDir).catch(() => []);
+      for (const file of commandFiles) {
+        if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
+        const content = await fs.readFile(path.join(sourceCommandsDir, file), "utf8");
+        await fs.writeFile(path.join(antigravityCommands, file), content);
+      }
+    }
+
+    // 5. Copy governance policy into .agents/docs/policies/ so the relative
+    //    link ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md in each
+    //    .agents/skills/{skill}/SKILL.md resolves correctly.
+    const sourcePoliciesDir = path.join(this.cwd, installRoot, "opencode", "docs", "policies");
+    const antigravityPolicies = path.join(antigravityDir, "docs", "policies");
+    if (await this.exists(sourcePoliciesDir)) {
+      await fs.mkdir(antigravityPolicies, { recursive: true });
+      const policyFiles = await fs.readdir(sourcePoliciesDir).catch(() => []);
+      for (const file of policyFiles) {
+        if (!file.endsWith(".md")) continue;
+        const content = await fs.readFile(path.join(sourcePoliciesDir, file), "utf8");
+        await fs.writeFile(path.join(antigravityPolicies, file), content);
+      }
+    }
+
+    // 6. Inject project settings.json
+    const settingsPath = path.join(antigravityDir, "settings.json");
+    if (!(await this.exists(settingsPath))) {
+      const settings = {
+        model: { name: "auto" },
+        ui: { theme: "Ayu" }
+      };
+      await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    }
+  }
+
+  async exists(p) {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Deploys the main ANTIGRAVITY.md and .antigravityignore instructions to the project root.
+   */
+  async deployInstructions() {
+    const targetPath = path.join(this.cwd, "ANTIGRAVITY.md");
+    const ignorePath = path.join(this.cwd, ".antigravityignore");
+    
+    // Deploy ANTIGRAVITY.md if it doesn't exist
+    try {
+      await fs.access(targetPath);
+    } catch {
+      const instructions = `# AI Workflow Kit - Engineering Governance
+
+## Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority** (./specs).
+
+## Ternary Architecture
+- **Root:** Orchestration and config.
+- **.ai-workflow/:** Implementation (The Muscle).
+- **./specs:** Specifications (The Brain).
+
+## Branch Gates
+- **main Branch:** READ-ONLY.
+- **Validation:** Merges require successful observed validation; full/release workflows may persist EVIDENCE.json.
+
+## Primary Agents
+- **Atlas (Orchestrator)**
+- **Orion (Strategist)**
+- **Sage (Auditor)**
+- **Nexus (Spec Architect)**
+- **Astra (Developer)**
+- **Phoenix (Healer)**
+
+## Operational Preferences
+- Use \`token-economy\` and \`minimal-context\` skills.
+- **Native Discovery**: This project uses workspace-specific extensions in \`.agents/\`.
+- **Workflow Entry**: Use \`/atlas\` to begin any task.
+`;
+      await fs.writeFile(targetPath, instructions);
+    }
+
+    // Deploy .antigravityignore if it doesn't exist
+    try {
+      await fs.access(ignorePath);
+    } catch {
+      const ignoreContent = `.ai-workflow/
+.ai-workflow-backups/
+node_modules/
+.git/
+EVIDENCE.json
+*.tgz
+*.zip
+*.tar
+.agents/tmp/
+.agents/history/
+`;
+      await fs.writeFile(ignorePath, ignoreContent);
+    }
+  }
+}