chief-clancy 0.5.12 → 0.7.0

package/src/agents/verification-gate.md

@@ -0,0 +1,128 @@
+# Verification Gate Agent
+
+You are the verification gate agent for Clancy. You run as a `type: "agent"` Stop hook in Claude Code. Your job is to run lint, test, and typecheck before delivery — and block the stop if any check fails, giving the implementation agent a chance to fix the errors.
+
+You have full tool access: Read, Edit, Write, Glob, Grep, Bash. NEVER ask the user questions — this runs autonomously with no human present.
+
+## Instructions
+
+Work through the following steps in order. Exit early whenever an early-exit condition is met.
+
+### Step 1 — Check if in a Clancy run
+
+Read `.clancy/lock.json` in the project root. If the file does not exist, this is not a Clancy implementation session. Respond immediately:
+
+```json
+{"decision": "allow"}
+```
+
+### Step 2 — Check for stop hook recursion
+
+Check the hook input for `stop_hook_active: true`. If set, respond immediately to prevent infinite loops:
+
+```json
+{"decision": "allow"}
+```
+
+### Step 3 — Read retry state
+
+Read `.clancy/verify-attempt.txt` from the project root. If the file does not exist, this is attempt 1. If it exists, parse the number inside it — that number is the current attempt.
+
+### Step 4 — Check max retries
+
+Read the `CLANCY_FIX_RETRIES` environment variable. Default to `2` if not set.
+
+**Special case: `CLANCY_FIX_RETRIES=0`** means "verify once but never retry." On attempt 1, run checks normally. If they fail, write `1` to `.clancy/verify-attempt.txt` and respond with `{"decision": "allow"}` — do NOT block. The PR body will include the verification warning. On attempt 2+, allow immediately.
+
+**Normal case: `CLANCY_FIX_RETRIES >= 1`** — The first attempt (attempt 1) ALWAYS runs verification. On subsequent attempts, check if retries are exhausted: if the current attempt is greater than `maxRetries + 1`, max retries have been exhausted (attempt 1 = initial check, attempts 2 through maxRetries+1 = fix retries). When exhausted, keep `.clancy/verify-attempt.txt` in place (the delivery flow reads it to add a verification warning to the PR body). Respond immediately:
+
+```json
+{"decision": "allow"}
+```
+
+The PR body will include a verification warning — delivery should not be blocked indefinitely.
+
+### Step 5 — Detect check commands
+
+First check for the `CLANCY_VERIFY_COMMANDS` environment variable. If set, use its value as a comma-separated list of **full shell commands** to run (e.g. `npm run lint,npm test,npm run typecheck`). Execute each command directly via Bash — do NOT wrap in `npm run`. Skip auto-detection.
+
+If `CLANCY_VERIFY_COMMANDS` is not set, read `package.json` and inspect the `scripts` object. Auto-detect checks by matching script names:
+
+| Script name pattern | Check type |
+|---|---|
+| `lint`, `eslint` | lint |
+| `test`, `vitest`, `jest` | test |
+| `typecheck`, `tsc`, `check-types` | typecheck |
+
+Match exact script names only — do not match partial names like `test:e2e` or `lint:fix`. Use the first match per check type.
+
+If no check commands are detected at all, respond immediately:
+
+```json
+{"decision": "allow"}
+```
+
+### Step 6 — Run checks
+
+Execute each detected command using Bash: `npm run <script-name>`. Run them sequentially (not in parallel) so output is clear. Capture both stdout and stderr for each command.
+
+Truncate each command's output to the last 500 lines. This prevents overwhelming context on large test suites.
+
+Track which checks passed and which failed.
+
+### Step 7 — All checks passed
+
+If every check exits with code 0, delete `.clancy/verify-attempt.txt` if it exists, then respond:
+
+```json
+{"decision": "allow"}
+```
+
+### Step 8 — One or more checks failed
+
+If any check fails:
+
+1. Write the next attempt number to `.clancy/verify-attempt.txt` (current attempt + 1).
+2. Build the reason string with the format below.
+3. Respond with a block decision.
+
+Read `CLANCY_FIX_RETRIES` (default 2) to determine the max. Use the current attempt number and max to select an escalation hint:
+
+- **Attempt 1**: "Fix the specific errors reported above."
+- **Attempt 2**: "If the same errors persist, consider reverting the problematic change and taking a different approach."
+- **Attempt 3+**: "Consider reverting to the last known working state. Focus on delivering working code rather than complete code."
+
+Response format:
+
+```json
+{
+  "decision": "block",
+  "reason": "Verification failed (attempt N of M):\n\n[check name]: FAILED\n[truncated output — last 500 lines]\n\n[check name]: PASSED\n\n[escalation hint]"
+}
+```
+
+Include output only for failed checks. List passed checks on a single line with no output.
+
+---
+
+## Fail-open rule
+
+If the agent itself encounters an unexpected error at any point (file read failure, malformed JSON, missing tool, etc.), respond with:
+
+```json
+{"decision": "allow"}
+```
+
+Never crash or leave the stop unresolved. The gate is a safety net, not a hard barrier.
+
+---
+
+## Rules
+
+- NEVER ask the human questions. This runs autonomously as a stop hook.
+- NEVER modify source code. Your job is to run checks and report — the implementation agent fixes errors on the retry.
+- Always respond with exactly one JSON object: `{"decision": "allow"}` or `{"decision": "block", "reason": "..."}`.
+- No other output format is accepted. Do not wrap the JSON in markdown code fences in your final response.
+- Truncate command output to 500 lines maximum per check. Prefer the tail (last N lines) — error summaries are usually at the end.
+- Sequential execution only — run one check at a time so failures are clearly attributed.
+- Clean up `.clancy/verify-attempt.txt` on success only. On max-retries-exhausted, keep the file so the delivery flow can detect it and add a verification warning to the PR body.

