Ywc Agentic

ywc-agentic (Agentic Orchestrator)

Announce at start: "I'm using the ywc-agentic skill to orchestrate the ywc-* pipeline autonomously from goal to verified implementation."

This skill turns a single natural-language goal into delivered code by orchestrating the existing ywc-* skills through an autonomous Plan → Execute → Evaluate → Repeat loop. It does not implement code itself — it sequences ywc-plan, ywc-spec-validate, ywc-task-generator, an executor, ywc-impl-review, and (for Small-scale goals) ywc-code-gen, then re-plans on evaluation failure until the implementation passes review or a user-defined iteration ceiling is reached.

User → Goal → Agent [Plan → Execute → Evaluate → Repeat] → Result

Rationalization Defense

When tempted to bypass a rule, check this table first:

| Excuse | Reality | |---|---| | "The loop does not look like it is converging — bump --max-iterations" | --max-iterations is a user-defined safety valve. The agent never raises it autonomously. If the ceiling is reached, emit the partial-completion report and stop — surfacing non-convergence to the user is the correct outcome, not silently grinding more iterations. | | "The evaluation failed but the issues look trivial — continue without re-planning" | Any ywc-impl-review finding at HIGH or CRITICAL severity triggers a mandatory re-plan. There is no "trivial" exception. DONE_WITH_CONCERNS is a Fail verdict for loop-control purposes — only DONE (zero CRITICAL/HIGH) ends the loop with a Pass. | | "Re-run the already-merged tasks too, just to be safe" | Merged tasks (present in /completed/ or already in the base-branch git log) are never re-executed. Re-running them risks duplicate commits, merge conflicts, and undoing later iterations. Resume safety depends on this invariant. | | "Small path only needs a plan.md, so ywc-task-generator is dead weight — skip straight to executor" | Small path is a dedicated route: ywc-plan (Small verdict) → ywc-code-gen directly, with no ywc-task-generator and no executor. It is not a degraded Medium path. Do not invent a hybrid. The loop control (max iterations, evaluate, re-plan) is identical, but the Plan and Execute phases use the Small Path contract in Step 3 / Step 5. | | "ywc-impl-review --code can just look at everything — simpler than tracking git ranges" | Iterative evaluation always uses --git-range ..HEAD so each pass scopes to that iteration's changes, and always passes the original full spec via --spec. Using --code or a narrow re-plan spec lets iteration-1 regressions slip through undetected. The pre-iteration SHA is recorded in Step 5 before the executor runs. | | "Re-plan produced roughly the same spec — run it anyway, maybe it works this time" | A re-plan that produces the same scope as the previous iteration means the loop is stuck. Detect it (Step 7 recursion guard), mark the iteration failed, and stop. Repeating an identical iteration burns budget and never converges. | | "A merge conflict appeared mid-execute — resolve it automatically and keep going" | The loop never auto-recovers from merge conflicts or CI errors. Record the state in tasks/agentic-log.md, report to the user, and stop. Automatic conflict resolution risks silent data loss. |

Violating the letter of these rules is violating the spirit. The loop is trustworthy only because its termination conditions and re-plan triggers are non-negotiable.

Arguments

| Parameter | Format | Default | Description | |---|---|---|---| | ` | positional string | _(required)_ | Natural-language description of the goal to achieve. | | --goal | --goal "" | — | Alternative to the positional . If both are given, the positional value wins. | | --max-iterations | --max-iterations | 3 | Maximum loop iterations. User-defined safety valve — never raised autonomously. | | --executor | --executor | auto | Forces an executor. auto selects from tasks/dependency-graph.md (see Step 4). | | --tasks-dir | --tasks-dir | tasks/ | Root directory for task directories and agentic-log.md. | | --resume | flag | — | Skip the Plan Phase and resume from existing tasks/ (Resume Mode). | | --dry-run | flag | — | Print the planned phase sequence only; invoke no skills and make no changes. | | --terse | flag | — | Minimal output — phase headers and the final report only, no per-phase prose. | | --pr-lang | --pr-lang | auto | PR title/description language, forwarded unchanged to the executor. auto` resolves through shared YWC language policy; if no tier resolves a language, ask the user before invoking the selected executor. |

Workflow

The loop runs Steps 3–8 once per iteration. Steps 1–2 run once at start; Step 9 runs once at the end. Each phase transition announces progress to the user (suppressed under --terse).

Step 1: Receive and Validate the Goal (FR-1)

Read the goal from the positional ` argument or the --goal` flag. If both are present, the positional value takes precedence.

• If no goal is supplied, ask the user: "What goal should I implement? Provide a natural-language description." Do not proceed without a goal.
• Derive a filesystem-safe `` from the goal (lowercase, hyphenated, ≤40 chars) for deterministic artifact paths.
• If --dry-run is set, from here on only print the phase plan (Plan → Task → Execute → Evaluate, with the chosen Mode) and stop without invoking any skill.

