chief-clancy 0.7.3 → 0.8.0

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

@@ -314,25 +314,29 @@ Could not update plan comment. The plan is still promoted to the description.
 
 ---
 
-## Step 6 — Post-approval transition
+## Step 6 — Post-approval label transition
 
-Transition the ticket from the planning queue to the implementation queue. This is **best-effort** — warn on failure, continue.
+Transition the ticket from the planning queue to the implementation queue via pipeline labels. This is **best-effort** — warn on failure, continue.
 
-### GitHub (always, not configurable)
+**Crash safety:** Add the new label BEFORE removing the old one. A ticket briefly has two labels (harmless) rather than zero labels (ticket lost).
 
-1. **Remove planning label:**
+**This label transition is mandatory — always apply and remove.** Use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`. Use `CLANCY_LABEL_PLAN` from `.clancy/.env` if set, otherwise fall back to `CLANCY_PLAN_LABEL`, otherwise `clancy:plan`. Ensure the build label exists on the board (create if missing), add it to the ticket, then remove the plan label.
+
+### GitHub
+
+1. **Add build label** (ensure it exists first):
    ```bash
+   # Ensure label exists (ignore 422 = already exists)
    curl -s \
      -H "Authorization: Bearer $GITHUB_TOKEN" \
      -H "Accept: application/vnd.github+json" \
      -H "X-GitHub-Api-Version: 2022-11-28" \
-     -X DELETE \
-     "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/labels/$CLANCY_PLAN_LABEL"
-   ```
-   `CLANCY_PLAN_LABEL` defaults to `needs-refinement`. URL-encode the label name. Ignore 404 (label not on issue). If `CLANCY_PLAN_LABEL` is not set, use the default `needs-refinement`.
+     -H "Content-Type: application/json" \
+     -X POST \
+     "https://api.github.com/repos/$GITHUB_REPO/labels" \
+     -d '{"name": "$CLANCY_LABEL_BUILD", "color": "0075ca"}'
 
-2. **Add implementation label** (only if `CLANCY_LABEL` is set — skip if unset):
-   ```bash
+   # Add to issue
    curl -s \
      -H "Authorization: Bearer $GITHUB_TOKEN" \
      -H "Accept: application/vnd.github+json" \
@@ -340,38 +344,68 @@ Transition the ticket from the planning queue to the implementation queue. This
      -H "Content-Type: application/json" \
      -X POST \
      "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/labels" \
-     -d '{"labels": ["$CLANCY_LABEL"]}'
+     -d '{"labels": ["$CLANCY_LABEL_BUILD"]}'
    ```
-   If `CLANCY_LABEL` is not set, skip this step entirely (only the plan label removal is done). `CLANCY_LABEL` has no default — it is fully optional. When set (e.g. `clancy`), use its value. If the label does not exist on the repo, attempt to create it:
+
+2. **Remove plan label:**
    ```bash
    curl -s \
      -H "Authorization: Bearer $GITHUB_TOKEN" \
      -H "Accept: application/vnd.github+json" \
+     -H "X-GitHub-Api-Version: 2022-11-28" \
+     -X DELETE \
+     "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/labels/$(echo $CLANCY_LABEL_PLAN | jq -Rr @uri)"
+   ```
+   Ignore 404 (label not on issue).
+
+### Jira
+
+1. **Add build label** (Jira auto-creates labels):
+   ```bash
+   # Fetch current labels
+   CURRENT_LABELS=$(curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -H "Accept: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?fields=labels" | jq -r '.fields.labels')
+
+   # Add build label
+   UPDATED_LABELS=$(echo "$CURRENT_LABELS" | jq --arg build "$CLANCY_LABEL_BUILD" '. + [$build] | unique')
+
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -X PUT \
      -H "Content-Type: application/json" \
