chief-clancy 0.5.0 → 0.5.2

package/README.md

@@ -168,7 +168,37 @@ npx chief-clancy
 | `/clancy:uninstall`    | Remove Clancy commands — optionally remove `.clancy/` too               |
 | `/clancy:help`         | Command reference                                                        |
 
-¹ Planner is an optional role. Enable with `CLANCY_ROLES=planner` in `.clancy/.env` and re-run the installer.
+¹ Planner is an optional role — see [Roles](#roles) below.
+
+---
+
+## Roles
+
+Clancy organises its commands into **roles** — each role handles a different stage of the development workflow.
+
+| Role | Purpose | Commands |
+| --- | --- | --- |
+| **Implementer** | Plan → code. Picks up tickets, implements, commits, merges | `/clancy:once`, `/clancy:run`, `/clancy:dry-run` |
+| **Reviewer** | Score ticket readiness and track progress | `/clancy:review`, `/clancy:status`, `/clancy:logs` |
+| **Setup** | Configure and maintain Clancy | `/clancy:init`, `/clancy:settings`, `/clancy:doctor`, etc. |
+| **Planner** *(optional)* | Refine backlog tickets into structured implementation plans | `/clancy:plan`, `/clancy:approve` |
+
+**Core roles** (Implementer, Reviewer, Setup) are always installed. **Optional roles** (Planner) are opt-in — add them to `CLANCY_ROLES` in `.clancy/.env` and re-run the installer:
+
+```bash
+# Enable the Planner role
+echo 'CLANCY_ROLES="planner"' >> .clancy/.env
+npx chief-clancy@latest --local   # or --global
+```
+
+You can also toggle roles from within Claude Code using `/clancy:settings`.
+
+Each role has detailed documentation:
+
+- [Implementer](docs/roles/IMPLEMENTER.md) — picks up tickets, implements, commits, merges (AFK loop support)
+- [Reviewer](docs/roles/REVIEWER.md) — scores ticket readiness, tracks progress
+- [Setup & Maintenance](docs/roles/SETUP.md) — init wizard, settings, diagnostics, codebase mapping
+- [Planner](docs/roles/PLANNER.md) — refines backlog tickets into structured implementation plans
 
 ---
 
@@ -198,75 +228,11 @@ Clancy also merges a section into your `CLAUDE.md` (or creates one) that tells C
 
 ---
 
-## Optional enhancements
-
-Set during `/clancy:init` advanced setup, or by editing `.clancy/.env` directly. Use `/clancy:settings` → "Save as defaults" to save non-credential settings to `~/.clancy/defaults.json` — new projects created with `/clancy:init` will inherit them automatically.
-
-### Figma MCP
-
-```
-FIGMA_API_KEY=your-key
-```
-
-When a ticket description contains a Figma URL, Clancy fetches design specs automatically:
-
-1. Figma MCP: `get_metadata` → `get_design_context` → `get_screenshot` (3 calls)
-2. Figma REST API image export (fallback)
-3. Ticket image attachment (fallback)
-
-### Playwright visual checks
-
-```
-PLAYWRIGHT_ENABLED=true
-PLAYWRIGHT_DEV_COMMAND="yarn dev"
-PLAYWRIGHT_DEV_PORT=5173
-PLAYWRIGHT_STORYBOOK_COMMAND="yarn storybook"  # if applicable
-PLAYWRIGHT_STORYBOOK_PORT=6006                 # if applicable
-PLAYWRIGHT_STARTUP_WAIT=15
-```
-
-After implementing a UI ticket, Clancy starts the dev server or Storybook, screenshots, assesses visually, checks the console, and fixes anything wrong before committing.
-
-### Status transitions
-
-```
-CLANCY_STATUS_IN_PROGRESS="In Progress"
-CLANCY_STATUS_DONE="Done"
-```
-
-Clancy automatically moves tickets through your board when it picks up and completes them. Set these to the exact column name shown in your Jira or Linear board. Best-effort — a failed transition never stops the run. Configurable via `/clancy:settings`.
-
-### Notifications
-
-```
-CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url
-```
-
-Posts to Slack or Teams when a ticket completes or Clancy hits an error. URL is auto-detected.
-
----
-
-## How the loop works
+## Configuration
 
-```
-clancy-afk.js
-  └─ while i < MAX_ITERATIONS:
-       node clancy-once.js
-         1. Preflight checks (credentials, git state, board reachability)
-         2. Fetch next ticket from board (maxResults=1)
-         3. git checkout $EPIC_BRANCH
-         4. git checkout -b feature/{ticket-key}
-         5. Read .clancy/docs/* (especially GIT.md)
-         6. echo "$PROMPT" | claude --dangerously-skip-permissions
-         7. git checkout $EPIC_BRANCH
-         8. git merge --squash feature/{ticket-key}
-         9. git commit -m "feat(TICKET): summary"
-        10. git branch -D feature/{ticket-key}
-        11. Append to .clancy/progress.txt
-       if "No tickets found": break
-```
+Clancy supports optional enhancements — Figma design specs, Playwright visual checks, status transitions, and Slack/Teams notifications. All are configured via `.clancy/.env` or `/clancy:settings`.
 
-Clancy reads `GIT.md` before every run and follows whatever conventions are documented there. The defaults above apply on greenfield projects or when GIT.md is silent.
+See [Configuration guide](docs/guides/CONFIGURATION.md) for full details and all environment variables.
 
 ---
 
@@ -288,80 +254,9 @@ Clancy is what happens when you take that idea seriously for team development. S
 
 ## Security
 
-### Permissions model
-
-Clancy runs Claude with `--dangerously-skip-permissions`, which suppresses all permission prompts so it can work unattended. This means Claude has full read/write access to your file system and can execute shell commands without asking.
-
-**Only run Clancy on codebases you own and trust.** Review the scripts in `.clancy/` before your first run if you want to see exactly what executes.
-
-**Alternative — granular permissions:** if you run Claude Code without `--dangerously-skip-permissions` by default, you can pre-approve only the commands Clancy needs. Add this to `.claude/settings.json` in your project (or `~/.claude/settings.json` globally):
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(git:*)",
-      "Bash(bash:*)",
-      "Bash(node:*)",
-      "Bash(npm:*)",
-      "Bash(mkdir:*)",
-      "Bash(cat:*)",
-      "Bash(cp:*)",
-      "Bash(echo:*)",
-      "Bash(ls:*)",
-      "Bash(grep:*)",
-      "Bash(wc:*)",
-      "Bash(sort:*)",
-      "Bash(tr:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(lsof:*)",
-      "Bash(command:*)"
-    ]
-  }
-}
-```
-
-### Protect your credentials from Claude
-
-Your board tokens and API keys live in `.clancy/.env`. Although Claude doesn't need to read this file during a run (the JS shim loads it before invoking Claude), adding it to Claude Code's deny list is good defence-in-depth. Add it to `.claude/settings.json` in your project, or `~/.claude/settings.json` globally:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.clancy/.env)",
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)"
-    ]
-  }
-}
-```
-
-This prevents Claude from reading these files regardless of what commands run. Clancy automatically adds `.clancy/.env` to `.gitignore` during init, but the deny list is an additional layer.
-
-### Credential guard
-
-Clancy installs a `PreToolUse` hook (`clancy-credential-guard.js`) that scans every Write, Edit, and MultiEdit operation for credential patterns — API keys, tokens, passwords, private keys, and connection strings. If a match is found, the operation is blocked with a message telling Claude to move the credential to `.clancy/.env` instead. Files that are expected to contain credentials (`.clancy/.env`, `.env.example`, etc.) are exempt.
-
-This is best-effort — it won't catch every possible credential format, but it prevents the most common accidental leaks.
+Clancy runs Claude with `--dangerously-skip-permissions` for unattended operation. It includes a credential guard hook, recommended permission deny lists, and token scope guidance.
 