package/src/roles/planner/workflows/approve-plan.md

@@ -22,7 +22,7 @@ Promote an approved Clancy plan from a ticket comment to the ticket description.
 
 ### If no argument provided:
 
-1. Scan `.clancy/progress.txt` for entries matching `| PLAN |` or `| REVISED |` that have no subsequent `| APPROVE |` for the same key.
+1. Scan `.clancy/progress.txt` for entries matching `| PLAN |` or `| REVISED |` that have no subsequent `| APPROVE_PLAN |` for the same key.
 2. Sort by timestamp ascending (oldest first).
 3. If 0 found:
    ```
@@ -456,7 +456,7 @@ Plan promoted. Moved to unstarted. Ready for /clancy:once.
 
 Append to `.clancy/progress.txt`:
 ```
-YYYY-MM-DD HH:MM | {KEY} | APPROVE | —
+YYYY-MM-DD HH:MM | {KEY} | APPROVE_PLAN | —
 ```
 
 On failure:

package/src/roles/reviewer/workflows/logs.md

@@ -28,22 +28,23 @@ Each line has one of these formats:
 - `YYYY-MM-DD HH:MM | TICKET-KEY | REVIEW | {score}%` — ticket review
 - `YYYY-MM-DD HH:MM | TICKET-KEY | PLAN | {S/M/L}` — plan generated
 - `YYYY-MM-DD HH:MM | TICKET-KEY | REVISED | {S/M/L}` — plan revised after feedback
-- `YYYY-MM-DD HH:MM | TICKET-KEY | APPROVE | —` — plan promoted to description
+- `YYYY-MM-DD HH:MM | TICKET-KEY | APPROVE_PLAN | —` — plan promoted to description
 - `YYYY-MM-DD HH:MM | TICKET-KEY | SKIPPED | {reason}` — ticket skipped
 - `YYYY-MM-DD HH:MM | TICKET-KEY | POST_FAILED | {reason}` — failed to post comment to board
+- `YYYY-MM-DD HH:MM | BRIEF | {slug} | {N} proposed tickets` — brief generated (slug-based format)
+- `YYYY-MM-DD HH:MM | APPROVE_BRIEF | {slug} | {N} tickets created` — brief approved (slug-based format)
 
 Parse each line:
 - Date (YYYY-MM-DD)
 - Time (HH:MM)
-- Ticket key (e.g. PROJ-42)
-- Action type (DONE, REVIEW, PLAN, REVISED, APPROVE, SKIPPED, POST_FAILED, or summary text)
-- Detail (status, score, size, or reason)
+- Key or status (BRIEF/APPROVE_BRIEF entries put the status here, standard entries put the ticket key)
+- Detail (status, score, size, reason, or slug for brief entries)
 
 Extract:
 - Total DONE tickets
 - First and latest run dates
 - All DONE tickets from the current calendar week (Mon–Sun)
-- Counts for each action type: PLAN, REVISED, APPROVE, REVIEW, SKIPPED, POST_FAILED
+- Counts for each action type: PLAN, REVISED, APPROVE_PLAN, REVIEW, SKIPPED, POST_FAILED, BRIEF, APPROVE_BRIEF
 - Epic key from ticket key — e.g. PROJ-42 → epic likely PROJ-10 (use parent field if logged, otherwise group by project prefix)
 
 ---
@@ -75,6 +76,8 @@ By epic:
 Plans generated: {N}      (only show if > 0)
 Plans revised: {N}        (only show if > 0)
 Plans approved: {N}       (only show if > 0)
+Briefs generated: {N}     (only show if > 0)
+Briefs approved: {N}      (only show if > 0)
 Reviews run: {N}          (only show if > 0)
 Tickets skipped: {N}      (only show if > 0)
 Post failures: {N}        (only show if > 0)
@@ -90,7 +93,7 @@ Full log: .clancy/progress.txt
 - Progress bars: ASCII, proportional to highest count, width 10 chars, `█` filled, `░` empty
 - Epic grouping: group by epic key in the ticket's parent field (from progress.txt if logged), or by project prefix if not available
 - Tickets without an epic: group under `(other)`
-- REVIEW, PLAN, REVISED, APPROVE, SKIPPED, and POST_FAILED lines: shown separately at the end as counts — not included in ticket count
+- REVIEW, PLAN, REVISED, APPROVE_PLAN, BRIEF, APPROVE_BRIEF, SKIPPED, and POST_FAILED lines: shown separately at the end as counts — not included in ticket count
 
 ---
 

package/src/roles/setup/commands/help.md

@@ -22,6 +22,13 @@ integration, structured codebase docs, and a git workflow built for team develop
 | `/clancy:plan --fresh` | Discard any existing plan and start from scratch |
 | `/clancy:approve-plan` | Promote an approved plan to the ticket description |
 
+### Strategist *(optional — enable via `CLANCY_ROLES=strategist` in `.clancy/.env`)*
+
+| Command | Description |
+|---|---|
+| `/clancy:brief` | Generate a strategic brief (research + grill + decomposition) |
+| `/clancy:approve-brief` | Convert a brief into tickets on the board |
+
 ### Implementer
 
 | Command | Description |

package/src/roles/setup/workflows/init.md

@@ -452,6 +452,51 @@ If [2]: store `CLANCY_MODE=afk` in `.clancy/.env`.
 
 ---
 
+### Q3h (all boards): Reliable autonomous mode
+
+Output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Reliable Autonomous Mode
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+These settings control self-healing and safety limits for autonomous runs.
+```
+
+**Fix retries:**
+
+```
+Max self-healing attempts after a verification failure? [2]
+(Range: 0–5. When lint/test/typecheck fails, Clancy retries up to this many times before delivering anyway.)
+```
+
+If a number 0–5 is entered: store as `CLANCY_FIX_RETRIES` in `.clancy/.env`.
+If enter is pressed with no value: use default 2 — store `CLANCY_FIX_RETRIES=2` in `.clancy/.env`.
+If the value is outside 0–5: re-prompt.
+
+**Time limit:**
+
+```
+Per-ticket time limit in minutes? [30]
+(0 to disable. Clancy will stop working on a ticket after this many minutes.)
+```
+
+If a non-negative integer is entered: store as `CLANCY_TIME_LIMIT` in `.clancy/.env`.
+If enter is pressed with no value: use default 30 — store `CLANCY_TIME_LIMIT=30` in `.clancy/.env`.
+If the value is negative or not a number: re-prompt.
+
+**Branch guard:**
+
+```
+Enable branch guard hook? Prevents accidental commits to the base branch. [Y/n]
+```
+
+If `y`, `Y`, or enter: store `CLANCY_BRANCH_GUARD=true` in `.clancy/.env`.
+If `n` or `N`: store `CLANCY_BRANCH_GUARD=false` in `.clancy/.env`.
+
+---
+
 ### Q4: Base branch (auto-detect)
 
 Silently detect the base branch — do not ask unless detection fails:
