ai-driven-dev-v2 0.1.0a1__tar.gz

ai_driven_dev_v2-0.1.0a1/.agents/skills/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+This directory holds reusable development workflows for coding agents.
+
+## Rules
+
+- Keep each skill focused on one repeatable workflow.
+- Prefer repo-specific instructions over generic advice.
+- Update skills when the roadmap, architecture, or contributor workflow changes.

ai_driven_dev_v2-0.1.0a1/.agents/skills/aidd-eval/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: aidd-eval
+description: Run harness and eval scenarios for ai_driven_dev_v2, validate document-first stage outputs, preserve runtime logs, analyze failures, and produce durable audit artifacts for deterministic and manual-live lanes.
+---
+
+# aidd-eval
+
+## Use when
+
+- You need to run a harness scenario against one of the maintained runtimes.
+- You need to validate stage outputs against Markdown document contracts.
+- You need to check self-repair behavior after validator failures.
+- You need to capture runtime logs, normalized events, and log-analysis artifacts.
+- You need to audit generated artifacts and generated code after execution.
+
+For **local live-run operator guidance**, prefer `live-e2e`.
+Use `aidd-eval` when the main task is generic eval execution, artifact analysis,
+validation discipline, grading, and failure classification across deterministic
+and manual-live lanes.
+
+## Required reading
+
+1. `docs/architecture/eval-harness-integration.md`
+2. `docs/architecture/document-contracts.md`
+3. `docs/architecture/adapter-protocol.md`
+4. `docs/architecture/runtime-matrix.md`
+5. `docs/e2e/scenario-matrix.md`
+6. `docs/e2e/live-quality-rubric.md` for live scenarios
+7. the selected scenario under `harness/scenarios/`
+8. `.agents/skills/aidd-eval/references/e2e-flow-audit.md`
+
+## Lane split
+
+- Deterministic scenarios use `feature_source.mode: fixture-seed` and may run in `ci` or `manual`.
+- Live scenarios use `feature_source.mode: curated-issue-pool`, must live under `harness/scenarios/live/`, and are manual-only.
+
+## Hard rules
+
+1. Never hand-edit runtime-generated stage output documents during an eval run.
+2. Always probe the adapter first.
+3. Always preserve raw runtime logs.
+4. Always validate output Markdown documents against their contracts.
+5. Always allow the stage self-repair loop to run if the scenario expects repairable failures.
+6. Always keep question/answer events as durable artifacts.
+7. Always generate log-analysis output.
+8. Keep infrastructure failures separate from model or document failures.
+9. For live scenarios, preserve install evidence, issue-selection evidence, and quality artifacts.
+10. Never mutate roadmap or backlog files as part of live quality auditing.
+
+## Default procedure
+
+1. Load the scenario and confirm the requested runtime is allowed.
+2. Probe the adapter and record capability information.
+3. Prepare or reset the fixture workspace or target repository.
+4. Run the requested stage or flow through the harness.
+   For live scenarios, select the first curated issue, install the artifact under test first, and run AIDD from the target repository root.
+5. Capture:
+   - install transcript and artifact identity for live scenarios,
+   - issue-selection evidence for live scenarios,
+   - fixture-seed metadata for deterministic scenarios,
+   - raw runtime logs,
+   - structured runtime logs when available,
+   - normalized events,
+   - question/answer events,
+   - validator outcomes,
+   - repair attempts.
+6. Validate all required output documents.
+7. Run live quality commands and score artifact/code quality when the scenario requires it.
+8. Run graders.
+9. Run log analysis.
+10. Write the final audit artifacts.
+11. Report the final execution verdict and quality conclusion explicitly.
+
+## Canonical output locations
+
+- `.aidd/reports/evals/<run_id>/runtime.log`
+- `.aidd/reports/evals/<run_id>/runtime.jsonl` when supported
+- `.aidd/reports/evals/<run_id>/events.jsonl` when supported
+- `.aidd/reports/evals/<run_id>/install-transcript.json`
+- `.aidd/reports/evals/<run_id>/issue-selection.json`
+- `.aidd/reports/evals/<run_id>/validator-report.md`
+- `.aidd/reports/evals/<run_id>/repair-history.md`
+- `.aidd/reports/evals/<run_id>/log-analysis.md`
+- `.aidd/reports/evals/<run_id>/grader.json`
+- `.aidd/reports/evals/<run_id>/verdict.md`
+- `.aidd/reports/evals/<run_id>/quality-report.md`
+- `.aidd/reports/evals/<run_id>/quality-transcript.json`
+
+## Execution verdict taxonomy
+
+For eval harness runs, preserve the stable execution verdict taxonomy:
+
+- `pass`
+- `fail`
+- `blocked`
+- `infra-fail`
+
+Quality remains additive and must be reported separately as:
+
+- `pass`
+- `warn`
+- `fail`
+- `none`
+
+## Example command shape
+
+```bash
+aidd eval run harness/scenarios/smoke/plan-stagepack-smoke.yaml --runtime opencode
+```