-### Token scopes
-
-Use the minimum permissions each integration requires:
-
-| Integration | Recommended scope |
-|---|---|
-| GitHub PAT | `repo` — read/write issues and contents for your repo only |
-| Jira API token | Standard user — no admin rights needed |
-| Linear API key | Personal API key — read/write to your assigned issues |
-| Figma API key | Read-only access is sufficient |
-
-### Webhook URLs
-
-If you configure Slack or Teams notifications, treat the webhook URL as a secret — anyone who has it can post to your channel. Keep `.clancy/.env` gitignored (Clancy does this automatically during init) and never share the URL.
+See [Security guide](docs/guides/SECURITY.md) for full details — permissions model, credential protection, token scopes, and webhook security.
 
 ---
 
@@ -369,70 +264,7 @@ If you configure Slack or Teams notifications, treat the webhook URL as a secret
 
 **Start here:** run `/clancy:doctor` — it tests every integration and tells you exactly what's broken and how to fix it.
 
----
-
-**Commands not found after install?**
-
-Restart Claude Code to reload commands, then verify the files exist:
-
-```bash
-ls ~/.claude/commands/clancy/    # global install
-ls .claude/commands/clancy/      # local install
-```
-
-If missing, re-run `npx chief-clancy`.
-
----
-
-**Board connection fails?**
-
-Run `/clancy:doctor` to test your credentials. If it reports a failure, open `.clancy/.env` and check your tokens — they're the most common cause. You can also run `/clancy:settings` → Switch board to re-enter credentials without re-running full init.
-
----
-
-**No tickets showing up?**
-
-Run `/clancy:status` to see what Clancy would pick up. If the queue is empty:
-
-- Check that tickets are assigned to you on the board
-- For Jira: verify the status filter in `/clancy:settings` matches your board's status name exactly (e.g. `To Do` vs `TODO`)
-- For Linear: Clancy filters by `state.type: unstarted` — ensure your backlog state maps to this type
-
----
-
-**`.clancy/clancy-once.js` not found?**
-
-Re-run `/clancy:init` — it will detect the existing setup and offer to re-scaffold without asking for credentials again.
-
----
-
-**Playwright port already in use?**
-
-```bash
-lsof -ti:5173 | xargs kill -9   # replace 5173 with your PLAYWRIGHT_DEV_PORT
-```
-
----
-
-**Updating Clancy?**
-
-```bash
-/clancy:update
-```
-
-Or directly: `npx chief-clancy@latest`
-
-The update workflow shows what's changed (changelog diff) and asks for confirmation before overwriting. If you've customised any command or workflow files, they're automatically backed up to `.claude/clancy/local-patches/` before the update — check there to reapply your changes afterwards.
-
----
-
-**Uninstalling?**
-
-```
-/clancy:uninstall
-```
-
-Removes slash commands from your chosen location. Cleans up the `<!-- clancy:start -->` / `<!-- clancy:end -->` block from `CLAUDE.md` (or deletes it entirely if Clancy created it) and removes the `.clancy/.env` entry from `.gitignore`. Optionally removes `.clancy/` (credentials and docs).
+See [Troubleshooting guide](docs/guides/TROUBLESHOOTING.md) for common issues and solutions.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chief-clancy",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Autonomous, board-driven development for Claude Code — scaffolds docs, integrates Kanban boards, runs tickets in a loop.",
   "keywords": [
     "claude",

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

@@ -22,9 +22,9 @@ Before asking any questions, silently check:
 - Is this an existing project? Check for `package.json`, `.git`, `src/`, `app/`, `lib/`
 - Is a board already configured? Check `.clancy/.env` for `JIRA_BASE_URL`, `GITHUB_TOKEN`, `LINEAR_API_KEY`
 - Does `CLAUDE.md` already exist? Flag for merge — never overwrite
-- Does `.clancy/` already exist? Warn and offer re-init or abort
+- Does `.clancy/.env` already exist? This means init has been completed before — warn and offer re-init or abort. Note: `.clancy/` alone may exist from the installer (runtime scripts) without init having run.
 
-If `.clancy/` exists, output:
+If `.clancy/.env` exists, output:
 
 It looks like Clancy is already set up in this project.
 
@@ -239,6 +239,82 @@ If enter is pressed with no value: skip — omit the label clause entirely (Clan
 
 ---
 
+### Q3d (Jira and Linear only): Status transitions
+
+Output:
+
+**GitHub:** Skip this step entirely — GitHub Issues use `open`/`closed`, not status columns. Clancy closes issues automatically on completion.
+
+**Jira:** Output:
+
+```
+When Clancy picks up a ticket, it can transition it on your Jira board.
+Jira uses transition action names (e.g. "In Progress", "Start Progress").
+These usually match the column name, but check your Jira workflow if transitions fail.
+
+What transition should Clancy use when it starts working on a ticket?
+
+[1] In Progress (most common)
+[2] Enter a different value
+[3] Skip — don't transition on pickup (ticket stays in its current column)
+```
+
+If [1]: store `CLANCY_STATUS_IN_PROGRESS="In Progress"` in `.clancy/.env`.
+If [2]: prompt for the value, store as `CLANCY_STATUS_IN_PROGRESS` in `.clancy/.env`. Wrap in double quotes.
+If [3] or the user says "skip"/"none": skip — no `CLANCY_STATUS_IN_PROGRESS` line written.
+
+Then ask:
+
+```
+What transition should Clancy use after implementation is complete?
+
+[1] Done
+[2] Ready for Review
+[3] Enter a different value
+[4] Skip — don't transition on completion (ticket stays in its current column)
+```
+
+If [1]: store `CLANCY_STATUS_DONE="Done"` in `.clancy/.env`.
+If [2]: store `CLANCY_STATUS_DONE="Ready for Review"` in `.clancy/.env`.
+If [3]: prompt for the value, store as `CLANCY_STATUS_DONE` in `.clancy/.env`. Wrap in double quotes.
+If [4] or the user says "skip"/"none": skip — no `CLANCY_STATUS_DONE` line written.
+
+**Linear:** Output:
+
+```
+When Clancy picks up a ticket, it can move it to a workflow state on your board.
+
+What state should Clancy move a ticket to when it starts working on it?
+
+[1] In Progress (most common)
+[2] Enter a different value
+[3] Skip — don't transition on pickup (ticket stays in its current state)
+```
+
+If [1]: store `CLANCY_STATUS_IN_PROGRESS="In Progress"` in `.clancy/.env`.
+If [2]: prompt for the value, store as `CLANCY_STATUS_IN_PROGRESS` in `.clancy/.env`. Wrap in double quotes.
+If [3] or the user says "skip"/"none": skip — no `CLANCY_STATUS_IN_PROGRESS` line written.
+
+Then ask:
+
+```
+What state should Clancy move a ticket to after implementation is complete?
+
+[1] Done
+[2] Ready for Review
+[3] Enter a different value
+[4] Skip — don't transition on completion (ticket stays in its current state)
+```
+
+If [1]: store `CLANCY_STATUS_DONE="Done"` in `.clancy/.env`.
+If [2]: store `CLANCY_STATUS_DONE="Ready for Review"` in `.clancy/.env`.
+If [3]: prompt for the value, store as `CLANCY_STATUS_DONE` in `.clancy/.env`. Wrap in double quotes.
+If [4] or the user says "skip"/"none": skip — no `CLANCY_STATUS_DONE` line written.
+
+You can always configure these later via `/clancy:settings`.
+
+---
+
 ### Q4: Base branch (auto-detect)
 
 Silently detect the base branch — do not ask unless detection fails:
@@ -322,6 +398,28 @@ Note: as more roles are added in future versions, they appear as additional numb
 
 ---
 
+## Step 4d (Jira only, if Planner role selected): Planning queue status
+
+Only ask this if the user selected Planner in Step 4c above (or if re-running init and `CLANCY_ROLES` already includes `planner`).
+
+If the planner role is not enabled, skip this step entirely.
+
+Output:
+
+```
+The Planner role picks tickets from a separate queue for planning.
+
+Which Jira status should Clancy pick planning tickets from?
+
+[1] Backlog (default)
+[2] Enter a different value
+```
+
+If [1]: store `CLANCY_PLAN_STATUS="Backlog"` in `.clancy/.env`.
+If [2]: prompt for the value, store as `CLANCY_PLAN_STATUS` in `.clancy/.env`. Wrap in double quotes.
+
+---
+
 ## Step 5 — Optional enhancements
 
 Output:

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

@@ -335,6 +335,7 @@ JIRA_USER=your-email@example.com
 JIRA_API_TOKEN=your-api-token-from-id.atlassian.com
 JIRA_PROJECT_KEY=PROJ
 
+# ─── Implementation Queue ─────────────────────────────────────────────────────
 # Status name for "ready to be picked up" (default: To Do)
 # Must be quoted if the status name contains spaces (e.g. "Selected for Development")
 CLANCY_JQL_STATUS="To Do"
@@ -377,10 +378,17 @@ MAX_ITERATIONS=5
 
 # ─── Optional: Status transitions ────────────────────────────────────────────
 # Move tickets automatically when Clancy picks up or completes them.
-# Set to the exact status name shown in your Jira board column header.
+# Set to the Jira transition name (the action label, not the column header).
+# In many workflows these match, but check your Jira workflow if transitions fail.
+# "Done" can be any transition to a post-implementation status.
 # CLANCY_STATUS_IN_PROGRESS="In Progress"
 # CLANCY_STATUS_DONE="Done"
 
+# ─── Optional: Planner queue ─────────────────────────────────────────────────
+# Status for backlog tickets that /clancy:plan fetches from (default: Backlog)
+# Only used if Planner role is enabled via CLANCY_ROLES
+# CLANCY_PLAN_STATUS="Backlog"
+
 # ─── Optional: Notifications ──────────────────────────────────────────────────
 # Webhook URL for Slack or Teams notifications on ticket completion
 # CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url
@@ -397,10 +405,14 @@ MAX_ITERATIONS=5
 GITHUB_TOKEN=ghp_your-personal-access-token
 GITHUB_REPO=owner/repo-name
 
-# Optional: only pick up issues with this label (in addition to 'clancy').
-# Useful for mixed backlogs where not every issue is suitable for autonomous implementation.
+# Recommended: only pick up issues with this label.
+# Without this, Clancy picks up all open issues assigned to you.
 # Create the label in GitHub first, then add it to any issue you want Clancy to pick up.
-# CLANCY_LABEL=clancy
+# CLANCY_LABEL="clancy"
+
+# ─── Planner Queue (optional — requires CLANCY_ROLES to include "planner") ───
+# Label for backlog issues that /clancy:plan fetches from (default: needs-refinement)
+# CLANCY_PLAN_LABEL="needs-refinement"
 
 # ─── Git ──────────────────────────────────────────────────────────────────────
 # Base integration branch. Clancy branches from here when an issue has no milestone.
@@ -479,7 +491,8 @@ MAX_ITERATIONS=20
 
 # ─── Optional: Status transitions ────────────────────────────────────────────
 # Move issues automatically when Clancy picks up or completes them.
-# Set to the exact workflow state name shown in your Linear board column header.
+# Set to the exact workflow state name shown in your Linear team settings.
+# "Done" can be any post-implementation state (e.g. "Ready for Review", "In Review").
 # CLANCY_STATUS_IN_PROGRESS="In Progress"
 # CLANCY_STATUS_DONE="Done"