baldart 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.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).
+
+> **Why.** Before v4.0.0 the worktree base was hardcoded `origin/develop`, so creation always worked. Making it config-driven was correct, but the missing-key path should degrade to autodetection, not a hard failure — and the safety gate that would have caught the failure was removed in the same release. The fix resolves the trunk the same way `configure.js` already does (`origin/HEAD` → local `develop`/`main`/`master`), which is *not* "assume develop": it resolves the branch the repo actually uses.
+
+### Fixed
+
+- **`worktree-manager` `nw-docs` + `nw` pre-flight** — when `git.trunk_branch` is absent from `baldart.config.yml`, autodetect the real default branch (`git symbolic-ref refs/remotes/origin/HEAD` → first existing local `develop`/`main`/`master`) and warn, instead of `exit 1`. Hard-abort only when even autodetection finds nothing (bare repo / no branches). This unblocks `/prd` and `/new` worktree creation on consumers that updated without re-running `configure`.
+- **`/prd` Step 1 worktree gate** (`prd/references/discovery-phase.md`) — restored from "MONITORING SIGNAL (non-blocking)" back to a **BLOCKING gate**: the kickoff "Ho creato la sessione PRD … in un worktree dedicato" message is emitted only after the worktree is verified on disk; if `nw-docs` aborted, HALT and surface the error verbatim instead of proceeding to Discovery on the main checkout (HARD RULE 17).
+- **`/new` Phase 0 trunk resolution** (`new/SKILL.md`) — when `git.trunk_branch` is absent, `/new` now autodetects the trunk with the **same** `origin/HEAD` → `develop`/`main`/`master` logic as `worktree-manager`, instead of hard-assuming the `develop` literal. Keeps `/new`'s `$TRUNK` (used by the divergence gate and every `git diff "$TRUNK...HEAD"` gate) in lockstep with the branch `nw` actually bases the worktree on — a `main`-trunk repo no longer diverges between the two.
+- **`update.js` schema-drift notice** — when the user declines `configure` and `git.trunk_branch` is among the missing keys, the CLI now states that `/prd` and `/new` will autodetect the trunk and warn until the key is set, replacing the previous (inaccurate for this key) "skills will prompt for the missing keys on first use" reassurance.
+
 ## [4.1.0] - 2026-06-02
 
 **Portability: framework-wide path-literal de-contamination (`docs/…`, `backlog/`, `src/components/…` → `${paths.*}`) + new `paths.docs_dir` config key.** Closes the open follow-up forward-referenced in v4.0.3: a dedicated, per-occurrence judgment pass over the path-literals `contamination.js` flags across `framework/`. The scanner's `autofixable` count drops **219 → 49**; the 49 survivors are legitimate and intentionally kept. The new `paths.docs_dir` config key makes this **MINOR**.

package/VERSION

@@ -1 +1 @@
-4.1.0
+4.2.0

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
@@ -16,7 +17,7 @@ description: >
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; default `develop`), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer`.
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; autodetected from `origin/HEAD` when the key is absent — see Phase 0 step 0), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer`.
 **Gated by features:** `features.has_backlog` (skill REFUSES to run when `false` — this orchestrator operates on backlog cards by definition).
 **Overlay:** loads `.baldart/overlays/new.md` if present — project-specific canonical-docs registry (e.g. ssot-registry, linking-protocol guides), tooling paths (e.g. validation scripts).
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -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)
@@ -130,7 +140,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
 0. **Feature gate + config resolution (BLOCKING)** — before anything else:
    - Read `features.has_backlog` from `baldart.config.yml`. If it is `false` (or the key is absent and the user confirms there is no backlog), this skill REFUSES to run: print "`/new` operates on backlog cards and requires `features.has_backlog: true` — run `npx baldart configure` to enable." and HALT. Do NOT proceed to step 1.
