@luizsantiago/spec-guardrails 3.1.4 → 3.1.8

package/README.md

@@ -32,12 +32,12 @@ npx @luizsantiago/spec-guardrails install
 
 | Lands in your project | Purpose |
 | --- | --- |
-| `.cursor/skills/` + `.claude/skills/` | Hub, phase references, sister skills (first shipped **adapters** — not the only supported agents) |
+| `.cursor/skills/` + `.claude/skills/` + `.github/skills/` + `.codex/skills/` | Hub, phase references, sister skills (**shipped adapters** — same content, product-specific paths) |
 | `.specs/guardrails/scripts/` | Python gate scripts (Brakes mode) |
 | `.specs/STATE.md`, `.specs/features/`, … | Project memory (any agent) |
 | `.cursor/rules/engineering-baseline.mdc` | Always-on Cursor rule |
 
-**Agent environments:** the **core** (`.specs/`, CLI, hub, Python gates) works with any AI agent that reads repo instructions and runs shell commands. Install ships Cursor + Claude Code adapters today; Codex, GitHub Copilot, and others are documented in [Architecture](docs/guide/Architecture.md).
+**Agent environments:** the **core** (`.specs/`, CLI, hub, Python gates) works with any AI agent. **Install** ships adapters for **Cursor, Claude Code, GitHub Copilot, and OpenAI Codex** (plus root `AGENTS.md`). See [Architecture](docs/guide/Architecture.md).
 
 Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
 
@@ -60,7 +60,7 @@ Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
 | **Brakes / Gates** | Structural stop-gates | Python scripts exit non-zero when paperwork or evidence is missing |
 | **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
 | **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
-| **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
+| **Memory** | Persistent project state | `.specs/` — specs, decisions, and handoff survive across chats |
 
 **You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
 
@@ -186,7 +186,7 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/gui
 | [Concepts](docs/guide/concepts.md) | Spec-driven + guardrails + loop + graph |
 | [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
 | [Gates](docs/guide/gates.md) | How each gate works |
-| [Platform parity](docs/guide/Platform-parity.md) | Shipped adapters (Cursor, Claude Code) — core works with any agent |
+| [Platform parity](docs/guide/Platform-parity.md) | Shipped adapters (Cursor, Claude, Copilot, Codex) — core works with any agent |
 | [FAQ](docs/guide/FAQ.md) | Common questions |
 | [Changelog](docs/CHANGELOG.md) | Full version history |
 
@@ -202,7 +202,7 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
-| **3.1.x** | Doctor STATE fix; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status`; Claude `CLAUDE.md` |
+| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; unified execution contracts; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
 | **3.0.x** | Final name Spec Guardrails; `.specs/guardrails/`; no dual-path ([Migration](docs/guide/Migration.md)) |
 | **2.2.x** | Seatbelt-era paths & markers; `doctor` Execute hints; docs split from README |
 | **2.1.x** | `loop-plan` + parallel `/loop` waves |

package/lib/adapters.js

@@ -0,0 +1,17 @@
+import { injectAgentsMd } from "./agents-md.js";
+import { injectCodexAgents } from "./codex-agents.js";
+import { injectCopilotInstructions } from "./copilot-instructions.js";
+
+/**
+ * Install shipped platform adapter entry files (Copilot, Codex, AGENTS.md).
+ * Cursor and Claude adapters are injected separately in install.js.
+ *
+ * @param {string} cwd
+ */
+export async function installPlatformAdapters(cwd) {
+  return Promise.all([
+    injectCopilotInstructions(cwd),
+    injectAgentsMd(cwd),
+    injectCodexAgents(cwd),
+  ]);
+}

package/lib/agent-contract.js

@@ -0,0 +1,74 @@
+import {
+  CURSORRULES_MARKER_BEGIN,
+  CURSORRULES_MARKER_END,
+} from "./constants.js";
+
+/**
+ * Build a Spec Guardrails execution contract block for a platform adapter.
+ *
+ * @param {{ skillPrefix: string, footerLines?: string[] }} options
+ * @returns {string}
+ */
+export function buildExecutionContractBlock({ skillPrefix, footerLines = [] }) {
+  const footer =
+    footerLines.length > 0 ? `\n${footerLines.join("\n")}\n` : "\n";
+
+  return `${CURSORRULES_MARKER_BEGIN}
+# Execution Contract (Spec Guardrails)
+
+When planning architecture, specs, or multi-step features, read the hub first:
+
+- \`${skillPrefix}/agent-architecture.md\` — SDD hub: contract, phases, gates, complexity router
+- \`${skillPrefix}/references/\` — phase procedures (explore, project-init, constitution, specify, discuss, design, tasks, analyze, implement, validate, converge, archive, memory, quick-mode, context-limits, lessons, sub-agents)
+- \`${skillPrefix}/task-graph-engineering.md\` — task DAG, parallelism, verify topology
+- \`${skillPrefix}/engineering-standards.md\` — secure coding, code quality, artifact language
+- \`${skillPrefix}/security-review.md\` — security checklist for /verify
+- Sister skills (\`appsec\`, \`qa-strategy\`, \`code-simplify\`, \`ship-ready\`, \`git-handoff\`) — load **one conditional** at a time
+
+Deterministic gates (\`python3\`, non-zero exit means STOP):
+
+- Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
+- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`.
+- Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
+- Onboarding: \`.specs/GETTING_STARTED.md\`
+
+All project artifacts are written in English.
+Persistent state: \`.specs/STATE.md\`, \`.specs/lessons.json\`, \`.specs/LESSONS.md\`.${footer}${CURSORRULES_MARKER_END}
+`;
+}
+
+/** @returns {string} Core contract body without adapter-specific footers (for parity tests). */
+export function extractContractCore(block) {
+  const begin = block.indexOf(CURSORRULES_MARKER_BEGIN);
+  const end = block.indexOf(CURSORRULES_MARKER_END);
+  if (begin === -1 || end === -1 || end < begin) {
+    return block.trim();
+  }
+  let core = block.slice(begin + CURSORRULES_MARKER_BEGIN.length, end).trim();
+  const footerMarkers = [
+    "Project rules:",
+    "Cursor users also get",
+    "GitHub Copilot reads",
+    "OpenAI Codex adapter",
+    "Agent-agnostic entry",
+  ];
+  for (const marker of footerMarkers) {
+    const idx = core.indexOf(marker);
+    if (idx !== -1) {
+      core = core.slice(0, idx).trimEnd();
+    }
+  }
+  return core;
+}
+
+export const CURSORRULES_BLOCK = buildExecutionContractBlock({
+  skillPrefix: ".cursor/skills",
+  footerLines: ["Project rules: `.cursor/rules/engineering-baseline.mdc`"],
+});
+
+export const CLAUDE_MD_BLOCK = buildExecutionContractBlock({
+  skillPrefix: ".claude/skills",
+  footerLines: [
+    "Cursor users also get `.cursorrules` + `.cursor/rules/engineering-baseline.mdc` — same contract, different entrypoint. See Platform-parity docs in the package repo.",
+  ],
+});