ai_driven_dev_v2-0.1.0a1/.agents/skills/aidd-eval/references/e2e-flow-audit.md

@@ -0,0 +1,20 @@
+# E2E Flow Audit Reference
+
+Use this reference when writing or reviewing eval audit output.
+
+## Minimum audit sections
+
+- scenario summary
+- runtime and adapter used
+- repository pin or fixture identity
+- stage or flow scope
+- validator outcomes
+- repair history
+- user questions and answers
+- log analysis
+- final verdict
+- follow-up actions
+
+## First-failure principle
+
+The audit should name the earliest decisive failure signal, not only the last visible symptom.

ai_driven_dev_v2-0.1.0a1/.agents/skills/backlog-ops/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: backlog-ops
+description: Select, split, create, promote, and close roadmap tasks while keeping `roadmap.md` and `backlog.md` synchronized.
+---
+
+# backlog-ops
+
+Use this skill whenever you touch `docs/backlog/roadmap.md` or `docs/backlog/backlog.md`.
+
+## Planning sources
+
+Read these in order:
+
+1. `docs/backlog/backlog.md`
+2. `docs/backlog/roadmap.md`
+3. `docs/product/user-stories.md`
+4. the nearest `AGENTS.md` for the code or docs area you will touch
+
+## Canonical rules
+
+- `docs/backlog/roadmap.md` is the canonical hierarchy.
+- `docs/backlog/backlog.md` is the short actionable queue.
+- Work must always fit `wave -> epic -> slice -> local task`.
+- A local task must be reviewable without another decomposition pass.
+- Update `roadmap.md` first, then update `backlog.md`.
+
+## Taking a task
+
+1. Read the `Next` section in `docs/backlog/backlog.md`.
+2. Pick the first local task marked `next` unless it is blocked by a documented dependency.
+3. Read the full parent slice in `docs/backlog/roadmap.md`.
+4. Read the linked user stories and architecture notes for the touched area.
+5. Restate the task in your own words before coding:
+   - exact output;
+   - touched module or file family;
+   - main verification signal;
+   - dependencies that must already exist.
+
+Do not start coding if you cannot name all four items above.
+
+## Local-task quality bar
+
+A valid local task has:
+
+- one clear output artifact or code change;
+- one dominant touched area;
+- one main verification path;
+- explicit upstream dependencies;
+- wording that starts with a concrete verb.
+
+A task must be split immediately if any of these are true:
+
+- it touches more than one subsystem family, such as core + adapter + harness;
+- it mixes contract design and broad downstream rollout;
+- it has multiple independent outputs that could be reviewed separately;
+- it has no single pass/fail check;
+- it would require another planning discussion during implementation.
+
+## Local-task template
+
+When you create or rewrite a local task, make it fit this template:
+
+- **ID** — `W<wave>-E<epic>-S<slice>-T<task>`
+- **Action** — starts with a verb such as `Define`, `Implement`, `Write`, `Add`, `Expose`, `Render`
+- **Output** — name the artifact, module, or command that changes
+- **Scope** — keep one dominant touched area
+- **Verification** — state how the task will be proven done
+
+Example:
+
+- `W4-E1-S2-T4` Implement stdout and stderr streaming to the CLI while the subprocess runs.
+
+That is good because it names the subsystem, the behavior, and the direct review target.
+
+## Creating a new local task
+
+Create a new local task when the discovered work:
+
+- clearly belongs to an existing slice goal;
+- can be reviewed independently;
+- has one dominant output and one verification signal.
+
+Workflow:
+
+1. Add the new task under the correct slice in `roadmap.md`.
+2. Keep the existing slice goal unless the outcome changed materially.
+3. Preserve the current task id for the first surviving piece whenever you split active work.
+4. Append new task ids after the preserved one.
+5. Update slice dependencies, touched areas, or exit evidence if the new task changes them.
+6. Pull the new task into `backlog.md` only if it is immediately actionable.
+
+## Creating a new slice
+
+Create a new slice only when the discovered work is a different meaningful outcome, for example:
+
+- a new stage contract;
+- a new adapter capability;
+- a separate harness scenario lane;
+- a separate operator command surface.
+
+Do **not** create a new slice just because the current task is too large. Split into more local tasks first.
+
+A good slice has:
+
+- one outcome sentence in the goal;
+- explicit primary outputs;
+- touched areas;
+- dependencies;
+- exit evidence.
+
+## Creating a new epic
+
+Create a new epic only when the theme changes enough that the work is no longer one coherent track, for example:
+
+- moving from validators into runtime adapters;
+- moving from harness execution into release operations.
+
+If the work still serves the same theme, keep it inside the current epic.
+
+## Splitting workflow
+
+When a task or slice is too large:
+
+1. Identify the dominant outputs hidden inside the oversized work.
+2. Keep the current id for the first smallest reviewable piece.
+3. Create follow-up task ids for the remaining pieces.
+4. Reword each new task so it names the output directly.
+5. Check whether the parent slice still has one clear outcome.
+6. Update `backlog.md` so only the immediate next pieces stay in `Next`.
+
+## Dependency rules
+
+- Dependencies belong on the slice, not repeated on every task unless there is an exception.
+- A task may assume slice dependencies are already satisfied.
+- If one task inside a slice depends on another task in the same slice, order the tasks so the dependency is obvious.
+- If discovered work depends on another wave or epic, add that dependency explicitly to the slice.
+
+## Promotion rules for `backlog.md`
+
+Use `backlog.md` as a queue, not as a second roadmap.
+
+- `Next` contains immediately actionable local tasks only.
+- `Soon` contains tasks that are likely next but still depend on `Next`.
+- `Parking lot` holds later-wave tasks that should stay visible.
+- Never place a slice or epic in `backlog.md`; only local task ids belong there.
+- Never add a task to `backlog.md` unless it already exists in `roadmap.md`.
+
+## Closing work
+
+After implementation:
+
+1. Mark the task or slice state in `roadmap.md` if it materially changed.
+2. Remove completed tasks from `backlog.md`.
+3. Add follow-up tasks to `roadmap.md` before mentioning them elsewhere.
+4. Delete stale wording instead of leaving historical clutter.
+5. Make sure the new plan still reads cleanly from wave to task.
+
+## Sync checklist
+
+Any change to planning files should leave all of these true:
+
+- every backlog id exists in the roadmap;
+- every `Next` item is a local task, not a slice;
+- no task wording is ambiguous or multi-output;
+- parent slices still have one meaningful outcome;
+- dependencies and exit evidence still match the work.
+
+## Output when reporting planning work
+
+When you finish a planning update, report:
+
+- the local task you took or the slice you decomposed;
+- new or changed task ids;
+- any new dependencies you added;
+- which items moved into `Next`, `Soon`, or `Parking lot`.

