@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -0,0 +1,356 @@
+---
+model_tier: inherit
+name: subagent-orchestration
+description: "Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# subagent-orchestration
+
+## When to use
+
+* A task benefits from a second agent reviewing before apply — safety,
+  regression risk, cross-layer change
+* A plan has clear, independent slices that can be worked on in
+  parallel — unrelated bug fixes, multi-file migrations
+* A solution space is broad enough that multiple candidate
+  implementations are worth producing and comparing
+* The user explicitly asks "have a second agent review this" or "try
+  this two different ways"
+
+Do NOT use when:
+
+* The task is small and the overhead of a second agent exceeds the
+  value — single file, one-liner fix
+* The user is still exploring — route to brainstorming / planning
+  skills first
+* Budget is the constraint — each subagent call multiplies cost
+* The implementer and judge would be the same model on the same
+  context — no added signal
+
+## Goal
+
+Land a verified change (or set of changes) by combining implementer
+and judge subagents in a mode chosen deliberately, with model pairing
+read from `.agent-settings.yml` — never silently improvised.
+
+## The Iron Law
+
+```
+NO JUDGE ON THE SAME MODEL AS THE IMPLEMENTER ON THE SAME CONTEXT.
+```
+
+Same model + same context = same blind spots. The whole point of a
+judge is a fresh pair of eyes. If `.agent-settings.yml` resolves to
+identical implementer and judge models, surface the mismatch before
+running — do not silently continue.
+
+## RDP: parallel async dispatch by default
+
+Within the Reasoning Discipline Protocol, dispatch independent subtasks to
+parallel subagents **by default** and keep working while they run (async), rather
+than blocking on each return — intervene only if one goes off track. Engage per
+[`rdp-gate`](../../contexts/execution/rdp-gate.md).
+
+## The seven modes
+
+Each mode has a decision row: when to use, when not, and the expected
+model pairing. Defaults come from
+[`subagent-configuration`](../../contexts/subagent-configuration.md).
+
+### Topology hints — per-mode communication shape
+
+Descriptive, not enforced. Documents the **expected agent-to-agent
+communication topology** so consumers can predict latency, failure
+modes, and where consensus is required. Cited from
+an internal findings note (local-only) <!-- council-ref-allowed: ADR decision trace for topology anti-drift defaults -->
+row 7 (the external runtime's `hierarchical, 6–8 agents, raft consensus` anti-drift
+default).
+
+| Mode | Topology | Anti-drift default | Notes |
+|---|---|---|---|
+| do-and-judge | `hierarchical` | 1 implementer · 1 judge · session-orchestrated | Two-node hub-and-spoke; orchestrator owns the loop. |
+| do-and-judge-two-stage | `hierarchical` | 1 implementer · 2 sequential judges | Stages are serialized; spec-judge gates quality-judge. |
+| do-in-steps | `ring` | N steps · 1 judge between each | Step N output → judge → step N+1 input; cycle on revise. |
+| do-in-parallel | `star` | 6–8 implementers · 1 judge · session-hub | Capped by `subagents.max_parallel`; judge runs once on union. |
+| do-competitively | `mesh` | 2–4 implementers · 1 judge | Implementers do not see each other; judge sees all candidates. |
+| judge-with-debate | `hierarchical-mesh` | 2 judges · 1 meta-judge | Judges debate (mesh edge); meta-judge reconciles (hierarchical). |
+| do-in-worktrees | `adaptive` | per-step topology of the underlying mode | Each worktree picks its own shape; chain is hierarchical. |
+
+**Anti-drift default** (the external runtime convention, descriptive only):
+`hierarchical, 6–8 agents, raft consensus`. Consumers free to
+override per orchestration — the table is the **starting point**,
+not a constraint. Topology is metadata for capacity planning, not
+runtime-enforced.
+
+**Glossary:**
+- `hierarchical` — orchestrator hub; agents reply to hub only.
+- `mesh` — agents see each other's outputs (e.g. competing diffs).
+- `hierarchical-mesh` — peer debate followed by hub reconciliation.
+- `ring` — output of step N feeds input of step N+1 in order.
+- `star` — N agents fan out from a single hub; no peer comms.
+- `adaptive` — topology shifts per step; outer chain remains hub.
+
+### 1. do-and-judge
+
+Implementer produces a diff; judge reviews; loop applies, revises, or
+hands off. Hard ceiling: **two revision cycles**, then stop and hand
+back to the user.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
+
+### 2. do-and-judge-two-stage
+
+Implementer produces a diff; **two judges run sequentially** — first a
+spec-compliance reviewer (does the diff satisfy the stated spec /
+acceptance criteria?), then a code-quality reviewer (is the diff well-
+written for the codebase it lands in?). The orchestrator only proceeds
+to stage two if stage one returns `DONE` or `DONE_WITH_CONCERNS`. A
+stage-one `BLOCKED` shortcuts the loop — there is no point quality-
+reviewing a diff that does not satisfy the spec.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Spec is contested or AC are detailed; diff size makes one judge prone to missing one axis (correctness vs craft) | Spec is one sentence, or the diff is one line (collapse to mode 1) | implementer = session; spec-judge = one tier up; quality-judge = same tier as spec-judge, fresh context |
+
+**Why two stages, not one judge with both rubrics:** combining the
+rubrics in one prompt reliably regresses one of them — the judge "spends
+attention" on whichever rubric appears last. Splitting the prompts
+forces each judge to commit fully to its rubric.
+
+**Stage-routing rule:**
+- Stage-1 returns `DONE` → run stage-2.
+- Stage-1 returns `DONE_WITH_CONCERNS` → run stage-2; concerns carry
+  forward to the final envelope.
+- Stage-1 returns `NEEDS_CONTEXT` → pause; stage-2 does not run.
+- Stage-1 returns `BLOCKED` → final verdict is `BLOCKED`; stage-2
+  does not run (saves cost).
+
+### 3. do-in-steps
+
+Plan is split into N steps; judge runs **between** steps. A step that
+fails judgment is revised before the next step starts. Used for
+multi-file changes where a mid-plan mistake would cascade.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
+
+### 4. do-in-parallel
+
+Independent slices run concurrently. No judge per slice — judge runs
+once on the aggregated result. Parallelism capped by
+`subagents.max_parallel` in `.agent-settings.yml`.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
+
+### 5. do-competitively
+
+Multiple implementers produce candidate diffs for the **same** slice.
+Judge picks the winner and rejects the losers. Expensive — use only
+when the solution space is genuinely broad.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
+
+### 6. judge-with-debate
+
+Two judges each produce a verdict; a meta-judge reconciles
+disagreements. Used for high-stakes changes (security, data
+migration, public API) where a single judge is too easy to fool.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
+
+### 7. do-in-worktrees
+
+Cross-wing or cross-skill chain executed across isolated git
+worktrees — each handoff in the chain runs in its own worktree, so
+the workspace state of one step never leaks into the next. Operationalizes
+the worktree boundary clause in
+[`docs/contracts/cross-wing-handoff.md`](../../../docs/contracts/cross-wing-handoff.md)
+§ 3. State-machine layer only — worktree creation/destruction lives
+in [`using-git-worktrees`](../using-git-worktrees/SKILL.md) and
+[`finishing-a-development-branch`](../finishing-a-development-branch/SKILL.md).
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step cross-wing chain (≥2 senior skills, each ≥30 min) where one step's open files / branch state would confuse the next | Fast iteration where each step < 30 min — worktree overhead exceeds isolation benefit | implementers = same tier per step; judge = one tier up at chain end |
+
+**Handoff shape:** initiator-skill emits the typed output declared in
+its `## Output` block → control passes to delegated-skill in a fresh
+worktree → delegated-skill consumes the input shape declared in its
+`## Input` (or `## When the agent should load this`) block. The
+handoff is auditable; `lint_handoffs.py` validates the chain.
+
+**Example chain (W3 launch):** `positioning-strategy` (worktree A) →
+`messaging-architecture` (worktree B, consumes positioning's
+`positioning-statement.md`) → `gtm-launch` (worktree C, consumes
+both prior artifacts). Each worktree carries one branch; the chain
+end produces a single integration PR.
+
+**Anti-pattern:** do not use for fast iteration loops where each
+step is under ~30 minutes. The branch-creation, context-switch, and
+worktree-cleanup cost dominates. Stick with mode 1 (do-and-judge)
+or mode 3 (do-in-steps) for those.
+
+**Competitive variant — per-candidate isolation.** When mode 5
+(`do-competitively`) is combined with worktrees, each candidate
+implementer runs in its own worktree (so candidates cannot read each
+other's open files or branch state). Selection rules:
+
+- **No auto-merge.** The orchestrator never merges a candidate
+  branch. Hard Floor per [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) —
+  applies even under standing autonomy. ADR-005 records the reasoning.
+- **Ranked presentation.** Judge ranks candidates (1..N) with a
+  one-line justification per rank; user picks the winner.
+- **Loser worktrees stay.** The orchestrator does not delete losing
+  worktrees automatically — the user keeps the option to harvest a
+  partial idea before cleanup.
+
+## Status taxonomy — every subagent return uses one envelope
+
+Every implementer or judge return must conform to
+[`schemas/subagent-status.json`](schemas/subagent-status.json). Four
+statuses, no free-form alternatives:
+
+| Status | Meaning | Required keys (beyond `status`, `summary`) |
+|---|---|---|
+| `DONE` | Work shipped, all gates green. | `evidence[]` |
+| `DONE_WITH_CONCERNS` | Work shipped but caller must act on concerns. | `evidence[]`, `concerns[]` |
+| `NEEDS_CONTEXT` | Paused; caller can unblock by answering. | `blocking_question` |
+| `BLOCKED` | No path forward exists. | `blocking_reason` |
+
+**Why a fixed taxonomy:** orchestrators (`/do-and-judge`, `/do-in-steps`)
+route on status. Free-form "kind of done" returns force the orchestrator
+to interpret prose, which silently regresses the two-revision ceiling and
+the judge-rejected-do-not-apply rule. The schema makes routing mechanical.
+
+**Tests:** `tests/test_subagent_status_schema.py` exercises all four
+statuses plus rejection cases (missing required keys, unknown status,
+extra fields, conditional-key violations).
+
+**Distinguishing `NEEDS_CONTEXT` from `BLOCKED`:** `NEEDS_CONTEXT` means
+*"you, the caller, can fix this by telling me X"*. `BLOCKED` means
+*"no input from you unblocks this — escalate or rescope"*. If a subagent
+is unsure, it picks `BLOCKED` and the caller can downgrade.
+
+## Dispatch prompts — externalized
+
+Each mode's literal dispatch template lives under
+[`prompts/{mode}.md`](prompts/README.md). The orchestrator loads the
+matching prompt at dispatch time and substitutes `{{placeholders}}`.
+Edits to a prompt do not bloat this skill against the 400-line sunset
+trigger; `tests/test_subagent_prompt_loading.py` confirms each of the
+seven modes resolves to a loadable prompt that cites all four taxonomy
+statuses.
+
+## Procedure
+
+### 1. Inspect the task shape
+
+Before picking a mode, check:
+
+* Is the task single-change or multi-step?
+* Are slices truly independent, or do they share state?
+* Is solution space narrow (one right answer) or broad (trade-offs)?
+* Is risk high enough to justify debate?
+
+Do not pick a mode until these four questions have concrete answers.
+
+### 2. Resolve models
+
+Read `.agent-settings.yml`:
+
+* `subagents.implementer_model` → empty = session model
+* `subagents.judge_model` → empty = one tier above implementer
+* `subagents.max_parallel` → integer, default 3
+
+If resolution produces an unknown alias or implementer == judge in the
+same context, **stop** and report. Do not improvise.
+
+### 3. Pick the mode
+
+Match task shape to one of the seven modes. When two modes could fit,
+prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
+`do-in-steps` < `do-in-parallel` < `do-competitively` <
+`judge-with-debate` < `do-in-worktrees`).
+
+**Mode 6 (`do-in-worktrees`) is gated by `worktrees.mode`** from
+`.agent-settings.yml` (default: `ask`). Resolve before picking:
+
+| `worktrees.mode` | Mode 6 |
+|---|---|
+| `ask` | Eligible. `using-git-worktrees` will run the per-creation permission ask. |
+| `on` | Eligible. Per-creation ask suppressed. |
+| `off` | **Not eligible.** Fall back to mode 3 (`do-in-steps`) — same step-by-step chain, in-place on the current branch. Unless the user **explicitly asked this turn** for a worktree chain, in which case proceed with mode 6 and acknowledge the override per [`using-git-worktrees § Pre-flight`](../using-git-worktrees/SKILL.md). |
+
+### 4. Dispatch
+
+Hand off to the matching command:
+
+* `do-and-judge` → [`/do-and-judge`](../../commands/do-and-judge.md)
+* `do-in-steps` → [`/do-in-steps`](../../commands/do-in-steps.md)
+* `judge` (standalone) → [`/judge`](../../commands/judge.md)
+
+Modes without a dedicated command (`do-in-parallel`,
+`do-competitively`, `judge-with-debate`) are orchestrated inline via
+the skill — describe the dispatch explicitly in chat so the user can
+follow it.
+
+### 5. Report
+
+Follow the output format below. Never merge a diff without reporting
+the judge verdict.
+
+## Gotcha
+
+* **Identical model both sides** — same blind spots. The Iron Law
+  blocks this before dispatch.
+* **Judge drifts off-task** — judge reviews *the diff*, not the task
+  description. Always attach the diff to the judge prompt.
+* **Infinite revision loop** — hard ceiling of two revisions in
+  `do-and-judge`; then hand back to the user.
+* **`do-in-parallel` on overlapping slices** — race conditions,
+  conflicting diffs. Verify independence before splitting.
+* **Cost surprise on `do-competitively`** — N implementers + 1 judge =
+  N+1 subagent calls for one slice. Confirm budget before dispatch.
+
+## Output format
+
+1. **Mode chosen** — one of the seven, with the one-line reason
+2. **Model pairing** — implementer model / judge model (resolved)
+3. **Verdict** — applied / revised / handed back
+4. **Evidence** — diff summary, test output, or judge transcript
+5. **Next step** — what the user does now (review PR, pick winner, etc.)
+
+## Do NOT
+
+* NEVER run implementer and judge on the same model and same context
+* NEVER exceed the two-revision ceiling in `do-and-judge` without user
+  consent
+* NEVER run `do-in-parallel` on slices that touch shared files
+* NEVER apply a diff that the judge rejected without explicit user
+  override
+* NEVER silently resolve an unknown model alias to a fallback
+
+## Handover
+
+| Task                                 | Skill / command                      |
+|--------------------------------------|--------------------------------------|
+| Configuration reference              | [`subagent-configuration`](../../contexts/subagent-configuration.md) |
+| Do-and-judge loop                    | [`/do-and-judge`](../../commands/do-and-judge.md) |
+| Stepwise plan with judge gates       | [`/do-in-steps`](../../commands/do-in-steps.md) |
+| Standalone judge on an existing diff | [`/judge`](../../commands/judge.md)  |
+| External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
+| Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |

package/dist/agent-src/skills/tailwind-engineer/SKILL.md

@@ -0,0 +1,154 @@
+---
+model_tier: medium
+name: tailwind-engineer
+description: "Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'."
+personas:
+  - frontend-engineer
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# tailwind-engineer
+
+> Apply utility-first discipline. Reach for design tokens before
+> arbitrary values, compose with `@apply` only where it earns its
+> keep, and reject inline `style=` drift. The skill is the **how**
+> for any Tailwind-stack screen; pair with
+> [`existing-ui-audit`](../existing-ui-audit/SKILL.md) for the **what
+> already exists** and [`fe-design`](../fe-design/SKILL.md) for the
+> **why**.
+
+## When to use
+
+- Writing or reviewing Tailwind classes in Blade, Livewire, or React
+  components.
+- A diff introduces inline `style=` for dynamic values, hex codes
+  not in `tailwind.config`, or `!important`.
+- Class lists balloon past ~12 utilities and the component is
+  hard to read or duplicate.
+- German triggers: "stile mit Tailwind", "design tokens nutzen",
+  "warum nicht inline?".
+
+Do NOT use when:
+
+- The stack is not Tailwind (vanilla CSS, CSS-in-JS, MUI) — skip.
+- The question is component shape, not styling — route to
+  [`ui-component-architect`](../ui-component-architect/SKILL.md).
+- An accessibility issue is the symptom (focus ring, contrast, hit
+  area) — route to [`accessibility-auditor`](../accessibility-auditor/SKILL.md).
+
+## Procedure
+
+### 1. Resolve to design tokens first
+
+Inspect `tailwind.config.{js,ts}` (or the equivalent `@theme` block)
+and identify the configured tokens. Map every requested colour,
+radius, spacing, shadow, font-size to a configured token. If the design hands you `#3B82F6`, use
+`bg-blue-500` (or the project's named token). Arbitrary values
+(`bg-[#3B82F6]`, `mt-[17px]`) are a smell — accept only with a
+one-line comment naming the design source.
+
+Token authoring (DTCG 3-layer, CSS-var/Tailwind generation):
+[`design-tokens`](../design-tokens/SKILL.md); its `tokens.py validate
+--dir <path>` is the **single token-discipline linter** behind this rule.
+Greenfield config: bundled `scripts/tailwind_config_gen.py`
+(Apache-2.0-derived, pure templating) scaffolds `tailwind.config.{js,ts}`.
+
+### 2. Compose, don't inline
+
+Inline `style="..."` is allowed only for **runtime-computed values**
+the build cannot know (server-pushed colour, animated transform
+target). Static values inline are a regression — replace with a
+utility, an arbitrary value, or a token extension.
+
+### 3. Order classes for scan-ability
+
+Group by axis: layout → box-model → typography → colour → state
+→ responsive. Most projects pin this with `prettier-plugin-tailwindcss`;
+if the plugin is configured, run it; if not, follow the order
+manually. Reviewer should read intent in one pass.
+
+### 4. Extract only when duplicated ≥ 3 times
+
+The first two repetitions are noise; the third is a pattern.
+Extract via:
+
+| Mechanism | When |
+|---|---|
+| Component (Blade/Livewire/React) | Different content, same shell |
+| Class string constant | Same shell, different consumers in same file |
+| `@apply` in CSS | Cross-file shared visual primitive (button, badge) |
+| Tailwind plugin | Tokens or variants, not classes |
+
+`@apply` for a one-off is a regression — keep utilities inline
+until the third use earns extraction.
+
+### 5. Responsive + dark + state in that order
+
+Class order within an axis: base → `sm:` → `md:` → `lg:` → `xl:` →
+`dark:` → state (`hover:`, `focus:`, `disabled:`, `aria-*:`).
+Mixing the order makes diffs noisy. State on top of dark on top
+of responsive matches Tailwind's cascade and reads top-down.
+
+## Output format
+
+When reviewing or proposing styles, return:
+
+1. Token map — every colour, spacing, radius, shadow, font-size mapped
+   to its configured token; arbitrary values flagged with the design
+   source they cite.
+2. Class list — ordered (layout → box-model → typography → colour →
+   state → responsive); inline-style use justified per element.
+3. Extraction + risk call-out — component / constant / `@apply` / none
+   with reason; risks named (arbitrary values, `!important`, dark-mode
+   gaps, non-token references).
+
+Concrete shape:
+
+```
+Element:        <selector or component name>
+Token map:      <colour/spacing/etc → config token>
+Class list:     <ordered classes>
+Inline style:   <only if runtime-computed; else "none">
+Extraction:     <component | constant | @apply | none — reason>
+Risks:          <arbitrary values, !important, dark-mode gaps>
+```
+
+## Gotcha
+
+- `space-x-*` / `space-y-*` collide with `flex-wrap` and RTL — use
+  `gap-*` on the flex/grid parent unless the design demands otherwise.
+- `dark:` variants need a token map in both modes; one-sided dark
+  styling is half a feature.
+- Arbitrary values (`mt-[17px]`) survive Tailwind upgrades but
+  break the design system; they accumulate silently.
+- `@apply` inside component CSS interacts with PurgeCSS — keep it
+  in files Tailwind scans, not in vendor CSS.
+- **Anti-AI-slop: gradients.** Unless audit-pinned or brief-explicit,
+  avoid the default purple-to-blue / cyan-to-pink gradients on white —
+  they read as auto-generated. Reach for a single accent from the
+  token map, or a duotone built from configured tokens.
+- **Anti-AI-slop: typography.** Unless audit-pinned, avoid surfacing
+  the system stack (`font-sans` fallback to Arial / Helvetica / Inter
+  via system defaults) as the *visible* body face. If `tailwind.config`
+  pins a font family, use it; if not, treat the missing token as a
+  gap to flag, not a license to ship the OS default.
+- **Anti-AI-slop: layout.** Unless audit-pinned, the centered hero +
+  3-column features + CTA stack is the AI-template tell. Break the
+  grid intentionally (asymmetric column split, overlap, diagonal
+  flow) when the brief allows; cite the design brief's `aesthetic:`
+  line if `fe-design`'s aesthetic-direction section produced one.
+
+## Do NOT
+
+- Do NOT add `!important` to win a specificity fight; restructure
+  the cascade or extract the conflicting style.
+- Do NOT introduce a new colour outside `tailwind.config` without
+  also adding the token; one-off hex codes drift the system.
+- Do NOT use `@apply` to avoid utility verbosity inside a single
+  component — extract the component instead.
+- Do NOT ship `style=` for static values; that is a CSS regression
+  the linter will not catch.