-     -X POST \
-     "https://api.github.com/repos/$GITHUB_REPO/labels" \
-     -d '{"name": "$CLANCY_LABEL", "color": "0075ca"}'
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
+     -d "{\"fields\": {\"labels\": $UPDATED_LABELS}}"
    ```
-   If 403 (no admin access) or 422 (invalid name): warn, continue without label.
 
-### Jira (only if `CLANCY_STATUS_PLANNED` is set)
+2. **Remove plan label:**
+   ```bash
+   # Re-fetch labels (may have changed), remove plan label
+   CURRENT_LABELS=$(curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -H "Accept: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?fields=labels" | jq -r '.fields.labels')
 
-If `CLANCY_STATUS_PLANNED` is not set: skip transition, no warning needed.
+   UPDATED_LABELS=$(echo "$CURRENT_LABELS" | jq --arg plan "$CLANCY_LABEL_PLAN" '[.[] | select(. != $plan)]')
 
-If `CLANCY_STATUS_PLANNED` is set:
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -X PUT \
+     -H "Content-Type: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
+     -d "{\"fields\": {\"labels\": $UPDATED_LABELS}}"
+   ```
 
-1. **Fetch transitions:**
+3. **Status transition** (only if `CLANCY_STATUS_PLANNED` is set — skip if unset):
    ```bash
+   # Fetch transitions
    curl -s \
      -u "$JIRA_USER:$JIRA_API_TOKEN" \
      -H "Accept: application/json" \
      "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions"
-   ```
 
-2. **Find matching transition:** Look for a transition where `.name` matches `CLANCY_STATUS_PLANNED` (case-insensitive). This matches the pattern used in the runtime Jira module.
-
-3. **Execute transition:**
-   ```bash
+   # Find matching transition and execute
    curl -s \
      -u "$JIRA_USER:$JIRA_API_TOKEN" \
      -X POST \
@@ -385,23 +419,50 @@ On failure:
 Could not transition ticket. Move it manually to your implementation queue.
 ```
 
-### Linear (always)
+### Linear
+
+1. **Add build label** (ensure it exists, then add):
+   ```graphql
+   # Ensure label exists — check team labels, workspace labels, create if missing
+   mutation {
+     issueLabelCreate(input: {
+       teamId: "$LINEAR_TEAM_ID"
+       name: "$CLANCY_LABEL_BUILD"
+       color: "#0075ca"
+     }) { success issueLabel { id } }
+   }
+
+   # Fetch current label IDs on the issue, add build label ID
+   mutation {
+     issueUpdate(
+       id: "$ISSUE_UUID"
+       input: { labelIds: [...currentLabelIds, buildLabelId] }
+     ) { success }
+   }
+   ```
+
+2. **Remove plan label:**
+   ```graphql
+   # Fetch current label IDs, filter out plan label ID
+   mutation {
+     issueUpdate(
+       id: "$ISSUE_UUID"
+       input: { labelIds: [currentLabelIds without planLabelId] }
+     ) { success }
+   }
+   ```
 
-1. **Resolve "unstarted" state:**
+3. **State transition** (always):
    ```graphql
+   # Resolve "unstarted" state
    query {
      workflowStates(filter: {
        team: { id: { eq: "$LINEAR_TEAM_ID" } }
        type: { eq: "unstarted" }
-     }) {
-       nodes { id name }
-     }
+     }) { nodes { id name } }
    }
-   ```
-   Use `nodes[0].id` as the target state. If nodes is empty: warn `No 'unstarted' state found for team.` Skip transition.
 
-2. **Transition:**
-   ```graphql
+   # Transition
    mutation {
      issueUpdate(
        id: "$ISSUE_UUID"
@@ -409,6 +470,7 @@ Could not transition ticket. Move it manually to your implementation queue.
      ) { success }
    }
    ```
+   If no `unstarted` state found: warn, skip transition.
 
 On failure:
 ```
@@ -421,20 +483,13 @@ Could not transition ticket. Move it manually to your implementation queue.
 
 On success, display a board-specific message:
 
-**GitHub (with CLANCY_LABEL set):**
+**GitHub:**
 ```
-Plan promoted. Label swapped: {plan_label} → {impl_label}. Ready for /clancy:once.
+Plan promoted. Label swapped: {CLANCY_LABEL_PLAN} → {CLANCY_LABEL_BUILD}. Ready for /clancy:once.
 
 "Book 'em, Lou." — The ticket is ready for /clancy:once.
 ```
 
