baldart 4.1.1 → 4.2.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.1] - 2026-06-03
+
+**`/prd` pre-dev audit: `code-reviewer` swapped for `plan-auditor` (card grounding) in the `check-audit` team.** The Step 6 pre-development audit ran `code-reviewer` on backlog `.yml` cards — but `code-reviewer` is built around a *diff* (scope = `git diff --name-only`, diff-simulation pass, completion-report cross-check, line-range/`repro_steps` findings schema, `PASS/FAIL/NEEDS_REWORK` verdict), none of which applies before any code exists. The audit had to re-purpose it with an ad-hoc mandate and override its native output format. `plan-auditor` is the agent purpose-built for this surface (native `.yml` INPUT TYPE DETECTION + BACKLOG CARD ATTACK SURFACE + native `[Target: <field>]` tagging + project memory), so it now fills that slot. **PATCH** (refinement of an existing capability — swaps which already-shipped agent audits cards; no new agent/skill/template, no `baldart.config.yml` key).
+
+> **Why.** Step 6.6d already replaced `plan-auditor`'s *plan-logic* role with a cross-model Codex adversarial audit, and kept `code-reviewer` as the Claude-side reviewer. But `code-reviewer`'s repurposed mandate (conflicts with existing patterns, reuse gaps, adjacent-card file conflicts) overlapped ~90% with the Codex `attack_surface` plus the Step 6.4 adjacent-card retrieval already fed to every agent. The only non-overlapping sliver — project memory of recurring code-level pitfalls — is covered *better* by `plan-auditor` (which has its own `.claude/agent-memory/plan-auditor/`). The swap aligns fit without losing coverage; the Maintenance Note's ablation rubric flagged `code-reviewer`-on-cards as the prime removal candidate. `code-reviewer` is unchanged and remains the agent for post-dev review (`/new` Phase 3, `/codexreview`).
+
+### Changed
+
+- **`framework/.claude/skills/prd/references/audit-phase.md`** — Step 6.6c agent-type mapping swaps the `code-reviewer` row for `plan-auditor` (card grounding, Always). New 6.6e agent-specific block runs `plan-auditor` with **full card-attack-surface coverage but team-aware spawn suppression**: no `codebase-architect` re-spawn (`/prd` already primed context at kickoff), no specialist auto-spawn (`security-reviewer` / `api-perf-cost-auditor` run as first-class teammates in the same team), and an output-format override to the teammate contract (`### [CARD-ID] — Plan Audit Findings` + `## FINDINGS` via `TaskUpdate`) — `plan-auditor`'s never-suppress list (`git_strategy: TBD`, missing-auth, `claimed_path_collision`, `adr_required_missing`, injection) still binds.
+- **Codex fallback dedup (Step 6.6d)** — the Codex-unavailable fallback now spawns a **FULL-mode** `plan-auditor` and explicitly SKIPS the card-grounding `plan-auditor` teammate, preventing two `plan-auditor` instances on the same cards.
+- **Consolidated report + Audit Engine Summary (Step 6.7)** — `### Code Review Findings` → `### Plan Audit Findings (card grounding — Claude-side)`; the engine summary now distinguishes the cross-model Codex pass from the Claude-side card-grounding pass.
+
+## [4.2.0] - 2026-06-03
+
+**Per-skill reasoning effort: every shipped skill now declares an `effort:` baseline + honors an inline `effort=<level>` override.** Different skills should reason at different depths — routine narration shouldn't pay for deep deliberation, and structured planning shouldn't be starved of it. Each of the 29 skills gets a frontmatter `effort:` baseline (`prd` → `high`, the other 28 → `medium`) and a `## Effort` body block letting the user dial reasoning depth per-run, e.g. `/prd effort=high <content>`. **MINOR** (new protocol module + new template = capability added; no `baldart.config.yml` key, so the schema-change propagation rule does not apply).
+
+> **Why.** Claude Code's native `effort:` frontmatter is the right knob for the *baseline*, but its precedence puts frontmatter **above** the session `/effort` level — only the global `CLAUDE_CODE_EFFORT_LEVEL` env var beats it, and a running skill cannot re-set the knob itself ([anthropics/claude-code#47275](https://github.com/anthropics/claude-code/issues/47275)). So a naive "default + inline flag that overrides" is impossible with the native knob alone. The inline override is therefore implemented as a **body-level reasoning escalation**: the skill reads `effort=<level>` from its arguments and engages the matching thinking directive (`think hard` → `ultrathink`), which the harness interprets from the text. Fully portable — no env var, no consumer config. Escalation upward is reliable; de-escalation below the frontmatter baseline is best-effort (the body can skip optional deliberation but can't lower the native budget).
+
+### Added
+
+- **`framework/agents/effort-protocol.md`** (new protocol module, #21) — the textual SSOT: native-knob precedence chain, tiering rubric for choosing a baseline, the `effort=<level>` inline-override parsing contract (detect once at kickoff, strip the token before consuming user input — modeled on the existing `-stats` flag in `prd`), and the level→behavior mapping (`low` → no extended thinking; `high`/`xhigh`/`max` → `think hard`/`think harder`/`ultrathink`). Routed from `framework/agents/index.md`.
+- **`framework/templates/skill-effort.snippet.md`** (new template) — copy-paste starter for the `effort:` frontmatter key + the `## Effort` body block, twin of `skill-project-context.snippet.md`.
+- **`effort:` frontmatter + `## Effort` body block on all 29 skills** — `prd` is `high`; `new`, `bug`, `simplify`, `frontend-design`, `ui-design`, `design-system-init`, `e2e-review`, `issue-review`, and the remaining 19 are `medium`. Any `medium` skill can be pushed to `high`/`xhigh`/`max` per-run via the inline override.
+
+### Changed
+
+- **`skill-creator`** now instructs authors to set the `effort:` baseline (per the tiering rubric) and to paste the `## Effort` block for every new skill — the previous "do not include any other fields in YAML frontmatter" guidance is updated to permit `effort`.
+
+### Out of scope (future)
+
+- **Agents** (`framework/.claude/agents/*.md`) also support `effort:` in frontmatter, but they receive no inline arguments (they are spawned by orchestrators via the Task tool). Their override story — static baseline per agent + orchestrator passing the desired level in the Task prompt — is deferred to a separate release to avoid mixing two override models.
+
 ## [4.1.1] - 2026-06-02
 
 **Fix: `/prd` (and `/new`) silently stopped creating their worktree after updating to ≥4.0.0.** Regression introduced in v4.0.0: `worktree-manager` was rewritten to resolve the worktree base from the **new `git.trunk_branch` config key** and to **hard-`exit 1`** when it is absent ("never assume develop"). Because `baldart update` never overwrites `baldart.config.yml`, every consumer that updated without re-running `configure` had no `git.trunk_branch` → the `nw-docs` / `nw` pre-flight aborted → no worktree. v4.0.0 also downgraded the `/prd` Step 1 worktree gate from BLOCKING to a non-blocking "MONITORING SIGNAL", so the abort no longer surfaced as a hard STOP — the session drifted into Discovery on the main checkout instead. **PATCH** (regression fix, no new capability, no schema change).

package/VERSION

@@ -1 +1 @@
-4.1.1
+4.2.1

package/framework/.claude/skills/api-design-principles/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: api-design-principles
+effort: medium
 description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
 ---
 
@@ -7,6 +8,15 @@ description: Master REST and GraphQL API design principles to build intuitive, s
 
 Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## When to Use This Skill
 
 - Designing new REST or GraphQL APIs

package/framework/.claude/skills/baldart-push/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: baldart-push
+effort: medium
 description: "Guidance for contributing local framework improvements upstream to the BALDART repository. Use when the user says /baldart-push, 'contribuisci al framework', 'push del framework', 'manda upstream', 'pusha le modifiche al framework', or wants to share local improvements made to .framework/. The skill walks the user through the contribution flow and hands off to `npx baldart push` (which must run in the user's terminal because the CLI is interactive). Never pushes baldart.config.yml, .baldart/overlays/, or .claude/hooks/ customizations — only generic framework payload."
 contamination_scan: skip
 ---
@@ -56,6 +57,15 @@ overlay content: extra contamination rules specific to the consumer's domain
 (e.g. internal codenames, private endpoints).
 **On missing/empty keys:** not applicable.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Hard rules
 
 1. **NEVER push** `baldart.config.yml`, anything under `.baldart/`, anything

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: baldart-update
+effort: medium
 description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Two modes, auto-detected: INTERACTIVE (a human is present) replicates the native CLI's user-decision points (preview diff, working-tree stash) as chat-side confirmations; AUTONOMOUS (unattended — CI / scheduled routine, signalled by BALDART_AUTONOMOUS / CI / GITHUB_ACTIONS env) runs `npx baldart update --yes` with zero prompts and hard-STOP guardrails (never forces a merge or reset on custom divergence / conflicts). Both let the CLI auto-resolve mechanical noise (hook backfill, subtree-merge commits, schema migration) and assert post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
 contamination_scan: skip
 ---
@@ -215,6 +216,15 @@ verification steps (e.g. "run `npm test` after symlink reconcile").
 own state files. See [framework/agents/project-context.md](../../../agents/project-context.md)
 for the protocol.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Hard rules
 
 0. **MUST run mode detection FIRST** (the `printenv | grep` probe above) and

package/framework/.claude/skills/bug/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: bug
+effort: medium
 description: >
   Structured bug investigation and resolution workflow (framework-agnostic; project-specific entry points are loaded from `.baldart/overlays/bug.md`).
   Use when: the user says /bug, 'debug', 'c e un bug', 'non funziona', 'errore', 'broken',
@@ -21,6 +22,15 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
 **Overlay:** loads `.baldart/overlays/bug.md` if present — project-specific debug entry points (e.g. SWR debug switches, env summary helpers, error-code modules). The base skill stays generic; project-specific code paths live in the overlay.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## MCP dependencies
 
 See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.

package/framework/.claude/skills/capture/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: capture
+effort: medium
 description: Distilla una sintesi cross-document della conversazione recente in una synthesis page riusabile del wiki overlay (path da `paths.wiki_dir`/syntheses/ in `baldart.config.yml`). Usare quando l'utente invoca `/capture`, dice "capture synthesis", "salva sintesi", "distilla conversazione", "save this as wiki", "questa conversazione in wiki", o quando chiede di trasformare un ragionamento cross-document appena fatto in una pagina stabile. Due modalità — manual (sempre funzionante) e proactive (conditional sui candidati in `.claude/capture-queue/`). Implementa il loop query→wiki file-back di Karpathy.
 version: 0.1.0
 ---
@@ -15,6 +16,15 @@ Turns a recent multi-turn synthesis (cross-document reasoning done by the assist
 **Overlay:** loads `.baldart/overlays/capture.md` if present — project-specific wiki-log helper path, domain vocabulary for the `domain:` frontmatter field.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Two Modes
 
 | Mode | When | How |

package/framework/.claude/skills/context-primer/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: cont
+effort: medium
 description: >
   Load codebase context silently before starting work, optimized for LLM
   comprehension using research-backed structured formatting.
@@ -20,6 +21,15 @@ Load structured, task-adaptive context about a topic into the conversation befor
 **Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Key Research Principles
 
 1. **Constraints FIRST** — primacy effect: critical info at start gets +30% recall

package/framework/.claude/skills/copywriting/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: copywriting
+effort: medium
 version: 1.0.0
 description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
 ---
@@ -15,6 +16,15 @@ You are an expert conversion copywriter. Your goal is to write marketing copy th
 **Overlay:** loads `.baldart/overlays/copywriting.md` if present — this is where project-specific brand voice pillars, audience register rules, and language constraints live. Sections marked `## [OVERRIDE] <topic>` replace base sections.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Brand Voice Context (MANDATORY for UI copy)
 
 When writing copy that will render in UI (buttons, empty states, banners, confirmation dialogs, inline hints, navigation labels, error messages), the brand voice is canonical — do not invent a new tone on the fly. The following reads are BLOCKING prerequisites:

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: design-system-init
+effort: medium
 description: >
   Bootstrap a component registry / design system on a project that doesn't have
   one yet. Scaffolds ${paths.design_system}/INDEX.md (component index +
@@ -42,6 +43,15 @@ recipe for non-Tailwind stacks).
 **On missing keys:** ask the user; do not assume defaults. See
 `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## What This Skill Does
 
 1. **Refusal check.** Reads `baldart.config.yml`.

package/framework/.claude/skills/doc-writing-for-rag/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: doc-writing-for-rag
+effort: medium
 description: "Writes high-density reference documentation optimized for RAG indexing. Uses compact templates, minimal frontmatter, cross-references to schemas.md/errors.md (paths from `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Load this skill when creating or rewriting files in `${paths.references_dir}`, `${paths.prd_dir}`, or when you hear 'endpoint template', 'compact docs', 'doc for RAG', 'dense documentation', 'signal/noise ratio'."
 ---
 
@@ -14,6 +15,15 @@ Writing protocol for reference docs optimized for LightRAG indexing. Validated o
 **Overlay:** loads `.baldart/overlays/doc-writing-for-rag.md` if present — project-specific domain list, schema naming conventions, frontmatter extensions.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## When to Use
 
 Load this skill when:

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: e2e-review
+effort: medium
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via
@@ -54,6 +55,15 @@ the implementing agent (`coder`) and the verifying agent
 (`visual-fidelity-verifier`) are distinct, with rule-based aggregation in
 between — no agent grades its own work.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 ## Invocation Modes

package/framework/.claude/skills/find-skills/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: find-skills
+effort: medium
 description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
 ---
 
@@ -7,6 +8,15 @@ description: Helps users discover and install agent skills when they ask questio
 
 This skill helps you discover and install skills from the open agent skills ecosystem.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## When to Use This Skill
 
 Use this skill when the user:

package/framework/.claude/skills/frontend-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: frontend-design
+effort: medium
 description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
 license: Complete terms in LICENSE.txt
 ---
@@ -15,6 +16,15 @@ This skill guides creation of distinctive, production-grade frontend interfaces
 
 The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Design Thinking
 
 Before coding, understand the context and commit to a BOLD aesthetic direction:

package/framework/.claude/skills/gamification-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: gamification-design
+effort: medium
 version: 1.0.0
 description: Use when designing or analyzing points systems, reward loops, progression mechanics, engagement features, or loyalty programs. Triggers include "points system," "rewards design," "progression," "engagement loop," "battle pass," "loyalty mechanics," "gamification," or "retention hooks." For B2C customer-facing features in this codebase, this skill invokes the hyper-gamification-designer agent.
 ---
@@ -15,6 +16,15 @@ Analyze and optimize gamification elements for maximum engagement and retention.
 **Overlay:** loads `.baldart/overlays/gamification-design.md` if present — project-specific reward economy facts (point name, tier ladder, lottery format), motion vocabulary, brand voice register for customer surfaces.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## When to Use
 
 Invoke this skill when working on:

package/framework/.claude/skills/issue-review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: issue-review
+effort: medium
 description: Run the GitHub issue review workflow for triage and planning. Use when the user asks to review or triage a GitHub issue, requests the /issue-review slash command, or needs an issue summary with priority/plan/tests.
 ---
 
@@ -7,6 +8,15 @@ description: Run the GitHub issue review workflow for triage and planning. Use w
 
 ## Overview
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 Run the `/issue-review` automation, capture issue context, and produce a triage + plan summary using the project's GitHub issue subagent protocol.
 
 ## Workflow

package/framework/.claude/skills/kie-ai/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: kie-ai
+effort: medium
 description: >
   Generate images, videos, and audio using Kie.ai's unified AI API platform (80+ models).
   Use when: (1) generating images from text or editing images (Nano Banana 2, Imagen 4, Flux Kontext,
@@ -23,6 +24,15 @@ description: >
 **Overlay:** loads `.baldart/overlays/kie-ai.md` if present — project-specific illustration character library, video-prompt motion vocabulary, and forbidden aesthetic patterns.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Visual Contract (project-specific)
 
 When generating images, videos, or animation prompts for product illustrations, the project's design-system SSOT is a BLOCKING prerequisite before model selection or prompt writing — but only when the project has one. Reading order:

package/framework/.claude/skills/lsp-bootstrap/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: lsp-bootstrap
+effort: medium
 description: >
   Install, verify, and document the LSP symbol-search layer for this project.
   Detects languages (TypeScript, Python, Go, Rust, Ruby), installs the matching
@@ -25,6 +26,15 @@ context on textual collisions; with it, references resolve to the same symbol
 **Overlay:** loads `.baldart/overlays/lsp-bootstrap.md` if present — project-specific install commands (e.g. a system-managed pyright via uv, a non-standard gopls path).
 **On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## What This Skill Does
 
 1. Reads `baldart.config.yml` and confirms `features.has_lsp_layer: true`.

package/framework/.claude/skills/motion-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: motion-design
+effort: medium
 description: >
   Applies motion design principles to create emotionally-driven, technically sound animations and transitions.
   Provides timing, easing, choreography, and Disney animation principles adapted for UI.
@@ -21,6 +22,15 @@ metadata:
 **Overlay:** loads `.baldart/overlays/motion-design.md` if present — project-specific motion vocabulary, brand-mandated easing curves, character-motion library.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Visual Contract
 
 When designing motion for generated marketing illustrations, prompts, or short product videos, the project's illustration-motion spec is a BLOCKING prerequisite when present:

package/framework/.claude/skills/new/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: new
+effort: medium
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and
@@ -39,6 +40,15 @@ If no card IDs are provided, ask the user which cards to implement.
 
 **Opt-in session telemetry (`-stats` / `--stats`)**: strip `-stats` / `--stats` from the args list exactly like `-full` (it is NOT a card ID), and set an internal flag `STATS=true` for this run. When present, Phase 8 additionally measures REAL token + wall-clock cost per agent role (coder, code-reviewer, …) by post-processing the session transcripts — zero model-token overhead, runs in Bash after the work is done. When absent, Phase 8 behaves exactly as before. The flag is batch-scoped and composes with `-full` (`/new FEAT-005 -full -stats`).
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 ## Context Tracking (CRITICAL)

package/framework/.claude/skills/overlay/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: overlay
+effort: medium
 description: "Guided author of .baldart/overlays/ — the per-project customisation layer for BALDART skills, agents, and commands. Use when the user says /overlay, 'customizza skill', 'modifica agente upstream', 'personalizza comando', 'crea overlay', 'extend skill X', 'override agent Y', 'overlay drift', or when the framework-edit-gate hook blocked an edit and pointed here. The skill walks the user through choosing the right canal (skill / agent / command), scaffolds the overlay with correct frontmatter and section markers via `npx baldart overlay scaffold`, validates the merge via `npx baldart overlay validate`, and surfaces drift via `npx baldart overlay drift`. Never edits `.framework/` directly and never re-implements the merger logic — the CLI is the source of truth."
 contamination_scan: skip
 ---
@@ -41,6 +42,15 @@ The skill MUST NOT re-implement any of the above. If you find yourself writing p
 **Overlay:** this skill has no overlay (it would be paradoxical).
 **On missing/empty keys:** not applicable.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Hard rules
 
 1. **NEVER edit files under `.framework/` directly.** The contamination scanner will block the edit, and even if it didn't, `baldart update` would overwrite the change.

package/framework/.claude/skills/playwright-skill/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: playwright-skill
+effort: medium
 description: E2E browser testing with Playwright Test CLI. Write .spec.ts files in tests/e2e/, run via `npm run test:e2e`. Supports headed mode, debug, UI mode, filtering, retries, screenshots, and trace on failure. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing.
 ---
 
@@ -17,6 +18,15 @@ All browser testing uses the **Playwright Test CLI** via `playwright.config.ts`
 **Overlay:** loads `.baldart/overlays/playwright-skill.md` if present — project-specific test URLs, auth helpers, theming pairing assertions.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## MCP dependencies
 
 See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.

package/framework/.claude/skills/prd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: prd
+effort: high
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 
@@ -15,6 +16,15 @@ cards. Anti-drift by design — rigid step sequence, persistent state, visible p
 **Overlay:** loads `.baldart/overlays/prd.md` if present — project-specific terminology, card layout overrides, segment names, mandated review gates.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: high` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 ## EXECUTION MODEL

package/framework/.claude/skills/prd/references/audit-phase.md

@@ -118,8 +118,8 @@ For each audit agent type (except plan-auditor), spawn ONE teammate using the `T
 
 | Audit Role | `subagent_type` | Name | Condition |
 |------------|-----------------|------|-----------|
-| ~~plan-auditor~~ | — | — | **Replaced by Codex adversarial audit (Step 6.6d)** |
-| code-reviewer | `code-reviewer` | `code-reviewer` | Always |
+| ~~plan-auditor (plan-logic role)~~ | — | — | **Replaced by Codex adversarial audit (Step 6.6d)** |
+| plan-auditor (card grounding) | `plan-auditor` | `plan-auditor` | Always — but SKIP if the Codex fallback to FULL plan-auditor fires (6.6d), to avoid two plan-auditor instances on the same cards |
 | doc-reviewer | `doc-reviewer` | `doc-reviewer` | Always |
 | api-perf-cost-auditor | `api-perf-cost-auditor` | `perf-auditor` | `perf_review_needed: true` |
 | security-reviewer | `security-reviewer` | `security-reviewer` | `security_review_needed: true` |
@@ -239,7 +239,7 @@ Suppress findings where the strongest false-positive argument is convincing.
 2. If the file is empty or its content is `CODEX_NOT_FOUND`, fall back to `plan-auditor` subagent.
 3. Merge into the consolidated report at Step 6.7 under `### Codex Plan Audit Findings`.
 
-**Fallback**: If Codex is unavailable (not installed, not authenticated, or timeout), fall back to the `plan-auditor` subagent with `subagent_type: "plan-auditor"`. Log the fallback reason in the audit report.
+**Fallback**: If Codex is unavailable (not installed, not authenticated, or timeout), fall back to a **FULL-mode** `plan-auditor` subagent with `subagent_type: "plan-auditor"`. Log the fallback reason in the audit report. **When this fallback fires, do NOT also run the card-grounding plan-auditor teammate from 6.6c** — the FULL fallback subsumes its coverage; running two plan-auditor instances on the same cards is the exact double-fan-out the dedup guard below exists to prevent.
 
 **Dedup guard on the fallback spawn (avoid double fan-out).** plan-auditor internally auto-spawns `codebase-architect` (always) and `security-reviewer` (when the cards carry auth/session signals). This audit session may have ALREADY produced those artifacts — `security-reviewer` runs as a first-class teammate whenever `security_review_needed: true` (Step 6.6c). To prevent a redundant second pass, the fallback `plan-auditor` invocation MUST be passed a context note instructing it to REUSE this session's artifacts rather than re-spawn:
 - If `codebase-architect` was already spawned earlier this session (its summary is in the session tracker artifact registry), pass that summary in the prompt and instruct plan-auditor NOT to re-invoke `codebase-architect`.
@@ -364,7 +364,13 @@ After challenge pass, rank ALL surviving findings relative to each other by impa
 
 **plan-auditor**: **Handled by Codex adversarial audit (Step 6.6d).** Not included in the teammate agent team. If Codex is unavailable, the fallback plan-auditor uses INVEST criteria, DoR checks, and requirements smell detection — see Step 6.6d attack_surface for the full checklist.
 
-**code-reviewer**: Read existing files in `files_likely_touched` and assess: conflicts with existing patterns? Architectural concerns? Alignment with conventions (per `identity.design_philosophy`, project lint/type-check rules, `identity.language`)? Existing utilities the card should reuse but doesn't mention? Check `## Adjacent Cards` for parallel file modifications.
+**plan-auditor (card grounding)**: This is the Claude-side, codebase-grounded counterpart to the cross-model Codex plan audit (6.6d) — it brings what Codex lacks: project memory (`.claude/agent-memory/plan-auditor/MEMORY.md`) and the card-native `[Target: <field>]` tagging this audit consumes. Apply the **full BACKLOG CARD ATTACK SURFACE** (INVEST, requirements-smell detection, persistence-specific checks per `stack.database`, card-structure checks) against each card's `.yml`, reading the existing files in `files_likely_touched` to ground claims about conflicts with existing patterns, missing reuse opportunities, and convention alignment (per `identity.design_philosophy`, project lint/type-check rules, `identity.language`). Check `## Adjacent Cards` for parallel file modifications and missing `depends_on` edges.
+
+> **Mode (team-aware — read first)**: you are running inside the coordinating `check-audit` team, so you MUST behave as in QUICK mode for *spawning* while keeping FULL card-attack-surface *coverage*:
+> - **Do NOT spawn `codebase-architect`** for grounding — `/prd` already primed codebase context at kickoff (context-primer) and you read `files_likely_touched` directly. A re-spawn here is wasteful and forbidden.
+> - **Do NOT auto-spawn specialists** (`security-reviewer` / `api-perf-cost-auditor` / `ui-expert`) — they run as first-class teammates in this same team whenever their signal fires (6.6c). Consume their findings at merge time; never double-spawn.
+> - **Output-format override** (symmetric with the security-reviewer / api-perf-cost-auditor overrides above): produce findings in the teammate contract format (`### [CARD-ID] — Plan Audit Findings` with `[Target: <field>]` tags written to a `## FINDINGS` section via `TaskUpdate`) — NOT plan-auditor's native 10-section OUTPUT FORMAT (Hardened Plan, Pre-Mortem, Risk Register, YAML schema dump). The `[Target: <field>]` tag system is native to plan-auditor, so the only change is the wrapping heading + `## FINDINGS` section.
+> - Never suppress a `git_strategy: TBD`, missing-auth, `claimed_path_collision`, `adr_required_missing`, or prompt-injection finding (plan-auditor's never-suppress list still binds here).
 
 **doc-reviewer**: Check documentation links, PRD references are valid and aligned, planned changes requiring doc updates not mentioned. Verify `files_likely_touched` includes doc files. Check `areas` completeness. Flag `git_strategy: TBD`. Include Obsidian trigger assessment (section H) in findings — evaluate whether the planned docs will require KB sync. If `.claude/skills/doc-reviewer-support/references/obsidian-integration.md` is present, use its criteria; otherwise apply a minimal check: does the card introduce new or significantly modified public documentation that should appear in the knowledge base? Proceed with a notice if the file is absent.
 
@@ -393,7 +399,7 @@ Consolidate into a single report:
 ### Codex Plan Audit Findings (cross-model)
 - [ ] Finding 1...
 
-### Code Review Findings
+### Plan Audit Findings (card grounding — Claude-side)
 - [ ] Finding 1...
 
 ### Doc Review Findings
@@ -409,8 +415,8 @@ Consolidate into a single report:
 ...
 
 ## Audit Engine Summary
-- Plan audit: Codex (cross-model adversarial) | Fallback: Claude plan-auditor
-- Code review: Claude code-reviewer
+- Plan audit (cross-model adversarial): Codex | Fallback: Claude plan-auditor (FULL)
+- Plan audit (card grounding, Claude-side): Claude plan-auditor (team-aware, no double-spawn) — suppressed when the Codex FULL fallback fires
 - Doc review: Claude doc-reviewer
 - Performance: Claude api-perf-cost-auditor (if triggered)
 - Security: Claude security-reviewer (if triggered)

package/framework/.claude/skills/prd-add/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: prd-add
+effort: medium
 description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
 ---
 
@@ -16,6 +17,15 @@ need revision, then executes only the affected ones.
 **Overlay:** loads `.baldart/overlays/prd-add.md` if present — and inherits the prd overlay's terminology + design-system reads (since prd-add operates on /prd's artifacts).
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 ## TRIGGER MODES

package/framework/.claude/skills/remotion-best-practices/SKILL.md

@@ -1,10 +1,21 @@
 ---
 name: remotion-best-practices
+effort: medium
 description: Best practices for Remotion - Video creation in React
 metadata:
   tags: remotion, video, react, animation, composition
 ---
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
+
 ## When to use
 
 Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.

package/framework/.claude/skills/seo-audit/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: seo-audit
+effort: medium
 version: 1.0.0
 description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup.
 ---
@@ -8,6 +9,15 @@ description: When the user wants to audit, review, or diagnose SEO issues on the
 
 You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Initial Assessment
 
 **Check for product marketing context first:**

package/framework/.claude/skills/simplify/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: simplify
+effort: medium
 description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Use when completing a coding task, after implementation, or when the user says /simplify. Covers deduplication (exact/near/inline), code quality patterns, and performance.
 ---
 
@@ -12,6 +13,15 @@ description: Review changed code for reuse, quality, and efficiency, then fix an
 **Overlay:** loads `.baldart/overlays/simplify.md` if present — project-specific utility module paths, hook conventions.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 You are a ruthless deduplication and cleanup agent. You do not suggest. You find issues and you eliminate them.

package/framework/.claude/skills/skill-creator/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: skill-creator
+effort: medium
 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 license: Complete terms in LICENSE.txt
 ---
@@ -8,6 +9,15 @@ license: Complete terms in LICENSE.txt
 
 This skill provides guidance for creating effective skills.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## About Skills
 
 Skills are modular, self-contained packages that extend Claude's capabilities by providing
@@ -303,15 +313,18 @@ Any example files and directories not needed for the skill should be deleted. Th
 
 ##### Frontmatter
 
-Write the YAML frontmatter with `name` and `description`:
+Write the YAML frontmatter with `name`, `description`, and `effort`:
 
 - `name`: The skill name
 - `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
   - Include both what the Skill does and specific triggers/contexts for when to use it.
   - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
   - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+- `effort`: The skill's baseline reasoning effort — one of `low | medium | high | xhigh | max`. Pick it by the skill's dominant cognitive load per the tiering rubric in `framework/agents/effort-protocol.md` (routine/lookup → `low`; standard authoring/review → `medium`; deep reasoning/orchestration → `high`). When in doubt, default to `medium` and let the user escalate per-run via the inline override.
+
+Beyond `name`, `description`, and `effort`, do not include other fields in YAML frontmatter.
 
-Do not include any other fields in YAML frontmatter.
+Then paste the `## Effort` body block from `framework/templates/skill-effort.snippet.md` right after `## Project Context` (or after the title if the skill has no Project Context header), so the skill honors the inline `effort=<level>` override. See `framework/agents/effort-protocol.md` for the parsing contract.
 
 ##### Body
 

package/framework/.claude/skills/ui-design/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: ui-design
+effort: medium
 description: "UI design workflow. Generates context-aware mockups with GAN-inspired generator/evaluator separation, visual verification via Playwright, and structured sprint contracts. Use when: (1) designing new pages or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning existing pages, (4) creating design options for user review, (5) any task involving 'design UI', 'mockup', 'opzioni di design', 'progetta interfaccia', '3 opzioni', 'design page', 'UI design'. Not for: bug fixes, small tweaks, copy-only changes, or implementing an already-chosen design."
 ---
 
@@ -29,6 +30,15 @@ own mockups — separating generation from scoring keeps the quality gate honest
 
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ## Working Directory (MANDATORY when invoked from `/prd`, since v3.22.0)
 
 When `/prd` Step 3 invokes this skill, the caller passes (or sets as cwd) an

package/framework/.claude/skills/webapp-testing/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: webapp-testing
+effort: medium
 description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
 license: Complete terms in LICENSE.txt
 ---
@@ -13,6 +14,15 @@ license: Complete terms in LICENSE.txt
 **Overlay:** loads `.baldart/overlays/webapp-testing.md` if present — project-specific test URLs, auth helpers.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 ---
 
 ## E2E Review Integration (since v3.18.0)

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: worktree-manager
+effort: medium
 description: >
   Manage fully independent git worktrees for parallel coding agents.
   Commands: /nw (new worktree) creates an isolated workspace with its own
@@ -21,6 +22,15 @@ description: >
 - `paths.metrics` — JSONL telemetry dir (default `docs/metrics`) used by the rebase conflict-resolution table.
 - Protocol reference: `framework/agents/project-context.md`. Skills must ASK when a needed key is missing — never assume.
 
+## Effort
+
+**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+
+
 **IMMEDIATE EXECUTION**: When invoked via `/nw`, `/mw`, `/lw`, or `/cw`, do NOT explain the process. Start executing the matching command flow immediately:
 
 - `/nw` → Ask for **slug** (required) and optionally a **card ID**, then execute all steps (pre-flight → create → install → build → report). If the user provided args, skip questions and use them directly. Supports three forms:

package/framework/agents/effort-protocol.md

@@ -0,0 +1,121 @@
+# Effort Protocol
+
+## Purpose
+
+Define how BALDART skills (and, by extension, agents) choose a **reasoning
+effort** level: a per-skill *baseline* declared in frontmatter, plus a portable
+*inline override* the user can pass at invocation time. The goal is to let
+routine skills run lean and reasoning-heavy skills run deep — and to let the
+user dial that up or down for a single run without touching config or
+environment.
+
+## Scope
+
+**In**: The `effort:` frontmatter key, its baseline-per-skill rubric, the
+`effort=<level>` inline-override convention, and how a skill body reacts to it.
+**Out**: The native Claude Code effort knob mechanics themselves (slider,
+`/effort` command, `CLAUDE_CODE_EFFORT_LEVEL`) — those are documented by Claude
+Code, not by BALDART. This protocol only governs how skills *use* them.
+
+## Background — the native knob and its precedence
+
+Claude Code supports an `effort:` frontmatter key on skills and subagents with
+values `low | medium | high | xhigh | max` (availability varies by model). When
+that skill/subagent is active, its frontmatter effort overrides the session
+level. The resolution order, highest first, is:
+
+```
+CLAUDE_CODE_EFFORT_LEVEL (env)  >  effort: frontmatter  >  /effort session level  >  model default
+```
+
+Two consequences shape this protocol:
+
+1. **The frontmatter sits *above* the session `/effort` level.** So a user
+   cannot raise a skill's effort just by running `/effort high` first — the
+   frontmatter wins. Only the global env var beats it.
+2. **A running skill cannot mutate the effort knob itself.** There is no tool
+   for a skill to re-set its own effort mid-run.
+
+Therefore the inline override below does **not** drive the native knob. It is a
+**body-level reasoning escalation**: the skill reads the token from its
+arguments and engages the corresponding *thinking directive* (`think hard` …
+`ultrathink`), which the harness interprets from the text. This is fully
+portable — no env var, no consumer config.
+
+## Tiering rubric — choosing a skill's baseline
+
+Assign the frontmatter `effort:` baseline by the skill's dominant cognitive
+load, not by how "important" it feels:
+
+| Baseline | When | Examples of work |
+|----------|------|------------------|
+| `low`    | mechanical, lookup, narration over a deterministic CLI | git plumbing, listing, scaffolding from a fixed template |
+| `medium` | standard authoring/implementation/review work | most skills — design, docs, tests, scaffolding with judgment |
+| `high`   | deep multi-step reasoning, architecture, end-to-end orchestration, structured planning | PRD authoring, root-cause analysis, deep code review |
+| `xhigh` / `max` | reserved — set only when a skill is *consistently* a hard reasoning problem | (rare; prefer raising via inline override instead of pinning the baseline) |
+
+Prefer a conservative baseline plus inline escalation over a permanently high
+baseline: a `medium` skill the user can push to `high` for a hard run costs less
+across the common case than a skill pinned `high` for every trivial invocation.
+
+## Inline override — `effort=<level>`
+
+**Convention.** The user may pass the token `effort=<low|medium|high|xhigh|max>`
+anywhere in the invocation arguments, e.g.:
+
+```
+/prd effort=high  Build a referral program with tiered rewards
+/simplify effort=low
+```
+
+**Parsing contract (every skill that honors overrides MUST follow this):**
+
+1. **Detect once, at kickoff.** Inspect `$ARGUMENTS` for a case-insensitive
+   `effort=<level>` token. Model the parse on the existing `-stats` flag in the
+   `prd` skill — detect early, before the arguments are consumed as content.
+2. **Strip the token.** Remove `effort=<level>` from the argument string before
+   using the remainder as the user's actual input (feature text, target, etc.).
+   The token is control metadata, never part of the payload.
+3. **Validate.** If the level is not one of the five valid values, ignore the
+   token (treat as baseline) and note it; do not error out.
+
+## Level → behavior mapping (the body contract)
+
+Once the effective level is known (inline override if present and valid, else
+the frontmatter baseline), the skill applies:
+
+| Effective level | Reasoning behavior in the body |
+|-----------------|--------------------------------|
+| `low`    | No extended thinking. Execute directly and tersely; skip optional deliberation steps. |
+| `medium` | Normal operation — the skill's default reasoning. |
+| `high`   | Engage **`think hard`** at each decision point / phase boundary. |
+| `xhigh`  | Engage **`think harder`** at each decision point / phase boundary. |
+| `max`    | Engage **`ultrathink`** at each decision point / phase boundary. |
+
+**Honest limits.** Escalation *upward* is reliable (thinking keywords deepen
+reasoning regardless of the frontmatter baseline). De-escalation *below* the
+frontmatter baseline is best-effort: the body can skip optional deliberation,
+but it cannot lower the native budget the frontmatter already set — only the env
+var can. Skills should therefore pick a baseline they are comfortable paying for
+on every run.
+
+## The canonical body block
+
+Every skill that ships an `effort:` baseline pastes a short `## Effort` section
+into its body (right after `## Project Context`, or after the title for skills
+without a Project Context header). Keep it dense — cite this module, do not
+re-explain the mapping:
+
+```markdown
+## Effort
+
+**Baseline:** `effort: <level>` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.
+```
+
+A copy-paste starter lives at `framework/templates/skill-effort.snippet.md`.
+The `skill-creator` skill emits both the `effort:` frontmatter key and this
+block for every new skill.

package/framework/agents/index.md

@@ -31,6 +31,7 @@ Route agents to the right module with minimal reading.
 - If touching security or auth risk -> read `agents/security.md`.
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
+- If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
 - If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
 - For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
 - For legacy context -> read `archive/project_full_legacy.md` if it exists.

package/framework/templates/skill-effort.snippet.md

@@ -0,0 +1,25 @@
+<!--
+  EFFORT HEADER — paste this into any BALDART skill that declares an `effort:`
+  baseline and honors the inline `effort=<level>` override.
+
+  1. Add the frontmatter key (pick the baseline per the tiering rubric):
+
+         effort: medium      # one of: low | medium | high | xhigh | max
+
+  2. Paste the `## Effort` block below right after `## Project Context`
+     (or after the skill title, for skills without a Project Context header).
+     Replace <level> with the same baseline you set in frontmatter.
+
+  Full protocol: framework/agents/effort-protocol.md
+
+  Keep this header DENSE (3-4 lines). Do not re-explain the mapping —
+  cite framework/agents/effort-protocol.md instead.
+-->
+
+## Effort
+
+**Baseline:** `effort: <level>` (frontmatter). **Inline override:** pass
+`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
+reasoning depth for this run — detect it once at kickoff and strip the token
+before consuming user input. Level→behavior mapping, parsing contract, and
+precedence caveats: `framework/agents/effort-protocol.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.1.1",
+  "version": "4.2.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"