phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/skills_bundle/gemini-run-train/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/gemini-run-train/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: gemini-run-train
+description: "Harness CLI entry point for the cross-repo release-train coordinator. Use when the user wants to run, resume, or inspect a multi-repo train roadmap: draft PRs across all nodes in topo order, gather train-level review, then merge sequentially with downstream re-verification."
+---
+
+# Harness Run Train
+
+Thin bridge for the `phase-loop run-train` coordinator. All preflight,
+draft-PR sequencing, train-level review, sequential merge, and downstream
+re-verify logic lives in the runtime; this skill is the human entry point only.
+Do NOT re-implement or contradict runtime guarantees here.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Use the repo-local CLI: `phase-loop run-train --train <train-roadmap-file>`.
+- Pass `--governed` to enable the merge phase (train-level review + sequential
+  merge + downstream re-verify). Omitting `--governed` stops at `drafts_open`.
+- Do NOT invoke `phase-loop run` on the train roadmap file — that is the
+  per-repo loop and will not orchestrate a multi-repo train.
+- Do NOT merge, force-push, or close PRs outside the coordinator; the runtime
+  enforces the partial-merge and false-green guards.
+- Inspect `phase-loop train-status --train <file>` to check the ledger without
+  modifying state.
+
+## Inputs
+
+- Train roadmap path: a Markdown file with `## Nodes` listing
+  `### Node: <repo> / <plan>` entries with `**Depends on:**` and
+  `**Channel:**` fields.
+- Optional `--governed` flag: activates train-level review → sequential merge →
+  downstream re-verify.
+- Optional `--ledger <path>`: explicit ledger path for crash-resume.
+
+## Workflow
+
+1. Resolve the train roadmap path (explicit arg or the user-supplied path).
+2. Run preflight:
+   `phase-loop run-train --train <file> --dry-run` (or inspect logs for
+   preflight errors before the first real run).
+3. Open draft PRs across all nodes in topo order:
+   `phase-loop run-train --train <file>`
+   The coordinator runs each repo's `run_loop` in series; a preflight failure
+   stops before any PR is opened.
+4. After all draft PRs are open (`status=drafts_open`), gather review:
+   `phase-loop run-train --train <file> --governed`
+   The train-level panel reviews the full set of draft changes.
+5. On approval, the coordinator merges upstream nodes first, then re-verifies
+   each downstream node against the upstream MERGED SHA before merging it.
+   A re-verify failure halts the merge at that node; upstream merges are
+   forward-only (never reverted).
+6. Inspect the outcome: `phase-loop train-status --train <file>`.
+
+## Failure Diagnostics
+
+- `preflight_failed`: one or more nodes failed preflight checks; zero PRs were
+  opened. Fix the reported issues and re-run.
+- `drafts_open`: draft PRs opened; merge phase not yet run. Pass `--governed`
+  to continue to review and merge.
+- `review_halted`: the train-level panel did not approve; `terminal_blocker`
+  carries `human_required=False` (the block is a non-human review terminal).
+  No nodes were merged. Re-run after addressing review findings.
+- `merge_halted`: upstream node(s) merged but a downstream re-verify failed;
+  the failed node and all its dependents are blocked. The forward-only guard
+  means already-merged nodes stay merged. Fix the integration issue and resume.
+- `merge_failed`: a merge call returned an error (e.g. conflict, branch
+  protection). The ledger records the failed node as `blocked`. Fix and resume.
+
+## Resume
+
+The coordinator is crash-resumable. If a run is interrupted, re-invoke the
+same command with `--governed`; the ledger state drives which nodes are skipped
+(already merged), re-verified (upstream merged but downstream not yet merged),
+or retried (blocked).

