@williambeto/ai-workflow 2.4.9 → 2.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.4.9",
+  "version": "2.6.4",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",
@@ -34,69 +34,12 @@
   },
   "files": [
     "bin",
-    "src",
+    "core",
     "dist-assets",
-    "PUBLISH_MANIFEST.json",
+    "*.js",
+    "package.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md",
-    "AGENTS.md",
-    "docs/getting-started",
-    "docs/compatibility"
-  ],
-  "scripts": {
-    "build": "node internal/validate/build-publish.mjs",
-    "validate": "node internal/validate/validate-all.mjs",
-    "validate:json": "node internal/validate/validate-json.mjs",
-    "validate:structure": "node internal/validate/validate-structure.mjs",
-    "validate:refs": "node internal/validate/validate-refs.mjs",
-    "validate:artifact-safety": "node internal/validate/validate-artifact-safety.mjs",
-    "validate:links": "node internal/validate/validate-links.mjs",
-    "validate:docs-consistency": "node internal/validate/validate-doc-consistency.mjs",
-    "validate:workflow": "node internal/validate/validate-workflow.mjs",
-    "validate:schemas": "node internal/validate/validate-schemas.mjs",
-    "validate:skills": "node internal/validate/validate-skills.mjs",
-    "validate:subagents": "node internal/validate/validate-subagents.mjs",
-    "validate:commands": "node internal/validate/validate-commands.mjs",
-    "validate:agents": "node internal/validate/validate-agents.mjs",
-    "validate:policy-refs": "node internal/validate/validate-policy-refs.mjs",
-    "validate:privacy-gate": "node internal/validate/validate-privacy-gate.mjs",
-    "validate:ui-evidence": "node internal/validate/validate-ui-evidence-gate.mjs",
-    "validate:delegation": "node internal/validate/validate-delegation.mjs",
-    "validate:routing": "node internal/validate/validate-routing-consistency.mjs",
-    "validate:cli-smoke": "node internal/validate/validate-cli-smoke.mjs",
-    "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 tests/unit/",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "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",
-    "validate:upgrade": "node internal/validate/validate-upgrade-path.mjs",
-    "validate:visual": "node internal/validate/validate-visual.mjs",
-    "validate:release-readiness": "node internal/validate/validate-release-readiness.mjs"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.60.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.8",
-    "@semantic-release/npm": "^13.1.5",
-    "@vitest/coverage-v8": "^4.1.7",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
-    "axe-core": "^4.10.0",
-    "markdownlint-cli": "^0.49.0",
-    "playwright": "^1.60.0",
-    "semantic-release": "^25.0.3",
-    "vitest": "^4.1.7"
-  }
-}
+    "CHANGELOG.md"
+  ]
+}

package/{src/core/workspace/read-only-workspace.js → read-only-workspace-PZBE7KAX.js}

@@ -1,8 +1,10 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import os from "node:os";
-import crypto from "node:crypto";
+import "./chunk-5WRI5ZAA.js";
 
+// src/core/workspace/read-only-workspace.ts
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
 async function copyDirectory(src, dest) {
   const entries = await fs.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
@@ -11,7 +13,6 @@ async function copyDirectory(src, dest) {
     }
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-
     if (entry.isDirectory()) {
       await fs.mkdir(destPath, { recursive: true });
       await copyDirectory(srcPath, destPath);
@@ -20,13 +21,11 @@ async function copyDirectory(src, dest) {
     }
   }
 }
-
 async function captureHashSnapshot(dir) {
   const snapshot = {};
   await scanDir(dir, dir, snapshot);
   return snapshot;
 }
