AGENT SKILL

vibey-domain-model

Phases, jobs, ledger, handoff, rotation, and the no-loss gate — the core domain types and invariants in vibey.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
3

01 前言 Front Matter

name
vibey-domain-model
description
Phases, jobs, ledger, handoff, rotation, and the no-loss gate — the core domain types and invariants in vibey.
allowed-tools
Read

03 SKILL.md 正文

vibey domain model

Read docs/plans/domain-model.md before touching domain/. This skill is a compressed orientation; the full spec lives in that doc.

Phases

Six numbered phases plus optional visual interstitial:

INTAKE → ① DESIGN → [optional VISUAL_DESIGN] → ② BUILD ⇄ ③ REVIEW
         ▲──────────────────────────┘               │
                                                     │
③ ── user declines deployment ──────────────────────→ DONE (local)
  │ user opts into deployment
  ▼
④ DEPLOY_DESIGN → ⑤ DEPLOY_EXECUTE → ⑥ DEPLOY_REVIEW → DONE (deployed)

Interactive phases (talk to the user): ①, ③, ④, ⑥, VISUAL_DESIGN. Autonomous phases (unattended): ②, ⑤.

Loop-backs:

  • BUILD → DESIGN when blocked on ambiguity (spec insufficient).
  • REVIEW → DESIGN (default) or REVIEW → BUILD (fast path when every finding is unambiguous). See ADR-0010.
  • DEPLOY_REVIEW can route to ④, ⑤, or back to ①/②/③ depending on the failure classification.

Opt-in gates:

  • Visual design: after ① accepts a buildable spec, vibey asks whether to enter the visual-design interstitial. Declining takes the DESIGN → BUILD edge directly.
  • Deployment: after ③ has no open product findings, vibey asks whether to work on deployment. Declining records completion_mode = "local" and transitions to DONE without enqueueing any Azure job.

See ADR-0014 (optional visual-design and deployment opt-in).

Jobs

Job kinds are strings registered against handlers in bootstrap.py (25 kinds as of 2026-09-15):

  • DESIGN: design.interview, design.research, design.synthesize, design.spec
  • VISUAL_DESIGN: visual.inventory, visual.plan
  • BUILD: build.decompose (alias build.plan), build.implement, build.verify, build.integrate
  • REVIEW: review.demo, review.collect, review.triage, review.deployment_choice
  • DEPLOY_DESIGN: deploy.design, deploy.interview, deploy.synthesize, deploy.spec (alias deploy.accept)
  • DEPLOY_EXECUTE: deploy.execute (alias deploy.graph)
  • DEPLOY_REVIEW: deploy.demo, deploy.triage, deploy.route

docs/plans/phase-protocols.md also names kinds that are not registered (media.generate.*, visual.review, deploy.discover/plan/validate/apply/ release/verify/recover/collect); treat those as planned. Handoff is not a job kind: it runs inside the engine-driven job through application/wind_down.py and application/handoff_orchestration.py.

Job lifecycle (domain/job.py::JobState): ready → leased → succeeded | failed | awaiting_human | awaiting_capacity | cancelled.

Failure classes (domain/job.py::FailureClass): capacity (opens the circuit), engine (opens after 3), work (the code is wrong; circuit untouched), vibey (our bug; circuit untouched).

Bounded ladders park, they do not loop. When build.implement or build.verify exhausts its effort ladder (or a spend cap), the job parks behind a human gate. The answer can grant a bound (max_attempts for implement attempts, max_rounds for verify repair rounds, max_dollars/max_turns for spend); further attempts run at the ladder's top effort until that grant is used up, then park again (ADR-0024; granted_limit/granted_amount in application/build_verify_handler.py).

Idempotency: every job is idempotent under replay via idempotency_key — a deterministic hash of (project_id, cycle, kind, subject). Re-enqueueing the same logical work is a no-op. Handlers also guard their own side effects.

Parallel vs serial: some jobs run in parallel (e.g., build.implement — each work item in its own git worktree). Others are serial (e.g., build.integrate — one integration branch, serialised per project and cycle by a Postgres advisory lock in infrastructure/db/advisory_lock.py, ADR-0029).

See domain/job.py (JobState, FailureClass, backoff(), idempotency_key()) and the handlers in application/*_handler.py.

Ledger

The append-only event log in Postgres, written in a vendor-neutral schema. Vendor transcripts (~/.claude/projects/**/*.jsonl, codex rollouts) are copied in as attachments referenced by events — they are evidence, not state.

Event kinds (26 total, domain/ledger.py::EventKind): SessionSeeded, TurnRequested, TurnCompleted, ToolInvoked, TranscriptRecorded, FileEdited, VerdictRendered, CapacityRejected, QuestionAsked, AnswerGiven, DecisionRecorded, AssumptionStated, FindingRaised, FindingResolved, ArtifactProduced, SavePointCreated, HandoffInitiated, HandoffAccepted, PhaseTransitioned, BudgetSpent, and the ADR-0014 opt-in gate events VisualDesignOptedIn, VisualDesignDeclined, VisualDesignAccepted, VisualDesignWaived, DeploymentOptedIn, DeploymentDeclined.