@@ -513,18 +558,30 @@ If no: skip the commit silently. The user can commit manually later.
 Clancy includes the Implementer, Reviewer, and Setup roles by default. Optional roles add extra capabilities.
 
 ```
-Clancy includes the Implementer, Reviewer, and Setup roles by default.
-You can enable additional roles:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Optional Roles
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  [1] Planner   — Refine vague tickets into structured implementation plans
+Core roles (always installed): Implementer, Reviewer, Setup
 
-Enter roles to enable (e.g. 1 or "all") or press Enter to skip:
+Additional roles extend what Clancy can do:
+
+  [1] Planner
+      Refine vague tickets into structured implementation plans.
+      Commands: /clancy:plan, /clancy:approve-plan
+
+  [2] Strategist
+      Generate strategic briefs — research the codebase, grill
+      requirements, decompose into tickets with dependencies.
+      Commands: /clancy:brief, /clancy:approve-brief
+
+Enable: 1, 2, all, or Enter to skip
 ```
 
-Accept numbers, role names (e.g. "planner"), "all", or Enter to skip.
+Accept numbers, role names (e.g. "planner", "strategist"), "all", or Enter to skip.
 
 If any roles are selected:
-- Store as `CLANCY_ROLES="planner"` (comma-separated if multiple) in `.clancy/.env`
+- Store as `CLANCY_ROLES="planner,strategist"` (comma-separated if multiple) in `.clancy/.env`
 - The selected roles' commands and workflows will be installed on the next `npx chief-clancy` run
 
 If skipped (Enter): no `CLANCY_ROLES` line is written — only core roles are installed.
@@ -608,6 +665,54 @@ If [2]: skip — no `CLANCY_STATUS_PLANNED` line written.
 
 ---
 
+## Step 4f (if Strategist role selected): Strategist config
+
+Only ask this if the user selected Strategist in Step 4c above (or if re-running init and `CLANCY_ROLES` already includes `strategist`).
+
+If the strategist role is not enabled, skip this step entirely.
+
+**All boards:** Output:
+
+```
+Default parent epic/milestone for briefs created from text or file input?
+This sets CLANCY_BRIEF_EPIC so tickets created by /clancy:brief are parented automatically.
+
+[1] Skip — no default parent (set per-brief or omit)
+[2] Enter an epic key (e.g. PROJ-100, #42, ENG-50)
+```
+
+If [1]: skip — no `CLANCY_BRIEF_EPIC` line written.
+If [2]: prompt for the value, store as `CLANCY_BRIEF_EPIC` in `.clancy/.env`. Wrap in double quotes.
+
+**Jira only:** Output:
+
+```
+What issue type should /clancy:brief use when creating tickets? [Task]
+
+[1] Task (default)
+[2] Story
+[3] Enter a different value
+```
+
+If [1] or enter: do not add `CLANCY_BRIEF_ISSUE_TYPE` to `.clancy/.env` (uses default `Task`).
+If [2]: store `CLANCY_BRIEF_ISSUE_TYPE="Story"` in `.clancy/.env`.
+If [3]: prompt for the value, store as `CLANCY_BRIEF_ISSUE_TYPE` in `.clancy/.env`. Wrap in double quotes.
+
+**All boards:** Output:
+
+```
+Auto-set a component on tickets created by /clancy:brief?
+Only affects ticket creation — does not filter the implementation queue.
+
+[1] Skip — no component
+[2] Enter a component name
+```
+
+If [1]: skip — no `CLANCY_COMPONENT` line written.
+If [2]: prompt for the value, store as `CLANCY_COMPONENT` in `.clancy/.env`. Wrap in double quotes.
+
+---
+
 ## Step 5 — Optional enhancements
 
 Output:

package/src/roles/setup/workflows/scaffold.md

@@ -412,6 +412,17 @@ MAX_ITERATIONS=5
 # Can also be overridden per-invocation with --afk flag.
 # CLANCY_MODE=interactive
 
+# ─── Optional: Strategist ───────────────────────────────────────────────────
+# Issue type for tickets created by /clancy:brief (Jira only, default: Task)
+# CLANCY_BRIEF_ISSUE_TYPE="Task"
+
+# Default parent epic for briefs created from text or file input
+# CLANCY_BRIEF_EPIC="PROJ-100"
+
+# Auto-set on tickets created by /clancy:brief.
+# Only affects ticket creation — does not filter the implementation queue.
+# CLANCY_COMPONENT="frontend"
+
 # ─── Optional: Planner queue ─────────────────────────────────────────────────
 # Status for backlog tickets that /clancy:plan fetches from (default: Backlog)
 # Only used if Planner role is enabled via CLANCY_ROLES
@@ -425,6 +436,16 @@ MAX_ITERATIONS=5
 # Set to "false" to disable skip comments
 # CLANCY_SKIP_COMMENTS=true
 
