opencode-skills-collection 4.0.67 → 4.0.68

package/bundled-skills/ralph-loop-yylo/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ralph-loop-yylo
+description: Execute exactly one explicitly assigned YYLO Ledger task through the
+  Ralph loop to a validated queued commit. Use only when the user explicitly requests
+  ralph-loop-yylo.
+category: agent-orchestration
+risk: critical
+source: https://github.com/yylo-dev/yylo-skills
+source_repo: yylo-dev/yylo-skills
+source_type: community
+date_added: '2026-09-19'
+license: MIT
+license_source: https://github.com/yylo-dev/yylo-skills/blob/main/LICENSE
+compatibility: Requires the `yy` CLI, git and bash. Executes one explicitly assigned
+  Ledger task in its admitted worktree through `yy task start/finish` to a validated
+  queued commit. Never pushes, deploys, merges, or releases.
+---
+
+# Execute one assigned task in the Ralph loop
+
+Read [references/implement.md](references/implement.md) completely and follow it.
+
+Stay within the assigned task. Do not select unrelated work, edit `tasks.md`, auto-tag releases, push, deploy, mutate production, or broaden scope because another issue is noticed. Record a bounded related Kanban follow-up when necessary.
+
+Keep durable instructions concise and evidence-backed. Status belongs in the task response and runtime receipts, not `AGENTS.md`.
+
+Controller checkpoints are best-effort local durability warnings after terminal metadata is durable. They never gate `yy pi`, `yy task`, `yy merge`, product commits, candidates, or releases.
+
+## Complete assigned request
+
+Treat the following as the complete user-assigned request. Preserve task references and directives literally; resolve them only through the normal agent workflow.
+
+$ARGUMENTS
+
+## When to Use
+
+- The user explicitly requests `ralph-loop-yylo` for one already-assigned YYLO Ledger task.
+- You need to implement exactly that task through the validated loop to a queued, review-ready commit.
+
+## Limitations
+
+- Exactly one assigned task per run: never select unrelated work, broaden scope, push, deploy, merge, release, or mutate production.
+- Requires `yy task start TASK_ID` admission and `yy task finish TASK_ID` closure; stop after queueing - only the target owner runs `yy merge land`.
+- Docs-only import: the upstream `scripts/kanban.sh` wrapper is intentionally not bundled; `references/` holds the worker contract.
+- Controller checkpoints are best-effort durability warnings, never lifecycle gates.
+
+### Example
+
+```bash
+yy task start TASK_ID
+yy task preflight TASK_ID
+yy task finish TASK_ID
+```
+
+> Adapted from [yylo-dev/yylo-skills](https://github.com/yylo-dev/yylo-skills) (MIT) - v2.0.1; frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: `scripts/kanban.sh` runtime not bundled.

package/bundled-skills/ralph-loop-yylo/references/first_check.md

@@ -0,0 +1,18 @@
+### Check once
+
+Before editing, verify the task worktree, clean starting state, and frozen admitted
+path scope. Inspect ignore files only when the assigned task requires an ignore
+rule or the task's validation would otherwise produce untracked generated output.
+
+Modify an ignore file only when all of the following are true:
+
+- the change is necessary for the assigned task;
+- the exact file is included in the task's admitted paths;
+- existing project conventions support the rule; and
+- the change is included in focused validation and the task commit.
+
+Do not create or expand `.gitignore`, `.dockerignore`, `.eslintignore`,
+`.prettierignore`, `.npmignore`, `.terraformignore`, or `.helmignore` merely
+because a related tool is present. If a useful ignore-file change is outside the
+assigned scope, record a bounded related follow-up and continue only when the
+current task remains valid without it.

package/bundled-skills/ralph-loop-yylo/references/implement.md

@@ -0,0 +1,60 @@
+<!-- GENERATED DESTINATIONS: edit this canonical source, then run `npm run generate:implementation-contract`. -->
+---
+description: Implement exactly one assigned Kanban task in its admitted Bolt product worktree and stop after queueing it.
+---
+
+# Bolt implementation worker contract
+
+An implementation worker owns one explicitly assigned task. It does not select
+other work, mutate the product target, merge, release, deploy, or clean another
+task's workspace.
+
+## 1. Resolve and preserve admission
+
+1. Read `AGENTS.md` and the complete assigned task from the canonical controller.
+2. Run `yy task start TASK_ID` unless the handoff already contains the matching
+   active Bolt task record. Verify the returned worktree, branch, full target ref,
+   and exact base SHA before editing; stop on missing or contradictory evidence.
+3. Work only in that product worktree. Never edit product files in the controller
+   or copy controller ledgers, specs, state, or artifacts into a task worktree.
+4. Preserve controller identity and workspace-role checks. Controller checkpoints
+   are best-effort local durability warnings after terminal metadata is durable;
+   they are not product inputs or lifecycle gates.
+
+## 2. Implement
+
+1. Edit only requested product paths and preserve project sources of truth.
+2. Use focused affected tests in the edit loop. Other feature worktrees may run
+   concurrently; do not wait for or modify them.
+3. Do not launch lifecycle-semantic reviewers from implementation. Semantic
+   review and project checks are explicit owner operations outside native task
+   delivery; never claim they occurred because a task was queued.
+4. If blocked, record bounded truthful state and stop without claiming success.
+   Durable diagnostic output belongs in a verified Ledger Artifact Record when
+   the installed API supports it; otherwise preserve an external draft and stop,
+   never fall back to product documentation or direct controller-store edits.
+
+## 3. Queue and hand off
+
+1. Run focused tests, required dangerous-path checks, parity checks, and
+   `git diff --check`.
+2. Stage only task-owned paths, commit coherently, and leave the worktree clean.
+3. Run `yy task preflight TASK_ID` before expensive final validation. Repair any
+   admission, generated-output, runtime, or closure refusal while the task is
+   still `WORKING`.
+4. Run `yy task finish TASK_ID`; it validates the exact preflighted tip and
+   records `QUEUED` with its immutable review-ready closure.
+5. Record the commit and bounded response in Kanban. A lifecycle finalizer may
+   attempt a controller checkpoint after terminal metadata is durable; checkpoint
+   failure remains a warning and must not change the task or merge outcome.
+
+Stop after queueing. Read-only delivery observation uses `yy merge status`.
+Only the target owner runs `yy merge land TASK_ID`, which uses native Git and an
+expected-old ref update. If Git integration succeeded but Ledger projection did
+not, recover only with `yy merge project TASK_ID`. Implementation agents do not
+poll, steal authority, discard dirty bytes, or mutate the target.
+
+Release-version changes use this same ordinary task/merge lifecycle. Package
+preparation is maintainer-only and outside `yy`. Never create a tag, push,
+publish, deploy, mutate production, restart services, run post-deploy E2E, or
+clean worktrees without separate authority.

package/bundled-skills/resumable-implementation-contracts/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: resumable-implementation-contracts
+description: "Create repository-based execution contracts for multi-session implementation work, with stable task IDs, evidence, checkpoints, and exact resume state."
+category: project-management
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-19"
+author: ShianMike
+tags: [project-management, execution-contracts, checkpoints, verification, agent-workflows]
+tools: [claude, cursor, gemini, codex, antigravity]
+---
+
+# Resumable Implementation Contracts
+
+## Overview
+
+Turn a large, mostly defined implementation request into a repository contract
+that a fresh agent can read, update, verify, and resume without reconstructing
+the project from chat history. Keep stable intent separate from mutable
+execution state, and require evidence before any task is called complete.
+
+This is a tool-neutral document pattern. It does not depend on, replace, or
+configure any agent platform's built-in goal, task, plan, or project feature.
+
+This skill fills the layer between planning and execution. It does not replace
+product discovery, detailed technical design, project-wide state governance,
+or retrospective auditing.
+
+## When to Use This Skill
+
+Use it when work:
+
+- spans multiple sessions, agents, branches, or context windows;
+- has dependencies or acceptance criteria that must survive interruption;
+- needs an exact resume point rather than a narrative handoff;
+- can appear complete before runtime, artifact, UI, or test evidence exists;
+- must preserve partial work and unrelated repository changes.
+
+Skip it for a small task that can be completed and verified in one session.
+If requirements are still unsettled, resolve them before freezing the
+implementation contract.
+
+## Reuse Existing Project Documents
+
+Inspect the repository before creating files. Reuse equivalent documents and
+the project's established names when their ownership is clear. For substantial
+multi-session work, the minimum logical document set is:
+
+| Document | Owns | Must not become |
+| --- | --- | --- |
+| `IMPLEMENTATION_CONTRACT.md` | stable intent, scope, tasks, acceptance, definition of done | a live activity log |
+| `TASKS.md` | current task/subtask status, dependencies, evidence links | a second copy of the contract |
+| `CHECKPOINT.md` | authoritative current position and exact next action | a vague progress summary |
+| `DECISIONS.md` | material decisions, alternatives, and reasons | a transcript |
+| `VALIDATION.md` | checks actually run, results, evidence, and unresolved gates | a list of planned tests |
+
+These may live together under `docs/<contract-slug>/` or follow an existing
+repo layout. An existing `GOAL.md`, specification, or execution brief may own
+the contract role; do not rename it or create parallel files solely to match
+this skill.
+
+## Define Document Authority
+
+- Current owner instructions and applicable repository instructions govern
+  authorization and scope.
+- `IMPLEMENTATION_CONTRACT.md`, or its existing repository equivalent, owns
+  the implementation contract. Do not silently change it to fit the current
+  code.
+- The working tree, branch, commit, produced artifacts, and executed checks are
+  truth for implementation state.
+- The tracker files summarize that state; they do not override contrary
+  evidence on disk.
+
+When documents and reality disagree, reconcile status from evidence while
+preserving the contract's intent. Escalate any conflict that would materially
+change scope, behavior, or acceptance.
+
+## Write a Self-Contained Contract
+
+A new agent should be able to understand the work from the contract without
+the original conversation. Include only what is needed to execute correctly:
+
+1. objective and observable outcomes;
+2. current baseline and important constraints;
+3. in-scope work, exclusions, and authorization boundaries;
+4. operating rules, including interruption and validation policy;
+5. tasks with stable IDs, dependencies, acceptance, and breakpoints;
+6. final definition of done and handoff requirements.
+
+Use stable task and subtask IDs such as `T03` and `T03.2`. Never renumber them
+after execution starts; add new IDs or mark obsolete work explicitly.
+
+Each task should use this compact form:
+
+```markdown
+### T03 - <observable task outcome>
+
+- [ ] T03.1 <first implementation slice>
+- [ ] T03.2 <second implementation slice>
+
+Dependencies: T01
+
+Acceptance:
+- <observable behavior or artifact>
+- <required focused check and evidence>
+
+Breakpoint:
+- Update TASKS.md, VALIDATION.md, and CHECKPOINT.md after the accepted slice.
+```
+
+Write acceptance in pass/fail terms. File creation, code presence, or an
+agent's completion claim is not acceptance unless that is genuinely the whole
+requirement.
+
+## Read Before Acting
+
+At the start of a session or after interruption, read in this order:
+
+1. applicable repository instructions;
+2. the implementation contract;
+3. `TASKS.md`, `CHECKPOINT.md`, `DECISIONS.md`, and `VALIDATION.md`;
+4. current branch, `HEAD`, status, and relevant diff;
+5. only the code, tests, and artifacts needed for the active task.
+
+Reconcile the checkpoint with the working tree before editing. Preserve partial
+and unrelated changes. Resume the exact unfinished subtask when it is still
+valid; otherwise record why the next action changed.
+
+## Keep Writes Narrow and Durable
+
+- Change the implementation contract only when the owner changes intent or an
+  ambiguity is deliberately resolved.
+- Update `TASKS.md` when work starts, blocks, or becomes evidence-backed done.
+- Replace `CHECKPOINT.md` with the latest authoritative resume state; Git owns
+  its detailed history.
+- Add to `DECISIONS.md` only for choices that constrain later work.
+- Add to `VALIDATION.md` only after a check is actually run or explicitly
+  recorded as not run.
+- Update the checkpoint after a meaningful increment and before stopping.
+
+Do not duplicate the same mutable status across every document. Link to the
+owning record instead.
+
+## Use Evidence-Gated Status
+
+Use a small status vocabulary: `pending`, `in_progress`, `blocked`, and `done`.
+A task may become `done` only when its acceptance criteria have supporting
+evidence.
+
+For each validation record, capture:
+
+- timestamp and relevant commit or working-tree state;
+- exact command or manual procedure;
+- environment when it affects the result;
+- result, including failures and skipped checks;
+- artifact, log, screenshot, route, or report path when applicable;
+- unresolved caveats or gates.
+
+Run the smallest check that proves the current slice during implementation.
+Run broader integration or release suites at defined milestones or when the
+change's risk requires them. Never present a planned, mocked, or nominally
+successful check as observed behavior.
+
+## Make the Checkpoint Executable
+
+`CHECKPOINT.md` must let another agent continue immediately. Record:
+
+```markdown
+# Checkpoint
+
+Updated: <UTC timestamp>
+Branch / HEAD: <branch> / <commit>
+Active task: T03
+Active subtask: T03.2
+Status: in_progress
+
+Completed behavior:
+- <verified result and evidence link>
+
+Work in progress:
+- <files and partial state that must be preserved>
+
+Validation performed:
+- `<exact command>` -> <result>
+
+Blockers or uncertainties:
+- <blocker, owner, and condition for clearing it>
+
+Pre-existing or unrelated changes:
+- <paths or explicit none observed>
+
+Next exact action:
+- <one concrete edit, inspection, or command>
+
+Next verification:
+- <focused check that should follow that action>
+```
+
+Avoid next steps such as "continue implementation" or "finish tests." If the
+next agent must decide what those words mean, the checkpoint is incomplete.
+
+## Execution Loop
+
+1. Select the smallest dependency-ready task.
+2. Mark it `in_progress` and state the intended slice.
+3. Inspect the real path that owns the behavior.
+4. Make the minimum scoped change.
+5. Run focused verification and record the actual outcome.
+6. Update task status only from that evidence.
+7. Refresh the checkpoint with one exact next action.
+8. Repeat until every definition-of-done item is verified or explicitly
+  blocked.
+
+At final handoff, report completed outcomes, evidence, unresolved blockers,
+branch and commit state, and the exact next action if anything remains. Do not
+promote partial task completion into overall contract completion.
+
+## Limitations
+
+- This structure preserves execution state but cannot resolve unclear product
+  intent or choose among materially different outcomes for the owner.
+- Evidence quality depends on running checks that exercise the real behavior;
+  complete-looking documents do not prove implementation correctness.
+- Concurrent writers still need repository-level coordination to avoid
+  conflicting checkpoints and status updates.
+- The five-document layout is unnecessary overhead for small, single-session
+  tasks; reuse fewer existing documents when they provide the same ownership.
+
+## Common Failure Modes
+
+- Rewriting or renumbering task IDs after work has begun.
+- Treating checked boxes as evidence instead of linking the proof.
+- Recording only happy-path checks and losing failed attempts that constrain
+  the next decision.
+- Replaying all history instead of loading the authoritative current state.
+- Allowing implementation discoveries to silently expand the contract.
+- Running an expensive full suite after every small edit while skipping the
+  focused check that would isolate the defect.
+- Persisting credentials, tokens, private data, or sensitive command output in
+  tracking documents.
+
+## Relationship to Other Skills
+
+- Use `spec-driven-loop` when product requirements and technical design still
+  need structured discovery, freezing, and approval.
+- Use `planning-and-task-breakdown` when only an executable plan is needed.
+- Use `project-state-governor` when the need is canonical state across the
+  whole project rather than one scoped implementation effort.
+- Use `audit-agent-run-evidence` for a read-only retrospective audit of an
+  already completed run.
+
+This skill owns the compact execution contract that connects those concerns:
+stable intent, mutable progress, verification evidence, and exact resume state.

package/bundled-skills/understand-project-yylo/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: understand-project-yylo
+description: Inspect the current product architecture, dependencies, and validation
+  loops before planning or implementing a requested change.
+category: project-management
+risk: safe
+source: https://github.com/yylo-dev/yylo-skills
+source_repo: yylo-dev/yylo-skills
+source_type: community
+date_added: '2026-09-19'
+license: MIT
+license_source: https://github.com/yylo-dev/yylo-skills/blob/main/LICENSE
+compatibility: Requires read access to the product worktree and the `yy` CLI for task/spec
+  reads through the canonical controller. Read-only inspection; no mutations.
+argument-hint: '[Main Task] [Constraints] [Ultimate Goal]'
+enable-shell-directives: true
+---
+
+# Understand the project
+
+1. Read `AGENTS.md`/`CLAUDE.md`, repository status, relevant source, tests, and existing product documentation in the integration or assigned feature worktree.
+2. Read related Kanban tasks and durable specs through the canonical metadata controller. Do not assume `.juno_task/plan.md` exists and do not materialize controller-private metadata in a product worktree.
+3. Trace only the dependencies and runtime paths needed for the requested goal. Use bounded parallel investigation when independent questions justify it.
+4. Report current behavior, sources of truth, affected components, risks, unknowns, and the smallest useful validation loop.
+5. If the user requested planning, hand the findings to `plan-ledger-tasks-yylo`. If implementation was requested, work only in the task worktree returned by `yy task start TASK_ID`.
+6. Write a durable operational spec only when requested or materially useful. Draft it externally, preflight the installed `yy ledger artifact` API, capture it as an immutable `report` Artifact Record with provenance/retention, and verify retrieval, digest, and history. If that API is unavailable, stop with the external draft intact; never fall back to product `docs/`, task bodies/responses, new `.juno_task/specs`, or direct controller-store edits. Product `docs/` remains reserved for documentation shipped with the product. Do not update root instructions with transient status.
+
+## Invocation contract
+
+The structured views below intentionally alias parts of the complete request; they are not additional user arguments.
+
+### Main task
+
+$1
+
+### Constraints and context
+
+$2
+
+### Complete raw request
+
+$ARGUMENTS
+
+## When to Use
+
+- Before planning or implementing a requested change, when you need current architecture, dependencies, and validation loops.
+- To hand grounded findings to `plan-ledger-tasks-yylo` (planning) or a task worktree (implementation).
+
+## Limitations
+
+- Read-only: reports current behavior, sources of truth, affected components, risks, unknowns, and the smallest validation loop - does not implement.
+- Bounded investigation only; do not materialize controller-private metadata in a product worktree.
+- Durable specs are captured as immutable Artifact Records only when the installed `yy ledger artifact` API supports it; otherwise stop with the external draft intact.
+
+### Example
+
+```bash
+yy ledger search --status todo --limit 5
+yy ledger get TASK_ID
+```
+
+> Adapted from [yylo-dev/yylo-skills](https://github.com/yylo-dev/yylo-skills) (MIT) - v2.0.1; frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance.