Vilya

The Ring of Air — mightiest of the Three. The workflow that orchestrates every project.

Vilya is the Dev Loop system — not a product like Anduin or NaryaCommand. It holds the canonical skills, the registry/flows site, the prompts, and the tracking template that every product repo copies. Built for Claude Code + Cursor + Codex desktop, with per-stack crucible dialects across frontend (Next.js, .NET/Blazor) and backend/Python (general packages/CLI/jobs, FastAPI, Django, ML) repos.

Daytime is primary. You orchestrate with skills; the board is the shared state. Night-shift runs that same chain unattended via GitHub Actions on each product repo.

vilya/
├── skills/                     # canonical source of truth — the SKILL.md skills
│   ├── start-feature/          # process: issue → worktree → setup (Plan → /planner)
│   ├── finish-feature/         # process: tests → crucible → PR → changelog
│   ├── merge-pr/               # process: triage → test → squash-merge
│   ├── chip/                   # dispatch: issue → background worker session → PR
│   ├── prune/                  # cleanup: merged worktrees + leftover branches
│   ├── update-docs/            # routing: where does this go? (not on the happy path)
│   ├── adr/                    # decisions: issue-first ADR → DECISIONS.md mirror
│   ├── history/                # recall: reconstruct what we tried
│   ├── crucible-blazor/        # review: strict VSA+SOLID+Blazor (manual-only)
│   ├── crucible-nextjs/        # review: same for feature-slice + server/client
│   ├── crucible-fastapi/       # review: same, FastAPI dialect
│   ├── crucible-django/        # review: same, Django dialect
│   ├── crucible-python/        # review: general Python packages, CLI, automation/jobs
│   ├── crucible-ml/            # review: same, Python ML/data dialect
│   ├── planner/                # autonomous: drain needs:plan → plan:ready (Fable)
│   └── night-shift/            # autonomous: daytime chain → opens PRs
├── apps/
│   └── skill-registry/         # Next.js (VSA) app — The Dev Loop site + registry
├── docs/project-tracking/      # GITHUB-PROJECTS.md — per-repo config + shared process
└── scripts/
    ├── install-skills.sh       # link skills → ~/.claude/skills (Cursor reads it too)
    └── install-skills.ps1      # (Windows: junctions, no admin)

See HANDOFF.md for the exact steps to bootstrap this in Claude Code. Live site: https://vilya.jerrodtuck.com (Overview · Architect · Orchestrator · Skills · Setup · Night shift · Desktop differences).

The model

• Skills are user-level — link once per machine (scripts/install-skills.*): each ~/.claude/skills/<name> is a junction/symlink to the repo's skills/<name>, so skill merges are live on git pull with nothing to re-run. Cursor scans that directory as a compatibility root, so the same SKILL.md runs in both tools from one install. (A second install root in ~/.cursor/skills would double-list skills in Cursor — --include-cursor exists only for old Cursor builds.)
• Per-repo config is the only thing that varies — each product you run the loop on gets its own docs/project-tracking/GITHUB-PROJECTS.md (board ids, shared-file rules, night-shift Actions topology).
• Python selection: choose vl-crucible-python for general packages, CLI tools, automation and jobs; use the matching FastAPI, Django or ML variant for specialized projects. Select one variant per repo.
• Happy path: /start-feature → implement → crucible → /finish-feature → /merge-pr. /update-docs is routing only.
• The registry app reads skills/ as its source of truth (via SKILLS_DIR) and surfaces each skill's version history from git.

Codex desktop

Add the Codex skill target with pwsh scripts/install-skills.ps1 -IncludeCodex or bash scripts/install-skills.sh --include-codex: $HOME/.agents/skills, preserving the Claude/Cursor default and explicit custom targets. Verify actual discovery and the resolved source in the session, then use $vl-orch-codex or explicitly read/apply its SKILL.md. Installation alone is not invocation evidence.

The separate $vl-plan-codex Planner owns kickoff and verification plans. The orch enqueues needs:plan, consumes settled plan:ready artifacts, and dispatches implementation in a verified isolated worktree. $vl-plan retains compatibility; Claude uses /vl-plan-claude and Cursor keeps /vl-plan. Both host adapters load one shared Planner role contract. Subagent spawning alone is not isolation. Phase models are configurable: resolve current planning/workhorse families from runtime capabilities, honor explicit operator pins, and preserve configured defaults without authorized overrides. Applicable seat entries carry trusted human authorization for messaging within the repo/product board.

The #380 website phase reconciles explanations and copied prompts with merged Planner, impact, intake and health contracts. Verify actual browser/clipboard evidence separately from source publication and installed-session adoption.

Start with Setup, Architect, Orch planning/chips/recovery and Differences. Per-skill applicability is in the registry and coverage audit. Codex CLI and a new unattended backend are deferred; existing night-shift eligibility stays plan:ready ∧ night-shift:ready. The full desktop cycle and interruption recovery are separate #329 integration gates.

Deployment

The site + registry deploy to Railway as one service from the repo root (the app reads ../../skills and git history, so the service must not be scoped to apps/skill-registry). Config-as-code: railway.json (build/start commands, healthcheck), nixpacks.toml (adds git to the image), root package.json (proxy scripts). Live at https://vilya.jerrodtuck.com.

The name

Narya and Anduin are projects; Vilya is the ring that rules the process that builds them. You are its bearer — the orchestrator. The skills are your instruments; the board is the one shared state; the loop turns.