-
 async function scanDir(baseDir, currentDir, snapshot) {
   const entries = await fs.readdir(currentDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -35,7 +34,6 @@ async function scanDir(baseDir, currentDir, snapshot) {
     }
     const fullPath = path.join(currentDir, entry.name);
     const relPath = path.relative(baseDir, fullPath);
-
     if (entry.isDirectory()) {
       await scanDir(baseDir, fullPath, snapshot);
     } else if (entry.isFile()) {
@@ -44,24 +42,14 @@ async function scanDir(baseDir, currentDir, snapshot) {
         const hash = crypto.createHash("sha256").update(content).digest("hex");
         snapshot[relPath] = hash;
       } catch {
-        // ignore
       }
     }
   }
 }
-
-/**
- * Runs a function inside a temporary copy of the workspace.
- * Mutating the workspace inside this temp directory will trigger a BLOCKED result.
- */
-export async function runInReadOnlyWorkspace(originalCwd, runFn) {
+async function runInReadOnlyWorkspace(originalCwd, runFn) {
   const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-ro-"));
-  
   try {
-    // 1. Copy repository files recursively (excluding git/node_modules/tmp)
     await copyDirectory(originalCwd, tempDir);
-
-    // 2. Write the required opencode.jsonc permission config file
     const opencodeConfig = {
       permission: {
         edit: "deny",
@@ -80,16 +68,9 @@ export async function runInReadOnlyWorkspace(originalCwd, runFn) {
       path.join(tempDir, "opencode.jsonc"),
       JSON.stringify(opencodeConfig, null, 2)
     );
-
-    // 3. Capture initial file hash snapshot
     const snapshotBefore = await captureHashSnapshot(tempDir);
-
-    // 4. Execute the callback function inside the temp directory
     const runResult = await runFn(tempDir);
-
-    // 5. Capture post-run snapshot and verify no file mutations occurred
     const snapshotAfter = await captureHashSnapshot(tempDir);
-
     const mutated = [];
     for (const [file, hash] of Object.entries(snapshotAfter)) {
       if (snapshotBefore[file] !== hash) {
@@ -97,11 +78,10 @@ export async function runInReadOnlyWorkspace(originalCwd, runFn) {
       }
     }
     for (const file of Object.keys(snapshotBefore)) {
-      if (snapshotAfter[file] === undefined) {
+      if (snapshotAfter[file] === void 0) {
         mutated.push(file);
       }
     }
-
     if (mutated.length > 0) {
       return {
         success: false,
@@ -110,10 +90,13 @@ export async function runInReadOnlyWorkspace(originalCwd, runFn) {
         eventCount: runResult.eventCount || 0
       };
     }
-
     return runResult;
   } finally {
-    // 6. Delete the temporary workspace copy
-    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
+    });
   }
 }
+export {
+  runInReadOnlyWorkspace
+};
+//# sourceMappingURL=read-only-workspace-PZBE7KAX.js.map

package/{src/commands/validate.js → validate-Q2NLLQ5G.js}

@@ -1,32 +1,42 @@
-import { EvidenceCollector } from "../core/validation/evidence-collector.js";
-import { QualityGuard } from "../core/validation/quality-guard.js";
-import { ValidationPlanner } from "../core/validation/validation-planner.js";
-import { VisualVerifier } from "../core/validation/visual-verifier.js";
-import fs from "node:fs/promises";
-import path from "node:path";
+import {
+  EvidenceCollector,
+  QualityGuard,
+  ValidationPlanner,
+  VisualVerifier
+} from "./chunk-6EMG6FAO.js";
+import "./chunk-2AOV2ATY.js";
+import "./chunk-5WRI5ZAA.js";
 
-export async function runValidate({ cwd = process.cwd(), exitOnError = true, taskSlug = null, a11y = false, visualDist = null, port = 8080 }) {
+// src/cli/commands/validate.ts
+import fs from "fs/promises";
+import path from "path";
+async function runValidate({
+  cwd = process.cwd(),
+  exitOnError = true,
+  taskSlug = null,
+  a11y = false,
+  visualDist = null,
+  port = 8080
+}) {
   console.log("--- Running Validation ---");
-  const qualityGuard = new QualityGuard({ cwd, taskSlug, mode: "standard" });
+  const qualityGuard = new QualityGuard({ cwd, taskSlug, evidencePolicy: "optional", riskLevel: "medium" });
   const planner = new ValidationPlanner({ cwd, qualityGuard });
   const tasks = await planner.plan("standard");
-
-  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode: "standard" });
+  const collector = new EvidenceCollector({ cwd, timeout: 6e4, taskSlug, evidencePolicy: "optional" });
   const results = [];
-  
   for (const task of tasks) {
     console.log(`Running validation task: ${task.name}...`);
     const res = collector.runTask(task);
     results.push(res);
     console.log(`- Status: ${res.status} (${res.summary})`);
   }
-
   let a11yResult = null;
   if (a11y) {
     if (!visualDist) {
       throw new Error("Accessibility audit (--a11y) requires a target build directory specified via --visual-dist=<path>.");
     }
-    console.log(`\n--- Running Accessibility Audit ---`);
+    console.log(`
+--- Running Accessibility Audit ---`);
     console.log(`Serving ${visualDist} on port ${port}...`);
     try {
       const verifier = new VisualVerifier({ cwd, visualDist, port });
@@ -41,21 +51,17 @@ export async function runValidate({ cwd = process.cwd(), exitOnError = true, tas
       throw err;
     }
   }
-
-  // Load future configuration if present
   let config = {};
   try {
     const configContent = await fs.readFile(path.join(cwd, "ai-workflow.config.json"), "utf8");
     config = JSON.parse(configContent);
-  } catch {}
-
+  } catch {
+  }
   const hasFailure = results.some((r) => ["FAIL", "BLOCKED", "FAIL_QUALITY_GATE"].includes(r.status));
-  
   let hasA11yFailure = false;
   if (a11yResult) {
-    const criticalIsBlocker = true; // Critical violations are always blockers
+    const criticalIsBlocker = true;
     const seriousIsBlocker = config.a11y?.seriousAsBlocker === true;
-    
     if (criticalIsBlocker && a11yResult.critical.length > 0) {
       hasA11yFailure = true;
       console.error(`Accessibility FAILED: ${a11yResult.critical.length} critical accessibility violations detected.`);
@@ -69,13 +75,15 @@ export async function runValidate({ cwd = process.cwd(), exitOnError = true, tas
       }
     }
   }
-
   if (hasFailure || hasA11yFailure) {
     console.log("\nValidation FAILED.");
     if (exitOnError) process.exit(1);
     return { passed: false, results, a11yResult };
   }
-
   console.log("\nValidation PASSED.");
   return { passed: true, results, a11yResult };
 }
+export {
+  runValidate
+};
+//# sourceMappingURL=validate-Q2NLLQ5G.js.map

package/AGENTS.md

@@ -1,34 +0,0 @@
-# AI Workflow Kit contributor contract
-
-## Purpose
-
-Deliver useful software through proportionate workflow, minimum diff, observed validation, and concise evidence.
-
-## Non-negotiable safety
-
-- Never implement on `main` or `master`.
-- Preserve unrelated dirty work.
-- Run existing relevant validation commands.
-- Never report success after failed or unavailable required validation.
-- Bound remediation and stop when no progress is made.
-- Always await explicit conversational authorization from the human user in the chat before executing any codebase modification, Git commit, tagging, or remote push. Automated system approval hooks (e.g., artifact reviews) do not bypass this human-in-the-loop requirement.
-- Remote push is only permitted on non-protected feature/maintenance branches (e.g. feat/*, fix/*, chore/*, docs/*) with explicit conversational authorization, and is strictly prohibited on protected branches like main or master.
-
-## Routing & Delegation
-
-Atlas routes. Nexus owns discovery, requirements, and spec authoring. Orion owns planning, PR sequencing, and release strategy. Astra implements substantial scoped work. Sage independently validates when risk or full mode justifies separation. Phoenix performs bounded remediation. Delegation must improve the result; do not create agent theatre or claim handoffs that did not occur.
-
-## Modes
-
-- quick: small change, targeted validation, short summary;
-- standard: scoped feature, relevant validation, optional delegation;
-- full: formal planning, specialist implementation, independent validation, persisted evidence.
-
-## Evidence
-
-Quick and standard work require only branch, changed areas, commands/results, and limitations in the handoff. Full/release/audit/security work may persist machine-generated evidence.
-
-## Core Concept
-
-AI Workflow is an npm CLI that installs agents, commands, skills, policies and templates into your repository.
-It guides coding agents from request to implementation, validation and evidence. AI Workflow Kit preserves workflow integrity so coding agents cannot skip from request to code to success without an explicit implementation path, proportional validation, and final evidence.

package/PUBLISH_MANIFEST.json

@@ -1,34 +0,0 @@
-{
-  "name": "ai-workflow-publish-manifest",
-  "version": "1.0.0",
-  "layers": {
-    "core": [
-      "bin/**",
-      "src/**",
-      "package.json",
-      "opencode.jsonc"
-    ],
-    "assets": [
-      "dist-assets/skills/**",
-      "dist-assets/agents/**",
-      "dist-assets/commands/**",
-      "dist-assets/prompts/**",
-      "dist-assets/templates/**",
-      "dist-assets/schemas/**",
-      "dist-assets/runbooks/**",
-      "dist-assets/harness/**",
-      "dist-assets/docs/**",
-      "dist-assets/examples/**",
-      "dist-assets/AGENTS.md"
-    ]
-  },
-  "exclude": [
-    "internal/**",
-    "**/tests/**",
-    "**/evidence/**",
-    "**/*.original.md",
-    ".git/**",
-    ".ai-workflow/**",
-    "node_modules/**"
-  ]
-}

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

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

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

@@ -1,20 +0,0 @@
-# Gemini 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/compatibility/provider-usage.md

@@ -1,46 +0,0 @@
-# Provider Usage
-
-## OpenCode
-
-```bash
-npx @williambeto/ai-workflow init --yes
-npx @williambeto/ai-workflow doctor
-```
-
-Use `opencode.jsonc` and the generated OpenCode assets as the primary workflow interface.
-
-## Codex
-
-```bash
-npx @williambeto/ai-workflow init --yes --codex
-```
-
-Review generated `.github/agents/`, `.agents/skills/`, and `.codex/prompts/`. Preserve the repository's existing `AGENTS.md`; do not assume Codex reproduces OpenCode delegation semantics.
-
-## Claude Code
-
-```bash
-npx @williambeto/ai-workflow init --yes --claude
-```
-
-Review `CLAUDE.md` and `.claude/rules/`. Existing user-authored instructions must not be overwritten without backup and explicit intent.
-
-## Gemini CLI
-
-```bash
-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/docs/compatibility/runtime-matrix.md

@@ -1,31 +0,0 @@
-# Runtime Compatibility Matrix
-
-## Compatibility levels
-
-- **Primary:** native project target and most thoroughly exercised path.
-- **Supported:** generated integration and package-level smoke coverage exist; runtime limitations are documented.
-- **Supported with limitations:** assets are generated, but behavior is not equivalent to the primary runtime.
-- **Experimental:** adapter exists, but real-runtime evidence is insufficient for a stronger claim.
-
-| Runtime | Level | Generated integration | Current evidence | Known limitations |
-| --- | --- | --- | --- | --- |
-| OpenCode | Primary | `opencode.jsonc`, OpenCode agents, commands, and skills | init, doctor, package smoke, generated-file checks | Model may bypass canonical commands in direct conversation |
-| 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
-
-Compatibility levels must be based on evidence available in the release. Adapter code or generated files alone are not proof of full behavioral parity.
-
-## Promotion requirements
-
-A runtime may be promoted only after a clean consumer test records:
-
-1. package installation;
-2. `init` with the runtime flag;
-3. expected generated assets;
-4. runtime startup or configuration validation;
-5. at least one quick workflow scenario;
-6. known limitations and failures.

package/docs/getting-started/DESKTOP_PROMPT.md

@@ -1,52 +0,0 @@
-# Antigravity Desktop System Prompt
-
-Este documento fornece as instruções de sistema (System Prompt) prontas para serem utilizadas no **Antigravity Desktop** (no Windows). Ele configura o agente desktop para carregar, entender e respeitar os contratos de agentes, comandos, habilidades (skills) e validações do **AI Workflow Kit** localizados no WSL, direcionando execuções de comandos de forma consistente e prevenindo dogfooding recursivo.
-
----
-
-## Prompt de Integração
-
-Copie e cole as instruções abaixo na configuração de **System Prompt** (ou como a primeira mensagem da sessão) do seu Antigravity Desktop no Windows:
-
-```markdown
-Você é o Antigravity atuando sob o protocolo do **AI Workflow Kit** configurado para este workspace. Seu objetivo é guiar o desenvolvimento de software respeitando as diretrizes, papéis e validações definidos no framework.
-
----
-
-### 1. Localização do Framework
-O repositório do **AI Workflow Kit** está localizado no caminho de rede WSL:
-`\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit`
-
-Antes de iniciar qualquer tarefa conceitual ou de implementação, leia e entenda as regras e definições contidas em:
-- O contrato de contribuição: [AGENTS.md](file:///wsl.localhost/Ubuntu/home/williambeto/Development/dev-kit/AGENTS.md)
-- Os agentes e papéis disponíveis em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\agents\`
-- Os comandos e fluxo de trabalho em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\commands\`
-- As habilidades (skills) de governança em: `\\wsl.localhost\Ubuntu\home\williambeto\Development\dev-kit\dist-assets\skills\`
-
----
-
-### 2. Diretrizes de Comportamento e Não-Dogfooding
-- **Foco no Projeto Consumidor**: Você está desenvolvendo o código deste workspace específico (e não o próprio AI Workflow Kit). Use as regras de validação para garantir a qualidade do projeto atual.
-- **Evite Dogfooding Recursivo**: Não tente executar scripts de validação de forma aninhada ou recursiva na pasta do próprio framework `dev-kit`, a menos que seja explicitamente solicitado pelo usuário. O foco das execuções e comandos é o diretório de trabalho atual do seu workspace.
-- **Preservação de Estado**: Nunca altere branches protegidas (`main`/`master`) e preserve estados não rastreados que o usuário tenha deixado no repositório.
-
----
-
-### 3. Execução de Comandos em Ambiente WSL
-Como você está rodando no Windows Host e o projeto está no WSL, sempre que precisar rodar comandos do Git, Node, ou os próprios scripts do CLI do AI Workflow Kit, execute-os através do wrapper do WSL para garantir consistência de ambiente.
-Exemplos de execução:
-- Em vez de rodar direto no CMD, use: `wsl -d Ubuntu -- npm test` ou `wsl -d Ubuntu -- npm run validate`.
-- Para invocar o CLI local do projeto: `wsl -d Ubuntu -- ./node_modules/.bin/ai-workflow doctor`.
-
----
-
-### 4. Divisão de Papéis (Routing & Delegation)
-Assuma o papel correto dependendo da fase da tarefa solicitada pelo usuário:
-- **Nexus**: Para levantamento de requisitos, refinamento de ideias e escrita de especificações funcionais e técnicas (`SPEC.template.md`).
-- **Orion**: Para planejamento técnico de tarefas, criação de planos de testes e sequenciamento de Pull Requests.
-- **Astra**: Para a implementação de código funcional e modificação de arquivos de comportamento.
-- **Sage**: Para validação independente, testes de regressão e garantia de qualidade (nunca declare sucesso sem validação comprovada).
-- **Phoenix**: Para remediação rápida de falhas apontadas pelos validadores de qualidade.
-
-Por favor, confirme que leu os arquivos do framework no caminho indicado e que está pronto para atuar sob este protocolo.
-```

package/docs/getting-started/authoring-custom-skills.md

@@ -1,80 +0,0 @@
-# Authoring Custom Skills
-
-This guide explains how to author and integrate custom, project-specific capability skills to guide AI agents working inside your repository.
-
----
-
-## 1. What is a Skill?
-
-A **Skill** is a specialized folder containing structured instructions, examples, configurations, and scripts that extend an AI agent's capability for a specific task or technology.
-
-By default, the AI Workflow Kit automatically discovers skills placed inside the project configuration directory.
-
-### Recommended Directory Structure
-```text
-my-custom-skill/
-├── SKILL.md          # Primary instructions (with YAML frontmatter)
-├── examples/         # Reference implementations and coding patterns (optional)
-├── scripts/          # Helper validation or build scripts (optional)
-└── references/       # Detailed background specifications and policies (optional)
-```
-
----
-
-## 2. The `SKILL.md` Specification
-
-The only strictly required file is `SKILL.md`. It must contain a YAML frontmatter section at the very top, containing the skill's name and description.
-
-```markdown
----
-name: security-pci-dss
-description: Strict guidelines for PCI-DSS compliance, credit card hashing, and secure payment processing.
----
-
-# PCI-DSS Secure Coding Skill
-
-## Context
-Use this skill when implementing payment forms, logging mechanisms, or credit card handling modules.
-
-## Non-negotiable Rules
-1. **Never Log PAN:** The Primary Account Number (PAN) must never be written to application logs, crash reports, or stdout.
-2. **Use Strong Encryption:** All cardholder data must be encrypted in transit (TLS 1.3) and at rest (AES-256-GCM).
-3. **No Inline Card Formatting:** Use the custom secure tokenization library. Do not write custom Regex for credit card validation.
-```
-
-### Frontmatter Fields
-* **`name`**: The unique identifier of the skill. Agents will request this name using the `load_skill` or `load_profile` context directives.
-* **`description`**: A concise, search-friendly summary of the skill's purpose. The classifier uses this description to automatically match the skill to natural language developer requests.
-
----
-
-## 3. Registering Your Skills
-
-The AI Workflow Kit supports two discovery mechanisms:
-
-### Option A: Automatic Discovery (Default)
-Place your skill folder inside the standard project customizations root directory:
-* `.agents/skills/my-custom-skill/`
-
-The CLI dynamically loads and indexes all skills in this folder on initialization and execution. No manual registration is required.
-
-### Option B: Shared Customs JSON (`skills.json`)
-If you store your custom skills in a shared or non-standard directory (e.g. to share them across multiple corporate microservices), create a `skills.json` file in your project customizations root:
-
-```json
-{
-  "entries": [
-    { "path": "node_modules/@corporate/shared-skills/dist" },
-    { "path": "infrastructure/shared-skills" }
-  ],
-  "exclude": ["legacy-v1-tester-skill"]
-}
-```
-
----
-
-## 4. Best Practices for Skill Design
-
-1. **Keep Instructions Under 500 Lines:** If your skill requires extensive documentation, store the bulk in the `references/` subdirectory and link to it. Keep the primary `SKILL.md` focused on actionable rules and constraints.
-2. **Prioritize Capability over Roles:** Name your skills after capabilities (e.g., `performance-tuning`, `database-migrations`) rather than roles (e.g., `tech-lead`, `senior-dev`).
-3. **Add Validation Scripts:** If a skill enforces a pattern, write a small shell validator script under `scripts/validate.sh` and list it as a requirement in the `validation` section of the functional specifications.