feat(skills): add self-contained writing-aictrl-workflows skill + SPEC#2
Merged
Merged
Conversation
Publish the vendor-neutral, canonical authoring reference for aictrl workflow YAML to the public skills repo. Self-contained so it works offline in Claude Code / Cursor / OpenCode with no aictrl monorepo. Bundle: - SKILL.md — lean entry: authoring + GitOps apply loop, self-check, pointers - SPEC.md — design decisions, schema provenance stamp, manual sync procedure - reference/authoring-guide.md — full reference (6 node types + field exclusivity, 12 param types, input mappings, CEL binding model/reserved words/severity ranks, loops + bounds, retry, edges, quality gates, triggers, validation layers, checklist) - reference/workflow.schema.json — v1 JSON Schema, validation-verbatim from source commit 8ee36d05; only description annotations sanitized of monorepo-internal anchors (zero effect on validation) - reference/examples/*.yaml — two apply-ready examples, byte-verbatim - evals/writing-aictrl-workflows.eval.md + results.md — self-consistency golden check: both examples validate against the bundled schema (AJV 2020-12, strict:false); leakage grep clean Genericized: no server/ or test/ paths, issue numbers, or private-wiki links; apply documented as the external GitOps loop (.aictrl/workflows/ -> git-sync PR, fail-closed) + Studio import. Refs aictrl-dev/aictrl#3760 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Make explicit that the bundled schema tracks the upstream RELEASED (main) branch — what a workflow can apply against in production today — and that schema additions staged on a pre-release branch (e.g. new trigger types) are folded in only after they ship to prod. This prevents external authors from generating files that fail closed against not-yet-deployed constructs, and clarifies that being behind an unreleased branch is correct, not stale. Refs aictrl-dev/aictrl#3760 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…tatic DAG) Turns the bundled schema from a reference the model reads into an oracle it can test against. `validate.mjs <workflow.yaml>` runs the same layer-1 JSON Schema gate the apply-loader runs (Draft 2020-12, strict:false) PLUS the static DAG checks the schema can't express — duplicate node ids, dangling edges, cycles, loop nesting depth, and the nested-maxIterations product bound. Reports problems with JSON-paths and a schema/dag category; exit 0/1. Deps (ajv, ajv-formats, js-yaml) are dev-only and resolved from the host repo — not bundled — matching the repo's script convention. It cannot check layer-2 (does a template/workflow ref exist in your org — resolved org-scoped and fail-closed at apply) or CEL runtime semantics; the apply stays the definitive gate. SKILL.md's inline self-check snippet is replaced by the validator; authoring-guide and its checklist point at it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Publishes
writing-aictrl-workflows— the vendor-neutral, canonical authoring reference for aictrl workflow YAML — plus its specification, bundled v1 JSON Schema, examples, offline validator, and deterministic eval.Self-contained bundle
The skill works without access to the private monorepo and includes:
SKILL.mdandSPEC.mdvalidate.mjsfor layer-1 schema and static DAG checksSchema provenance
The bundled schema is synchronized with aictrl source commit
3e83fc6332e80138ba6a6eb67a1ce1d479e87a62(2026-07-12), including the releasedpr-ready,pr-opened, andchat-messagetrigger surface and the 10-trigger bound.Every validation-affecting type, pattern, enum, required field, numeric bound, and exclusivity rule is equivalent to the source schema. Only public-facing
descriptionannotations differ: internal issue numbers, private links, and implementation names are removed or reworded.Verification
pr-review-and-triage.yaml: VALIDreview-fix-loop.yaml: VALID7d23cf6a95e1d403e06e8b32e28b40c13a2c03cfb448892fa8f12724d9e473747d23cf6a95e1d403e06e8b32e28b40c13a2c03cfb448892fa8f12724d9e47374$idRefs aictrl-dev/aictrl#3760 and release PR aictrl-dev/aictrl#3812.