package/lib/agents-md.js

@@ -0,0 +1,21 @@
+import { buildExecutionContractBlock } from "./agent-contract.js";
+import { injectMarkedBlock } from "./marked-inject.js";
+
+export const AGENTS_MD_BLOCK = buildExecutionContractBlock({
+  skillPrefix: ".github/skills",
+  footerLines: [
+    "Agent-agnostic entry (`AGENTS.md` open standard). Prefer the skills tree your tool loads:",
+    "- GitHub Copilot → `.github/skills/`",
+    "- OpenAI Codex → `.codex/skills/` (see `.codex/AGENTS.md`)",
+    "- Cursor → `.cursor/skills/` | Claude Code → `.claude/skills/`",
+  ],
+});
+
+/**
+ * Install or refresh root `AGENTS.md` for Codex and other agents that read it.
+ *
+ * @param {string} cwd
+ */
+export async function injectAgentsMd(cwd) {
+  return injectMarkedBlock(cwd, "AGENTS.md", AGENTS_MD_BLOCK);
+}

package/lib/claude-md.js

@@ -1,63 +1,14 @@
-import path from "node:path";
-
+import { CLAUDE_MD_BLOCK } from "./agent-contract.js";
+import { injectMarkedBlock } from "./marked-inject.js";
 import {
   CURSORRULES_MARKER_BEGIN,
   CURSORRULES_MARKER_END,
-  LEGACY_CURSORRULES_MARKER_PAIRS,
 } from "./constants.js";
-import {
-  appendFileSafe,
-  readFileSafe,
-  writeFileSafe,
-} from "./fs-utils.js";
 
 export const CLAUDE_MD_MARKER_BEGIN = CURSORRULES_MARKER_BEGIN;
 export const CLAUDE_MD_MARKER_END = CURSORRULES_MARKER_END;
 