phase_loop_runtime/skills_bundle/gemini-skill-editor/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/gemini-skill-editor/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gemini-skill-editor
+description: "Harness skill editor. Use when the user wants to apply an improvement plan produced by <harness>-skill-improvement-planner to Harness skill files. Edits only targeted `<harness>-*` skills by default, archives consumed reflections after successful edits, and uses structured file-editing tools for manual changes."
+---
+
+# Harness Skill Editor
+
+Applies a structured improvement plan to Harness skill files. It is deliberately narrower than arbitrary skill editing: it consumes plans from `<harness>-skill-improvement-planner` and updates the named target skills.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Harness meta-skill source changes move through three tiers: canonical source at `<harness>-config/skills/<harness>-<skill>/SKILL.md`, harness-neutral bundle at `vendor/phase-loop-skills/<bare-skill>/SKILL.md`, and installed runtime roots at `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/`, and `~/.opencode/skills/`.
+- The harness-neutral bundle is currently bundle-derived-from-codex. Leave `vendor/phase-loop-skills/` and installed runtime roots stale until the end-of-v36 cutover; after edits, report bundle regeneration from the codex-derived source path plus `./bootstrap.sh` as the required follow-up. `./bootstrap.sh` installs the bundle with `python3 -m phase_loop_runtime.cli install --source vendor/phase-loop-skills --symlink --apply`.
+- Read the improvement plan and target `SKILL.md` before editing.
+- Use the active session's file-editing tool for manual edits.
+- Edit only skills named by the plan.
+- Default target set is `<harness>-*` skills. Do not edit the original Claude-oriented skills unless the plan explicitly names them and the user confirms that scope.
+- Preserve skill frontmatter validity.
+- Do not push or commit unless the user explicitly requests it.
+- Archive consumed reflections only after all recommendations citing them succeeded.
+
+## Pipeline
+
+The three-tier pipeline is canonical source -> harness-neutral bundle -> installed runtime roots. Edit only `<harness>-config/skills/<harness>-<skill>/SKILL.md` during this skill-editor workflow; bundle regeneration plus `./bootstrap.sh` is the explicit cutover trigger after approved canonical edits.
+
+## Inputs
+
+- Plan path: explicit path, or latest `resolve_skill_bundle_root("gemini")/<harness>-skill-improvement-planner/plans/plan-v*.md`.
+- `--dry-run`: parse and report intended edits without changing files.
+
+If no plan path is explicit, first check the current repo and branch handoff from `<harness>-skill-improvement-planner` using `<harness>-config/shared/runtime-state.md`: read the repo-local handoff resolver target `.dev-skills/handoffs/<harness>-skill-improvement-planner/latest.md`, validate `from`, `repo`, `repo_root`, `branch`, `branch_slug`, `commit`, and `artifact`, then use the artifact only if it exists under the current repo root. Ignore missing or mismatched handoffs unless the user explicitly asks to reuse cross-branch state.
+
+## Workflow
+
+1. Resolve and read the plan.
+2. Parse:
+   - `reflections_consumed`;
+   - recommendations by skill;
+   - cross-cutting recommendations;
+   - contradictions.
+3. If contradictions exist, stop and ask the user how to resolve them unless the plan already contains a resolution.
+4. Validate target skills:
+   - source path under `<harness>-config/skills/<harness>-<skill>/SKILL.md` when working in this dotfiles repo;
+   - symlink/runtime path under `resolve_skill_bundle_root("gemini")/<skill>/SKILL.md` only when no source path exists.
+5. For `--dry-run`, report the target files and recommendation summaries, then stop.
+6. Apply recommendations:
+   - group changes per target skill to avoid conflicting edits;
+   - keep `SKILL.md` concise;
+   - move lengthy examples into `references/`;
+   - update `agents/openai.yaml` when display metadata becomes stale.
+7. Validate:
+   - YAML frontmatter parses;
+   - `name` matches the skill directory intent;
+   - `description` clearly states trigger scope and non-scope;
+   - referenced files exist.
+8. Archive reflections:
+   - move successfully consumed reflection files to an `archive/` directory under the same repo and branch subtree;
+   - leave reflections in place for failed recommendations.
+
+## Failure Policy
+
+- Malformed plan: stop and report exact parse failure.
+- Missing target skill: mark that recommendation failed; continue only if other independent targets remain.
+- Patch conflict: re-read the file, adjust once, then report if still blocked.
+- Validation failure: fix if local to the edit; otherwise roll forward with a clear report and do not archive affected reflections.
+
+## Closeout
+
+Closeout payload shape is defined by `EmitPhaseCloseout` in `phase_loop_runtime/baml_src/emit_phase_closeout.baml` (if that path is absent in the checkout, use the operator/prompt-supplied field contract or the installed `phase_loop_runtime` package — the missing vendored BAML source is not a blocker); keep skill text focused on value selection and handoff routing, not duplicated field ceremony.
+
+Report:
+
+- applied recommendations;
+- skipped or failed recommendations;
+- files changed;
+- reflections archived;
+- validation commands run.
+
+If writing self-improvement state, resolve handoff writes through `shared/phase-loop/handoff_path.py` and the repo-local handoff resolver; legacy harness handoff roots are read only for migration. Follow `<harness>-config/shared/runtime-state.md` and use Harness paths only:
+
+- Reflection: `resolve_skill_bundle_root("gemini")/<harness>-skill-editor/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `<repo>/.dev-skills/handoffs/<harness>-skill-editor/<run_id>.md`
+- Latest handoff pointer: `<repo>/.dev-skills/handoffs/<harness>-skill-editor/latest.md`
+
+Handoff frontmatter must include `from: <harness>-skill-editor`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, and `artifact:`. Update `latest.md` with the same handoff content.

phase_loop_runtime/skills_bundle/gemini-skill-editor/assets/editor_prompt.md

@@ -0,0 +1,72 @@
+# Editor prompt
+
+You are applying **one** recommendation from a skill improvement plan to **one** target SKILL.md. The recommendation was produced by an aggregator that distilled multiple reflection files; you're the last link in the chain.
+
+## Your inputs
+
+- **Target skill** — the skill's name (e.g., `claude-plan-phase`).
+- **Target SKILL.md path** — absolute path.
+- **Change to apply** — a natural-language instruction in directive-only imperative form.
+- **Rationale** — why this change was proposed (one clause).
+
+(These are appended to the end of this prompt by the caller.)
+
+## Your task
+
+1. `Read` the target SKILL.md in full.
+2. Interpret the change. Find the specific location in the file where it applies. If the change names a step, heading, or section (e.g., "In Step 5 of claude-plan-phase/SKILL.md, add a bullet after 'Apply the claude-task-contextualizer checklist' stating: …"), locate that anchor.
+3. Apply the change with `Edit`. Preserve:
+   - **Directive-only house style.** Imperative form. No war stories, no stats, no narrative justification. Reasons stated in one clause.
+   - **Existing structure.** Headings, tables, lists stay where they are unless the change explicitly moves them.
+   - **Exact whitespace.** Match indentation (tabs vs spaces) from the surrounding lines.
+   - **Existing cross-references.** If the change adds a new rule, don't accidentally break a pointer from another section.
+4. Verify: `Read` the modified region after editing. Confirm the change landed in the right place and the surrounding text still makes sense.
+
+## Refusing to apply
+
+You **must** refuse (and report `applied: false`) if any of:
+
+- The change names a specific project, codebase, domain, filename outside this skill, or company — the plan should have rejected these, but a slipped one surfaces here. Say so in `error`.
+- The change is too vague to pin to a specific location ("improve Step 5 somehow"). Say so in `error` and quote the vague phrasing.
+- The target file doesn't have the anchor the change references (e.g., "after 'Apply the claude-task-contextualizer checklist'" but no such line exists). Say so in `error` and list what you searched for.
+- Applying would contradict an instruction already present (without the change text acknowledging the contradiction). Say so in `error`.
+
+Do not attempt partial or creative application in any of these cases — better to fail cleanly and let the planner's next cycle reconsider.
+
+## House style reference
+
+Before editing, skim the skill's existing prose to match tone. The pattern across this repo:
+
+- Every rule uses imperative form ("Do X.", "Run Y."). Not "You should do X" or "X is recommended."
+- Rationale is a single clause ("because downstream lanes depend on it") rather than a paragraph.
+- No self-referential filler ("The skill is designed to…"). Just the directive.
+- Tables over prose where a table fits.
+- References to other skills use `/<skill-name>` (the invocation form) not `<skill-name>/SKILL.md` (the filesystem form), unless specifically naming a file.
+
+## Your response
+
+After editing (or deciding not to), return a single JSON object on stdout:
+
+```json
+{
+  "applied": true,
+  "files_modified": ["/abs/path/to/SKILL.md"],
+  "diff_summary": "Added bullet to Step 5 brief-construction list specifying that phase Exit criteria must be copied verbatim, not paraphrased.",
+  "error": null
+}
+```
+
+Or on failure:
+
+```json
+{
+  "applied": false,
+  "files_modified": [],
+  "diff_summary": null,
+  "error": "Change references 'after \"Apply the claude-task-contextualizer checklist\"' but no such line exists in the target file. Closest match: 'Apply the `/claude-task-contextualizer` checklist to every brief.' — unclear if these are the same anchor."
+}
+```
+
+Keep `diff_summary` to one sentence. Keep `error` specific enough that the planner's next run can address it.
+
+Do not output anything before the JSON object.

phase_loop_runtime/skills_bundle/gemini-skill-improvement-planner/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/gemini-skill-improvement-planner/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: gemini-skill-improvement-planner
+description: "Harness skill feedback aggregator. Use when the user wants to review Harness skill reflections, aggregate recurring feedback, or plan improvements to `<harness>-*` skills. Produces an improvement plan for <harness>-skill-editor and does not edit skills itself."
+---
+
+# Harness Skill Improvement Planner
+
+Aggregates reflection files for Harness skills and produces a structured improvement plan. It does not edit skills; `<harness>-skill-editor` applies the plan.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Harness meta-skill source changes move through three tiers: canonical source at `<harness>-config/skills/<harness>-<skill>/SKILL.md`, harness-neutral bundle at `vendor/phase-loop-skills/<bare-skill>/SKILL.md`, and installed runtime roots at `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/`, and `~/.opencode/skills/`.
+- The harness-neutral bundle is currently bundle-derived-from-codex. Leave `vendor/phase-loop-skills/` and installed runtime roots stale until the end-of-v36 cutover; the cutover regenerates the bundle from the codex-derived source path and runs `./bootstrap.sh`, which installs the bundle with `python3 -m phase_loop_runtime.cli install --source vendor/phase-loop-skills --symlink --apply`.
+- Planning only. Do not modify `SKILL.md` files.
+- Scan Harness skill state under `resolve_skill_bundle_root("gemini")/<skill>/reflections/**`.
+- Also scan the codex-derived source-controlled reflection root `resolve_skill_bundle_root("codex")/<skill>/reflections/**`.
+- Exclude any path with an `archive/` component.
+- Follow the recursive reflection rules in `<harness>-config/shared/runtime-state.md`.
+- Act only on recurring evidence unless the user explicitly asks to apply one-off feedback.
+- Do not spawn subagents unless the user explicitly asks for delegated analysis.
+
+## Pipeline
+
+The three-tier pipeline is canonical source -> harness-neutral bundle -> installed runtime roots. Edit and plan against `<harness>-config/skills/<harness>-<skill>/SKILL.md`; do not treat bundle or installed copies as source of truth. Bundle regeneration plus `./bootstrap.sh` is the explicit cutover trigger after approved canonical edits.
+
+## Inputs
+
+- `--target <skill-name>`: plan for one skill.
+- `--min-reflections <N>`: default `2`.
+- `--output <path>`: default `resolve_skill_bundle_root("gemini")/<harness>-skill-improvement-planner/plans/plan-v<N>-<ISO>.md`.
+
+## Workflow
+
+1. Enumerate unarchived reflections for:
+   - `<harness>-phase-roadmap-builder`
+   - `<harness>-plan-phase`
+   - `<harness>-execute-phase`
+   - `<harness>-task-contextualizer`
+   - `<harness>-skill-improvement-planner`
+   - `<harness>-skill-editor`
+   - `<harness>-plan-detailed`
+2. Parse each reflection:
+   - skill name;
+   - version or timestamp;
+   - `What worked`;
+   - `Improvements to SKILL.md`;
+   - raw body when headings are missing.
+3. Gate on minimum evidence:
+   - zero reflections: report that there is nothing to aggregate;
+   - fewer than `--min-reflections` for a skill: record as skipped.
+4. Aggregate recommendations:
+   - group recurring themes by skill;
+   - separate actionable changes from speculative notes;
+   - flag contradictions instead of resolving them silently;
+   - reject repo-specific recommendations unless the target skill is intentionally repo-specific.
+5. Produce a plan with:
+   - frontmatter listing consumed reflection paths;
+   - recommendations by skill;
+   - cross-cutting recommendations;
+   - speculative notes;
+   - contradictions;
+   - archival directive for `<harness>-skill-editor`.
+
+## Plan Format
+
+```markdown
+---
+from: <harness>-skill-improvement-planner
+timestamp: <ISO>
+min_reflections: <N>
+reflections_consumed:
+  - <absolute path>
+---
+
+# Harness skill improvement plan — <ISO>
+
+## Summary
+
+## Recommendations by skill
+
+### <skill-name>
+- **Change**: <directive>
+  - **Rationale**: <evidence>
+  - **Supporting reflections**: <ids>
+
+## Cross-cutting recommendations
+
+## Speculative / low-confidence notes
+
+## Contradictions surfaced
+
+## Archival directive for <harness>-skill-editor
+```
+
+## Closeout
+
+Closeout payload shape is defined by `EmitPhaseCloseout` in `phase_loop_runtime/baml_src/emit_phase_closeout.baml` (if that path is absent in the checkout, use the operator/prompt-supplied field contract or the installed `phase_loop_runtime` package — the missing vendored BAML source is not a blocker); keep skill text focused on value selection and handoff routing, not duplicated field ceremony.
+
+In Default mode, write the plan only if the user asked for an artifact. Otherwise summarize the recommendations. Do not archive reflections; that is the editor's job.
+
+If writing self-improvement state, resolve handoff writes through `shared/phase-loop/handoff_path.py` and the repo-local handoff resolver; legacy harness handoff roots are read only for migration. Follow `<harness>-config/shared/runtime-state.md` and use Harness paths only:
+
+- Reflection: `resolve_skill_bundle_root("gemini")/<harness>-skill-improvement-planner/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `<repo>/.dev-skills/handoffs/<harness>-skill-improvement-planner/<run_id>.md`
+- Latest handoff pointer: `<repo>/.dev-skills/handoffs/<harness>-skill-improvement-planner/latest.md`
+
+Handoff frontmatter must include `from: <harness>-skill-improvement-planner`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, and `artifact:`. Update `latest.md` with the same handoff content.

phase_loop_runtime/skills_bundle/gemini-skill-improvement-planner/assets/aggregator_prompt.md

@@ -0,0 +1,79 @@
+# Aggregator prompt
+
+You are an aggregator. You will receive a set of **reflection files** produced at close-out by the planning-chain skills (`claude-phase-roadmap-builder`, `claude-plan-phase`, `claude-execute-phase`) and the meta-skills that operate on them (`claude-skill-improvement-planner`, `claude-skill-editor`). Each reflection is a short markdown document with two sections: `## What worked` and `## Improvements to SKILL.md`. Your job is to read them, find what matters, and produce a concrete plan that a downstream claude-skill-editor can apply. The meta-skills' reflections are in-scope so the planner and editor can be improved by the same loop they drive.
+
+## Inputs
+
+You will be given:
+
+- A concatenated block of reflections, grouped by skill.
+- Each reflection is tagged with its skill name and version (`v<N>`).
+- A `min_reflections` threshold (integer).
+
+## What to produce
+
+A single markdown document in the exact format described at the end of this prompt. No preamble, no chat, no apologies.
+
+## Rules
+
+1. **Identify recurring themes.** A "theme" is a concern that appears in:
+   - At least `min_reflections` distinct reflections for a given skill, OR
+   - At least 2 reflections across different skills (cross-cutting theme).
+   Single-mention items are NOT themes; record them under `## Speculative / low-confidence notes` instead.
+
+2. **Repo-agnostic output.** The reflections were instructed to be repo-agnostic. Double-check. Reject any proposed change that names:
+   - A specific project, product, or company.
+   - A specific filename or path (except where naming a file *inside this skill's own SKILL.md* that needs editing — e.g., "Step 5 of claude-plan-phase/SKILL.md" is fine; "the auth.py in the consiliency project" is not).
+   - A specific domain (finance, healthcare, etc.) unless the theme is generic enough to apply across domains.
+   If a theme looks repo-specific, either drop it or rewrite it generically.
+
+3. **Directive-only style in proposed edits.** Write each proposed SKILL.md change in imperative form. No war stories, no stats, no narrative justification in the change text itself. Use short clauses for rationale ("because X," not paragraphs).
+
+4. **Concrete edits, not directions to edit.** Bad: "Consider improving Step 5." Good: "In Step 5 of claude-plan-phase/SKILL.md, add a bullet after 'Apply the claude-task-contextualizer checklist' stating: 'Include the phase's full Exit criteria list, not just the Objective.'"
+
+5. **Cite supporting reflections.** For each theme, list the reflection versions that raised it (e.g., "claude-plan-phase v3, v5, v7"). Lets the user trace back.
+
+6. **Flag contradictions.** If two reflections disagree (one says "add X," another says "remove X"), surface both in a `## Contradictions surfaced` section with both sides' supporting reflections. Let the user decide.
+
+7. **Stay lean.** If a skill had no recurring themes, write "No recurring themes above the `--min-reflections` threshold." Do not invent work. The goal is a useful plan, not a long plan.
+
+8. **Speculative section is a valid output, not a dump.** Use it for single-mention observations that seem plausible but lack support. Each should be a single line. If it's garbage, drop it entirely.
+
+## Output format (emit exactly this structure)
+
+```markdown
+# Skill improvement plan — <ISO timestamp>
+
+## Summary
+
+<1–2 paragraphs. Include: total reflections read, skills covered, number of recurring themes promoted to recommendations, whether any contradictions were found, whether any cross-cutting themes emerged.>
+
+## Recommendations by skill
+
+### <skill-name>
+- **Change**: <specific SKILL.md edit in directive-only imperative form>
+  - **Rationale**: <one-clause reason, tied to the recurring theme>
+  - **Supporting reflections**: <skill> v3, v5, v7
+
+(Repeat per recommendation. Group all recommendations for a skill under that skill's subheading. Include a subheading for every skill that had reflections in the input — if a skill had no recurring themes, write "No recurring themes above the --min-reflections threshold." under that skill's subheading.)
+
+## Cross-cutting recommendations
+
+<Themes that affect multiple skills simultaneously. Each item names the skills it touches. Same rationale + supporting-reflections format.>
+
+(If none, write "None this pass.")
+
+## Speculative / low-confidence notes
+
+<Single-line observations from one-off reflections worth recording but not acting on. No rationale needed beyond the observation itself.>
+
+(If none, write "None this pass.")
+
+## Contradictions surfaced
+
+<Where reflections disagreed. Name both sides and their supporting reflections. Do not pick a winner — the user decides.>
+
+(If none, write "None this pass.")
+```
+
+End of prompt. Do not output anything before the `# Skill improvement plan` heading.

phase_loop_runtime/skills_bundle/gemini-task-contextualizer/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/gemini-task-contextualizer/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gemini-task-contextualizer
+description: "Harness subagent briefing guide. Use before spawning Harness explorer or worker subagents, especially for parallel research or implementation. Produces concise prompts with file paths, architecture context, ownership boundaries, expected output, and non-reversion rules."
+---
+
+# Harness Task Contextualizer
+
+Use this before any Harness subagent delegation call. Subagents need concrete context and boundaries; broad prompts waste time and increase the chance of conflicting edits.
+
+## When to Use
+
+- The user explicitly asked for agents, subagents, delegation, or parallel work.
+- You are about to delegate to a read-only or implementation agent.
+- You need several independent investigations or disjoint implementation lanes.
+
+Do not spawn a subagent only because a task is large. If the next critical-path step depends on the answer, do it locally.
+
+## Mandatory Brief Contents
+
+Every subagent prompt must include:
+
+- **Goal**: one sentence.
+- **Starting files**: exact paths or narrow globs.
+- **Architecture context**: one or two sentences explaining how the files fit.
+- **Scope boundary**: what not to touch.
+- **Ownership**: files the agent may edit, or "read-only" for explorers.
+- **Related files**: tests, configs, types, fixtures.
+- **Expected output**: answer format or changed-file report.
+- **Coordination rule**: "You are not alone in the codebase; do not revert edits made by others."
+
+## Explorer Brief
+
+Use the available read-only agent role for reconnaissance questions. Ask a specific question and require file:line evidence.
+
+```text
+Goal: Map how <feature/module> works so the main thread can plan safely.
+
+Starting files:
+- <path>
+
+Architecture context:
+<1-2 sentences>
+
+Scope:
+Read-only. Do not edit files. Do not run mutating commands.
+
+Questions:
+- <specific question>
+- <specific constraint/risk to check>
+
+Expected output:
+Return concise findings with file:line references, reusable patterns, files likely to change, and hidden coupling.
+```
+
+## Worker Brief
+
+Use the available implementation agent role only when write ownership is disjoint.
+
+```text
+Goal: Implement <bounded task>.
+
+Owned files:
+- <paths/globs the worker may edit>
+
+Read-only related files:
+- <paths/globs the worker may inspect but not modify>
+
+Architecture context:
+<1-2 sentences>
+
+Scope:
+Only edit owned files. Do not revert unrelated changes. You are not alone in the codebase; adjust to peer changes instead of overwriting them.
+
+Tasks:
+- <test task>
+- <implementation task>
+- <verification task>
+
+Expected output:
+List changed paths, tests run, failures, blockers, and any assumptions.
+```
+
+## Reference
+
+For copy-ready variants, read `references/task-templates.md`.
+
+## Runtime State
+
+This skill normally writes no reflection or handoff. If a future workflow adds self-improvement state, follow `<harness>-config/shared/runtime-state.md` and use Harness paths only:
+
+- Reflection: `resolve_skill_bundle_root("gemini")/<harness>-task-contextualizer/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `resolve_handoff_root(repo)/<harness>-task-contextualizer/<run_id>.md`
+- Latest handoff pointer: `resolve_handoff_root(repo)/<harness>-task-contextualizer/latest.md`
+
+Handoff frontmatter must include `from: <harness>-task-contextualizer`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, and `artifact:`. Update `latest.md` with the same handoff content.
+
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.

phase_loop_runtime/skills_bundle/gemini-task-contextualizer/references/task-templates.md

@@ -0,0 +1,103 @@
+# Task Prompt Templates
+
+Copy and fill in the placeholders (in ALL_CAPS) for each task type.
+
+## Bug Fix Template
+
+```
+Fix DESCRIPTION in FILE_PATH.
+
+Error: "ERROR_MESSAGE" at line LINE_NUMBER.
+
+Related files:
+- TYPE_DEFS_PATH — type definitions used by this file
+- BASE_CLASS_PATH — parent class or service it extends
+- TEST_FILE_PATH — existing tests for this module
+- CONFIG_PATH — relevant config (tsconfig.json, etc.)
+
+Architecture: BRIEF_DESCRIPTION of how this module fits into the system.
+
+Scope: Only modify ALLOWED_FILES. Do not change EXCLUDED_FILES.
+Expected output: Modified files that resolve the type error.
+```
+
+## New Feature Template
+
+```
+Implement FEATURE_DESCRIPTION.
+
+Example to follow: EXAMPLE_FILE_PATH (shows the pattern for similar features)
+Create new files in: TARGET_DIRECTORY
+Naming convention: NAMING_PATTERN (e.g., camelCase, kebab-case)
+
+Related files:
+- ROUTER_OR_INDEX_PATH — where to register/export the new feature
+- TYPE_DEFS_PATH — existing types to reuse or extend
+- TEST_PATTERN_PATH — example test file showing test conventions
+
+Architecture: BRIEF_DESCRIPTION of how new features are structured in this project.
+
+Scope: Create new files in TARGET_DIRECTORY. Register in ROUTER_FILE. Do not modify EXCLUDED_FILES.
+Expected output: New files implementing the feature + registration in index/router.
+```
+
+## Explore / Research Template
+
+```
+Research QUESTION about this codebase.
+
+Start from these files:
+- FILE_1 — BRIEF_DESCRIPTION
+- FILE_2 — BRIEF_DESCRIPTION
+- FILE_3 — BRIEF_DESCRIPTION
+
+What I already know:
+- KNOWN_FACT_1
+- KNOWN_FACT_2
+
+Specific questions to answer:
+1. QUESTION_1
+2. QUESTION_2
+3. QUESTION_3
+
+Expected output: A summary answering each question with file paths and line references.
+```
+
+## Refactor Template
+
+```
+Refactor DESCRIPTION across these files:
+- FILE_1
+- FILE_2
+- FILE_3
+
+Current pattern: CURRENT_PATTERN_DESCRIPTION
+Target pattern: TARGET_PATTERN_DESCRIPTION
+
+Constraints:
+- CONSTRAINT_1 (e.g., "maintain backward compatibility with existing API")
+- CONSTRAINT_2 (e.g., "do not change test files, only source files")
+
+Type definitions: TYPE_DEFS_PATH
+Test file: TEST_FILE_PATH (run after refactor to verify)
+
+Expected output: Modified files following the target pattern. All existing tests must still pass.
+```
+
+## Multi-File Edit Template
+
+```
+Make the following related changes:
+
+1. In FILE_1: CHANGE_DESCRIPTION_1
+2. In FILE_2: CHANGE_DESCRIPTION_2
+3. In FILE_3: CHANGE_DESCRIPTION_3
+
+These changes are related because: RELATIONSHIP_DESCRIPTION
+
+Type definitions: TYPE_DEFS_PATH
+Config: CONFIG_PATH
+
+Verification: After all edits, run VERIFICATION_COMMAND to confirm no errors.
+Scope: Only modify the listed files.
+```

phase_loop_runtime/skills_bundle/opencode-advisor-board/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.