ai_driven_dev_v2-0.1.0a1/.agents/skills/live-e2e/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: live-e2e
+description: Run or prepare a manual full-flow live end-to-end scenario against a public GitHub repository with repository pinning, curated issue selection, quality checks, and full log capture.
+---
+
+# live-e2e
+
+## Use when
+
+- You need to execute or author a scenario from `docs/e2e/live-e2e-catalog.md`.
+- You need to compare live provider behavior on a real repository.
+- You need to prove the installed operator flow from `idea` through `qa` as a manual external audit.
+- You need a **local source-checkout runbook** for manual live E2E, not just the abstract eval contract.
+
+## This skill vs `aidd-eval`
+
+- Use `live-e2e` when the main question is: "How do I make a local live run work from this checkout?"
+- Use `aidd-eval` when the main question is: "How do I audit artifacts, validation, grading, and failure classification across eval lanes?"
+- `live-e2e` is the primary local operator playbook for live runs.
+- `aidd-eval` remains the generic eval and artifact-analysis skill.
+
+## Read first
+
+This skill is intended to be sufficient for a prepared local run, but these files
+remain the authoritative deeper references:
+
+1. `docs/e2e/live-e2e-catalog.md`
+2. `docs/e2e/scenario-matrix.md`
+3. `docs/operator-handbook.md`
+4. the selected manifest in `harness/scenarios/live/`
+
+## What must already exist
+
+If you only use this skill from the current project, the run still needs these
+external prerequisites to already be true:
+
+- you are in a prepared local **source checkout** of this repository;
+- `uv sync --extra dev` has already completed successfully;
+- the selected live manifest exists under `harness/scenarios/live/`;
+- the requested runtime appears in the scenario's `runtime_targets`;
+- the machine has network access to clone the pinned public target repository;
+- the selected provider is already authenticated and runnable on the machine;
+- the selected provider CLI is available, or you have an AIDD-compatible wrapper
+  command override for the chosen live runtime.
+
+This skill does **not** provision runtime authentication, wrapper scripts, or provider setup for you.
+
+## Runtime-command contract
+
+For local manual live runs, `claude-code`, `codex`, and `opencode` use native provider CLI
+commands by default. You may provide a runtime-command override through
+environment variables when you need a custom wrapper:
+
+- `AIDD_EVAL_CLAUDE_CODE_COMMAND` for `claude-code`
+- `AIDD_EVAL_CODEX_COMMAND` for `codex`
+- `AIDD_EVAL_OPENCODE_COMMAND` for `opencode`
+
+When set, the value must point to an **AIDD-compatible wrapper command**:
+
+- it must be invokable from the shell on the current machine;
+- it must accept the adapter flags AIDD passes for that runtime;
+- it may be a wrapper around the upstream provider CLI rather than the raw provider binary;
+- `aidd doctor` distinguishes provider probe readiness from execution command readiness.
+
+There are no repo-local wrapper templates in this wave. The operator must already
+have provider auth and a working provider CLI or wrapper execution surface.
+
+## Local preflight checklist
+
+Before the live run, confirm all of these:
+
+1. `uv sync --extra dev`
+2. `uv run aidd doctor`
+3. the selected scenario is under `harness/scenarios/live/`
+4. the scenario has `automation_lane: manual`
+5. the scenario forces `stage_scope: idea -> qa`
+6. the runtime you plan to use appears in `runtime_targets`
+7. `uv run aidd eval doctor <manifest> --runtime <runtime>` reports execution readiness
+8. any wrapper env var you choose to set resolves on the machine and uses the expected auth state
+
+Recommended local preflight:
+
+```bash
+uv sync --extra dev
+uv run aidd doctor
+uv run aidd eval doctor harness/scenarios/live/sqlite-utils-detect-types-header-only.yaml --runtime codex
+```
+
+Optional wrapper override:
+
+```bash
+export AIDD_EVAL_CODEX_COMMAND='<aidd-compatible codex wrapper>'
+export AIDD_EVAL_OPENCODE_COMMAND='<aidd-compatible opencode wrapper>'
+export AIDD_EVAL_CLAUDE_CODE_COMMAND='<aidd-compatible claude-code wrapper>'
+```
+
+## Canonical local launch
+
+The primary execution path for this skill is a local run from the AIDD source checkout:
+
+```bash
+uv run aidd eval run harness/scenarios/live/sqlite-utils-detect-types-header-only.yaml --runtime codex
+```
+
+or:
+
+```bash
+uv run aidd eval run harness/scenarios/live/sqlite-utils-detect-types-header-only.yaml --runtime opencode
+```
+
+or:
+
+```bash
+uv run aidd eval run harness/scenarios/live/sqlite-utils-detect-types-header-only.yaml --runtime claude-code
+```
+
+The GitHub `manual-live-e2e` workflow is a secondary alternate entrypoint, not the primary flow described by this skill.
+
+## What the harness will do
+
+During a successful local live run, the harness will:
+
+1. load the selected scenario and validate the live-lane contract;
+2. resolve and record the pinned target repository commit;
+3. prepare a clean working copy of the target repository;
+4. select the **first listed issue** from the curated issue pool;
+5. write issue-selection evidence to the eval bundle and target-repo context;
+6. seed `.aidd/` inside the target repository;
+7. write a live `aidd.example.toml` with the runtime command and execution mode for the chosen provider;
+8. build and install the AIDD artifact under test with `uv tool`;
+9. run installed `aidd` from the target repository root with explicit workflow bounds `idea -> qa`;
+10. run setup, verify, and quality commands and write the final audit artifacts.
+
+## Validations and blockers
+
+The live run can be rejected or downgraded at several layers:
+
+- manifest validation rejects non-live scenarios, non-manual live scenarios, missing `quality`, invalid `runtime_targets`, or any live scenario that is not bounded to `idea -> qa`;
+- runtime admission rejects a requested runtime that is not declared in `runtime_targets`;
+- stage execution stays bounded to `idea -> qa`;
+- stage outputs must validate against Markdown document contracts;
+- repair loops are allowed to run when validation failures are repairable;
+- interview scenarios block when required answers are missing;
+- repo-local `verify.commands` must pass;
+- repo-local `quality.commands` must pass for a clean quality result;
+- execution `pass` is impossible if any stage in scope is missing required validated artifacts.
+
+Live execution verdicts remain:
+
+- `pass`
+- `fail`
+- `blocked`
+- `infra-fail`
+
+Quality is additive:
+
+- `pass`
+- `warn`
+- `fail`
+- `none`
+
+## Output locations and success criteria
+
+The canonical eval bundle for a local live run lives under:
+
+- `.aidd/reports/evals/<run_id>/`
+
+Expected live artifacts include:
+
+- `issue-selection.json`
+- `install-transcript.json`
+- `runtime.log`
+- `validator-report.md`
+- `repair-history.md`
+- `log-analysis.md`
+- `grader.json`
+- `verdict.md`
+- `quality-report.md`
+- `quality-transcript.json`
+
+A live run is only "clean" when execution evidence exists, verification output is present, and the bundle includes `quality-report.md` plus `quality-transcript.json`.
+
+## First triage for common failures
+
+- Provider executable missing: install/login to the selected provider CLI, or export `AIDD_EVAL_CODEX_COMMAND` / `AIDD_EVAL_OPENCODE_COMMAND` for a wrapper.
+- Runtime launches but immediately fails in native mode: inspect provider auth, model selection, and sandbox permissions.
+- Runtime launches but immediately fails in `adapter-flags` mode: the configured command is probably not an AIDD-compatible wrapper command.
+- `unsupported-runtime`: the runtime is not declared in the scenario's `runtime_targets`.
+- `blocked`: inspect `questions.md` / `answers.md` expectations for interview scenarios.
+- `fail` after run success: inspect `verify-transcript.json`, `quality-transcript.json`, and the stage-local validator reports.
+- Missing clean execution despite zero exit codes: inspect `verdict.md` and `grader.json` for pass-guard failures caused by missing `stage-result.md` or `validator-report.md`.
+
+## Procedure
+
+1. Confirm the selected scenario is in `harness/scenarios/live/`, has `automation_lane: manual`, and declares the requested runtime in `runtime_targets`.
+2. Run the local preflight checks from this skill, including `aidd eval doctor`.
+3. Export a wrapper env var only when you intentionally want `adapter-flags` mode.
+4. Launch `uv run aidd eval run <manifest> --runtime <runtime>`.
+5. Preserve the resulting bundle and inspect `verdict.md`, `grader.json`, `quality-report.md`, and transcripts before judging the run.
+6. If the setup, provider coverage, size classification, quality recipe, or verification recipe had to change, update the scenario manifest, matrix doc, and catalog after the run as separate follow-up work.
+
+## Hard rules
+
+- Never treat live E2E as a CI or release lane.
+- Never assume this skill provisions runtime auth, wrappers, or provider setup.
+- Never dispatch the manual GitHub workflow without provider execution readiness for the selected runtime.
+- Never run a live scenario without storing the resolved repo pin.
+- Never run a live scenario without storing the selected issue snapshot.
+- Never treat a live scenario as canonical unless it executes `idea -> qa`.
+- Never treat a live scenario as passed without install evidence and verification output.
+- Never treat a live scenario as clean without `quality-report.md` and `quality-transcript.json`.
+- Preserve all runtime logs.
+- Keep `.aidd` rooted inside the target repository for installed live runs.