-   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml` (default `develop` only when the key is absent). Persist it as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from config".
+   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml`. **When the key is absent** (consumer updated to ≥4.0.0 without re-running `configure`), do NOT hard-assume `develop` — autodetect the repo's real default branch exactly as worktree-manager does, so `/new` and `nw` agree on the base: `git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD` (strip `refs/remotes/origin/`), else the first existing local branch among `develop` / `main` / `master`. A `main`-trunk repo defaulted to `develop` here would diverge from the worktree base `nw` picks and break every `git diff "$TRUNK...HEAD"` gate. Only HALT ("Trunk branch unresolved — run `npx baldart configure`") if nothing resolves. Persist the resolved value as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from the tracker".
 
 1. **Resolve `$MAIN`** — the absolute path of the main repo (not a worktree). If `/new` was invoked from inside a worktree, walk up to the parent repo via `git rev-parse --show-superproject-working-tree` or `git worktree list` until you find the non-worktree root. Persist as `Main repo:` in the tracker `## Worktree` section. **Write `$MAIN` to the tracker the moment it is computed** — every later consumer (Phase 6c, Phase 6b) MUST re-read it from the tracker and HALT with "`$MAIN` absent from tracker" if the field is missing or empty, never silently use an undefined `$MAIN` (it does not survive context compaction).
 
@@ -1280,7 +1290,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
 
-`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, default `develop`). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
+`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
 
 ```bash
 cd <worktree-path>

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/assets/state-template.md

@@ -6,7 +6,7 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}
 - main_path: {{absolute path of the MAIN repo checkout ($MAIN) — persisted at Step 1 so finalization (validation-phase Step 7.5) never references an undefined var}}
-- trunk_branch: {{resolved git.trunk_branch (default develop)}}
+- trunk_branch: {{resolved git.trunk_branch (autodetected from origin/HEAD when the config key is absent)}}
 - branch: prd/{{slug}}
 - kind: docs
 - created_at: {{ISO-8601 UTC}}

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

@@ -149,12 +149,17 @@ la feature prima di scrivere qualsiasi documento.
 <Progress Bar>
 ```
 
-**MONITORING SIGNAL (non-blocking):** docs worktree created (registry entry with
-`kind: "docs"` present) AND state file exists on disk inside the worktree AND
-all tasks created AND context loaded. These are logged for observability; they
-do not halt execution. Precondition failures that would surface as a STOP are
-already handled by the BLOCKING gates in points 3 and 4 above — this note is
-a post-completion consistency reminder only, not an additional gate.
+**Gate (BLOCKING).** Before leaving Step 1 you MUST verify, on disk, that the
+docs worktree actually exists: `pwd` prints the absolute worktree path AND its
+registry entry (`kind: "docs"`) is present AND the state file exists inside the
+worktree AND all tasks were created AND context loaded. If the worktree was NOT
+created — e.g. `nw-docs` aborted because no trunk branch could be resolved, or
+`.worktrees/` is not in `.gitignore` — **HALT and surface the `nw-docs` error
+verbatim**. Do NOT show the "Ho creato la sessione PRD … in un worktree
+dedicato" message and do NOT proceed to Discovery: writing PRD artefacts on the
+main checkout breaks HARD RULE 17 and pollutes every parallel session. This is a
+hard gate, not an observability note — the kickoff output above is emitted only
+after this gate passes.
 
 **Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
 and ask the mockup intake question in the same turn.

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:
@@ -110,14 +120,30 @@ if [ ! -f "$MAIN_ROOT/.gitignore" ] || ! grep -qE '^\.worktrees/?$' "$MAIN_ROOT/
   exit 1
 fi
 
-# 0b. Resolve the trunk branch from config (R7) — no bare 'develop' literal.
-#     TRUNK MUST be non-empty before any fetch/branch.
+# 0b. Resolve the trunk branch (R7). Prefer the config key; if the consumer
+#     updated to >=4.0.0 without re-running `configure`, `git.trunk_branch` may
+#     be absent — in that case AUTODETECT the repo's real default branch
+#     (origin/HEAD → local develop/main/master) instead of hard-failing. This is
+#     NOT "assume develop": it resolves the branch the repo actually uses, the
+#     same logic configure.js applies. Only abort when even autodetection finds
+#     nothing (bare repo / no branches). Without this fallback a config missing
+#     the v4.0.0 key silently blocked every `/prd` worktree (regression v4.0.0).
 TRUNK=$(grep -A40 '^git:' "$MAIN_ROOT/baldart.config.yml" 2>/dev/null \
   | grep 'trunk_branch:' | head -1 \
   | sed -E 's/.*trunk_branch:[[:space:]]*([A-Za-z0-9._\/-]+).*/\1/' || true)
 if [ -z "$TRUNK" ]; then