+# ─── Optional: Reliable autonomous mode ───────────────────────────────────────
+# Max self-healing attempts after verification failure (default: 2, range 0-5)
+# CLANCY_FIX_RETRIES=2
+
+# Per-ticket time limit in minutes (default: 30, 0 to disable)
+# CLANCY_TIME_LIMIT=30
+
+# Prevent accidental commits to the base branch (default: true)
+# CLANCY_BRANCH_GUARD=true
+
 # ─── Optional: Notifications ──────────────────────────────────────────────────
 # Webhook URL for Slack or Teams notifications on ticket completion
 # CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url
@@ -497,11 +518,29 @@ MAX_ITERATIONS=20
 # Can also be overridden per-invocation with --afk flag.
 # CLANCY_MODE=interactive
 
+# ─── Optional: Strategist ───────────────────────────────────────────────────
+# Default parent epic/milestone for briefs created from text or file input
+# CLANCY_BRIEF_EPIC="#42"
+
+# Auto-set on tickets created by /clancy:brief.
+# Only affects ticket creation — does not filter the implementation queue.
+# CLANCY_COMPONENT="frontend"
+
 # ─── Optional: Skip comments ──────────────────────────────────────────────
 # When Clancy skips a ticket (irrelevant/infeasible), post a comment explaining why
 # Set to "false" to disable skip comments
 # CLANCY_SKIP_COMMENTS=true
 
+# ─── Optional: Reliable autonomous mode ───────────────────────────────────────
+# Max self-healing attempts after verification failure (default: 2, range 0-5)
+# CLANCY_FIX_RETRIES=2
+
+# Per-ticket time limit in minutes (default: 30, 0 to disable)
+# CLANCY_TIME_LIMIT=30
+
+# Prevent accidental commits to the base branch (default: true)
+# CLANCY_BRANCH_GUARD=true
+
 # ─── Optional: Notifications ──────────────────────────────────────────────────
 # Webhook URL for Slack or Teams notifications on ticket completion
 # CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url
@@ -579,6 +618,14 @@ MAX_ITERATIONS=20
 # Can also be overridden per-invocation with --afk flag.
 # CLANCY_MODE=interactive
 
+# ─── Optional: Strategist ───────────────────────────────────────────────────
+# Default parent epic for briefs created from text or file input
+# CLANCY_BRIEF_EPIC="ENG-50"
+
+# Auto-set on tickets created by /clancy:brief.
+# Only affects ticket creation — does not filter the implementation queue.
+# CLANCY_COMPONENT="frontend"
+
 # ─── Optional: Git host (PR creation) ───────────────────────────────────────
 # When an issue has no parent, Clancy pushes the feature branch and creates a
 # pull request instead of squash-merging locally. Requires a git host token.
@@ -589,6 +636,16 @@ MAX_ITERATIONS=20
 # CLANCY_GIT_PLATFORM=gitlab               # override auto-detection (github/gitlab/bitbucket)
 # CLANCY_GIT_API_URL=https://gitlab.example.com/api/v4  # self-hosted git API base URL
 
+# ─── Optional: Reliable autonomous mode ───────────────────────────────────────
+# Max self-healing attempts after verification failure (default: 2, range 0-5)
+# CLANCY_FIX_RETRIES=2
+
+# Per-ticket time limit in minutes (default: 30, 0 to disable)
+# CLANCY_TIME_LIMIT=30
+
+# Prevent accidental commits to the base branch (default: true)
+# CLANCY_BRANCH_GUARD=true
+
 # ─── Optional: Skip comments ──────────────────────────────────────────────
 # When Clancy skips a ticket (irrelevant/infeasible), post a comment explaining why
 # Set to "false" to disable skip comments

package/src/roles/setup/workflows/settings.md

@@ -9,6 +9,7 @@ View and change Clancy configuration. Reads `.clancy/.env`, shows current values
 This workflow runs inside a Claude Code session. Accept natural language alongside option codes:
 - "G1", "max iterations", "change iterations" → all resolve to the max iterations setting
 - "enable planner", "R1", "planner" → all resolve to the Planner role toggle
+- "enable strategist", "R2", "strategist" → all resolve to the Strategist role toggle
 - "switch board", "S" → switch board flow
 - If a response is ambiguous, ask for clarification
 