Step 2: Detect Project Context — Resume vs. Full Mode (FR-2)

Read the project's convention files to ground every downstream skill call:

• AGENTS.md, CODEX.md, CLAUDE.md — project rules, language policy, CI commands.
• package.json / pyproject.toml / Makefile / go.mod — language and build/test/lint commands.
• docs/ubiquitous-language.md (if present) — canonical domain terms to forward to the executor.

Then decide the Mode:

• Resume Mode — Enter when --resume is set, or when / exists and contains at least one task directory that is not under /completed/. Resume Mode skips Step 3 (Plan Phase) entirely.
• Full Mode — Enter otherwise (no tasks/, or every task already completed). Full Mode starts from Step 3.

Edge case: if --resume is set but / is empty or absent, do not silently restart — report the mismatch and propose switching to Full Mode (see Edge Cases).

Step 3: Plan Phase (FR-3)

Skipped entirely in Resume Mode. In Full Mode (first iteration) and on Re-plan (subsequent iterations):

Full Mode — first iteration:

1. Invoke ywc-plan non-interactively with a deterministic output path:

``text ywc-plan --non-interactive --output docs/ywc-plans/agentic--iter1.md ` --non-interactive makes ywc-plan fill open questions with anchored defaults instead of prompting. --output` pins the artifact path so later steps and re-plans can locate it.

1. Branch on the scale verdict from ywc-plan:

• Small → take the Small Path: ywc-plan produced a plan.md. Skip Steps 4 and the executor; go directly to ywc-code-gen in Step 5 (Small Path). ywc-task-generator is not used.
• Medium / Large → ywc-plan produced a spec. Run ywc-spec-validate against it; if ywc-spec-validate reports any CRITICAL issue, stop and report (the spec is not safe to decompose). Otherwise continue to Step 4 (Task Phase).

Re-plan — iteration N > 1 after an Evaluate Fail:

• Do not create a new spec file. Invoke:

``text ywc-plan --update-spec docs/ywc-plans/agentic--iter1.md --failure-context "" ``

• --update-spec appends an ## Iteration N Amendments section to the original spec, so completed-task context is preserved. --failure-context carries the prioritized CRITICAL/HIGH findings from the previous Evaluate Phase (Step 6) — the corrective scope, not the whole spec.
• After the amendment, Medium/Large goals re-enter Step 4 with only the amended/uncovered tasks; Small Path goals re-enter Step 5 (Small Path) with the amended plan.md.

The "original spec" reference (docs/ywc-plans/agentic--iter1.md) is fixed for the entire run and reused verbatim by every Evaluate Phase.

Step 4: Task Phase (FR-4)

Medium/Large goals only. Skipped on the Small Path.

1. Invoke ywc-task-generator against the (possibly amended) spec, writing into the configured directory:

``text ywc-task-generator --tasks-dir ` ywc-task-generator resolves output language through [../references/language-resolution.md](../references/language-resolution.md). Pass --lang en|ja|ko|zh|es only when the user explicitly requested a task/spec language or a shared config tier resolves one for task/spec artifacts. Otherwise preserve the no---lang behavior and let ywc-task-generator` ask if needed.

1. Read /dependency-graph.md and select the executor:

• --executor is explicit → use that executor.
• --executor auto and the graph yields multiple waves with independent tasks → ywc-parallel-executor.
• --executor auto and all tasks are strictly sequential → ywc-sequential-executor.

1. On a Re-plan iteration, ywc-task-generator numbers the new tasks past the highest existing sequence so already-completed tasks are untouched.

Step 5: Execute Phase (FR-5)

Record the pre-iteration baseline first. Before invoking any executor, capture and store the current commit SHA:

git rev-parse HEAD   →   

This SHA is the lower bound of the --git-range passed to the Evaluate Phase. Record it in the iteration's working state.

Medium/Large path: invoke the executor selected in Step 4 in local-merge mode:

ywc--executor --all --tasks-dir  --local-merge --pr-lang 

--local-merge keeps iterations fast — no PR round-trip; completed tasks merge to the base branch directly. After the executor returns, collect each task's success/failure status from its return payload.

Forward --pr-lang unchanged when it is one of en|ja|ko|zh|es; do not normalize zh or es before the selected executor receives it. When --pr-lang auto or no PR language is supplied, use [../references/language-resolution.md](../references/language-resolution.md); if no tier resolves a language, ask the user before invoking the selected executor, then forward only the resolved language code.

Small Path: invoke ywc-code-gen directly against the plan.md from Step 3. No executor, no tasks/ directory. ywc-code-gen commits its output to the base branch so the Evaluate Phase can range over it.

If the executor or ywc-code-gen reports a merge conflict or unrecoverable CI error, stop immediately — record to agentic-log.md (Step 8) and report (see Edge Cases). Never auto-resolve.

Step 6: Evaluate Phase (FR-6)