-export const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARKER_BEGIN}
-# Execution Contract (Spec Guardrails)
-
-When planning architecture, specs, or multi-step features, read the hub first:
-
-- \`.claude/skills/agent-architecture.md\` — SDD hub: contract, phases, gates, complexity router
-- \`.claude/skills/references/\` — phase procedures (explore, project-init, constitution, specify, discuss, design, tasks, analyze, implement, validate, converge, archive, memory, quick-mode, context-limits, lessons, sub-agents)
-- \`.claude/skills/task-graph-engineering.md\` — task DAG, parallelism, verify topology
-- \`.claude/skills/engineering-standards.md\` — secure coding, code quality, artifact language
-- \`.claude/skills/security-review.md\` — security checklist for /verify
-- Sister skills (\`appsec\`, \`qa-strategy\`, \`code-simplify\`, \`ship-ready\`, \`git-handoff\`) — load **one conditional** at a time
-
-Deterministic gates (\`python3\`, non-zero exit means STOP):
-
-- Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
-- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`.
-- Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
-- Onboarding: \`.specs/GETTING_STARTED.md\`
-
-All project artifacts are written in English.
-Persistent state: \`.specs/STATE.md\`, \`.specs/lessons.json\`, \`.specs/LESSONS.md\`.
-
-Cursor users also get \`.cursorrules\` + \`.cursor/rules/engineering-baseline.mdc\` — same contract, different entrypoint. See \`docs/guide/Platform-parity.md\` in the package repo.
-${CLAUDE_MD_MARKER_END}
-`;
-
-const MARKER_PAIRS = [
-  [CLAUDE_MD_MARKER_BEGIN, CLAUDE_MD_MARKER_END],
-  ...LEGACY_CURSORRULES_MARKER_PAIRS,
-];
-
-/**
- * @param {string} content
- */
-function locateBlock(content) {
-  for (const [begin, endMarker] of MARKER_PAIRS) {
-    const start = content.indexOf(begin);
-    const end = content.indexOf(endMarker);
-    if (start !== -1 && end !== -1 && end >= start) {
-      return { start, end, endMarker };
-    }
-  }
-  return null;
-}
+export { CLAUDE_MD_BLOCK };
 
 /**
  * Install or refresh `.claude/CLAUDE.md` with the Spec Guardrails contract.
@@ -65,39 +16,5 @@ function locateBlock(content) {
  * @param {string} cwd
  */
 export async function injectClaudeMd(cwd) {
-  const target = path.join(cwd, ".claude", "CLAUDE.md");
-  const expected = CLAUDE_MD_BLOCK.trim();
-
-  try {
-    const existing = await readFileSafe(target);
-    const located = locateBlock(existing);
-    if (located) {
-      const current = existing.slice(
-        located.start,
-        located.end + located.endMarker.length,
-      );
-      if (current.trim() === expected) {
-        return { created: false, updated: false };
-      }
-      const before = existing.slice(0, located.start);
-      const after = existing.slice(located.end + located.endMarker.length);
-      const replaced = `${before}${expected}\n${after.replace(/^\n+/, "")}`;
-      await writeFileSafe(
-        target,
-        replaced.endsWith("\n") ? replaced : `${replaced}\n`,
-      );
-      return { created: false, updated: true };
-    }
-
-    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-    await appendFileSafe(target, `${separator}${CLAUDE_MD_BLOCK}\n`);
-    return { created: false, updated: true };
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      throw err;
-    }
-  }
-
-  await writeFileSafe(target, `${CLAUDE_MD_BLOCK}\n`);
-  return { created: true, updated: false };
+  return injectMarkedBlock(cwd, ".claude/CLAUDE.md", CLAUDE_MD_BLOCK);
 }

package/lib/codex-agents.js

@@ -0,0 +1,19 @@
+import { buildExecutionContractBlock } from "./agent-contract.js";
+import { injectMarkedBlock } from "./marked-inject.js";
+
+export const CODEX_AGENTS_BLOCK = buildExecutionContractBlock({
+  skillPrefix: ".codex/skills",
+  footerLines: [
+    "OpenAI Codex adapter — skills under `.codex/skills/`.",
+    "Root `AGENTS.md` and other platform files may also be present — use the tree your Codex session loads.",
+  ],
+});
+
+/**
+ * Install or refresh `.codex/AGENTS.md` for OpenAI Codex.
+ *
+ * @param {string} cwd
+ */
+export async function injectCodexAgents(cwd) {
+  return injectMarkedBlock(cwd, ".codex/AGENTS.md", CODEX_AGENTS_BLOCK);
+}

package/lib/constants.js

@@ -20,7 +20,12 @@ export const REPO_RAW_URL = `${REPO_RAW_BASE}/${PINNED_REF}`;
 
 export const FALLBACK_REPO_URL = `${REPO_RAW_BASE}/${FALLBACK_REF}`;
 
-export const SKILL_DIRS = [".cursor/skills", ".claude/skills"];
+export const SKILL_DIRS = [
+  ".cursor/skills",
+  ".claude/skills",
+  ".github/skills",
+  ".codex/skills",
+];
 
 export const CURSOR_RULES_DIR = ".cursor/rules";
 
@@ -160,31 +165,6 @@ export const LEGACY_CURSORRULES_MARKER_BEGIN = "<!-- AGENTIC-HARNESS:BEGIN -->";
 /** @deprecated Use LEGACY_CURSORRULES_MARKER_PAIRS */
 export const LEGACY_CURSORRULES_MARKER_END = "<!-- AGENTIC-HARNESS:END -->";
 