ai_driven_dev_v2-0.1.0a1/.agents/skills/project-navigation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: project-navigation
+description: Map a task to the right AIDD docs, modules, checks, and scenario assets before making changes.
+---
+
+# project-navigation
+
+## Use when
+
+- You are starting work in this repository.
+- You do not know which module or document set owns the change.
+
+## Procedure
+
+1. Read `AGENTS.md` and `docs/product/user-stories.md`.
+2. Classify the task as one of: docs, contracts, core, adapters, validators, harness, evals, or CLI.
+3. Read the nearest nested `AGENTS.md` for that area.
+4. Identify the expected checks and scenario updates.
+5. Name the primary files that should change before editing.
+
+## Output
+
+Produce a short work map: owning area, likely files, checks to run, and whether a scenario update is required.

ai_driven_dev_v2-0.1.0a1/.agents/skills/runtime-log-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: runtime-log-triage
+description: Analyze runtime and adapter logs to identify the first decisive failure signal and classify it correctly.
+---
+
+# runtime-log-triage
+
+## Use when
+
+- A scenario or stage run failed.
+- You need to separate document, model, adapter, auth, permission, timeout, or environment failures.
+
+## Procedure
+
+1. Read `runtime.log`, `events.jsonl`, and `validator-report.md`.
+2. Identify the earliest decisive signal.
+3. Separate runtime startup failures from document validation failures.
+4. Check whether a user question should have blocked the run.
+5. Write a short `log-analysis.md` that names the first cause, not just the final symptom.
+
+## Output
+
+Return the likely failure class and the evidence chain that supports it.