Run ywc-impl-review over only this iteration's changes, judged against the original full spec:

ywc-impl-review --spec docs/ywc-plans/agentic--iter1.md --git-range ..HEAD

• --spec is always the original full spec, never a re-plan's narrow amendment. A narrow spec would not flag regressions that iteration N introduced into iteration 1's code.
• --git-range scopes the review to commits added during this iteration (`` recorded in Step 5).
• Small Path: --spec is the plan.md from Step 3; --git-range is unchanged.

Classify the verdict from ywc-impl-review's Completion Status:

| ywc-impl-review status | Verdict | Meaning | |---|---|---| | DONE | Pass | No CRITICAL or HIGH issues. | | DONE_WITH_CONCERNS | Fail | One or more CRITICAL/HIGH issues — re-plan required. | | BLOCKED / NEEDS_CONTEXT | Fail (hard stop) | Review could not complete — record and stop, do not re-plan blindly. |

Step 7: Loop Control (FR-7)

Maintain an iteration counter starting at 1. After each Evaluate Phase:

| Condition | Action | |---|---| | Verdict = Pass | Exit the loop. Proceed to Step 8 (log) then Step 9 (Completion Report). | | Verdict = Fail and iteration = max-iterations | Exit the loop. Proceed to Step 8 then Step 9, which emits a partial-completion report listing unresolved issues. | | Verdict = Fail (hard stop) | Exit the loop immediately. Record to agentic-log.md and report — the loop cannot make a safe decision. |

Recursion guard: before starting a Re-plan iteration, compare the new amendment's scope against the previous iteration's scope. If they are effectively identical (same target files/tasks, same fix list), the loop is stuck — mark this iteration failed, log it, and stop instead of looping. Do not raise --max-iterations to escape this.

Step 8: Iteration Log (FR-8)

After every iteration (Pass or Fail), append a structured record to /agentic-log.md. The file is append-only — never rewrite prior entries. Format:

## Iteration  — 
- Phase: 
- Tasks completed: /
- ywc-impl-review:   issues)>
  - :    ← one line per issue, Fail only

Concrete example:

## Iteration 1 — 2026-05-15T10:30:00Z
- Phase: Full Mode / Plan → Spec → Tasks → Execute → Evaluate
- Tasks completed: 4/4
- ywc-impl-review: FAIL (2 HIGH issues)
  - HIGH: Missing input validation in POST /api/users
  - HIGH: SQL injection risk in search query

Tasks completed is the integer / pair (for the Small Path, use 1/1 when ywc-code-gen succeeds, 0/1 when it fails). If the loop stopped on an exception, append the exception cause as a final line before reporting.

Long-run compaction: from iteration 6, or whenever 5+ iterations accumulate in context, keep only a one-line iteration digest per prior iteration in working context. Treat /agentic-log.md as the durable source of truth for prior details; re-read it before evaluating historical decisions instead of relying on transcript memory.

Step 9: Completion Report (FR-9)

Emit one final report to the user:

• Goal — the original goal string.
• Mode — Full / Resume, and Small Path / Medium-Large path.
• Iterations run — ` of `.
• Tasks completed — aggregate completed/total across the run.
• Outcome — Converged (final verdict Pass), Ceiling reached (max iterations hit), or Stopped (exception).
• Remaining issues — bullet list of unresolved CRITICAL/HIGH findings, if any.
• Artifacts — original spec path, agentic-log.md path.

End the report with one Completion Status line — nothing follows it:

Output Format

## Agentic Result: 

### Iterations
- Iteration :  — 

### Artifacts
- Spec: 
- Tasks: 
- Review: 

### Completion Status

Completion Status rules:

| Status | When | |---|---| | DONE | Final verdict Pass — implementation passed ywc-impl-review. | | DONE_WITH_CONCERNS | Ceiling reached with unresolved issues, or partial completion. | | BLOCKED | Loop stopped on a merge conflict, CI error, or other exception requiring human action. | | NEEDS_CONTEXT | Goal or arguments were too ambiguous to start the loop. |

Edge Cases

| Case | Handling | |---|---| | ywc-plan returns a Large verdict (15+ tasks) | Defer to ywc-plan's existing Large-scale logic — it proposes splitting the spec to the user. Proceed with whatever ywc-plan produces; do not override its scale judgment. | | Merge conflict during the Execute Phase | Stop immediately. Append the conflict (files, affected tasks) to agentic-log.md, report to the user, request manual resolution. Never auto-abort, force, or auto-resolve. | | Re-plan produces an identical-scope spec | Recursion guard (Step 7): mark the current iteration failed, append to agentic-log.md, and stop. An identical re-plan means the loop cannot converge — escalate to the user. | | --resume set but / is empty or absent | Report the mismatch: "--resume was requested but no pending tasks exist in /." Propose switching to Full Mode and wait for the user's confirmation before continuing. | | **Max iterations reached wi

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yongwoon
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.