-export const CURSORRULES_BLOCK = `${CURSORRULES_MARKER_BEGIN}
-# Execution Contract (Spec Guardrails)
-When planning architecture, specs, or multi-step features, read the hub first:
-- \`.cursor/skills/agent-architecture.md\` — SDD hub: contract, phases, gates, complexity router
-- \`.cursor/skills/references/\` — phase procedures (explore, project-init, constitution, specify, discuss, design, tasks, analyze, implement, validate, converge, archive, memory, quick-mode, context-limits, lessons, sub-agents)
-- \`.cursor/skills/task-graph-engineering.md\` — task DAG, parallelism, verify topology
-- \`.cursor/skills/engineering-standards.md\` — secure coding, code quality, artifact language
-- \`.cursor/skills/security-review.md\` — security checklist for /verify
-- \`.cursor/skills/appsec.md\` — conditional AppSec (Complex / attack surface); never with other conditionals at once
-- \`.cursor/skills/qa-strategy.md\` — conditional QA strategy; load after AppSec if both apply
-- \`.cursor/skills/code-simplify.md\` — conditional simplify (Medium+ after A–D or owner ask)
-- \`.cursor/skills/ship-ready.md\` — conditional ship checklist (owner ask; does not authorize push)
-- \`.cursor/skills/git-handoff.md\` — git sync and session handoff for .specs/
-
-Deterministic gates (python3, non-zero exit means STOP):
-- Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
-- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`. Full CLI: \`npx @luizsantiago/spec-guardrails --help\`.
-- Onboarding: \`.specs/GETTING_STARTED.md\`
-
-All project artifacts are written in English.
-Persistent state: \`.specs/STATE.md\` (decisions/handoff), \`.specs/lessons.json\` (canonical lessons), and \`.specs/LESSONS.md\` (generated playbook).
-Project rules: \`.cursor/rules/engineering-baseline.mdc\`
-${CURSORRULES_MARKER_END}
-`;
-
 const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
 
 /**

package/lib/copilot-instructions.js

@@ -0,0 +1,23 @@
+import { buildExecutionContractBlock } from "./agent-contract.js";
+import { injectMarkedBlock } from "./marked-inject.js";
+
+export const COPILOT_INSTRUCTIONS_BLOCK = buildExecutionContractBlock({
+  skillPrefix: ".github/skills",
+  footerLines: [
+    "GitHub Copilot reads this file as repository custom instructions.",
+    "Cursor and Claude Code use their own adapter entry files — see Platform-parity.md in the package repo.",
+  ],
+});
+
+/**
+ * Install or refresh `.github/copilot-instructions.md` for GitHub Copilot.
+ *
+ * @param {string} cwd
+ */
+export async function injectCopilotInstructions(cwd) {
+  return injectMarkedBlock(
+    cwd,
+    ".github/copilot-instructions.md",
+    COPILOT_INSTRUCTIONS_BLOCK,
+  );
+}