-  echo "ERROR: git.trunk_branch not set in baldart.config.yml — ASK the user (never assume 'develop')." >&2
-  exit 1
+  TRUNK=$(git -C "$MAIN_ROOT" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null \
+    | sed -E 's#^refs/remotes/origin/##' || true)
+  if [ -z "$TRUNK" ]; then
+    for cand in develop main master; do
+      if git -C "$MAIN_ROOT" show-ref --verify --quiet "refs/heads/$cand"; then TRUNK="$cand"; break; fi
+    done
+  fi
+  if [ -z "$TRUNK" ]; then
+    echo "ERROR: git.trunk_branch not set in baldart.config.yml and no trunk branch could be autodetected (origin/HEAD / develop / main / master). Run 'npx baldart configure' to set git.trunk_branch, or create the trunk branch first." >&2
+    exit 1
+  fi
+  echo "WARN: git.trunk_branch missing from baldart.config.yml — autodetected '$TRUNK'. Run 'npx baldart configure' to persist it and silence this warning." >&2
 fi
 
 # 1. Pre-flight — read-only fetch, NEVER touches main repo HEAD
@@ -344,12 +370,25 @@ Supports three modes:
 # persist both onto the registry entry created in step 6 (R6). Every later step
 # reads them from the registry with a presence guard — never from in-context state.
 MAIN="$(git rev-parse --show-toplevel)"
+# Prefer git.trunk_branch; autodetect the repo's real default branch if the
+# config key is absent (consumer updated to >=4.0.0 without re-running
+# `configure`). Same fallback as nw-docs — never hard-fail on a resolvable repo.
 TRUNK=$(grep -A40 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
   | grep 'trunk_branch:' | head -1 \
   | sed -E 's/.*trunk_branch:[[:space:]]*([A-Za-z0-9._\/-]+).*/\1/' || true)
 if [ -z "$TRUNK" ]; then
-  echo "ERROR: git.trunk_branch not set in baldart.config.yml — ASK the user (never assume 'develop')." >&2
-  exit 1
+  TRUNK=$(git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null \
+    | sed -E 's#^refs/remotes/origin/##' || true)
+  if [ -z "$TRUNK" ]; then
+    for cand in develop main master; do
+      if git -C "$MAIN" show-ref --verify --quiet "refs/heads/$cand"; then TRUNK="$cand"; break; fi
+    done
+  fi
+  if [ -z "$TRUNK" ]; then
+    echo "ERROR: git.trunk_branch not set in baldart.config.yml and no trunk branch could be autodetected (origin/HEAD / develop / main / master). Run 'npx baldart configure' to set git.trunk_branch, or create the trunk branch first." >&2
+    exit 1
+  fi
+  echo "WARN: git.trunk_branch missing from baldart.config.yml — autodetected '$TRUNK'. Run 'npx baldart configure' to persist it." >&2
 fi
 
 # Fetch latest trunk from remote — read-only, does NOT touch the main repo's HEAD.

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.0",
+  "version": "4.2.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/update.js

@@ -1172,6 +1172,11 @@ async function update(options = {}, unknownArgs = []) {
                 await configureCmd(autoYes ? { nonInteractive: true } : undefined);
               } else {
                 UI.info('Skipped. Skills will prompt for the missing keys on first use.');
+                if (allMissing.includes('git.trunk_branch')) {
+                  UI.warning('`git.trunk_branch` drives worktree creation in `/prd` and `/new`. '
+                    + 'Until it is set, those skills autodetect the trunk (origin/HEAD → develop/main/master) '
+                    + 'and warn on each run; run `npx baldart configure` to persist it and make it deterministic.');
+                }
               }
             }
           } catch (_) {