vinta-ai-workflows 0.1.7

package/schemas/README.md

@@ -0,0 +1,84 @@
+# Schemas
+
+JSON Schema (Draft 2020-12) contracts for every YAML file the vinta-ai-workflows toolchain produces or consumes. Every YAML file carries a `schema_version` integer at its top level; that integer matches the suffix on the schema filename.
+
+## Inventory
+
+| Artifact | YAML location in target project | Schema file | Authored by | Read by |
+|---|---|---|---|---|
+| Project config | `.vinta-ai-workflows.yaml` (repo root) | [`vinta-ai-workflows-config.v1.schema.json`](vinta-ai-workflows-config.v1.schema.json) | `vinta-bootstrap-ai-tools` (initial) → `vinta-sync-ai-tools` (updates) | every builder skill, every template render, every meta-skill |
+| Sub-agent definition | `ai-tools/agents/<name>.yaml` | [`sub-agent.v1.schema.json`](sub-agent.v1.schema.json) | `vinta-derive-subagents` | `setup-ai-tools.mjs` (emits per-vendor copies) |
+| PR-context frontmatter | top-of-file YAML in `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` | [`prs-context-frontmatter.v1.schema.json`](prs-context-frontmatter.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
+| PR-context inline comments | YAML inside the ` ```yaml ... ``` ` fence under `# Comments` of the same file | [`prs-context-comments.v1.schema.json`](prs-context-comments.v1.schema.json) | `implement-plan` / `amend-plan` | `open-pr.sh` |
+| MCP preflight cache | `.vinta-ai-workflows/cache.yaml` (gitignored — per-developer-machine state) | [`mcp-preflight-cache.v1.schema.json`](mcp-preflight-cache.v1.schema.json) | rendered `systematic-debugging` SKILL.md (writes during Phase 0) | rendered `systematic-debugging` SKILL.md (reads at Phase 0 start) |
+
+## Versioning rules
+
+Each schema file carries its own major version. The major appears in the filename (`*.vN.schema.json`) and in the YAML payload's `schema_version` field.
+
+- **Adding an optional field** → no version bump. Update the schema in place.
+- **Adding a required field** → only allowed at vN+1 (breaking). Bump major, ship `vN+1.schema.json` alongside `vN.schema.json`. Both files stay in the repo so old projects can validate; `vinta-sync-ai-tools` migrates payloads forward.
+- **Removing or renaming a field** → bump major. Same as above.
+- **Tightening an enum** (removing a permitted value) → bump major. New enum lands in vN+1.
+- **Loosening an enum / pattern** (allowing more values) → no bump.
+- **Changing the meaning of a field without changing its shape** → bump major even when the shape is identical. The schema is a contract; semantics is part of it.
+
+When you bump the major:
+
+1. Copy `<artifact>.vN.schema.json` to `<artifact>.v(N+1).schema.json`.
+2. Modify the new file. Set `schema_version.const` to `N+1`.
+3. Add a migration step in `vinta-sync-ai-tools` covering the diff between vN and vN+1.
+4. Document the breaking change in [CHANGELOG.md](../CHANGELOG.md).
+
+## IDE wiring
+
+Add the schema directive to the top of any YAML file you author by hand. Editors with the Red Hat YAML extension (VS Code, Cursor) auto-validate against the URL.
+
+```yaml
+# yaml-language-server: $schema=https://github.com/vintasoftware/vinta-ai-workflows/schemas/vinta-ai-workflows-config.v1.schema.json
+schema_version: 1
+vinta_ai_workflows_version: 0.1.2
+# ...
+```
+
+For PR-context files (markdown with YAML frontmatter), the directive goes inside the frontmatter block:
+
+```markdown
+---
+# yaml-language-server: $schema=https://github.com/vintasoftware/vinta-ai-workflows/schemas/prs-context-frontmatter.v1.schema.json
+schema_version: 1
+plan_id: checkout-flow
+# ...
+---
+
+# Title
+...
+```
+
+Local-path schemas work too if the project has the `vinta-ai-workflows` clone vendored:
+
+```yaml
+# yaml-language-server: $schema=./node_modules/vinta-ai-workflows/schemas/vinta-ai-workflows-config.v1.schema.json
+```
+
+Authoring tools (`vinta-bootstrap-ai-tools`, `vinta-derive-subagents`, `implement-plan`, `amend-plan`) embed the directive when they emit a fresh file.
+
+## Validation in CI
+
+Optional but recommended. Any of the standard tools work:
+
+```bash
+# Check the project config (uses ajv-cli + js-yaml)
+npx -y ajv-cli validate \
+  -s schemas/vinta-ai-workflows-config.v1.schema.json \
+  -d .vinta-ai-workflows.yaml
+
+# Check every sub-agent
+for f in ai-tools/agents/*.yaml; do
+  npx -y ajv-cli validate \
+    -s schemas/sub-agent.v1.schema.json \
+    -d "$f"
+done
+```
+
+For PR-context frontmatter, extract the YAML block first (`yq` does this cleanly), then validate.

package/schemas/mcp-preflight-cache.v1.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/mcp-preflight-cache.v1.schema.json",
+  "title": "MCP preflight cache",
+  "description": "Per-server preflight state for the `systematic-debugging` foundation skill. Lives at `.vinta-ai-workflows/cache.yaml` in the target project (gitignored — never committed; entries reflect the current developer machine, not project-wide truth). Read + written by the rendered `systematic-debugging` SKILL.md and the `refresh-mcp-cache` CLI command. No TTL — entries stay valid until something fails. A failed MCP call mid-debug-session marks the offending server `dirty`, forcing the next debug run to re-preflight that server (and only that server).",
+  "type": "object",
+  "required": ["schema_version", "mcp_preflight"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Schema major version. Bumped only on breaking changes.",
+      "type": "integer",
+      "const": 1
+    },
+    "mcp_preflight": {
+      "description": "Map of MCP server identifier (matching an entry in `skills.systematic-debugging.observability_mcp_servers` of `.vinta-ai-workflows.yaml`) to its last-known preflight state.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["status", "verified_at"],
+        "additionalProperties": false,
+        "properties": {
+          "status": {
+            "description": "`ok` skips preflight on subsequent runs. Any other value forces a fresh preflight on the next debug run AND surfaces the entry to the user as needing attention.",
+            "type": "string",
+            "enum": ["ok", "dirty", "missing", "auth-error", "unreachable"]
+          },
+          "verified_at": {
+            "description": "ISO 8601 timestamp the entry was last written. For `ok` entries, the time the server was last reachable + invocable. For non-ok entries, the time the failure was observed.",
+            "type": "string",
+            "format": "date-time"
+          },
+          "tools_count": {
+            "description": "Number of tools the server exposed when last preflighted with `status: ok`. Sanity signal — a sudden drop to zero on a previously-ok server is suspicious.",
+            "type": "integer",
+            "minimum": 0
+          },
+          "error_message": {
+            "description": "Verbatim error message captured when `status` is non-ok. Quoted to the user on the next debug run so they can see what failed without re-triggering the call.",
+            "type": "string"
+          },
+          "marked_dirty_during": {
+            "description": "Optional pointer to the debug session that flipped this entry to `dirty` (free-form — phase id, plan id, timestamp, whatever the caller passed). Helps trace which run discovered the failure.",
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/prs-context-comments.v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/prs-context-comments.v1.schema.json",
+  "title": "PR-context inline comments list",
+  "description": "YAML list embedded inside the ` ```yaml ... ``` ` fence under the `# Comments` section of a `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` file. Authored by `implement-plan` (or `amend-plan`); read by `open-pr.sh` to post each entry as an inline review comment via `gh` / `glab`. Empty list is valid (clean phase, nothing non-obvious).",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["file", "start_line", "body"],
+    "additionalProperties": false,
+    "properties": {
+      "file": {
+        "description": "Path relative to the repo root.",
+        "type": "string",
+        "minLength": 1
+      },
+      "start_line": {
+        "description": "First line of the commented region on the new side of the diff (1-based).",
+        "type": "integer",
+        "minimum": 1
+      },
+      "end_line": {
+        "description": "Optional last line of a multi-line comment (1-based, inclusive). Omit for single-line comments.",
+        "type": "integer",
+        "minimum": 1
+      },
+      "side": {
+        "description": "Which side of the diff the comment attaches to. `RIGHT` = post-change (default). `LEFT` = pre-change (rare; for comments on removed code).",
+        "type": "string",
+        "enum": ["LEFT", "RIGHT"],
+        "default": "RIGHT"
+      },
+      "body": {
+        "description": "Markdown comment body. 1–3 lines explaining non-obvious context. Reference the plan's `Goals + Non-goals` / `Guiding Decisions` entries by name when the decision lives there — never use `§N` shorthand. Don't restate code.",
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "allOf": [
+      {
+        "description": "If end_line is provided, it must be >= start_line.",
+        "if": { "required": ["end_line"] },
+        "then": {
+          "properties": {
+            "end_line": { "type": "integer" }
+          }
+        }
+      }
+    ]
+  }
+}

package/schemas/prs-context-frontmatter.v1.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/prs-context-frontmatter.v1.schema.json",
+  "title": "PR-context file frontmatter (`.vinta-ai-workflows/prs-context/<feature>/<phase>.md`)",
+  "description": "YAML frontmatter at the top of every `.vinta-ai-workflows/prs-context/{feature-kebab}/phase-{phase.id}.md` file. Authored by `implement-plan` (and rewritten by `amend-plan`); read + updated by the bundled `open-pr.sh` script. The `# Title`, `# Description`, `# Comments` body sections that follow the frontmatter are markdown / fenced YAML and not covered by this schema; the `# Comments` YAML list has its own schema (`prs-context-comments.v1.schema.json`).",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "plan_id",
+    "feature_name",
+    "phase_id",
+    "phase_title",
+    "branch",
+    "base",
+    "created_at",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Schema major version. Bumped only on breaking changes.",
+      "type": "integer",
+      "const": 1
+    },
+    "plan_id": {
+      "description": "Kebab-case identifier of the plan. Filename feature portion (strip `YYYY-MM-DD-` prefix and `_PLAN.md` suffix, lowercase).",
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "minLength": 1
+    },
+    "feature_name": {
+      "description": "`UPPERCASE_WITH_UNDERSCORES` feature name. Matches the plan + spec filename feature portion.",
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9_]*$",
+      "minLength": 1
+    },
+    "phase_id": {
+      "description": "Phase id verbatim from the plan's `Phased Rollout` section (e.g. `1`, `4a`, `2.5`).",
+      "type": "string",
+      "pattern": "^[0-9]+(\\.[0-9]+)?[a-z]?$",
+      "minLength": 1
+    },
+    "phase_title": {
+      "description": "Phase title verbatim from the plan's `Phased Rollout` section.",
+      "type": "string",
+      "minLength": 1
+    },
+    "branch": {
+      "description": "Source branch the PR opens from. Default convention `plan/<plan-id-kebab>/phase-<phase.id>`.",
+      "type": "string",
+      "minLength": 1
+    },
+    "base": {
+      "description": "Target branch. Either the project's default branch (`main`) or the previous phase's stacked branch.",
+      "type": "string",
+      "minLength": 1
+    },
+    "created_at": {
+      "description": "ISO 8601 timestamp when the PR-context file was first written.",
+      "type": "string",
+      "format": "date-time"
+    },
+    "status": {
+      "description": "Lifecycle. `pending` until `open-pr.sh` publishes; then `published`.",
+      "type": "string",
+      "enum": ["pending", "published"]
+    },
+    "pr_url": {
+      "description": "URL of the published PR / MR. Populated by `open-pr.sh` on success. Empty string while `status: pending`.",
+      "type": "string",
+      "anyOf": [
+        { "format": "uri" },
+        { "const": "" }
+      ]
+    }
+  }
+}