@@ -54,6 +55,9 @@ General
   [G4] Max rework        {CLANCY_MAX_REWORK:-3}
   [G5] TDD mode          {on if CLANCY_TDD=true, else off}
   [G6] Grill mode         {CLANCY_MODE:-interactive}
+  [G7] Fix retries        {CLANCY_FIX_RETRIES:-2}          self-healing attempts after verification failure
+  [G8] Time limit         {CLANCY_TIME_LIMIT:-30}          per-ticket time limit in minutes (0 = disabled)
+  [G9] Branch guard       {on if CLANCY_BRANCH_GUARD=true or unset, off if false}
 
 {If Jira:}
 Jira
@@ -73,6 +77,14 @@ Linear
 
 Roles
   [R1] Planner           {✅ enabled / ─ disabled}
+  [R2] Strategist        {✅ enabled / ─ disabled}
+
+{If Strategist enabled:}
+Strategist
+  [T1] Brief epic        {CLANCY_BRIEF_EPIC if set, else "off"}
+{If Jira:}
+  [T2] Issue type        {CLANCY_BRIEF_ISSUE_TYPE:-Task}
+  [T3] Component         {CLANCY_COMPONENT if set, else "off"}
 
 {If Planner enabled:}
 Planner
@@ -205,6 +217,59 @@ If [2]: write `CLANCY_MODE=afk` to `.clancy/.env`.
 
 ---
 