ai_driven_dev_v2-0.1.0a1/.agents/skills/stage-contract-change/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: stage-contract-change
+description: Make a safe change to a stage or document contract by updating contracts, validators, prompts, and scenarios together.
+---
+
+# stage-contract-change
+
+## Use when
+
+- You are changing a stage input or output document.
+- You are changing validation rules or repair behavior.
+
+## Procedure
+
+1. Update the relevant contract doc first.
+2. Update validator logic or validator plan.
+3. Update prompt files or prompt-pack references if the runtime needs new instructions.
+4. Update stage-result expectations and repair behavior if needed.
+5. Add or update at least one smoke or eval scenario.
+
+## Hard rules
+
+- Never change a stage contract in code only.
+- Never widen a stage output implicitly.
+- Keep Markdown as the canonical runtime-authored output form.

ai_driven_dev_v2-0.1.0a1/.agents/skills/task-slicing/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: task-slicing
+description: Turn a coarse roadmap item into reviewable local tasks with one output, one dominant touched area, and one main verification signal.
+---
+
+# task-slicing
+
+Use this skill when a roadmap task or slice still feels too vague to implement directly.
+
+## What "good slicing" means
+
+A strong local task has:
+
+- one concrete output;
+- one dominant touched area;
+- one main verification path;
+- wording that starts with a verb;
+- a scope small enough for one focused review.
+
+## Smells that mean "split again"
+
+Split again if the proposed task:
+
+- touches core plus adapter plus harness together;
+- mixes contract design with broad rollout;
+- produces multiple independent artifacts;
+- needs different verification strategies at once;
+- still contains words like `implement stage`, `finish adapter`, `wire everything`, or `support all cases`.
+
+## Split order
+
+Always try this order:
+
+1. split into more local tasks in the same slice;
+2. create a new slice only if there is a different meaningful outcome;
+3. create a new epic only if the theme changes.
+
+## Recipe
+
+1. Name the parent outcome in one sentence.
+2. List the concrete outputs hidden inside it.
+3. Group outputs by touched area.
+4. Turn each group into a verb-led task.
+5. Check that each task has one main verification signal.
+6. Reorder tasks so dependencies read top to bottom.
+
+## Examples
+
+Too broad:
+
+- `Implement the Claude Code adapter.`
+
+Better:
+
+- `Implement Claude Code command assembly from stage brief, workspace path, and prompt-pack inputs.`
+- `Stream raw Claude Code stdout and stderr to the operator CLI in real time.`
+- `Persist a full runtime.log that matches the raw streamed output as closely as possible.`
+- `Detect Claude Code question or pause events when the runtime exposes them.`
+
+Too broad:
+
+- `Finalize the implement stage.`
+
+Better:
+
+- `Define the required implement inputs, including task selection, repository state, and allowed write scope.`
+- `Define the required implement outputs, including change summary, touched files, and verification notes.`
+- `Define validator rules for missing diffs, unverifiable claims, and incomplete execution summaries.`
+- `Create the implement prompt-pack scaffold with explicit edit and verification guidance.`
+
+## Output
+
+When you use this skill, report:
+
+- the parent item you decomposed;
+- the new task ids;
+- why the old task was too broad;
+- the output and verification signal for each new task.