-**GitHub (without CLANCY_LABEL):**
-```
-Plan promoted. Label removed: {plan_label}. Add your implementation label manually, or run /clancy:once.
-
-"Book 'em, Lou."
-```
-
 **Jira (with transition):**
 ```
 Plan promoted. Ticket transitioned to {CLANCY_STATUS_PLANNED}.

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

@@ -136,9 +136,9 @@ Then skip to Step 3b with this single ticket.
 Build the JQL using planning-specific env vars:
 - `CLANCY_PLAN_STATUS` defaults to `Backlog` if not set
 - Sprint clause: include `AND sprint in openSprints()` if `CLANCY_JQL_SPRINT` is set
-- Label clause: include `AND labels = "$CLANCY_LABEL"` if `CLANCY_LABEL` is set
+- Label clause: include `AND labels = "$CLANCY_LABEL_PLAN"` if `CLANCY_LABEL_PLAN` is set (falls back to `CLANCY_PLAN_LABEL` if `CLANCY_LABEL_PLAN` is not set). If neither is set, include `AND labels = "$CLANCY_LABEL"` if `CLANCY_LABEL` is set.
 
-Full JQL: `project=$JIRA_PROJECT_KEY [AND sprint in openSprints()] [AND labels = "$CLANCY_LABEL"] AND assignee=currentUser() AND status="$CLANCY_PLAN_STATUS" ORDER BY priority ASC`
+Full JQL: `project=$JIRA_PROJECT_KEY [AND sprint in openSprints()] [AND labels = "$CLANCY_LABEL_PLAN"] AND assignee=currentUser() AND status="$CLANCY_PLAN_STATUS" ORDER BY priority ASC`
 
 ```bash
 RESPONSE=$(curl -s \
@@ -164,16 +164,16 @@ Then fetch issues:
 RESPONSE=$(curl -s \
   -H "Authorization: Bearer $GITHUB_TOKEN" \
   -H "X-GitHub-Api-Version: 2022-11-28" \
-  "https://api.github.com/repos/$GITHUB_REPO/issues?state=open&assignee=$GITHUB_USERNAME&labels=$CLANCY_PLAN_LABEL&per_page=<N>")
+  "https://api.github.com/repos/$GITHUB_REPO/issues?state=open&assignee=$GITHUB_USERNAME&labels=$CLANCY_LABEL_PLAN&per_page=<N>")
 ```
 
-- `CLANCY_PLAN_LABEL` defaults to `needs-refinement` if not set
+- `CLANCY_LABEL_PLAN` is the pipeline label for the planning queue (default: `clancy:plan`). Falls back to `CLANCY_PLAN_LABEL` if `CLANCY_LABEL_PLAN` is not set. If neither is set, defaults to `needs-refinement`.
 - Filter out PRs (entries with `pull_request` key)
 - For each issue, fetch comments: `GET /repos/$GITHUB_REPO/issues/{number}/comments`
 
 #### Linear
 
-Build the filter using `CLANCY_PLAN_STATE_TYPE` (defaults to `backlog` if not set):
+Build the filter using `CLANCY_PLAN_STATE_TYPE` (defaults to `backlog` if not set). If `CLANCY_LABEL_PLAN` is set (falls back to `CLANCY_PLAN_LABEL`), add a label filter to the query:
 
 ```graphql
 query {
@@ -182,6 +182,7 @@ query {
       filter: {
         state: { type: { eq: "$CLANCY_PLAN_STATE_TYPE" } }
         team: { id: { eq: "$LINEAR_TEAM_ID" } }
+        labels: { name: { eq: "$CLANCY_LABEL_PLAN" } }  # Only if CLANCY_LABEL_PLAN is set
       }
       first: $N
       orderBy: priority
@@ -214,7 +215,7 @@ If no tickets found:
 
 Then display board-specific guidance:
 
-- **GitHub:** `For GitHub: planning uses the "$CLANCY_PLAN_LABEL" label (default: needs-refinement), not "clancy". Apply that label to issues you want planned.`
+- **GitHub:** `For GitHub: planning uses the "$CLANCY_LABEL_PLAN" label (default: clancy:plan, fallback: $CLANCY_PLAN_LABEL or needs-refinement). Apply that label to issues you want planned.`
 - **Jira:** `Check that CLANCY_PLAN_STATUS (currently: "$CLANCY_PLAN_STATUS") matches a status in your Jira project, and that tickets in that status are assigned to you.`
 - **Linear:** `Check that CLANCY_PLAN_STATE_TYPE (currently: "$CLANCY_PLAN_STATE_TYPE") is a valid Linear state type (backlog, unstarted, started, completed, canceled, triage), and that tickets in that state are assigned to you in team $LINEAR_TEAM_ID.`
 

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

@@ -10,7 +10,9 @@ Display the following:
 
 Named after Chief Clancy Wiggum (Ralph's dad, The Simpsons). Built on the Ralph technique
 coined by Geoffrey Huntley (ghuntley.com/ralph/). Clancy extends that foundation with board
-integration, structured codebase docs, and a git workflow built for team development.
+integration (6 boards), structured codebase docs, and a git workflow built for team development.
+
+**Supported boards:** Jira, GitHub Issues, Linear, Shortcut, Notion, Azure DevOps
 
 ### Planner *(optional — enable via `CLANCY_ROLES=planner` in `.clancy/.env`)*
 

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

@@ -87,11 +87,16 @@ Which Kanban board are you using?
 [1] Jira
 [2] GitHub Issues
 [3] Linear
-[4] My board isn't listed
+[4] Shortcut
+[5] Notion
+[6] Azure DevOps
+[7] My board isn't listed
 
-If the user selects [4], output the dead-end message and stop:
+Auto-detection hint: silently check `.clancy/.env` for existing board env vars (`JIRA_BASE_URL`, `GITHUB_TOKEN`, `LINEAR_API_KEY`, `SHORTCUT_API_TOKEN`, `NOTION_DATABASE_ID`, `AZDO_ORG`). If detected, show: `Detected: {board} from your env vars. Use this? [Y/n]` — if yes, skip to Q2 for that board.
 
-Clancy currently supports Jira, GitHub Issues, and Linear out of the box.
+If the user selects [7], output the dead-end message and stop:
+
+Clancy currently supports Jira, GitHub Issues, Linear, Shortcut, Notion, and Azure DevOps out of the box.
 
 Your board isn't supported yet — but you can add it:
   · Open an issue:   github.com/Pushedskydiver/clancy/issues
@@ -106,6 +111,32 @@ Do not scaffold anything after this message. Stop completely.
 
 ---
 
+**Shortcut** — ask in this order:
+
+1. `Paste your Shortcut API token: (create one at app.shortcut.com/settings/account/api-tokens)`
+2. `What workflow should Clancy use? (press Enter to auto-detect)` — if blank, auto-detect the first workflow via `GET /api/v3/workflows`
+
+Store as `SHORTCUT_API_TOKEN` and optionally `SHORTCUT_WORKFLOW` in `.clancy/.env`.
+
+**Notion** — ask in this order:
+
+1. `Paste your Notion integration token: (create one at notion.so/my-integrations)`
+2. `What's your Notion database ID? (the 32-character hex string in your database URL)`
+3. `What property name represents the ticket status? [Status]`
+4. `What property name represents the assignee? [Assignee]`
+
+Store as `NOTION_TOKEN`, `NOTION_DATABASE_ID`, and optionally `CLANCY_NOTION_STATUS` and `CLANCY_NOTION_ASSIGNEE` in `.clancy/.env`.
+
+**Azure DevOps** — ask in this order:
+
+1. `What's your Azure DevOps organisation name? (e.g. your-org)`
+2. `What's your Azure DevOps project name?`
+3. `Paste your Azure DevOps personal access token: (needs Work Items Read & Write scope)`
+
+Store as `AZDO_ORG`, `AZDO_PROJECT`, and `AZDO_PAT` in `.clancy/.env`.
+
+---
+
 ### Q2: Board-specific config
 
 Ask each question individually and wait for an answer before moving to the next.
@@ -497,6 +528,47 @@ If `n` or `N`: store `CLANCY_BRANCH_GUARD=false` in `.clancy/.env`.
 
 ---
 
+### Q3i (all boards): Quiet hours
+
+Output:
+
+```
+Pause AFK runs during specific hours? (e.g. business hours, overnight)
+
+[1] Skip — no quiet hours
+[2] Set quiet hours
+```
+
+If [1] or enter: skip — no `CLANCY_QUIET_START` or `CLANCY_QUIET_END` written.
+If [2]: ask:
+
+```
+Quiet start time (HH:MM, 24h format, e.g. 22:00):
+```
+
+Then:
+
+```
+Quiet end time (HH:MM, 24h format, e.g. 06:00):
+```
+
+Store as `CLANCY_QUIET_START` and `CLANCY_QUIET_END` in `.clancy/.env`.
+
+---
+
+### Q3j (all boards): Desktop notifications
+
+Output:
+
+```
+Send desktop notifications when tickets complete or errors occur? [Y/n]
+```
+
+If yes or enter: store `CLANCY_DESKTOP_NOTIFY=true` in `.clancy/.env`.
+If no: store `CLANCY_DESKTOP_NOTIFY=false` in `.clancy/.env`.
+
+---
+
 ### Q4: Base branch (auto-detect)
 
 Silently detect the base branch — do not ask unless detection fails:
@@ -592,6 +664,74 @@ Note: as more roles are added in future versions, they appear as additional numb
 
 ---
 
+## Step 4c-2 — Pipeline labels (conditional)
+
+Only ask this if any optional role was enabled in Step 4c. If neither Planner nor Strategist was selected, skip this section entirely. If `CLANCY_LABEL` or `CLANCY_PLAN_LABEL` are already set in `.clancy/.env`, show:
+
+```
+Note: CLANCY_LABEL and CLANCY_PLAN_LABEL are deprecated.
+Use CLANCY_LABEL_BUILD and CLANCY_LABEL_PLAN instead.
+Your existing values will continue to work as fallbacks.
+```
+
+**If the user enabled Strategist (or both Strategist + Planner):**
+
+Output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Pipeline Labels
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Clancy uses labels to move tickets through pipeline stages:
+  brief → plan → build
+
+Each label marks which queue a ticket belongs to.
+```
+
+Then ask each label in order:
+
+```
+What label marks tickets that have been briefed (awaiting approval)?
+[clancy:brief]
+```
+
+If a value is entered: store as `CLANCY_LABEL_BRIEF` in `.clancy/.env`. Wrap in double quotes.
+If enter is pressed: use default — store `CLANCY_LABEL_BRIEF="clancy:brief"` in `.clancy/.env`.
+
+```
+What label marks tickets that need planning?
+[clancy:plan]
+```
+
+If a value is entered: store as `CLANCY_LABEL_PLAN` in `.clancy/.env`. Wrap in double quotes.
+If enter is pressed: use default — store `CLANCY_LABEL_PLAN="clancy:plan"` in `.clancy/.env`.
+
+```
+What label marks tickets ready to build?
+[clancy:build]
+```
+
+If a value is entered: store as `CLANCY_LABEL_BUILD` in `.clancy/.env`. Wrap in double quotes.
+If enter is pressed: use default — store `CLANCY_LABEL_BUILD="clancy:build"` in `.clancy/.env`.
+
+**If the user enabled Planner only (no Strategist):**
+
+Skip `CLANCY_LABEL_BRIEF` (no `/clancy:brief` command). Ask only:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Pipeline Labels
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Clancy uses labels to move tickets through pipeline stages:
+  plan → build
+```
+
+Then ask `CLANCY_LABEL_PLAN` and `CLANCY_LABEL_BUILD` using the same prompts and defaults as above.
+
+---
+
 ## Step 4d (if Planner role selected): Planning queue config
 
 Only ask this if the user selected Planner in Step 4c above (or if re-running init and `CLANCY_ROLES` already includes `planner`).