package/schemas/sub-agent.v1.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/sub-agent.v1.schema.json",
+  "title": "vinta-ai-workflows sub-agent definition",
+  "description": "Vendor-agnostic sub-agent definition. Lives at `ai-tools/agents/<name>.yaml` in a target project. Read by `setup-ai-tools.mjs` which emits per-vendor copies (Claude markdown, Cursor markdown, Copilot `.agent.md`, Codex TOML). One file per agent. See schemas/README.md for versioning rules.",
+  "type": "object",
+  "required": ["schema_version", "name", "description", "access", "body"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Schema major version. Bumped only on breaking changes.",
+      "type": "integer",
+      "const": 1
+    },
+    "name": {
+      "description": "Agent identifier. Lowercase kebab-case. Used as filename stem and as the agent's slash-command name.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1
+    },
+    "description": {
+      "description": "One-line role + when-to-use summary. Used in vendor frontmatter for delegation hints.",
+      "type": "string",
+      "minLength": 1
+    },
+    "access": {
+      "description": "Read/write capability profile. Drives vendor-specific defaults (Claude `tools:`, Cursor `readonly:`, Codex `sandbox_mode`, Copilot `tools[]`).",
+      "type": "string",
+      "enum": ["read-only", "read-write"]
+    },
+    "body": {
+      "description": "Markdown body of the agent prompt. Multi-line literal block. Becomes the body of every per-vendor file emitted by `setup-ai-tools.mjs`.",
+      "type": "string",
+      "minLength": 1
+    },
+    "claude-tools": {
+      "description": "Optional shorthand: top-level Claude Code `tools:` value. When set, overrides the default derived from `access`. Equivalent to `overrides.claude.tools`.",
+      "type": "string"
+    },
+    "model": {
+      "description": "Optional default model preference (per-vendor when present at top level). Vendor-specific overrides win.",
+      "type": "string"
+    },
+    "is_background": {
+      "description": "Cursor-only top-level flag — agent runs as a background task.",
+      "type": "boolean"
+    },
+    "overrides": {
+      "description": "Vendor-specific overrides. Each vendor's keys mirror what the vendor's frontmatter accepts.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "claude": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "tools": {
+              "description": "Comma-separated tool names (Claude format).",
+              "type": "string"
+            },
+            "model": { "type": "string" }
+          }
+        },
+        "cursor": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "model": { "type": "string" },
+            "readonly": { "type": "boolean" },
+            "is_background": { "type": "boolean" }
+          }
+        },
+        "copilot": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "tools": {
+              "description": "List of Copilot tool ids (e.g. `codebase`, `editFiles`, `runCommands`).",
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "model": { "type": "string" },
+            "user-invocable": { "type": "boolean" },
+            "disable-model-invocation": { "type": "boolean" }
+          }
+        },
+        "codex": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "sandbox_mode": {
+              "type": "string",
+              "enum": ["read-only", "workspace-write", "workspace-network"]
+            },
+            "model": { "type": "string" },
+            "model_reasoning_effort": {
+              "type": "string",
+              "enum": ["low", "medium", "high"]
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -0,0 +1,283 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/vinta-ai-workflows-config.v1.schema.json",
+  "title": "vinta-ai-workflows project config",
+  "description": "Single source of truth for vinta-ai-workflows configuration in a target project. Lives at `.vinta-ai-workflows.yaml` at the repo root. Authored by `vinta-bootstrap-ai-tools`; updated in place by `vinta-sync-ai-tools`. Read by every builder skill, foundation skill template, and meta-skill. See schemas/README.md for versioning rules.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "vinta_ai_workflows_version",
+    "project",
+    "commands",
+    "policies",
+    "vendors",
+    "foundation_skills",
+    "foundation_agents"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Schema major version. Bumped only on breaking changes.",
+      "type": "integer",
+      "const": 1
+    },
+    "vinta_ai_workflows_version": {
+      "description": "Last `vinta-ai-workflows` package version this project synced from. Compared against the cloned package version by `vinta-sync-ai-tools` to enumerate releases since.",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[A-Za-z0-9.-]+)?$"
+    },
+    "last_synced_at": {
+      "description": "ISO 8601 timestamp of the last successful bootstrap or sync run.",
+      "type": "string",
+      "format": "date-time"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name", "default_branch", "code_host", "stack_summary", "ai_plans_dir"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "default_branch": { "type": "string", "minLength": 1, "examples": ["main", "master"] },
+        "code_host": {
+          "type": "string",
+          "enum": ["github", "gitlab", "bitbucket", "self-hosted", "other"]
+        },
+        "stack_summary": {
+          "description": "Human-readable one-liner of the stack (lang + framework + key deps). Pulled from `vinta-analyze-codebase` inventory.",
+          "type": "string"
+        },
+        "ai_plans_dir": {
+          "description": "Directory holding `YYYY-MM-DD-FEATURE_NAME_{SPEC,PLAN}.md` files. Default `ai-plans`. Monorepos often nest it under a service dir (e.g. `apps/<service>/ai-plans`).",
+          "type": "string",
+          "minLength": 1,
+          "default": "ai-plans"
+        },
+        "pr_template_paths": {
+          "description": "Paths (relative to repo root) of the project's existing PR / MR templates. Detected at bootstrap by scanning for `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/PULL_REQUEST_TEMPLATE/*.md`, `pull_request_template.md`, `docs/pull_request_template.md` (GitHub case-insensitive) and `.gitlab/merge_request_templates/*.md` (GitLab). When non-empty, `implement-plan` / `amend-plan` use the template as the scaffold for the prs-context file's `# Description` section. Empty array → free-form description. Multiple entries (template dir) → orchestrator asks the user which to use, or picks `default.md` if present.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "default": []
+        }
+      }
+    },
+    "commands": {
+      "description": "Commands consumed by `implement-plan` / `amend-plan` / project foundation skills at runtime.",
+      "type": "object",
+      "required": ["lint", "build", "test_unit"],
+      "additionalProperties": true,
+      "properties": {
+        "lint": { "type": "string" },
+        "format": { "type": "string" },
+        "build": {
+          "description": "Type-check / build gate. Often the same as the test command on Python projects.",
+          "type": "string"
+        },
+        "test_unit": { "type": "string" },
+        "test_unit_scoped": {
+          "description": "Per-package or per-app scoped suite (e.g. `pnpm test:patient`).",
+          "type": "string"
+        },
+        "test_unit_new_pattern": {
+          "description": "Pattern for running a single new test file in isolation. Use placeholders like `<pkg>` / `<new-test-path>`.",
+          "type": "string"
+        },
+        "e2e": { "type": "string" }
+      }
+    },
+    "policies": {
+      "description": "Step-0 interview answers driving template rendering + agent prompts.",
+      "type": "object",
+      "required": ["pr_creation", "ai_coauthor", "commit_style", "stage_pattern"],
+      "additionalProperties": false,
+      "properties": {
+        "pr_creation": {
+          "description": "Whether agents open PRs or only push branches. Drives the `implement-plan` skill's `Open PR via context file` step matrix.",
+          "type": "string",
+          "enum": ["agents-create", "branches-only"]
+        },
+        "ai_coauthor": {
+          "description": "Whether commits may carry AI co-author trailers (`Co-Authored-By: Claude ...`).",
+          "type": "string",
+          "enum": ["allowed", "forbidden"]
+        },
+        "commit_style": {
+          "type": "string",
+          "enum": ["conventional", "imperative", "other"]
+        },
+        "stage_pattern": {
+          "description": "Default `git add` pattern shown to subagents (no `git add -A`).",
+          "type": "string"
+        },
+        "anti_git_add_all_reason": {
+          "description": "One-line reason `git add -A` is forbidden in this repo (e.g. secrets, build artifacts in tree).",
+          "type": "string"
+        }
+      }
+    },
+    "vendors": {
+      "description": "Vendor coverage selected at bootstrap. Consumed by `setup-ai-tools.mjs` `--only` flag.",
+      "type": "array",
+      "items": { "type": "string", "enum": ["claude", "cursor", "copilot", "codex"] },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "foundation_skills": {
+      "description": "Per-foundation-skill opt-in. Use `enabled` / `disabled`. `disabled` is a sticky opt-out — `vinta-sync-ai-tools` does not re-propose disabled skills.",
+      "type": "object",
+      "additionalProperties": { "type": "string", "enum": ["enabled", "disabled"] },
+      "properties": {
+        "plan-feature": { "type": "string", "enum": ["enabled", "disabled"] },
+        "create-spec": { "type": "string", "enum": ["enabled", "disabled"] },
+        "create-qa-use-cases": { "type": "string", "enum": ["enabled", "disabled"] },
+        "implement-plan": { "type": "string", "enum": ["enabled", "disabled"] },
+        "amend-plan": { "type": "string", "enum": ["enabled", "disabled"] },
+        "open-pr-from-context": { "type": "string", "enum": ["enabled", "disabled"] },
+        "add-e2e-test": { "type": "string", "enum": ["enabled", "disabled"] },
+        "add-env-var": { "type": "string", "enum": ["enabled", "disabled"] },
+        "add-one-off-script": {
+          "description": "Author safe operational one-off scripts (backfills, cleanups, ad-hoc data fixes) following a strict contract: dry-run by default, idempotent on re-run, batched DB operations, streamed reads, segmented CSV backups before destructive writes (max 1M cells/file, never nested across tables), interruption-safe signal handlers, and console + filesystem + S3 logging. Bundles a `BaseOneOffScript` class template under [resources/foundation-skills/add-one-off-script/resources/](resources/foundation-skills/add-one-off-script/resources/). When `enabled`, project-level configuration lives under `skills.add-one-off-script` (scripts dir, S3 bucket/prefix, default batch size).",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        },
+        "systematic-debugging": {
+          "description": "Root-cause-first debugging skill rendered from `vinta-derive-skills/resources/systematic-debugging-template.md`. When `enabled`, the per-project MCP tool selection lives in `skills.systematic-debugging.observability_mcp_tools`.",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
+        }
+      }
+    },
+    "foundation_agents": {
+      "description": "Per-foundation-agent opt-in. Foundation trio (`implementer` / `reviewer` / `fixer`) are usually `enabled`.",
+      "type": "object",
+      "additionalProperties": { "type": "string", "enum": ["enabled", "disabled"] },
+      "properties": {
+        "implementer": { "type": "string", "enum": ["enabled", "disabled"] },
+        "reviewer": { "type": "string", "enum": ["enabled", "disabled"] },
+        "fixer": { "type": "string", "enum": ["enabled", "disabled"] }
+      }
+    },
+    "stacks": {
+      "description": "Stack templates applied at bootstrap (e.g. `medplum`, `django`, `nextjs-app-router`).",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "default": []
+    },
+    "stack_specialist_agents": {
+      "description": "Stack-specific sub-agents shipped (e.g. `migration-author` for Django, `deploy-author` for Medplum).",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "default": []
+    },
+    "run_options": {
+      "description": "Per-skill run-option defaults. Skills override via per-invocation prompts; values here are the defaults shown.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "implement-plan": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "pause_between_phases": { "type": "boolean", "default": false },
+            "generate_inline_comments": { "type": "boolean", "default": false }
+          }
+        },
+        "amend-plan": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "blast_radius_signal_threshold": {
+              "description": "How many tripping signals before suggesting restart-from-scratch. 2 = `high-blast-radius`, 3 = `restart-recommended`.",
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 7,
+              "default": 2
+            }
+          }
+        },
+        "systematic-debugging": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allow_local_only_debug": {
+              "description": "Whether the user is permitted to opt out of the MCP preflight + categories block on a per-run basis (e.g. `/systematic-debugging local-only — flaky test`). Defaults to `true`. Set to `false` for projects where production-only bugs must always go through the observability sweep — the skill will then refuse the `local-only` keyword and require the user to wire up an MCP server (or remove `systematic-debugging` from the project) instead.",
+              "type": "boolean",
+              "default": true
+            }
+          }
+        }
+      }
+    },
+    "skills": {
+      "description": "Per-skill custom config. Open schema — each skill defines its own keys.",
+      "type": "object",
+      "additionalProperties": { "type": "object" },
+      "properties": {
+        "systematic-debugging": {
+          "description": "Configuration for the `systematic-debugging` foundation skill. Required when `foundation_skills.systematic-debugging` is `enabled`; ignored otherwise.",
+          "type": "object",
+          "required": ["observability_mcp_servers"],
+          "additionalProperties": false,
+          "properties": {
+            "observability_mcp_servers": {
+              "description": "Free-form list of MCP server identifiers the agent should introspect during Phase 0 (evidence sweep) before any hypothesis. Identifiers use whatever shorthand the team recognises (e.g. `sentry`, `datadog`, `our-internal-traces`, `grafana-prod`). No enum is enforced — the systematic-debugging agent discovers specific tool names + capabilities at runtime by listing the tools each server exposes and matching them against the evidence categories baked into the rendered SKILL.md (see `vinta-derive-skills/resources/systematic-debugging-mcp-tools.md`). Empty array is allowed but degrades the skill — the rendered Phase 0 collapses to 'local logs only'. Order is preserved in the rendered list; not significant otherwise.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true,
+              "default": []
+            }
+          }
+        },
+        "add-one-off-script": {
+          "description": "Configuration for the `add-one-off-script` foundation skill. Optional when `foundation_skills.add-one-off-script` is `enabled` — sensible defaults apply when omitted.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "scripts_dir": {
+              "description": "Where one-off scripts live in the repo. Default `scripts/one_off`. Override for monorepos that nest scripts under a service / package dir.",
+              "type": "string",
+              "minLength": 1,
+              "default": "scripts/one_off"
+            },
+            "language": {
+              "description": "Primary language for scripts; selects which `BaseOneOffScript` template to stage. Default inferred from project stack at bootstrap.",
+              "type": "string",
+              "enum": ["python", "typescript"]
+            },
+            "log_dir": {
+              "description": "Where logs, PID files, processed-items logs, and CSV backups land. Default `.vinta-ai-workflows/one-off-runs` (gitignored).",
+              "type": "string",
+              "minLength": 1,
+              "default": ".vinta-ai-workflows/one-off-runs"
+            },
+            "default_batch_size": {
+              "description": "Default batch size injected into the `BaseOneOffScript` config when scripts don't override. Smaller for wide rows / contended tables.",
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100000,
+              "default": 500
+            },
+            "csv_max_cells": {
+              "description": "Per-CSV-chunk cell cap (rows × columns) before the writer rolls over to the next file. The contract requires segmented CSVs so a single backup chunk stays loadable without OOM.",
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 10000000,
+              "default": 1000000
+            },
+            "s3_bucket": {
+              "description": "S3 bucket for log + CSV-backup uploads. Falls back to the `ONE_OFF_S3_BUCKET` env var at runtime when unset. Empty string disables S3 upload (filesystem copy remains authoritative).",
+              "type": "string"
+            },
+            "s3_prefix": {
+              "description": "S3 key prefix for uploads. Falls back to `ONE_OFF_S3_PREFIX` env, default `one-off-runs/`. Trailing slash recommended.",
+              "type": "string",
+              "default": "one-off-runs/"
+            }
+          }
+        }
+      }
+    }
+  }
+}