+### [G7] Fix retries
+
+```
+Fix retries — current: {value or 2}
+Max self-healing attempts after a verification failure (lint/test/typecheck).
+When exhausted, Clancy delivers anyway with a warning in the PR body.
+
+[1] 2 (default)
+[2] Enter a different number (0–5)
+[3] Cancel
+```
+
+Validate the input is an integer between 0 and 5. If invalid, re-prompt.
+
+If [1]: remove `CLANCY_FIX_RETRIES` from `.clancy/.env` (uses default).
+If [2]: prompt `How many fix retries?` then write `CLANCY_FIX_RETRIES=<value>` to `.clancy/.env`.
+
+---
+
+### [G8] Time limit
+
+```
+Time limit — current: {value or 30} minutes
+Per-ticket time limit. Clancy stops working on a ticket after this many minutes.
+Set to 0 to disable.
+
+[1] 30 minutes (default)
+[2] Enter a different number
+[3] Cancel
+```
+
+Validate the input is a non-negative integer. If invalid, re-prompt.
+
+If [1]: remove `CLANCY_TIME_LIMIT` from `.clancy/.env` (uses default).
+If [2]: prompt `Time limit in minutes? (0 to disable)` then write `CLANCY_TIME_LIMIT=<value>` to `.clancy/.env`.
+
+---
+
+### [G9] Branch guard
+
+```
+Branch guard — current: {on/off}
+Prevents accidental commits to the base branch during autonomous runs.
+
+[1] Enable (default)
+[2] Disable
+```
+
+If [1]: write `CLANCY_BRANCH_GUARD=true` to `.clancy/.env`.
+If [2]: write `CLANCY_BRANCH_GUARD=false` to `.clancy/.env`.
+
+---
+
 ### [B1] Jira status filter (Jira only)
 
 ```
@@ -394,6 +459,86 @@ If disabling:
 
 ---
 
+### [R2] Strategist role
+
+```
+Strategist role — currently: {enabled / disabled}
+The Strategist generates strategic briefs and creates tickets on the board.
+Commands: /clancy:brief, /clancy:approve-brief
+
+[1] Enable
+[2] Disable
+[3] Cancel
+```
+
+If enabling:
+- Add `strategist` to `CLANCY_ROLES` in `.clancy/.env` (create the key if it doesn't exist, append if other roles are listed)
+- Show `✅ Strategist role enabled. Re-run the installer to apply: npx chief-clancy@latest --local (or --global)`
+
+If disabling:
+- Remove `strategist` from `CLANCY_ROLES` in `.clancy/.env` (if empty after removal, remove the line entirely)
+- Keep strategist-specific settings (CLANCY_BRIEF_EPIC, CLANCY_BRIEF_ISSUE_TYPE, CLANCY_COMPONENT) in `.clancy/.env` so re-enabling is frictionless
+- Show `✅ Strategist role disabled. Re-run the installer to apply: npx chief-clancy@latest --local (or --global)`
+
+---
+
+### [T1] Brief epic
+
+Only shown when Strategist is enabled.
+
+```
+Brief epic — current: {value or "off"}
+Default parent epic/milestone for briefs created from text or file input.
+
+[1] Set epic key (e.g. PROJ-100, #42, ENG-50)
+[2] Off (no default parent)
+[3] Cancel
+```
+
+If [1]: prompt `What epic key should /clancy:brief parent tickets under?` then write `CLANCY_BRIEF_EPIC=<value>` to `.clancy/.env`. Wrap in double quotes.
+If [2]: remove `CLANCY_BRIEF_EPIC` from `.clancy/.env`.
+
+---
+
+### [T2] Issue type (Jira only)
+
+Only shown when Strategist is enabled and board is Jira.
+
+```
+Brief issue type — current: {value or "Task"}
+Issue type used when /clancy:brief creates tickets on the board.
+
+[1] Task (default)
+[2] Story
+[3] Enter a different value
+[4] Cancel
+```
+
+If [1]: remove `CLANCY_BRIEF_ISSUE_TYPE` from `.clancy/.env` (uses default).
+If [2]: write `CLANCY_BRIEF_ISSUE_TYPE="Story"` to `.clancy/.env`.
+If [3]: prompt `What issue type should /clancy:brief use?` then write `CLANCY_BRIEF_ISSUE_TYPE=<value>` to `.clancy/.env`. Wrap in double quotes.
+
+---
+
+### [T3] Component
+
+Only shown when Strategist is enabled.
+
+```
+Component — current: {value or "off"}
+Auto-set on tickets created by /clancy:brief.
+Only affects ticket creation — does not filter the implementation queue.
+
+[1] Set component name
+[2] Off (no component)
+[3] Cancel
+```
+
+If [1]: prompt `What component should /clancy:brief set on created tickets?` then write `CLANCY_COMPONENT=<value>` to `.clancy/.env`. Wrap in double quotes.
+If [2]: remove `CLANCY_COMPONENT` from `.clancy/.env`.
+
+---
+
 ### [P1] Plan queue status (Jira only)
 
 ```

package/src/roles/setup/workflows/update.md

@@ -212,6 +212,23 @@ Display completion message:
 View full changelog: github.com/Pushedskydiver/clancy/blob/main/CHANGELOG.md
 ```
 
+### New role hints
+
+After the completion message, check `.clancy/.env` for `CLANCY_ROLES` and display hints for any optional roles that are available but not enabled:
+
+- If `CLANCY_ROLES` does not include `planner`:
+  ```
+  💡 Planner role available — refine vague tickets into structured plans.
+     Run /clancy:settings to enable it.
+  ```
+- If `CLANCY_ROLES` does not include `strategist`:
+  ```
+  💡 Strategist role available — generate briefs, grill requirements, create tickets.
+     Run /clancy:settings to enable it.
+  ```
+- If `CLANCY_ROLES` is not set at all (env var missing), show both hints.
+- If all optional roles are already enabled, show nothing.
+
 ---
 
 ## Notes
@@ -219,3 +236,4 @@ View full changelog: github.com/Pushedskydiver/clancy/blob/main/CHANGELOG.md
 - If the user installed globally, the update applies globally
 - If the user installed locally, the update applies locally
 - After updating, restart Claude Code for new commands to take effect
+- New role hints are shown post-update so existing users discover features added in newer versions

package/src/roles/strategist/commands/approve-brief.md

@@ -0,0 +1,20 @@
+# /clancy:approve-brief
+
+Convert an approved brief into real tickets on the board. Creates child tickets under the parent, links dependencies, and posts a tracking summary.
+
+Accepts optional arguments:
+- **By slug:** `/clancy:approve-brief auth-rework` — approve a specific brief
+- **By index:** `/clancy:approve-brief 2` — approve the 2nd unapproved brief
+- **By ticket:** `/clancy:approve-brief PROJ-123` — approve brief sourced from this ticket
+- **Set parent:** `--epic PROJ-50` — override or set the parent epic
+- **Preview:** `--dry-run` — show what would be created without making API calls
+
+Examples:
+- `/clancy:approve-brief` — auto-select (if only 1 unapproved brief)
+- `/clancy:approve-brief auth-rework` — approve by slug
+- `/clancy:approve-brief --dry-run` — preview ticket creation
+- `/clancy:approve-brief --epic PROJ-50` — set parent and approve
+
+@.claude/clancy/workflows/approve-brief.md
+
+Follow the approve-brief workflow above. Parse the decomposition, create tickets on the board, link dependencies, and post a tracking comment.