package/lib/cursorrules.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 
+import { CURSORRULES_BLOCK } from "./agent-contract.js";
 import {
-  CURSORRULES_BLOCK,
   CURSORRULES_MARKER_BEGIN,
   CURSORRULES_MARKER_END,
   LEGACY_CURSORRULES_MARKER_PAIRS,

package/lib/doctor.js

@@ -3,13 +3,60 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 
-import { NPX, SKILL_DIRS } from "./constants.js";
+import {
+  CURSORRULES_MARKER_BEGIN,
+  NPX,
+  SKILL_DIRS,
+} from "./constants.js";
 import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
 import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
 
 const execFileAsync = promisify(execFile);
 
+/** @type {readonly string[]} */
+export const DOCTOR_PROCESS_CHECK_IDS = [
+  "skills-hub",
+  "specs-scaffold",
+  "config",
+  "baseline-rule",
+  "state-feature",
+  "platform-adapters",
+];
+
+/** @type {readonly string[]} */
+export const DOCTOR_BRAKES_CHECK_IDS = [
+  "gate-scripts",
+  "python",
+  "gate-smoke",
+];
+
+const ADAPTER_CONTRACT_PATHS = [
+  ".cursorrules",
+  ".claude/CLAUDE.md",
+  ".github/copilot-instructions.md",
+  "AGENTS.md",
+  ".codex/AGENTS.md",
+];
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function hasPlatformAdapterContract(cwd) {
+  for (const relativePath of ADAPTER_CONTRACT_PATHS) {
+    try {
+      const content = await readFileSafe(path.join(cwd, relativePath));
+      if (!content.includes(CURSORRULES_MARKER_BEGIN)) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * @typedef {{
  *   id: string,
@@ -61,18 +108,20 @@ export async function runDoctorChecks(cwd) {
   /** @type {DoctorCheck[]} */
   const checks = [];
 
-  const hubInstalled = (
-    await Promise.all(
-      SKILL_DIRS.map((dir) => pathExists(cwd, path.join(dir, "agent-architecture.md"))),
-    )
-  ).some(Boolean);
+  const hubResults = await Promise.all(
+    SKILL_DIRS.map((dir) => pathExists(cwd, path.join(dir, "agent-architecture.md"))),
+  );
+  const hubInstalled = hubResults.every(Boolean);
+  const missingHubDirs = SKILL_DIRS.filter((_dir, index) => !hubResults[index]);
 
   checks.push({
     id: "skills-hub",
-    label: "Agent hub skill (agent-architecture.md)",
+    label: "Agent hub skill in all adapter trees (agent-architecture.md)",
     weight: 12,
     pass: hubInstalled,
-    suggest: NPX("install"),
+    suggest: hubInstalled
+      ? undefined
+      : `${NPX("install")} — missing hub under: ${missingHubDirs.join(", ")}`,
   });
 
   const scriptsDir = await resolveScriptsDir(cwd);
@@ -131,6 +180,14 @@ export async function runDoctorChecks(cwd) {
     suggest: NPX("install"),
   });
 
+  checks.push({
+    id: "platform-adapters",
+    label: "Platform adapter contracts (Cursor, Claude, Copilot, Codex, AGENTS.md)",
+    weight: 5,
+    pass: await hasPlatformAdapterContract(cwd),
+    suggest: NPX("install"),
+  });
+
   const hasProjectMd = await pathExists(cwd, ".specs/project/PROJECT.md");
   checks.push({
     id: "project-context",
@@ -165,14 +222,21 @@ export async function runDoctorChecks(cwd) {
   if (gatesPresent && pythonOk) {
     try {
       const script = path.join(cwd, scriptsDir, "check_commit.py");
-      const python = await resolvePython();
-      if (python) {
-        await execFileAsync(python, [
-          script,
-          "--message",
-          "chore(guardrails): doctor smoke test",
-        ], { cwd });
-        gateSmoke = true;
+      const hasCommon = await pathExists(cwd, path.join(scriptsDir, "_common.py"));
+      const hasCheckCommit = await pathExists(
+        cwd,
+        path.join(scriptsDir, "check_commit.py"),
+      );
+      if (hasCommon && hasCheckCommit) {
+        const python = await resolvePython();
+        if (python) {
+          await execFileAsync(
+            python.command,
+            [...python.args, script, "--message", "chore(guardrails): doctor smoke test"],
+            { cwd },
+          );
+          gateSmoke = true;
+        }
       }
     } catch {
       gateSmoke = false;
@@ -256,8 +320,22 @@ export async function resolveExecuteHint(cwd, activeFeature) {
  * @returns {number}
  */
 export function scoreDoctorChecks(checks) {
-  const scored = checks.filter((check) => !check.optional);
-  const earned = scored.filter((check) => check.pass).reduce((sum, check) => sum + check.weight, 0);
+  return scoreDoctorChecksForIds(checks, null);
+}
+
+/**
+ * @param {DoctorCheck[]} checks
+ * @param {readonly string[] | null} ids when null, score all non-optional checks
+ * @returns {number}
+ */
+export function scoreDoctorChecksForIds(checks, ids) {
+  const idSet = ids ? new Set(ids) : null;
+  const scored = checks.filter(
+    (check) => !check.optional && (idSet === null || idSet.has(check.id)),
+  );
+  const earned = scored
+    .filter((check) => check.pass)
+    .reduce((sum, check) => sum + check.weight, 0);
   const total = scored.reduce((sum, check) => sum + check.weight, 0);
   if (total === 0) {
     return 0;
@@ -265,6 +343,19 @@ export function scoreDoctorChecks(checks) {
   return Math.round((earned / total) * 100);
 }
 
+/**
+ * @param {DoctorCheck[]} checks
+ * @returns {{ process: { score: number, ready: boolean }, brakes: { score: number, ready: boolean } }}
+ */
+export function scoreDoctorModes(checks) {
+  const processScore = scoreDoctorChecksForIds(checks, DOCTOR_PROCESS_CHECK_IDS);
+  const brakesScore = scoreDoctorChecksForIds(checks, DOCTOR_BRAKES_CHECK_IDS);
+  return {
+    process: { score: processScore, ready: processScore >= 80 },
+    brakes: { score: brakesScore, ready: brakesScore >= 80 },
+  };
+}
+
 /**
  * @param {DoctorCheck[]} checks
  * @param {number} limit
@@ -277,11 +368,12 @@ export function topDoctorSuggestions(checks, limit = 3) {
 /**
  * @param {string} cwd
  * @param {{ suggest?: boolean, json?: boolean }} [options]
- * @returns {Promise<{ score: number, checks: DoctorCheck[], suggestions: DoctorCheck[], executeHint: string | null }>}
+ * @returns {Promise<{ score: number, modes: ReturnType<typeof scoreDoctorModes>, checks: DoctorCheck[], suggestions: DoctorCheck[], executeHint: string | null, pythonMissing: boolean }>}
  */
 export async function doctor(cwd, options = {}) {
   const checks = await runDoctorChecks(cwd);
   const score = scoreDoctorChecks(checks);
+  const modes = scoreDoctorModes(checks);
   const suggestions = topDoctorSuggestions(checks);
   const activeFeature = await readActiveFeature(cwd);
   const executeHint = await resolveExecuteHint(cwd, activeFeature);
@@ -291,22 +383,28 @@ export async function doctor(cwd, options = {}) {
   if (options.json) {
     console.log(
       JSON.stringify(
-        { score, checks, suggestions, executeHint, pythonMissing },
+        { score, modes, checks, suggestions, executeHint, pythonMissing },
         null,
         2,
       ),
     );
-    return { score, checks, suggestions, executeHint, pythonMissing };
+    return { score, modes, checks, suggestions, executeHint, pythonMissing };
   }
 
   if (pythonMissing) {
     console.log(
-      "⚠ PYTHON MISSING — structural gates will not run automatically.\n" +
-        "  Install Python 3.10+ (python3 or python on PATH), then re-run doctor.\n" +
-        "  Until then the agent must perform the same checklists manually from skills/references/.\n",
+      "⚠ BRAKES OFF — Python 3.10+ not found.\n" +
+        "  Process mode works (workflow + .specs/ + manual checklists from skills/references/).\n" +
+        "  Install Python 3.10+ (python3 or python on PATH), then re-run doctor for Brakes mode.\n",
     );
   }
 
+  const brakesHint = modes.brakes.ready
+    ? ""
+    : " — install Python 3.10+ and gate scripts for automatic enforcement";
+  console.log("Operating modes");
+  console.log(`  Process: ${modes.process.score}/100`);
+  console.log(`  Brakes:  ${modes.brakes.score}/100${brakesHint}\n`);
   console.log(`Guardrails Ready: ${score}/100\n`);
 
   for (const check of checks) {
@@ -329,5 +427,5 @@ export async function doctor(cwd, options = {}) {
     console.log(`\nExecute hint:\n  → ${executeHint}`);
   }
 
-  return { score, checks, suggestions, executeHint, pythonMissing };
+  return { score, modes, checks, suggestions, executeHint, pythonMissing };
 }

package/lib/gates.js

@@ -5,7 +5,15 @@ import path from "node:path";
 
 import { NPX, GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
 
-const PYTHON_CANDIDATES = ["python3", "python"];
+/** @typedef {{ command: string, args: string[] }} PythonInterpreter */
+
+const PYTHON_CANDIDATES = [
+  { command: "python3", args: [] },
+  { command: "python", args: [] },
+  { command: "py", args: ["-3"] },
+];
+
+const MIN_PYTHON = [3, 10];
 
 const GATE_SCRIPTS = {
   "validate-spec": "validate_spec.py",
@@ -44,6 +52,61 @@ function run(command, args, options = {}) {
   });
 }
 
+/**
+ * @param {string} output
+ * @returns {[number, number] | null}
+ */
+export function parsePythonVersion(output) {
+  const match = output.match(/(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+
+/**
+ * @param {[number, number] | null} version
+ * @param {[number, number]} minimum
+ * @returns {boolean}
+ */
+export function satisfiesMinPython(version, minimum = MIN_PYTHON) {
+  if (!version) {
+    return false;
+  }
+  if (version[0] !== minimum[0]) {
+    return version[0] > minimum[0];
+  }
+  return version[1] >= minimum[1];
+}
+
+/**
+ * @param {PythonInterpreter} interpreter
+ * @returns {Promise<string>}
+ */
+async function readPythonVersion(interpreter) {
+  let output = "";
+  await new Promise((resolve, reject) => {
+    const child = spawn(interpreter.command, [...interpreter.args, "--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(undefined);
+      } else {
+        reject(new Error(`${interpreter.command} --version exited ${code}`));
+      }
+    });
+  });
+  return output;
+}
+
 /**
  * Resolve gate scripts directory (`.specs/guardrails/scripts` only — no legacy dual-path).
  *
@@ -55,18 +118,20 @@ export async function resolveScriptsDir(_cwd) {
 }
 
 /**
- * Resolve the available Python interpreter, or null when none is installed.
- * @returns {Promise<string | null>}
+ * Resolve a Python 3.10+ interpreter, or null when none qualifies.
+ *
+ * @returns {Promise<PythonInterpreter | null>}
  */
 export async function resolvePython() {
   for (const candidate of PYTHON_CANDIDATES) {
     try {
-      const code = await run(candidate, ["--version"], { stdio: "ignore" });
-      if (code === 0) {
+      const output = await readPythonVersion(candidate);
+      const version = parsePythonVersion(output);
+      if (satisfiesMinPython(version, MIN_PYTHON)) {
         return candidate;
       }
     } catch {
-      // Interpreter not on PATH; try the next candidate.
+      // Interpreter not on PATH or below minimum; try the next candidate.
     }
   }
 
@@ -112,12 +177,12 @@ export async function runGuardrailsScript(command, args, options = {}) {
 
   if (!python) {
     throw new Error(
-      "Python 3 not found. Install Python 3.10+ for Brakes mode (automatic gates), " +
+      "Python 3.10+ not found. Install Python 3.10+ for Brakes mode (automatic gates), " +
         "or perform the equivalent checks manually in Process mode.",
     );
   }
 
-  return run(python, [scriptPath, ...args], {
+  return run(python.command, [...python.args, scriptPath, ...args], {
     cwd,
     stdio: options.stdio,
   });

package/lib/install.js

@@ -12,6 +12,7 @@ import {
   DISPLAY_NAME,
   resolveAssetOverride,
 } from "./constants.js";
+import { installPlatformAdapters } from "./adapters.js";
 import { injectClaudeMd } from "./claude-md.js";
 import { injectCursorRules } from "./cursorrules.js";
 import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
@@ -115,8 +116,11 @@ export async function install(options = {}) {
     log("✅ LESSONS.md initialized [feedback loop]");
   }
 
+  log("🔗 Installing platform adapters...");
   await injectCursorRules(cwd);
   await injectClaudeMd(cwd);
+  await installPlatformAdapters(cwd);
+  log("✅ Adapters → .cursorrules, CLAUDE.md, copilot-instructions.md, AGENTS.md, .codex/AGENTS.md");
 
   const gettingStartedCreated = await writeFileIfMissing(
     path.join(cwd, ".specs/GETTING_STARTED.md"),

package/lib/marked-inject.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+
+import {
+  CURSORRULES_MARKER_BEGIN,
+  CURSORRULES_MARKER_END,
+  LEGACY_CURSORRULES_MARKER_PAIRS,
+} from "./constants.js";
+import {
+  appendFileSafe,
+  readFileSafe,
+  writeFileSafe,
+} from "./fs-utils.js";
+
+const MARKER_PAIRS = [
+  [CURSORRULES_MARKER_BEGIN, CURSORRULES_MARKER_END],
+  ...LEGACY_CURSORRULES_MARKER_PAIRS,
+];
+
+/**
+ * @param {string} content
+ * @returns {{ start: number, end: number, endMarker: string } | null}
+ */
+function locateBlock(content) {
+  for (const [begin, endMarker] of MARKER_PAIRS) {
+    const start = content.indexOf(begin);
+    const end = content.indexOf(endMarker);
+    if (start !== -1 && end !== -1 && end >= start) {
+      return { start, end, endMarker };
+    }
+  }
+  return null;
+}
+
+/**
+ * Install or refresh a markdown file with a marked Spec Guardrails block.
+ *
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @param {string} blockContent
+ * @returns {Promise<{ created: boolean, updated: boolean }>}
+ */
+export async function injectMarkedBlock(cwd, relativePath, blockContent) {
+  const target = path.join(cwd, relativePath);
+  const expected = blockContent.trim();
+
+  try {
+    const existing = await readFileSafe(target);
+    const located = locateBlock(existing);
+    if (located) {
+      const current = existing.slice(
+        located.start,
+        located.end + located.endMarker.length,
+      );
+      if (current.trim() === expected) {
+        return { created: false, updated: false };
+      }
+      const before = existing.slice(0, located.start);
+      const after = existing.slice(located.end + located.endMarker.length);
+      const replaced = `${before}${expected}\n${after.replace(/^\n+/, "")}`;
+      await writeFileSafe(
+        target,
+        replaced.endsWith("\n") ? replaced : `${replaced}\n`,
+      );
+      return { created: false, updated: true };
+    }
+
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    await appendFileSafe(target, `${separator}${blockContent}\n`);
+    return { created: false, updated: true };
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  await writeFileSafe(target, `${blockContent}\n`);
+  return { created: true, updated: false };
+}

package/lib/next-steps.js

@@ -2,6 +2,9 @@
  * Human-facing messages after install — keep CLI surface minimal.
  */
 
+const DOCS_BASE =
+  "https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide";
+
 /**
  * @param {{ pythonAvailable?: boolean, preset?: string }} [options]
  * @returns {string[]}
@@ -12,11 +15,11 @@ export function formatInstallNextSteps(options = {}) {
     "✨ Setup complete.",
     "",
     "Next:",
-    "  1. Open your AI coding agent in this project (Cursor and Claude Code adapters install automatically).",
+    "  1. Open your AI coding agent in this project (Cursor, Claude, Copilot, Codex, or AGENTS.md adapters install automatically).",
     "  2. Run **Specify** (`/specify` or “Specify a feature: …”).",
     "",
-    "  Other agents: core + CLI work anywhere — see docs/guide/Architecture.md",
-    "  Guide: docs/guide/Quick-start.md (repo) · .specs/GETTING_STARTED.md (this project)",
+    `  Architecture: ${DOCS_BASE}/Architecture.md`,
+    `  Quick start: ${DOCS_BASE}/Quick-start.md · .specs/GETTING_STARTED.md (this project)`,
   ];
 
   if (options.preset) {
@@ -34,7 +37,7 @@ export function formatInstallNextSteps(options = {}) {
     "",
     "Optional CLI (you rarely need these on day one):",
     "  project-init   existing repo with code already",
-    "  doctor         if something looks wrong",
+    "  doctor         Process + Brakes readiness scores",
     "  --help         full command list",
     "",
   );

package/lib/project-rules.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { CURSOR_RULES_DIR, RULE_ASSETS } from "./constants.js";
-import { ensureDir } from "./fs-utils.js";
+import { assertSafeWriteTarget, ensureDir } from "./fs-utils.js";
 
 /** Markers around the catalog skills table — refreshed on every install. */
 export const SKILLS_MAP_START = "<!-- guardrails-managed:skills-map:start -->";
@@ -194,12 +194,14 @@ export async function installProjectRules(cwd, options) {
       }
 
       if (!exists) {
+        await assertSafeWriteTarget(destPath);
         await fs.rename(tmpPath, destPath);
         continue;
       }
 
       const existing = await fs.readFile(destPath, "utf8");
       const merged = mergeBaselineRule(existing, shipped);
+      await assertSafeWriteTarget(destPath);
       await fs.writeFile(destPath, merged, "utf8");
       await fs.rm(tmpPath, { force: true });
     } catch (err) {

package/lib/specs-utils.js

@@ -36,7 +36,7 @@ export async function resolveFeatureId(raw, cwd) {
     const trimmed = raw.trim();
     const asPath = path.resolve(cwd, trimmed);
 
-    if (trimmed.endsWith(".md") || trimmed.includes("/")) {
+    if (trimmed.endsWith(".md") || trimmed.includes("/") || trimmed.includes("\\")) {
       const relative = path.relative(path.join(cwd, FEATURES_DIR), asPath);
       if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
         return relative.split(path.sep)[0];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.1.4",
-  "description": "Spec-driven process kit for any repo-local AI agent: Process mode (Node) or full Brakes mode (Node + Python gates). Progressive loading, independent verify, Guarantees matrix.",
+  "version": "3.1.8",
+  "description": "Keep AI coding agents honest — specify the work, prove each step, verify independently. Process mode (Node) for flexibility; Brakes mode (Node + Python) for structural gates and a Guarantees matrix. Progressive loading, independent verify — any AI agent.",
   "type": "module",
   "bin": {
     "spec-guardrails": "./index.js"
@@ -12,7 +12,7 @@
   "scripts": {
     "guardrails": "node index.js",
     "test": "npm run test:node && npm run test:gates",
-    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js",
+    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/skills/agent-architecture.md

@@ -14,7 +14,7 @@ This file is the contract and the map. Phase procedures live in `references/`; c
 
 ## Critical Rules (read before acting)
 
-**Reference files.** Phase procedures live in `references/` next to this file (`.cursor/skills/references/`, `.claude/skills/references/`). Read a reference **completely** before acting on it. Never act on a partial read. Load the working set per `references/context-limits.md` — one feature at a time, current phase only.
+**Reference files.** Phase procedures live in `references/` next to this file (`.cursor/skills/references/`, `.claude/skills/references/`, `.github/skills/references/`, `.codex/skills/references/` — use the tree your agent loads). Read a reference **completely** before acting on it. Never act on a partial read. Load the working set per `references/context-limits.md` — one feature at a time, current phase only.
 
 **Gate scripts.** Structural gates live in `.specs/guardrails/scripts/` at the project root. Run them with `python3`; never assume a project-local `scripts/` directory belongs to Spec Guardrails.
 
@@ -45,8 +45,11 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Before confirming a spec | `python3 .specs/guardrails/scripts/validate_spec.py [feature]` |
 | Before approving tasks | `python3 .specs/guardrails/scripts/analyze_artifacts.py [feature]` |
 | Before presenting tasks for approval | `python3 .specs/guardrails/scripts/validate_tasks.py [feature]` |
+| Before Execute waves (3+ tasks) | `npx @luizsantiago/spec-guardrails loop-plan [feature]` |
 | On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
 | Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |
+| Traceability (Medium+ features) | `python3 .specs/guardrails/scripts/validate_traceability.py [feature]` |
+| Quick mode evidence | `python3 .specs/guardrails/scripts/validate_quick.py [feature]` |
 | After Verify PASS | `npx @luizsantiago/spec-guardrails archive-feature [feature]` (Tier 0) |
 | Before a phase procedure (optional) | `npx @luizsantiago/spec-guardrails phase-context <phase>` |
 | After a FAIL verdict | `python3 .specs/guardrails/scripts/lessons.py add --source .specs/features/[feature]/validation.md` |
@@ -55,7 +58,7 @@ Gates accept a feature name, a feature directory, or a path to the artifact. Wit
 
 A **non-zero exit means STOP** — fix the artifact, then re-run the gate. Never continue past a failing gate.
 
-**Degraded mode.** If Python 3 or shell execution is unavailable, say so once, then perform the same checks by reading the artifact against the reference checklist. Degraded mode never lowers the standard; it only changes who runs the check.
+**Process mode (Brakes off).** If Python 3.10+ or shell execution is unavailable, say so once, then perform the same checks by reading the artifact against the reference checklist. Process mode never lowers the standard; it only changes who runs the check. Run `doctor` to see separate **Process** and **Brakes** scores.
 
 ## Phase Map
 

package/templates/GETTING_STARTED.md

@@ -4,7 +4,7 @@ You installed the **Spec Guardrails**. You do **not** need to memorize CLI comma
 
 ## What to do now
 
-1. Open your **AI coding agent** in this project (Cursor or Claude Code if you use those adapters).
+1. Open your **AI coding agent** in this project (Cursor, Claude Code, GitHub Copilot, OpenAI Codex, or any agent that reads root `AGENTS.md`).
 2. Start with **Specify** (an **agent command** — chat, not terminal):
 
    ```