Readers are forward compatible, writers strict (vibey#275): a stored kind this vibey does not know is read as UnrecognizedEventKind (so LedgerEvent.kind is EventKind | UnrecognizedEventKind), kept in every range, full ledger and digest, skipped by every projection, and never written. Match kinds with is EventKind.X and narrow with isinstance(kind, EventKind) before using a member-only attribute.

Closable events: QuestionAsked, DecisionRecorded, AssumptionStated, FindingRaised — these are the events the no-loss gate checks.

Digest: every event carries a digest (SHA-256 of canonical JSON payload). digest_range() computes an order-sensitive Merkle-ish fold of a sequence of events — this is what R6 (range integrity) checks.

See domain/ledger.py and docs/plans/handoff-protocol.md.

Handoff and the no-loss gate

When an engine hits CreditsExhausted, vibey:

  1. Produces a HandoffBrief (the outgoing engine writes it, or the incoming engine synthesizes it if the outgoing is dead).
  2. Verifies it against the no-loss gate (domain/noloss.py::verify()).
  3. If the gate passes, writes the full ledger to <worktree>/.vibey/handoff/ledger.jsonl and seeds the next engine.
  4. If the gate fails, regenerates (up to 3 attempts), then escalates to full_transcript mode, then raises a human gate. In that mode the gate waives R1–R5, R7, R9; the design inlines the whole range, but as built the range is only the ledger.jsonl file named in the seed prompt — do not describe it as inlined.

The 10 rules (R1–R10):

  • R1: remaining-work closure
  • R2: open-question closure
  • R3: decision closure
  • R4: assumption closure
  • R5: finding closure
  • R6: range integrity (digest match)
  • R7: artifact closure
  • R8: budget carry
  • R9: constraint closure
  • R10: containment (nothing in the brief contradicts the spec)

The gate is pure and deterministic — no model call. This is the reason rotation is safe.

See ADR-0004 (no-loss gate on handoff) and domain/noloss.py.

Rotation

Smooth weighted round robin (nginx-style SWRR), not naive modulo. Engines are selected from the eligible set via domain/rotation.py::select().

Eligibility: installed, authenticated (doctor passed within TTL), circuit not open, capability requirements met, and per-phase allow-list permits it.

When rotation happens: at boundaries only — never mid-turn. Triggers: new work item starts, capacity rejection (forced, exclude the rejecting engine), effort escalation, phase transition, operator-requested handoff.

Properties (property-tested):

  • No starvation: over sum(effective_weight) consecutive selections, every candidate with effective_weight > 0 is selected at least once.
  • Weight fidelity: selection counts converge to weight ratios within ±1 over any full period.
  • Smoothness: no candidate is selected twice consecutively while another with effective_weight > 0 has gone unselected longer.
  • Determinism: identical candidate state produces an identical selection.

Wiring: application/engine_selector.py::EngineSelector calls select() for engine-driven BUILD jobs, through SelectingEngineProvider in bootstrap.py. Candidates come from engine_health rows, so an engine without a recorded vibey doctor --conformance --record pass is never eligible. A local engine joins only while its switch is on — gptossloop unless switched off, qwenloop and claudeloop-local only when switched on — and is preferred first (ADR-0038, ADR-0064).

See ADR-0005 (smooth weighted round robin), ADR-0007 (rotate at boundaries), and domain/rotation.py.

Effort ladder

Vibey speaks a normalized 5-level ladder: TRIVIAL, LOW, STANDARD, HIGH, MAX. Each engine descriptor provides a projection onto native flags, which may saturate.

Phase base effort:

  • ① DESIGN: HIGH
  • VISUAL_DESIGN: HIGH
  • ② BUILD: LOW (auto-escalating to STANDARD → HIGH after failures)
  • ③ REVIEW: HIGH
  • ④ DEPLOY_DESIGN: HIGH
  • ⑤ DEPLOY_EXECUTE: LOW (auto-escalating)
  • ⑥ DEPLOY_REVIEW: HIGH

Phase also carries DEPLOY (a legacy single-phase bridge, base LOW) and ABANDONED; the phase diagram omits them deliberately.

See ADR-0006 (normalized effort ladder) and domain/effort.py.

Capacity states

Available | WindowExhausted | CreditsExhausted | AuthenticationFailed

The one rule that matters: CreditsExhausted has no resets_at field and can never acquire one. This is enforced at three independent layers:

  1. Type-level: domain/capacity.py's dataclass has no such attribute.
  2. Property-tested: schedule_probe(CreditsExhausted(...)) can only return a BackoffProbe, never a DeadlineProbe.
  3. Database-level: the engine_health table has a CHECK constraint credits_never_have_a_deadline that rejects any INSERT/UPDATE with capacity_state = 'CreditsExhausted' and non-null resets_at.

See domain/capacity.py, domain/circuit.py, the constraint in migrations/0007_engine_health_rotation.sql, and the CLAUDE.md non-negotiable "A capacity rejection always outranks a completion claim" (it has no ADR of its own).

04 同仓库更多 Skills

the-vibey-project
the-vibey-project/vibey

white-paper-writing

Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks "how should I structure this" for a long-form document.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-technical-mechanics

Use when editing or writing prose at a technical/mechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-mechanics

Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate/Jamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix "AI-sounding" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.

★ 5
the-vibey-project
the-vibey-project/vibey

narrative-structure

Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or "how should I structure this story/pitch/presentation" request.

★ 5
the-vibey-project
the-vibey-project/vibey

legal-brief-writing

Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic/neurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.

★ 5
the-vibey-project
the-vibey-project/vibey

journal-publishability-criteria

Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs/paper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.

★ 5