forge-behavior

name	forge-behavior
description	Manage dotforge v3 behavior governance — view status, toggle behaviors, adjust strictness. Use when the user asks about active behaviors, wants to disable one for the current session, or adjust escalation thresholds.

/forge behavior

Thin wrapper around scripts/forge-behavior/cli.sh. Dispatches behavior governance actions. This skill is part of dotforge v3 (Phase 1 of behavior governance) and should only be used inside dotforge itself or projects that have adopted v3 — not on v2.9 projects.

When to use

Invoke this skill when the user asks any of:

• "What behaviors are active?"
• "What's the counter on search-first?"
• "Disable search-first for this session"
• "Turn off the nudge on writes"
• "Make search-first stricter / more relaxed"

Do NOT invoke this skill for v2.9 configuration tasks (use /forge audit, /forge sync, etc.) or for behaviors that have not yet been catalogued (Phase 1 only ships search-first).

Actions

scripts/forge-behavior/cli.sh status [--session SESSION_ID]
scripts/forge-behavior/cli.sh on  <behavior_id> [--project | --session SESSION_ID]
scripts/forge-behavior/cli.sh off <behavior_id> [--project | --session SESSION_ID]
scripts/forge-behavior/cli.sh strict  <behavior_id>
scripts/forge-behavior/cli.sh relaxed <behavior_id>

status — Print the current catalogue (behaviors/index.yaml) plus a per-session summary from .forge/runtime/state.json: counters, effective levels, override counts, pending_block status, and any session-scope overrides.

on / off — Toggle a behavior's active state.

• --project (default): mutates behaviors/index.yaml. Persistent. After changing, recompile the behavior with scripts/compiler/compile.sh behaviors/<id>/behavior.yaml <output_dir> and restart Claude Code so the new hook registration takes effect.
• --session SESSION_ID: mutates only .forge/runtime/state.json's behavior_overrides[] for that session. The compiled hook short-circuits silently when disabled. No recompile needed. Effect lasts until the session is purged by TTL.

strict / relaxed — Mutate behaviors/<id>/behavior.yaml escalation:

• strict: halves each after threshold, minimum 1. Makes violations escalate sooner.
• relaxed: doubles each after threshold. Makes violations escalate later.
• Both project-scope only in v1. Session-scope strictness deferred to Phase 2 — the runtime would need to pass a strictness multiplier into forge_resolve_level, which v1 does not support.

Preconditions

• jq must be installed (runtime requirement).
• python3 with pyyaml must be installed (YAML reading/writing).
• The project must already have behaviors/index.yaml. If missing, create one with behaviors: [] and populate via on <id>.

Scope matrix

Action	--project	--session
status	always shown	filters to one session
on / off	mutates index.yaml	writes to state.json
strict	mutates yaml	(not implemented v1)
relaxed	mutates yaml	(not implemented v1)

Example flows

Check what is active right now:

/forge behavior status

Silence search-first for a noisy debugging session:

/forge behavior off search-first --session <session_id>

Tighten up for strict development mode:

/forge behavior strict search-first
# then recompile and restart

Notes

• The CLI honors FORGE_BEHAVIORS_DIR as an override of behaviors/ location — useful for tests and isolated environments.
• Direct tool result for tests: scripts/forge-behavior/tests/run_all.sh.