Skip to main content
VelinStyle v1.4.0
⌂ Home

Agent workflows 1.4.0

How AI agents use VelinStyle Skills 2.0: registry, domains, reuse-first routing, contracts, permissions, stop rules, migration intelligence, and rewrite gates. Twin: Deutsch · Runtime/CLI: AI Skills · Migration Intelligence.

Honest pilot status: SAFE_REWRITE = 0, catalog entries 0, manifest entries 0. Apply is not automatic. Tailwind is not “automatically safe.” Public product naming: Core Features / Core Architecture / Core Security (not internal codenames).

What are VelinStyle Skills?

Skills are registry-backed agent playbooks: each skill declares domain, purpose, capabilities, allowed/forbidden actions, permission tier, stop conditions, and risk. Agents discover skills via the registry and workflow graphs — they do not invent parallel toolchains.

Who are they for?

Using skills with AI agents

An agent should: resolve intent → run reuse-gate → pick domain skill(s) → stay inside permission → stop on missing evidence. It must not invent Velin APIs, CSS tokens, or mapping targets.

Skill registry

Source of truth: packages/velinstyle-skills/registry.json (version 1.0.0, 58 skills). Packs, graphs, bundles, and templates reference skill IDs. Validate with npm run skills:validate. See AI Skills for CLI/install surface.

Domains

Reuse-first

SEARCH → MATCH → COMPATIBILITY → REUSE / ADAPT → BUILD (only with evidenced gap)

Skill routing

REQUEST → INTENT → REUSE-GATE → DOMAIN → SKILL → ACTION → OUTPUT → REVIEW/GATE → NEXT

Unclear scope → stop (fail closed). Example: “check my rewrite manifest” routes to preflight, not manifest-create.

Phase 4.15–5.1 routing examples (fail closed unless noted):

Conditional Freeze: Apply stays off; SAFE_REWRITE = 0. Some everyday multi-intent phrases still fail closed until phrasing matches — security first; routing coverage continues to improve.

Skill contract

A skill never “gets everything.” Plan-only plans; review-only validates; write stays in scope; apply needs gate + approval.

Capabilities

Capabilities are dotted strings (no flat legacy migrate). They tell the agent what class of work a skill may perform — not a license to invent targets or escalate permission.

Permissions

Default is safe. No silent escalation from plan/review to apply.

Actions

Typical actions include PLAN, ANALYZE, VALIDATE, DRY_RUN, ACCEPT, WRITE, PREFLIGHT, APPLY. Privileged actions require matching permission and must not be invented by the agent.

Stop rules

Stop rules (SR-…) force fail-closed behavior: inventing targets, skipping reuse, treating acceptance as mapping, hash/path drift, missing approval, unclear scope, and more. Agents must stop — never quietly continue.

Agent orchestration

REQUEST → INTENT → REUSE → BUILD / REVIEW / MIGRATION
→ CLASSIFY → INTELLIGENCE → ACCEPTANCE → FREIGABE
→ CATALOG → MANIFEST → PREFLIGHT → DRY-RUN → APPLY-GATE → APPLY

Each arrow is a decision boundary. Skipping ahead without evidence is forbidden.

Acceptance vs Mapping vs Catalog vs Manifest vs Apply

Dry-run

Dry-run reports Mapped / Warning / Unresolved. It is not write and not apply. Tailwind migrate skills are typically plan-only for dry-run interpretation.

Write gates

Write requires write permission, in-scope paths, and evidenced mappings where migration is involved. Unresolved residuals stay unresolved.

Apply gates

Apply needs GATE_READY, successful dry-run where required, approval, snapshot, and path/hash integrity. Missing any check → fail closed. SAFE_REWRITE remains 0 until residual invent is honestly supported.

Fail closed

When unsure: stop. Prefer REUSE / BLOCKED-BY-DESIGN / STOP over guessing. No silent “best effort” token invention.

Tailwind migration

CLI + L-domain skills: scan → plan → dry-run → review/stop. Known catalog aliases may map; residuals and strategy blocks (THEME, STATE, PALETTE, DIM_PX, TYPO, HALF_STEP) must not be auto-mapped by name similarity. Example: do not invent a target for bg-background because it “sounds like” background. Guides: Tailwind migrate, limits.

Migration Intelligence

M-domain skills inventory/classify residuals and support acceptance — they do not invent mappings or apply rewrites. See Migration Intelligence.

Rewrite system

Preflight ≠ approval ≠ apply. Catalog/manifest writes are gated; pilot counts stay at zero until real freigabe paths fill them.

Best practices for AI agents

  1. Check reuse before build.
  2. Do not invent APIs or components.
  3. Do not invent tokens.
  4. Do not guess mapping targets.
  5. No migration write without evidenced mapping.
  6. Acceptance is not mapping.
  7. Catalog is not manifest.
  8. Dry-run is not apply.
  9. Stop when information is missing.
  10. Extend existing architecture — no parallel systems.
  11. Include accessibility from the start.
  12. Review after changes.
  13. Stay in scope (paths, permissions).
  14. No unauthorized writes.
  15. When unsure: fail closed.

Examples

Card

User: “Build a VelinStyle card with header, content, and actions.”

  1. Intent → build/card → reuse-gate
  2. Reuse .velin-card structure from components docs
  3. Compose header/body/actions with existing patterns — do not invent a second card system
  4. Review (page/a11y) before treating as done

Tailwind

User: “Analyze these Tailwind classes and plan migration.”

  1. L-domain scan/plan/dry-run
  2. Separate mapped vs residual
  3. THEME/PALETTE/STATE unclear → STOP (no invent)
  4. Residuals → Intelligence/acceptance — not silent map

Manifest check

User: “Check my rewrite manifest.” → preflight, not manifest-create. No apply.