Skip to content
Back to search

vibe

Vibe Code Orchestrator (VCO) is a governed runtime entry that freezes requirements, bounds execution, and enforces verification and phase cleanup.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/foryourhealth111-pixel/Vibe-Skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/foryourhealth111-pixel/Vibe-Skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/foryourhealth111-pixel--vibe-skills/badge.svg)](/listings/foryourhealth111-pixel--vibe-skills)

HTML

<a href="/listings/foryourhealth111-pixel--vibe-skills"><img src="/api/listings/foryourhealth111-pixel--vibe-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 244 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: vibe
  3. description: Vibe Code Orchestrator (VCO) is a governed runtime entry that freezes requirements, bounds execution, and enforces verification and phase cleanup.
  4. ---
  5. # Vibe Governed Runtime Entry
  6. This file is the host-facing SOP for entering canonical `vibe`. Keep it small: runtime details belong in `protocols/runtime.md`, execution discipline belongs in `protocols/do.md`, and host wrapper recipes belong in installer-generated wrapper docs.
  7. ## Trigger Contract
  8. Enter canonical `vibe` before ordinary execution when the user explicitly invokes `$vibe`, `/vibe`, or the `vibe` skill, or when the host intentionally chooses governed requirement/plan/execution closure for a complex task.
  9. Do not route every loosely related task into `vibe`. Lightweight questions,
  10. single-command checks, or tasks better served by another explicitly requested
  11. skill may proceed outside `vibe` unless the user explicitly invoked this entry.
  12. Installed-copy updates use `update --skills-dir <skills-dir>` on the same managed directory.
  13. User instructions, including CLAUDE.md, GEMINI.md, AGENTS.md and direct workflow limits such as TDD exceptions, remain highest priority. Preserve canonical launch and proof rules within those limits.
  14. ## Canonical Bootstrap
  15. `vibe` is a host-syntax-neutral skill contract. Before canonical launch, do only the minimum needed to launch:
  16. - Resolve `skill_root` and `workspace_root`.
  17. - Pass the current user task verbatim as the task specification; unrelated chat history may be excluded. Do not summarize, rewrite, or reduce it to keywords. Preserve exact input paths, input immutability constraints, exact output roots, synthetic-data evidence boundaries, module dependencies and safe parallel boundaries, and acceptance criteria.
  18. Do not search the current workspace, repository, or install root for canonical proof files before launch.
  19. Do not inspect the repo, protocol docs, or prior run outputs before canonical launch returns.
  20. Do not simulate stages, claim canonical entry from reading this file or wrapper text, or treat wrapper or AGENTS text as proof.
  21. Do not manually create `outputs/runtime/vibe-sessions/<run-id>/`.
  22. Do not use the Vibe installation root as the governed artifact root.
  23. Local skill candidate audit: semantic owner `packages/runtime-core/src/vgo_runtime/router_contract_runtime.py`; compatibility bridge `scripts/router/resolve-pack-route.ps1`
  24. The audit runs inside canonical `vibe` and exposes candidates for inspection. Include work type, domain/technology, deliverable, explicit constraints, and verified frozen facts on continuation. Its output is compatibility evidence only; the Agent owns skill choice, binding, and stage progression.
  25. Canonical entry command shape:
  26. ```powershell
  27. $env:PYTHONPATH = "<skill_root>/apps/vgo-cli/src"
  28. py -3 -m vgo_cli.main canonical-entry --repo-root "<skill_root>" --artifact-root "<workspace_root>" --prompt "<current user task, verbatim>"
  29. ```
  30. For PowerShell, do not place `$env:PYTHONPATH=...` inside a double-quoted `-Command` string; host interpolation may corrupt it to `:PYTHONPATH`.
  31. Bash-like hosts, including Claude Code, set `PYTHONPATH` in the outer shell and call Python directly. Try `py -3`, `python`, then `python3` according to availability.
  32. ```bash
  33. REPO_ROOT='<skill_root>'
  34. WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
  35. PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" python -m vgo_cli.main canonical-entry --repo-root "$REPO_ROOT" --artifact-root "$WORKSPACE_ROOT" --prompt "<current user task, verbatim>"
  36. ```
  37. `--host-id` and `--entry-id` remain compatibility-only for wrappers or older automation; omit them on a normal launch.
  38. Only validate canonical proof artifacts after canonical-entry returns a `session_root`.
  39. `check` proves `installed locally`; runtime coherence and delivery acceptance require their own evidence.
  40. Proof of canonical launch is post-launch and requires: `host-launch-receipt.json`, `runtime-input-packet.json`, `governance-capsule.json`, and `stage-lineage.json` under the returned `session_root`.
  41. `local-agent-kernel` follows the same proof rule. If it cannot produce those truth artifacts, it may produce local work scaffolds, but it must not be treated as `canonical verified`.
  42. If canonical launch fails, report `blocked` with the concrete failure reason instead of simulating the missing stages or proof artifacts.
  43. ## Consensus And Task Evolution
  44. Use `deep_interview` until the user and Agent agree on the goal, scope, constraints, deliverables, relevant unknowns, and completion criteria. Freeze the requirement after confirmation of that task-specific summary; the first clarification is an input to the conversation.
  45. Keep the agreement in the existing TaskCard. Append accepted revisions, update affected work and checks, and reuse results only while their inputs and acceptance remain valid. Surface decisions that change the agreed outcome, scope, risk, or required human judgment.
  46. ## Hard Stop And Re-entry
  47. The progressive governed stops are `requirement_doc`, `xl_plan`, and `phase_cleanup`.
  48. When `bounded_return_control.explicit_user_reentry_required = true`, stop the
  49. current assistant turn. Do not consume re-entry credentials until a later user
  50. message approves or revises the current boundary.
  51. This is a hard runtime boundary, not a suggestion. It overrides ordinary host
  52. autonomy rules such as "continue until done." A detailed original request is not
  53. approval of the frozen requirement or frozen plan. After a hard stop, do not
  54. perform equivalent manual work outside governed re-entry: no plan writing, task
  55. execution, manual workaround delivery, or final artifact delivery in the same
  56. assistant turn.
  57. For re-entry, inspect `runtime-summary.json ->
  58. bounded_return_control.host_decision_contract`, infer the user's intent, and
  59. write a structured host decision JSON file. Use the same `run_id`,
  60. `bounded_reentry_token`, and stable `workspace_root`:
  61. At a requirement stop, build `agent_skill_organization` directly from `agent_skill_organization_contract`; `preferred_payload` is incomplete until then, and the schema must not be learned through failed retries or runtime source inspection.
  62. Use the same `REPO_ROOT` and `WORKSPACE_ROOT` from bootstrap:
  63. ```bash
  64. DECISION_JSON="$WORKSPACE_ROOT/.vibeskills/tmp/host-decision.json"
  65. mkdir -p "$(dirname "$DECISION_JSON")"
  66. cat > "$DECISION_JSON" <<'JSON'
  67. {
  68. "decision_kind": "approval_response",
  69. "decision_action": "approve_requirement",
  70. "approval_decision": "approve",
  71. "agent_skill_organization": {
  72. "schema_version": "agent_skill_organization_v1", "derived_by": "agent", "workflow_level": "L",
  73. "modules": [{"module_id": "module-a", "goal": "...", "candidate_skill_ids": ["skill-a"], "depends_on": [], "execution_mode": "skill_assigned", "acceptance_criteria": [{"criterion_id": "module-a-result", "description": "The module result satisfies the frozen requirement.", "verification_mode": "automated"}]}],
  74. "selected_skills": [{"skill_id": "skill-a", "module_ids": ["module-a"], "responsibility": "...", "reason": "..."}],
  75. "uncovered_modules": [],
  76. "workflow_level_contract": {"L": "smallest complete organization", "XL": "bounded multi-lane organization"}
  77. }
  78. }
  79. JSON
  80. PYTHONPATH="$REPO_ROOT/apps/vgo-cli/src" py -3 -m vgo_cli.main canonical-entry \
  81. --repo-root "$REPO_ROOT" \
  82. --artifact-root "$WORKSPACE_ROOT" \
  83. --prompt "<current user task, verbatim>" \
  84. --continue-from-run-id "<source_run_id>" \
  85. --bounded-reentry-token "<reentry_token>" \
  86. --host-decision-json-file "$DECISION_JSON"
  87. ```
  88. A structured approval from a later user message advances to the next progressive stop. A structured
  89. revision must include non-empty `revision_delta` and refreezes the same bounded
  90. stage without asking the user for a separate approval first:
  91. ```json
  92. {
  93. "decision_kind": "approval_response",
  94. "decision_action": "revise_requirement",
  95. "approval_decision": "revise",
  96. "revision_delta": ["Use the revised dataset and agreed output scope."]
  97. }
  98. ```
  99. Bounded approvals or revisions must stay inside the surfaced bounded-stage action contract.
  100. At `requirement_doc`, read `runtime-summary.json -> host_user_briefing` and use `host_user_briefing.rendered_text` as the backbone of the user reply. Keep the same field order.
  101. Frame that stop around the Agent-led skill search guide: split the task into modules, search local skills per module, read candidate `SKILL.md`, organize both `L` / `XL` plans, and disclose uncovered modules honestly. Do not surface shortlist size, selected-skill rankings, or raw router ordering at requirement freeze.
  102. Do not ask the user to choose L or XL until the reply explains each task-specific workflow and names the task-specific candidate skill names for that option. Label every named skill as a candidate that is not yet selected or used; formal selection still belongs to the Agent organization produced after requirement approval.
  103. After requirement approval, the Agent must split the approved work into modules, search every declared local skill root for each module, and read each retained candidate's `SKILL.md`. The host must, before entering `xl_plan`, put the validated result in `HostDecisionJson.agent_skill_organization`; route output may remain candidate audit evidence but cannot populate this field. If one selected Skill owns multiple modules, include one `module_assignments` entry per module with the exact module id, an `owner`, `support`, or `verifier` role, module-specific responsibility, one concrete write scope, expected outputs, and verification. Role order is executable: `support` runs before and feeds the `owner`; `verifier` runs only after the `owner`. A post-owner review or minimality check must use `verifier`, not `support`. An `agent_direct` module must declare its own concrete `write_scope`, `expected_outputs`, and `verification`; the runtime must not replace them with a generic module label or restated goal. A task work scope must not claim canonical runtime artifacts such as `module-execution.json`; use a stable task-owned output scope or `no task-file writes` for read-only work. A plan revision that changes modules, Skills, roles, dependencies, write scopes, outputs, verification, or workflow level must resubmit the complete updated `agent_skill_organization`; `revision_delta` alone records text and does not mutate the frozen organization.
  104. Use the directory name that directly contains the retained `SKILL.md` as the exact `skill_id` in both `candidate_skill_ids` and `selected_skills[].skill_id`. A displayed Skill name or frontmatter `name` is descriptive, not an execution identifier. A nested retained `SKILL.md` uses its own containing directory name. Resolve this from the candidate path before submission instead of learning the identifier through failed retries.
  105. Module acceptance criteria must be satisfiable before canonical module-result re-entry. They must not require cleanup receipts, delivery acceptance, or completion-language permission, because canonical `phase_cleanup` creates those only after `module-execution.json` is accepted. Verify ordinary modules from their actual deliverables and normal command or test output. Do not invent task-specific hashes, receipts, ledgers, matrices, scans, or proof files solely to prove execution order, Skill use, or file scope. Only require an extra evidence artifact when the user or domain contract needs that artifact.
  106. After plan approval, reuse the frozen `agent_skill_organization` for `plan_execute` and cleanup, and do not rerun procedural skill selection, silently add skills, or replace declared gaps unless the user revises the frozen requirement or plan. `stage_order` records dependency depth, not permission to run in parallel; L still emits one-unit sequential waves even when independent units share a dependency stage. XL may place at most two dependency-ready units in one wave, and nested or overlapping write scopes must remain serial.
  107. After the required plan confirmation, continue through dependency-ready work
  108. without asking for routine permission between units. Give concise progress
  109. updates at meaningful boundaries. If the user revises the agreed task, record
  110. the revision and replan only the affected work before continuing.
  111. ## Unified Runtime Contract
  112. Canonical `vibe` owns one runtime authority and one visible requirement/plan
  113. surface. The fixed state machine is:
  114. 1. `skeleton_check`
  115. 2. `deep_interview`
  116. 3. `requirement_doc`
  117. 4. `xl_plan`
  118. 5. `plan_execute`
  119. 6. `phase_cleanup`
  120. These stages may be light for simple work, but they are not silently skipped.
  121. The full runtime contract, stage ownership, lineage rules, internal `M`/`L`/`XL`
  122. grades, user-visible L/XL workflow confirmation, cleanup rules, and output inventory are defined in
  123. `protocols/runtime.md`.
  124. `vibe` is the only public wrapper entry. Installed-copy updates use the command path described above.
  125. Compatibility stage wrappers stay internal-only. If an old caller still sends
  126. one, collapse it to canonical `vibe` before runtime launch and keep it out of
  127. the host-visible skill surface.
  128. ## Skill Execution
  129. The frozen `agent_skill_organization` is the only task-skill truth. Before plan
  130. approval, disclose modules, candidates, selected skills and reasons, gaps, and the L / XL difference.
  131. Organize each confirmed module as a verifiable work unit. Use declared Skill
  132. outputs to identify ownership, `plan_hints` to shape the work steps, and
  133. `verify_hints` to extend the module checks. Preserve explicit module
  134. dependencies and keep `agent_direct` as the visible fallback for a module with
  135. no suitable Skill. Every work unit must retain its intended outputs, checks,
  136. binding reason, and dependency links in the existing WorkPlan. Each bound
  137. assignment must project those fields and the selected Skill guidance into the
  138. existing ModuleAssignments artifact.
  139. Only selected skills become module-bound execution units. The host must not
  140. invent skills, promote route candidates, hide skill sessions, or open another
  141. requirement/plan/runtime surface. Selection, loading, planning, dispatch, or a
  142. generic manifest is not contribution proof; completion requires observable
  143. module results and the module acceptance defined in `protocols/runtime.md`.
  144. After plan approval, `module-work-plan.json` is the only dispatch authority.
  145. `agent-execution-handoff.json.result_contract` freezes the `module_execution_v1` submission bindings; after handoff, copy `result_contract.submission_template`, preserve every frozen binding, and fill only the result fields. `criterion_results` states must be exactly `passing`, `failing`, or `blocked`. If canonical rejects the format before cleanup, correct the same `module-execution.json` and reuse the same return command instead of creating another handoff. Code-task TDD evidence belongs inside the same `module-execution.json` when the handoff template includes `tdd_evidence`; fill that structured section before canonical return and do not create a separate `tdd-evidence.json` sidecar. The contract is not execution evidence.
  146. The Agent still does the real work and creates `module-execution.json`; required failure, blocking,
  147. missing evidence, or pending human review blocks task completion.
  148. For XL delegation, root/child hierarchy remains governed: only `root_governed`
  149. may freeze canonical requirements/plans or make final completion claims.
  150. `child_governed` lanes inherit the frozen context, stay inside assigned write
  151. scopes, validate `delegation-envelope.json`, and emit local receipts only.
  152. ## Quality Rules
  153. Never claim success without evidence. Minimum invariants:
  154. - Verify before completion.
  155. - Do not make silent no-regression claims.
  156. - Keep requirement and plan artifacts traceable to the launched run.
  157. - Emit cleanup receipts before claiming phase completion.
  158. - Expose failures, fallback, degraded status, or blocked state explicitly.
  159. - Do not add mock success paths, swallowed errors, or template-only pass results.
  160. - Treat scaffold or draft artifacts as `needs_execution` with `proof_ready = false`; do not call them completed work.
  161. - Reuse completed work only while effective task inputs, selected Skill content, dependency outputs, and delivered artifact hashes remain unchanged. Rerun affected dependency chains before verification; block dependents when prerequisites fail.
  162. - Do not use fallback or boundary behavior to bypass real execution,
  163. verification, or root-cause repair.
  164. - When a check fails within the confirmed scope, make at most one targeted
  165. repair for that failure and rerun the affected check. Report the remaining
  166. blocker when the repair fails, needs a scope decision, or lacks required
  167. evidence.
  168. ## User Delivery
  169. Use the existing WorkDossier as the detailed evidence source. Give the user a
  170. short delivery summary containing the verified results, their locations, the
  171. checks that actually ran, and genuine blockers. Exclude scaffolds from
  172. completed results. Keep internal receipts and
  173. diagnostic detail in the dossier unless they help the user make a decision.
  174. ## Protocol Map
  175. Read these references only after canonical launch or when maintaining the repo:
  176. - `protocols/runtime.md`: governed runtime contract and stage ownership
  177. - `protocols/think.md`: planning, research, and pre-execution analysis
  178. - `protocols/do.md`: coding, debugging, and verification
  179. - `protocols/review.md`: review and quality gates
  180. - `protocols/team.md`: XL multi-agent orchestration
  181. - `protocols/retro.md`: retrospective and evidence-backed corrections
  182. ## Maintenance
  183. - Runtime family: governed-runtime-first
  184. - Version: 4.1.2
  185. - Updated: 2026-11-04
  186. - Primary contract metadata: `core/skill-contracts/v1/vibe.json`
