From ywc-agent-toolkit
Drives a spec with Critical/Warning findings through repeated ywc-plan --update-spec and ywc-spec-validate until DONE, then hands off to the user for task generation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ywc-agent-toolkit:ywc-spec-readyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Announce at start:** "I'm using the ywc-spec-ready skill to drive the spec to ywc-spec-validate DONE by looping ywc-plan and ywc-spec-validate, then stop at the ywc-task-generator handoff."
Announce at start: "I'm using the ywc-spec-ready skill to drive the spec to ywc-spec-validate DONE by looping ywc-plan and ywc-spec-validate, then stop at the ywc-task-generator handoff."
This skill takes a spec file that ywc-plan already produced and recursively converges it to a task-ready state. Each iteration runs ywc-spec-validate; on DONE_WITH_CONCERNS it calls ywc-plan --update-spec with a fix-priority summary and re-validates. The loop ends on DONE (handoff printed, stop — never auto-invoke ywc-task-generator), on the iteration cap, or on a convergence-stall guard.
spec ──> [ywc-spec-validate ──DONE_WITH_CONCERNS──> ywc-plan --update-spec]* ──DONE──> handoff
It is not the full pipeline: ywc-agentic orchestrates goal→code with an impl-review loop and runs ywc-spec-validate only once. This skill fills the missing inner loop — multi-iteration spec convergence — that neither ywc-agentic Step 3 nor ywc-spec-validate's single-retry Programmatic Consumer Policy provides.
When tempted to bypass a rule, check this table first:
| Excuse | Reality |
|---|---|
| "spec-validate returned DONE_WITH_CONCERNS but the findings look trivial — just go to task-generator" | Only DONE ends the loop with a handoff. DONE_WITH_CONCERNS always triggers a re-plan iteration (or a guard stop). There is no "trivial" exception — task-generator consumes DONE specs only. |
"The loop is not converging — bump --max-iterations" | --max-iterations is a user-defined safety valve, never raised autonomously. At the cap, emit the partial report and stop. Surfacing non-convergence is the correct outcome. |
"DONE reached — chain straight into ywc-task-generator to finish the job" | Never invoke ywc-task-generator. This skill is a converger, not an executor. It prints the handoff and stops; the user decides when to decompose. |
| "User gave a goal, not a spec — I'll run ywc-plan from scratch first" | This skill takes --spec <path> only (an existing spec). Goal→spec is ywc-plan's job; goal→code is ywc-agentic's. If --spec is absent, return NEEDS_CONTEXT. |
| "Critical count went up after a re-plan — stop immediately, it's diverging" | A re-plan amendment may legitimately open new surface (one transient increase). Stop only after two consecutive non-decreasing iterations, or an identical finding signature / amendment scope (see references/convergence.md). |
| "advisor budget is annoying — let spec-validate escalate freely every iteration" | Track --max-advisor-calls across iterations and pass only the remaining budget. Unbounded per-iteration escalation is the cost blow-up this skill exists to prevent. |
| "spec-validate returned SOCRATIC — re-plan from its questions" | SOCRATIC is not a gate verdict. Detect it and stop as misuse (stop-misuse); never feed it into the convergence loop. |
Violating the letter of these rules is violating the spirit. The loop is trustworthy only because its termination conditions (DONE, cap, stall) and its no-auto-decompose boundary are non-negotiable.
| Parameter | Format | Default | Description |
|---|---|---|---|
--spec | --spec <path> | (required) | Existing spec file (produced by ywc-plan) to converge. Absent/missing → NEEDS_CONTEXT. |
--max-iterations | --max-iterations <n> | 5 | Validation loop ceiling. User-defined safety valve — never raised autonomously. <= 0 → NEEDS_CONTEXT. |
--max-advisor-calls | --max-advisor-calls <n> | 4 | Total Opus advisor budget across all iterations (cost guard). |
--log | --log <path> | <spec-dir>/<slug>.spec-ready-log.md | Append-only loop log. <slug> = --spec filename stem. |
--dry-run | flag | — | Print the planned command sequence only; invoke no sibling skill, write no amendment or log. |
--lang | --lang <lang> | auto | Report/handoff language; inferred from CLAUDE.md when auto. |
--focus | --focus <area> | — | Forwarded to ywc-spec-validate when set. |
--format | --format <markdown|html> | markdown | Forwarded to ywc-spec-validate when set. |
--terse | flag | — | Minimal output — phase headers and the final report only. |
Cost-guard note:
--max-advisor-callsis the cumulative Opus budget across all iterations. This skill tracks spend from eachywc-spec-validatereport header (Phase 2 advisor calls used: X of N) and injects the remaining budget into the next iteration viaywc-spec-validate --advisor-budget <min(2, global_remaining)>. When the budget reaches 0 the loop continues with escalation off (--advisor-budget 0) and only stops if a mandatory ambiguous Critical remains.
--spec is absent, or the file does not exist, stop with NEEDS_CONTEXT (report the missing path). Do not create a spec.--max-iterations <= 0, stop with NEEDS_CONTEXT.<slug> = --spec filename stem (drop directory and .md, lowercase-hyphenate). Resolve the log path (--log wins when given).--dry-run, print the planned sequence (ywc-spec-validate --spec <path> → conditional ywc-plan --update-spec <path> --failure-context "…", up to --max-iterations) and stop. Write nothing.Initialize iteration = 1, global_remaining = --max-advisor-calls, and an empty signature history. Repeat:
iter_cap = min(2, global_remaining) (the per-iteration advisor ceiling), then run ywc-spec-validate --spec <path> --advisor-budget <iter_cap> (forward --focus / --format when set). Parse the report: Critical/Warning/Suggestion counts, finding signatures, and the advisor-usage line (Phase 2 advisor calls used: X of N); subtract X from global_remaining (subtract the full iter_cap when the line is unparseable). When global_remaining == 0, pass --advisor-budget 0 (escalation off); if a mandatory ambiguous Critical then remains, stop with DONE_WITH_CONCERNS / stop-advisor-exhausted.DONE → Step 4. BLOCKED/NEEDS_CONTEXT/SOCRATIC/unparseable → Step 3 (hard stop). DONE_WITH_CONCERNS → continue.DONE_WITH_CONCERNS and the matching action (stop-non-converging). If iteration >= --max-iterations, stop with DONE_WITH_CONCERNS / stop-cap.ywc-plan --update-spec <path> --failure-context "<summary>". If this call itself fails (file vanished, non-zero, error), stop with BLOCKED / stop-replan-failed.iteration += 1, loop.BLOCKED / NEEDS_CONTEXT from ywc-spec-validate, an unparseable report, or SOCRATIC (misuse) end the loop immediately without a re-plan. Log the iteration (stop-blocked / stop-context / stop-misuse), surface the reason, and emit the Completion Report.
On DONE, print the handoff message verbatim and stop. Do not invoke ywc-task-generator.
✅ Spec ready: <path> (DONE after N/<cap> iterations, <X> advisor calls)
Next:
1. /ywc-task-generator <path>
2. (after tasks generated) /ywc-sequential-executor or /ywc-parallel-executor
Emit one report: spec path, iterations run / cap, final Completion Status, remaining Critical count (if any), cumulative advisor calls used, log path, and (on DONE) the handoff. The final line is one Completion Status — nothing follows it.
| spec-validate Status | ywc-spec-ready action |
|---|---|
DONE | End loop → print handoff → stop (Step 4) |
DONE_WITH_CONCERNS | Guards pass → fix-priority summary → ywc-plan --update-spec → next iteration; guard fires → stop (Step 2.3) |
BLOCKED | Stop immediately, report blocker (Step 3) |
NEEDS_CONTEXT | Stop immediately, report missing context (Step 3) |
SOCRATIC | Misuse — stop, report (stop-misuse) |
| status absent / unparseable | Implicit BLOCKED, surface raw excerpt |
| Status | When |
|---|---|
DONE | Loop converged to ywc-spec-validate = DONE |
DONE_WITH_CONCERNS | Cap reached / convergence stall / advisor budget exhausted, Critical remaining |
BLOCKED | spec-validate BLOCKED, unparseable report, or ywc-plan --update-spec failure |
NEEDS_CONTEXT | --spec missing/absent, bad argument, or spec-validate NEEDS_CONTEXT |
Before treating a run as complete, verify:
--spec path was provided and the file existed (else NEEDS_CONTEXT).ywc-spec-validate exactly once and routed strictly on its Completion Status.DONE_WITH_CONCERNS (that passed guards) produced exactly one ywc-plan --update-spec call.DONE, the iteration cap, a stall guard, or a hard stop — never an autonomous --max-iterations increase.ywc-task-generator was not invoked — the run ended at the handoff.--dry-run).ywc-task-generator anyway. The handoff IS the stop; the user owns the decompose decision.ywc-plan --update-spec (append amendments); never regenerate, which loses validated sections.ywc-plan (produces the initial spec this skill converges).ywc-spec-validate (per-iteration gate), ywc-plan --update-spec (per-iteration amendment).ywc-task-generator, then ywc-sequential-executor / ywc-parallel-executor.ywc-agentic Step 3 (Medium/Large) replaces its single ywc-spec-validate call with a delegation to this skill — the two skills' --max-iterations are independent ceilings (outer impl-review loop vs inner spec-convergence loop). Wiring lands in the integration task.npx claudepluginhub yongwoon/ywc-agent-toolkitGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.