README.md · README · 537 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="right">
  2. <strong>English</strong> | <a href="./README.zh.md">中文</a>
  3. </div>
  4. <div align="center">
  5. <img src="./logo.png" width="124" alt="VibeSkills logo">
  6. <h1 align="center">
  7. <picture>
  8. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wordmark-dark.svg">
  9. <img src="./docs/assets/readme-wordmark-light.svg" width="500" alt="VibeSkills">
  10. </picture>
  11. </h1>
  12. <picture>
  13. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-tagline-en-dark.svg">
  14. <img src="./docs/assets/readme-tagline-en-light.svg" width="560" alt="VibeSkills is a general-purpose Skill that automatically routes local Skills and intelligently orchestrates harness workflows.">
  15. </picture>
  16. <br>
  17. <a href="https://github.com/foryourhealth111-pixel/Vibe-Skills/releases/latest">
  18. <strong>Latest stable release</strong>
  19. </a>
  20. <br>
  21. <a href="./docs/install/README.en.md">
  22. <picture>
  23. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/install-cta-en-dark.svg">
  24. <source media="(prefers-color-scheme: light)" srcset="./docs/assets/install-cta-en-light.svg">
  25. <img src="./docs/assets/install-cta-en-light.svg" width="210" height="38" alt="Install VibeSkills">
  26. </picture>
  27. </a>
  28. <br>
  29. <a href="./docs/quick-start.en.md">Quick start</a> ·
  30. </div>
  31. <a id="skillsbench-performance"></a>
  32. <h2 align="center">Measured on SkillsBench</h2>
  33. <p align="center">
  34. <strong>Mean verifier reward: +21.12 pp</strong><br>
  35. <strong>Total tokens: -29.6%</strong> · <strong>Tool calls: -33.1%</strong>
  36. </p>
  37. **SkillsBench** is a benchmark designed to evaluate whether AI agents can effectively use Skills to complete professional tasks across diverse domains. Its purpose is to measure how much a model’s ability to solve complex real-world tasks improves when it is equipped with specialized Skills.
  38. To evaluate performance in production-like environments where a large number of Skills are installed simultaneously, we adapted SkillsBench into a more realistic **large-scale multi-Skill setting**. In the original SkillsBench setup, each task is provided only with the specialized Skill associated with that task. In our modified setting, every task is evaluated in a global environment containing all **195 specialized Skills**, while all other experimental conditions remain unchanged. This setting is intended to assess whether an agent can autonomously discover, select, and orchestrate the relevant Skills from a large installed Skill pool, and organize them into an effective workflow for completing complex tasks.
  39. **vibeskills v4.1.0** was benchmarked on **SkillsBench** (https://www.skillsbench.ai/) using **DeepSeekV4Flash-VE** and **OpenHands** as the baseline evaluation setup. Compared with the baseline without vibeskills, vibeskills increased the **mean verifier reward by 21.12 percentage points**, while reducing **token consumption by 29.6%** and **tool calls by 33.1%**.
  40. <p align="center"><sub>Analysis: 82 paired reward tasks · 81 paired resource tasks · Study: <code>full-skills-comparison</code> · Publication commit: <code>ef907ebf8370</code> · <a href="./config/benchmark-results.json">Machine-readable results and provenance</a></sub></p>
  41. <p align="center">
  42. <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/tree/main/studies/full-skills-comparison">
  43. <img src="./docs/assets/skillsbench-task-outcomes.png" width="900" alt="SkillsBench paired task outcomes: Lean Vibe increased mean reward from 50.3% to 71.4%, increased the full-score rate from 47.6% to 69.5%, scored higher on 23 tasks, tied on 55, and scored lower on 4">
  44. </a>
  45. </p>
  46. <p align="center"><sub>Task quality: 39 to 57 full-score tasks; Lean Vibe scored higher on 23 tasks, Native on 4, with 55 ties.</sub></p>
  47. <p align="center">
  48. <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/tree/main/studies/full-skills-comparison">
  49. <img src="./docs/assets/skillsbench-resource-use.png" width="900" alt="SkillsBench resource comparison: total token use fell from 491.1 million for Native to 345.8 million for Lean Vibe, while tool calls fell by 33.1%">
  50. </a>
  51. </p>
  52. <p align="center"><sub>Resource use: 491.122M to 345.756M total tokens, with tool calls reduced from 9,954 to 6,664.</sub></p>
  53. Analysis of the logs from the original benchmark shows that ***VibeSkills achieves better task performance not by invoking more Skills***.
  54. Instead, it first clarifies the task objective and delivery requirements, then decomposes a complex task into several verifiable subtasks. It subsequently selects only a small number of truly relevant capabilities from a large pool of candidate Skills and executes them in an order determined by their dependencies. This helps reduce misunderstandings of the task, omitted steps, and incorrect Skill selection, thereby improving overall task performance.
  55. ***In terms of token cost and tool usage***, this workflow also eliminates a substantial amount of ineffective trial and error. Native agents are more likely to repeatedly invoke tools in unproductive directions, reread the same context, and redo previous work. In contrast, VibeSkills converges more quickly on the critical steps through clearer planning and pre-delivery checks. As a result, it not only improves task quality, but also significantly reduces tool-call loops and the token overhead caused by repeated context processing.
  56. <p align="center">
  57. <a href="https://github.com/foryourhealth111-pixel/vibeskills-benchmark/blob/main/studies/full-skills-comparison/README.md">Study, public data, and reproduction</a> ·
  58. </p>
  59. <p align="center">
  60. <picture>
  61. <source media="(prefers-color-scheme: dark) and (max-width: 600px)" srcset="./docs/assets/readme-preface-v2-en-mobile-dark.svg">
  62. <source media="(prefers-color-scheme: light) and (max-width: 600px)" srcset="./docs/assets/readme-preface-v2-en-mobile-light.svg">
  63. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-preface-v2-en-dark.svg">
  64. <source media="(prefers-color-scheme: light)" srcset="./docs/assets/readme-preface-v2-en-light.svg">
  65. <img src="./docs/assets/readme-preface-v2-en-light.svg" width="900" alt="Skills are excellent local assets of reusable experience. After downloading and installing many Skills, it is easy to sometimes forget which Skills have already been installed and not know which Skills to invoke. Further, when a complex task involves the combined organization and invocation of multiple Skills from different domains, planning becomes complicated for people: they must explain to the AI in detail which Skills each module should use, while the AI may forget these designs during execution. Many current harness frameworks do not actively plan how to make good use of local Skill resources, and may even fall into an either-or scheduling conflict between the harness framework and domain Skill resources. The core of this project is to follow harness frameworks similar to Superpower and GSD. Based on modular decomposition by the planning state machine, it uses different Skills to assist different modules, fully schedules existing local resources, reduces users' planning and cognitive burden, and gives users an end-to-end delivery experience. It is committed to becoming a handy steward for the Skill resources around you. When a complex task appears, it can help users slowly sort out which modules are needed and which good experiences can be reused, then deliver an excellent result.">
  66. </picture>
  67. </p>
  68. <a id="vibeskills-ml-practice-case"></a>
  69. <h2 align="center">
  70. <picture>
  71. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-01-en-dark.svg">
  72. <img src="./docs/assets/readme-chapter-01-en-light.svg" width="720" alt="VibeSkills Practice Case: Completing a Machine-Learning Experiment">
  73. </picture>
  74. </h2>
  75. > **Task**
  76. >
  77. > *Use public data to complete a reproducible classification experiment and deliver a data audit, statistical review, 4 result figures, a scientific report, and a 7-slide group-meeting deck.*
  78. The diagram shows what happened after the requirement and plan were approved:
  79. how the task was executed, what it produced, and how the result was checked.
  80. The task used the `L` workflow and proceeded in order. During publication
  81. preparation, the configured folders on the same host contained more than 100
  82. Skills. VibeSkills reviewed the candidates and their `SKILL.md` files, selected
  83. 7 for this task, and arranged the work into 5 groups and 10 work units. Those
  84. units covered environment setup, data audit, modeling, statistical review,
  85. figures, the report, and the slide deck.
  86. After the work finished, VibeSkills ran 17 checks across the data, experiment
  87. results, figures, report, and slides. The task passed final acceptance after the
  88. required files, cross-deliverable consistency, and core reproduction all passed.
  89. <p align="center"><strong>7 Skills selected · 5 work groups · 10 / 10 work units completed · 17 / 17 checks passed</strong></p>
  90. ```mermaid
  91. %%{init: {"flowchart": {"curve": "monotoneX", "nodeSpacing": 18, "rankSpacing": 36}}}%%
  92. flowchart LR
  93. subgraph DISC["Skill discovery"]
  94. direction TB
  95. A["Configured Skill folders<br/>100+ Skills"]
  96. B["Shortlist candidates<br/>Read SKILL.md"]
  97. SEL["Skill selection<br/>7 Skills assigned"]
  98. A --> B
  99. B --> SEL
  100. end
  101. subgraph EXEC["Execution · 5 work groups · 10 work units"]
  102. direction TB
  103. subgraph G1["G1 · 01 Environment and data"]
  104. direction LR
  105. u01["U01<br/>Environment setup"]
  106. u02["U02<br/>Data audit"]
  107. u01 --> u02
  108. end
  109. subgraph G2["G2 · 02 Modeling and reproduction"]
  110. direction LR
  111. u03["U03<br/>Baseline experiment"]
  112. end
  113. subgraph G3["G3 · 03 Statistics and scientific review"]
  114. direction LR
  115. u04["U04<br/>Statistical analysis"]
  116. u05["U05<br/>Scientific review"]
  117. u04 --> u05
  118. end
  119. subgraph G4["G4 · 04 Figures and report"]
  120. direction LR
  121. u06["U06<br/>Result figures"]
  122. u07["U07<br/>Report draft"]
  123. u08["U08<br/>Report review"]
  124. u06 --> u07
  125. u07 --> u08
  126. end
  127. subgraph G5["G5 · 05 Slides and acceptance"]
  128. direction LR
  129. u09["U09<br/>Group-meeting slides"]
  130. u10["U10<br/>Case package and consistency"]
  131. u09 --> u10
  132. end
  133. G1 --> G2
  134. G2 --> G3
  135. G3 --> G4
  136. G4 --> G5
  137. end
  138. subgraph MID["Run and outputs"]
  139. direction TB
  140. S(["Run status<br/>10 / 10 completed<br/>0 failed · 0 blocked"])
  141. D["Real outputs<br/>4 figures · Scientific report<br/>7-slide deck"]
  142. S --> D
  143. end
  144. subgraph VERIFY["Verification · 17 checks"]
  145. direction TB
  146. subgraph V1["V1 · Foundation and plan"]
  147. direction LR
  148. t01["T01<br/>required-files"]
  149. t02["T02 module-output-<br/>patterns"]
  150. t03["T03 runtime-plan-<br/>binding"]
  151. t04["T04 environment-<br/>contract"]
  152. t01 --> t02
  153. t02 --> t03
  154. t03 --> t04
  155. end
  156. subgraph V2["V2 · Data, model, and reproduction"]
  157. direction LR
  158. t05["T05<br/>dataset-contract"]
  159. t06["T06 split-and-model-<br/>contract"]
  160. t07["T07<br/>baseline-results"]
  161. t08["T08 exact-<br/>reproduction"]
  162. t05 --> t06
  163. t06 --> t07
  164. t07 --> t08
  165. end
  166. subgraph V3["V3 · Statistics and deliverables"]
  167. direction LR
  168. t09["T09 uncertainty-<br/>consistency"]
  169. t10["T10 statistics-write-<br/>protection"]
  170. t11["T11 figure-<br/>traceability"]
  171. t12["T12 report-<br/>consistency"]
  172. t13["T13 slides-<br/>consistency"]
  173. t09 --> t10
  174. t10 --> t11
  175. t11 --> t12
  176. t12 --> t13
  177. end
  178. subgraph V4["V4 · Publication and boundaries"]
  179. direction LR
  180. t14["T14 bilingual-summary-<br/>consistency"]
  181. t15["T15 visual-material-<br/>guidance"]
  182. t16["T16 manifest-<br/>boundary"]
  183. t17["T17 artifact-path-<br/>boundary"]
  184. t14 --> t15
  185. t15 --> t16
  186. t16 --> t17
  187. end
  188. V1 --> V2
  189. V2 --> V3
  190. V3 --> V4
  191. end
  192. E(["Final acceptance<br/>17 / 17 checks passed<br/>PASS"])
  193. DISC --> EXEC
  194. EXEC --> MID
  195. MID --> VERIFY
  196. VERIFY --> E
  197. classDef source fill:#EAF3F3,stroke:#2B6F73,color:#182026;
  198. classDef selected fill:#F5EBEE,stroke:#8A5363,color:#182026;
  199. classDef unit fill:#FFFFFF,stroke:#5B7F83,color:#182026;
  200. classDef status fill:#F7EEF1,stroke:#8A5363,color:#182026,stroke-width:2px;
  201. classDef output fill:#E8F2F0,stroke:#2D7F75,color:#182026;
  202. classDef check fill:#FFFFFF,stroke:#8A9AA7,color:#182026;
  203. classDef result fill:#EAF4EE,stroke:#2F7A4B,color:#182026,stroke-width:2px;
  204. class A,B source;
  205. class SEL selected;
  206. class u01,u02,u03,u04,u05,u06,u07,u08,u09,u10 unit;
  207. class S status;
  208. class D output;
  209. class t01,t02,t03,t04,t05,t06,t07,t08,t09,t10,t11,t12,t13,t14,t15,t16,t17 check;
  210. class E result;
  211. style DISC fill:transparent,stroke:#AAB7C4,stroke-width:1px,stroke-dasharray:4 3;
  212. style EXEC fill:transparent,stroke:#AAB7C4,stroke-width:1px,stroke-dasharray:4 3;
  213. style MID fill:transparent,stroke:#AAB7C4,stroke-width:1px,stroke-dasharray:4 3;
  214. style VERIFY fill:transparent,stroke:#AAB7C4,stroke-width:1px,stroke-dasharray:4 3;
  215. style G1 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  216. style G2 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  217. style G3 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  218. style G4 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  219. style G5 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  220. style V1 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  221. style V2 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  222. style V3 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  223. style V4 fill:#FFFFFF,stroke:#DCE4EA,stroke-width:1px;
  224. linkStyle default stroke:#6D878B,stroke-width:1px;
  225. ```
  226. <p align="center">
  227. <a href="./docs/cases/ml-experiment/README.md#case-execution">View case execution</a> ·
  228. <a href="./docs/cases/ml-experiment/README.md#final-delivery">View final delivery</a>
  229. </p>
  230. <a id="how-vibeskills-carries-a-task-through-to-delivery"></a>
  231. <h2 align="center">
  232. <picture>
  233. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-02-en-dark.svg">
  234. <img src="./docs/assets/readme-chapter-02-en-light.svg" width="720" alt="How VibeSkills Carries a Task Through to Delivery">
  235. </picture>
  236. </h2>
  237. *VibeSkills gives an Agent one process from receiving a task to checking the delivery.*
  238. Each stage answers a concrete question: what needs to be done, how the
  239. work should proceed, which Skills should take part, what actually happened, and
  240. whether the result is ready to deliver.
  241. <p align="center">
  242. <img src="./docs/assets/vibeskills-harness-overview-en.svg" width="860" alt="VibeSkills confirms the requirement, chooses L or XL, organizes Skills, records the work, and checks the result; code work can enter a TDD loop">
  243. </p>
  244. <ol type="I">
  245. <li><strong>Confirms the requirement.</strong> Before work begins, it confirms the goal, constraints, available material, and expected delivery. The process stops here until the requirement is approved, giving the plan and final check a clear basis.</li>
  246. <li><strong>Recommends a level.</strong> VibeSkills recommends <code>L</code> or <code>XL</code> from the task's scope, steps, dependencies, and opportunities for parallel work. You then confirm the level. Manageable work proceeds in order; larger work is split more finely.</li>
  247. <li><strong>Organizes Skills.</strong> VibeSkills reviews the local Skill folders, selects the methods that fit each part, and states what each Skill owns, what it should deliver, and how completion will be checked.</li>
  248. <li><strong>Executes and records.</strong> After plan approval, the current Agent completes the work. Code tasks can use test-driven development (TDD) when appropriate: show the problem with a failing test, make the change, and run the tests again. Completed, failed, and blocked states are recorded so a later session can continue.</li>
  249. <li><strong>Checks the result.</strong> VibeSkills compares the actual result with every planned item. Required work that is incomplete, failed, or blocked prevents final acceptance.</li>
  250. </ol>
  251. <details>
  252. <summary><strong>When to use L or XL</strong></summary>
  253. | Level | Best for | How it works |
  254. |:---|:---|:---|
  255. | `L` | Multi-step work of manageable size | Splits the task, then works through the parts in order with less time and context overhead |
  256. | `XL` | Larger work with several relatively independent parts | Uses a more detailed breakdown and can run up to two non-conflicting parts at the same time, with additional coordination and result collection |
  257. </details>
  258. <a id="how-local-skills-take-part"></a>
  259. <h2 align="center">
  260. <picture>
  261. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-03-en-dark.svg">
  262. <img src="./docs/assets/readme-chapter-03-en-light.svg" width="720" alt="How Local Skills Take Part">
  263. </picture>
  264. </h2>
  265. *Local Skills can store tool usage, working steps, decision rules, and checking methods.*
  266. VibeSkills reviews the local Skill folders you configure, then
  267. shortlists the Skills that fit the work required by each part of the task.
  268. <p align="center">
  269. <img src="./docs/assets/vibeskills-skill-orchestration-en.png" width="860" alt="VibeSkills sits between task modules and local Skills, coordinating the work and selecting only the Skills each part needs">
  270. </p>
  271. The left side shows the different kinds of work in the task, VibeSkills makes
  272. the assignment in the middle, and the local Skill folders are on the right. A
  273. selected Skill is tied to concrete work, expected delivery, and a check. The
  274. current Agent then follows the shared plan.
  275. <table align="center" width="94%">
  276. <thead>
  277. <tr>
  278. <th width="50%" align="center">Passive Skill triggering</th>
  279. <th width="50%" align="center">With VibeSkills</th>
  280. </tr>
  281. </thead>
  282. <tbody>
  283. <tr>
  284. <td>The AI reacts to a few obvious words</td>
  285. <td><strong>It splits the whole task first</strong></td>
  286. </tr>
  287. <tr>
  288. <td>The same familiar Skills are used repeatedly</td>
  289. <td><strong>Each part is checked for a better-fitting Skill</strong></td>
  290. </tr>
  291. <tr>
  292. <td>Unmatched work is handled on the spot</td>
  293. <td><strong>A useful Skill is assigned to specific work with a stated result</strong></td>
  294. </tr>
  295. <tr>
  296. <td>Separate calls are left disconnected</td>
  297. <td><strong>All results are brought together and checked at the end</strong></td>
  298. </tr>
  299. </tbody>
  300. </table>
  301. VibeSkills does something straightforward: **it first makes the whole task
  302. clear, then assigns the right Skills to the relevant parts**. It coordinates
  303. the work and checks the combined result at the end. The task uses the Skills it
  304. needs; the rest of the local library stays available without entering the plan.
  305. You can keep adding your own Skills, team Skills, and third-party Skills.
  306. VibeSkills does not call every installed Skill automatically; it selects the
  307. Skills that fit the current task. The size of the library defines the available
  308. choices, not a list that every task must use.
  309. <details>
  310. <summary><strong>Will a large Skill library use a lot of tokens?</strong></summary>
  311. VibeSkills checks the Skill folders you configure, but finding files locally
  312. and placing their full contents in the model context are different operations.
  313. Discovery and index generation happen locally. VibeSkills first extracts compact
  314. information such as each Skill's name, description, intended use, and boundaries,
  315. then uses that information to shortlist candidates for each part of the task.
  316. Only retained candidates are then read as complete `SKILL.md` files. Execution
  317. uses only the Skills written into the plan. Token usage therefore depends mainly
  318. on how many candidates the task retains, how long those documents are, and how
  319. complex the task is. It is not the same as reading the full local Skill library
  320. into the model context.
  321. This overhead is not zero. More candidates, longer Skill documents, or a more
  322. finely divided task will use more context. The current design bounds that cost
  323. with a local index, candidate shortlisting, and on-demand reading.
  324. </details>
  325. <details>
  326. <summary><strong>Local folders and selection records</strong></summary>
  327. Alongside the shared Skills directory, more local folders can be listed in
  328. `~/.vibeskills/skill-roots.json` or
  329. `<workspace>/.vibeskills/skill-roots.json`.
  330. A Skill needs a readable `SKILL.md`, a name that does not conflict with another
  331. Skill, and a clear fit for the current work before it can be selected. Adding a
  332. local folder makes those Skills available to later tasks without waiting for the
  333. VibeSkills repository to include them.
  334. During planning, `agent_skill_organization` stores which Skills are intended for
  335. each part of the task. During execution, `module_assignments` stores the actual
  336. assignment. Finding a Skill means it can be considered; it does not mean the
  337. Skill has already taken part in the work.
  338. </details>
  339. <a id="how-a-task-can-continue-and-be-reviewed"></a>
  340. <h2 align="center">
  341. <picture>
  342. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-04-en-dark.svg">
  343. <img src="./docs/assets/readme-chapter-04-en-light.svg" width="720" alt="How a Task Can Continue and Be Reviewed">
  344. </picture>
  345. </h2>
  346. *A public example lets readers follow the requirement, plan, actual result, and final check.*
  347. VibeSkills keeps the approved requirement, plan, execution progress, and final
  348. check in the same task record. A later session can continue from the saved
  349. progress, and a review can compare the original plan with the actual result.
  350. Installation state is recorded separately so it is not confused with task
  351. completion.
  352. <details>
  353. <summary><strong>View the record files</strong></summary>
  354. | File or directory | What it is for |
  355. |:---|:---|
  356. | `install-receipt.json` | Records the files written by the installer so `check` can find missing or changed files |
  357. | `session_root` | Stores the input, progress, important decisions, and summary for one task |
  358. | `module-work-plan.json` | Stores the approved work plan, including responsibility, expected output, and checks |
  359. | `module-execution.json` | Stores what each part actually produced and whether it completed, failed, or was blocked |
  360. | `delivery-acceptance-report.json` or `.md` | Stores the final check and shows which items passed |
  361. Maintainers can use the
  362. [pre-release checks](https://github.com/foryourhealth111-pixel/Vibe-Skills/actions/workflows/vco-gates.yml). Start with
  363. the checks in that list and run wider audits only when there is a reason.
  364. </details>
  365. A successful installation does not mean the task ran, and a task record does
  366. not mean the final result passed its checks.
  367. <a id="use-vibeskills"></a>
  368. <h2 align="center">
  369. <picture>
  370. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-chapter-05-en-dark.svg">
  371. <img src="./docs/assets/readme-chapter-05-en-light.svg" width="720" alt="Use VibeSkills">
  372. </picture>
  373. </h2>
  374. <ol type="I">
  375. <li><strong>Invoke.</strong> In any AI application that supports local Skills, invoke VibeSkills through the application's Skills entry, using <code>$vibe</code>, <code>/vibe</code>, or the syntax it provides.</li>
  376. <li><strong>Discover.</strong> VibeSkills scans the Skills installation directory and any additional local Skill folders you configure to find the Skills currently available.</li>
  377. <li><strong>Organize.</strong> It selects suitable Skills for the task, assigns them to the relevant work, and coordinates the result. You do not need to remember which Skill should be used when.</li>
  378. </ol>
  379. <p align="center">
  380. <picture>
  381. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg">
  382. <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt="">
  383. </picture>
  384. </p>
  385. <a id="more-documentation"></a>
  386. <h2 align="center">More Documentation</h2>
  387. <table align="center" width="90%">
  388. <thead>
  389. <tr>
  390. <th width="50%" align="center">Need</th>
  391. <th width="50%" align="center">Start here</th>
  392. </tr>
  393. </thead>
  394. <tbody>
  395. <tr><td align="center">See a complete real run</td><td align="center"><strong><a href="./docs/cases/ml-experiment/README.md">Machine-learning experiment case</a></strong></td></tr>
  396. <tr><td align="center">Install, update, uninstall</td><td align="center"><strong><a href="./docs/install/README.en.md">Simple install</a></strong></td></tr>
  397. <tr><td align="center">First use</td><td align="center"><strong><a href="./docs/quick-start.en.md">Quick start</a></strong></td></tr>
  398. <tr><td align="center">Current release</td><td align="center"><strong><a href="https://github.com/foryourhealth111-pixel/Vibe-Skills/releases/latest">GitHub release metadata</a></strong></td></tr>
  399. <tr><td align="center">How it works</td><td align="center"><strong><a href="./docs/README.md">Documentation index</a></strong></td></tr>
  400. <tr><td align="center">Troubleshooting</td><td align="center"><strong><a href="./docs/troubleshooting.md">Troubleshooting guide</a></strong></td></tr>
  401. <tr><td align="center">Contributing</td><td align="center"><strong><a href="./CONTRIBUTING.md">Contribution guide</a></strong></td></tr>
  402. </tbody>
  403. </table>
  404. <p align="center">
  405. <picture>
  406. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg">
  407. <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt="">
  408. </picture>
  409. </p>
  410. <a id="community-and-credits"></a>
  411. <h2 align="center">Community and Credits</h2>
  412. Questions, corrections, and well-scoped contributions are welcome through
  413. [GitHub Issues](https://github.com/foryourhealth111-pixel/Vibe-Skills/issues)
  414. and pull requests.
  415. VibeSkills discussions and community practice can also continue on
  416. [LINUX DO](https://linux.do/). It is a place to exchange technical questions,
  417. AI practice, and experience. Thank you to the LINUX DO community for supporting
  418. this project.
  419. The [VibeSkills 3.1.0 community practice cases](https://linux.do/t/topic/2061161)
  420. collect several examples that were shared with the community.
  421. Community contributors include
  422. [xiaozhongyaonvli](https://github.com/xiaozhongyaonvli) and
  423. [ruirui2345](https://github.com/ruirui2345).
  424. Third-party software attribution and license information are listed in
  425. [NOTICE](./NOTICE) and [third-party licenses](./THIRD_PARTY_LICENSES.md).
  426. <p align="center">
  427. <picture>
  428. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/readme-wave-divider-dark.svg">
  429. <img src="./docs/assets/readme-wave-divider-light.svg" width="240" alt="">
  430. </picture>
  431. </p>
bundled/skills/autonomous-builder/assets/auto-continue.sh · Bundled script · 252 lines · 1 finding marked
  1. #!/bin/bash
  2. # =============================================================================
  3. # Auto-Continue Supervisor Script
  4. # Generated by: autonomous-builder skill
  5. # Purpose: Self-supervising long-running autonomous operation
  6. # =============================================================================
  7. # Configuration (will be replaced with actual values during initialization)
  8. PROJECT_DIR="{{PROJECT_DIR}}"
  9. BUILDER_DIR="$PROJECT_DIR/.builder"
  10. STATE_FILE="$BUILDER_DIR/state.json"
  11. SUPERVISOR_CONFIG="$BUILDER_DIR/supervisor.json"
  12. LOG_FILE="$BUILDER_DIR/supervisor.log"
  13. # Default monitoring settings
  14. CHECK_INTERVAL=60
  15. SESSION_TIMEOUT=300
  16. MAX_RESTART_ATTEMPTS=10
  17. RESTART_COOLDOWN=5
  18. # =============================================================================
  19. # Utility Functions
  20. # =============================================================================
  21. log() {
  22. echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
  23. }
  24. load_config() {
  25. if [ -f "$SUPERVISOR_CONFIG" ]; then
  26. # Parse JSON config (simple grep-based parsing)
  27. CHECK_INTERVAL=$(grep -o '"check_interval_seconds"[[:space:]]*:[[:space:]]*[0-9]*' "$SUPERVISOR_CONFIG" | grep -o '[0-9]*$')
  28. SESSION_TIMEOUT=$(grep -o '"session_timeout_seconds"[[:space:]]*:[[:space:]]*[0-9]*' "$SUPERVISOR_CONFIG" | grep -o '[0-9]*$')
  29. MAX_RESTART_ATTEMPTS=$(grep -o '"max_restart_attempts"[[:space:]]*:[[:space:]]*[0-9]*' "$SUPERVISOR_CONFIG" | grep -o '[0-9]*$')
  30. RESTART_COOLDOWN=$(grep -o '"restart_cooldown_seconds"[[:space:]]*:[[:space:]]*[0-9]*' "$SUPERVISOR_CONFIG" | grep -o '[0-9]*$')
  31. fi
  32. }
  33. get_project_status() {
  34. if [ -f "$STATE_FILE" ]; then
  35. grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | head -1 | cut -d'"' -f4
  36. else
  37. echo "not_initialized"
  38. fi
  39. }
  40. get_last_activity() {
  41. if [ -f "$STATE_FILE" ]; then
  42. grep -o '"last_activity"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | cut -d'"' -f4
  43. else
  44. echo ""
  45. fi
  46. }
  47. get_pending_features_count() {
  48. if [ -f "$STATE_FILE" ]; then
  49. # Count pending features
  50. python3 -c "
  51. import json
  52. with open('$STATE_FILE') as f:
  53. state = json.load(f)
  54. pending = [f for f in state.get('features', {}).get('pending', []) if f]
  55. print(len(pending))
  56. " 2>/dev/null || echo "0"
  57. else
  58. echo "0"
  59. fi
  60. }
  61. get_session_count() {
  62. if [ -f "$STATE_FILE" ]; then
  63. grep -o '"session_count"[[:space:]]*:[[:space:]]*[0-9]*' "$STATE_FILE" | grep -o '[0-9]*$'
  64. else
  65. echo "0"
  66. fi
  67. }
  68. update_statistics() {
  69. local sessions=$1
  70. local restarts=$2
  71. if [ -f "$SUPERVISOR_CONFIG" ]; then
  72. # Update statistics in config
  73. python3 -c "
  74. import json
  75. with open('$SUPERVISOR_CONFIG', 'r') as f:
  76. config = json.load(f)
  77. config['statistics']['total_sessions'] = $sessions
  78. config['statistics']['total_restarts'] = $restarts
  79. config['statistics']['last_restart_time'] = '$(date -Iseconds)'
  80. with open('$SUPERVISOR_CONFIG', 'w') as f:
  81. json.dump(config, f, indent=2)
  82. " 2>/dev/null
  83. fi
  84. }
  85. # =============================================================================
  86. # Health Check Functions
  87. # =============================================================================
  88. check_progress_stall() {
  89. local last_feature=$1
  90. local current_feature=$(grep -o '"current_feature"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | cut -d'"' -f4)
  91. if [ "$last_feature" = "$current_feature" ] && [ -n "$current_feature" ]; then
  92. # Same feature, check operations since progress
  93. local ops=$(grep -o '"operations_since_progress"[[:space:]]*:[[:space:]]*[0-9]*' "$STATE_FILE" | grep -o '[0-9]*$')
  94. if [ -n "$ops" ] && [ "$ops" -gt 10 ]; then
  95. return 0 # Stalled
  96. fi
  97. fi
  98. return 1 # Not stalled
  99. }
  100. check_error_spike() {
  101. if [ -f "$BUILDER_DIR/errors.json" ]; then
  102. local recent_errors=$(grep -c '"timestamp"' "$BUILDER_DIR/errors.json" 2>/dev/null || echo "0")
  103. if [ "$recent_errors" -gt 5 ]; then
  104. return 0 # Error spike detected
  105. fi
  106. fi
  107. return 1 # No error spike
  108. }
  109. # =============================================================================
  110. # Main Supervisor Loop
  111. # =============================================================================
  112. main() {
  113. log "=========================================="
  114. log "Autonomous Builder Supervisor Started"
  115. log "=========================================="
  116. log "Project: $PROJECT_DIR"
  117. log "Check Interval: ${CHECK_INTERVAL}s"
  118. log "Session Timeout: ${SESSION_TIMEOUT}s"
  119. log "Max Restart Attempts: $MAX_RESTART_ATTEMPTS"
  120. log ""
  121. local restart_count=0
  122. local last_feature=""
  123. local stall_count=0
  124. while true; do
  125. load_config
  126. # Check 1: Project completion
  127. local status=$(get_project_status)
  128. if [ "$status" = "completed" ]; then
  129. log "✅ Project completed! Supervisor exiting."
  130. log "Total sessions: $(get_session_count)"
  131. log "Total restarts: $restart_count"
  132. exit 0
  133. fi
  134. # Check 2: Pending features
  135. local pending=$(get_pending_features_count)
  136. if [ "$pending" -eq 0 ] && [ "$status" != "not_initialized" ]; then
  137. log "✅ All features completed! Project done."
  138. exit 0
  139. fi
  140. # Check 3: Progress stall
  141. if check_progress_stall "$last_feature"; then
  142. stall_count=$((stall_count + 1))
  143. log "⚠️ Progress stall detected (count: $stall_count)"
  144. if [ $stall_count -ge 3 ]; then
  145. log "🔴 Too many stalls. Pausing for user intervention."
  146. log "Type 'resume' to continue, or 'abort' to stop."
  147. read -t 60 user_input
  148. if [ "$user_input" = "abort" ]; then
  149. log "User aborted. Exiting."
  150. exit 1
  151. fi
  152. stall_count=0
  153. fi
  154. else
  155. stall_count=0
  156. fi
  157. # Check 4: Error spike
  158. if check_error_spike; then
  159. log "⚠️ Error spike detected. Recording for analysis."
  160. fi
  161. # Check 5: Max restart attempts
  162. if [ $restart_count -ge $MAX_RESTART_ATTEMPTS ]; then
  163. log "🔴 Max restart attempts reached ($MAX_RESTART_ATTEMPTS)"
  164. log "Please investigate manually. Supervisor pausing."
  165. sleep 300 # Wait 5 minutes before retry
  166. restart_count=0 # Reset counter
  167. fi
  168. # Start/Resume Claude Session
  169. log "🚀 Starting Claude session #$((restart_count + 1))..."
  170. log " Pending features: $pending"
  171. log " Current status: $status"
  172. # Update statistics before session
  173. update_statistics $(get_session_count) $restart_count
  174. # Run Claude with auto-continue flag
  175. # Note: --dangerously-skip-permissions enables unattended operation
  176. # WARNING: This bypasses all permission prompts - use only in trusted environments
  177. claude --skill autonomous-builder --project "$PROJECT_DIR" --dangerously-skip-permissions 2>&1 | tee -a "$LOG_FILE"
  178. local exit_code=$?
  179. # Session ended
  180. log "Session ended with code: $exit_code"
  181. # Update restart count
  182. restart_count=$((restart_count + 1))
  183. # Record current feature for stall detection
  184. last_feature=$(grep -o '"current_feature"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | cut -d'"' -f4)
  185. # Cooldown before restart
  186. log "Waiting ${RESTART_COOLDOWN}s before next session..."
  187. sleep $RESTART_COOLDOWN
  188. done
  189. }
  190. # =============================================================================
  191. # Signal Handlers
  192. # =============================================================================
  193. cleanup() {
  194. log "Supervisor stopped by signal. Saving state..."
  195. update_statistics $(get_session_count) $(cat /tmp/autonomous_restarts 2>/dev/null || echo "0")
  196. exit 0
  197. }
  198. trap cleanup SIGINT SIGTERM
  199. # =============================================================================
  200. # Entry Point
  201. # =============================================================================
  202. # Validate project directory
  203. if [ ! -d "$PROJECT_DIR" ]; then
  204. echo "Error: Project directory not found: $PROJECT_DIR"
  205. exit 1
  206. fi
  207. # Create .builder directory if not exists
  208. mkdir -p "$BUILDER_DIR"
  209. # Initialize log file
  210. touch "$LOG_FILE"
  211. # Run main loop
  212. main

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.