chief-clancy 0.1.0

package/src/workflows/settings.md

@@ -0,0 +1,344 @@
+# Clancy Settings Workflow
+
+## Overview
+
+View and change Clancy configuration. Reads `.clancy/.env`, shows current values, and lets the user update any setting interactively. Loops until the user exits. Never modifies anything other than `.clancy/.env`.
+
+---
+
+## Step 1 — Preflight
+
+Check `.clancy/` exists and `.clancy/.env` is present.
+
+If either is missing:
+
+```
+.clancy/ not found. Run /clancy:init to set up Clancy first.
+```
+
+Stop.
+
+---
+
+## Step 2 — Read current config
+
+Source `.clancy/.env` silently. Detect which board is configured:
+- `JIRA_BASE_URL` set → Jira
+- `GITHUB_TOKEN` set → GitHub Issues
+- `LINEAR_API_KEY` set → Linear
+
+---
+
+## Step 3 — Display settings menu
+
+Show all current values. Board-specific settings only appear when that board is configured.
+
+```
+Clancy settings — .clancy/.env
+
+General
+[1] Max iterations    {MAX_ITERATIONS:-5}          tickets per /clancy:run session
+[2] Claude model      {CLANCY_MODEL:-default}     model used for each ticket session
+[3] Base branch       {CLANCY_BASE_BRANCH:-main}
+
+{If Jira:}
+Jira
+[4] Status filter     {CLANCY_JQL_STATUS:-To Do}
+[5] Sprint filter     {on if CLANCY_JQL_SPRINT set, else off}
+[6] Label filter      {CLANCY_LABEL if set, else off — only pick up tickets with this label}
+
+{If Linear:}
+Linear
+[4] Label filter      {CLANCY_LABEL if set, else off — only pick up issues with this label}
+
+Optional enhancements
+[{N}] Figma MCP       {enabled if FIGMA_API_KEY set, else not set}
+[{N}] Playwright      {enabled if PLAYWRIGHT_ENABLED=true, else off}
+[{N}] Notifications   {configured if CLANCY_NOTIFY_WEBHOOK set, else not set}
+
+[{N}] Switch board    currently: {Jira / GitHub Issues / Linear}
+[{N}] Exit
+
+Which setting would you like to change?
+```
+
+Number each option sequentially. Show only the board-specific section that matches the configured board. If Jira: show [4] status, [5] sprint, [6] label. If Linear: show [4] label. If GitHub: no board-specific options.
+
+---
+
+## Step 4 — Handle each selection
+
+After the user picks a number, handle it as below. After saving, print `✓ Saved.` and loop back to Step 3 to show the updated menu.
+
+---
+
+### [1] Max iterations
+
+```
+Max iterations — current: {value}
+How many tickets should /clancy:run process per session?
+
+[1] 5 (default)
+[2] Enter a different number
+```
+
+Write `MAX_ITERATIONS=<value>` to `.clancy/.env`.
+
+---
+
+### [2] Claude model
+
+```
+Claude model — current: {value or "default"}
+
+[1] Default (Claude picks the best available model)
+[2] claude-opus-4-6     — most capable, slower
+[3] claude-sonnet-4-6   — balanced (recommended)
+[4] claude-haiku-4-5    — fastest, lightest
+[5] Enter a custom model ID
+[6] Clear (revert to default)
+```
+
+If the user picks [1] or [6]: remove `CLANCY_MODEL` from `.clancy/.env` (or leave it commented out).
+Otherwise: write `CLANCY_MODEL=<value>` to `.clancy/.env`.
+
+---
+
+### [3] Base branch
+
+```
+Base branch — current: {value}
+Branch Clancy uses as the integration target when a ticket has no parent epic.
+
+Enter new value (or press enter to keep current):
+```
+
+Write `CLANCY_BASE_BRANCH=<value>` to `.clancy/.env`.
+
+---
+
+### [4] Jira status filter (Jira only)
+
+```
+Jira status filter — current: {value}
+Which status name should Clancy pick tickets from?
+Common values: To Do, Selected for Development, Ready, Open
+
+[1] To Do (default)
+[2] Enter a different value
+```
+
+Write `CLANCY_JQL_STATUS=<value>` to `.clancy/.env`.
+
+---
+
+### [5] Jira sprint filter (Jira only)
+
+```
+Jira sprint filter — current: {on / off}
+Filter tickets to the active sprint? (Requires Jira Software)
+
+[1] On
+[2] Off (default)
+```
+
+If on: write `CLANCY_JQL_SPRINT=true` to `.clancy/.env`.
+If off: remove `CLANCY_JQL_SPRINT` from `.clancy/.env` (or comment it out).
+
+---
+
+### [6] Jira label filter (Jira only)
+
+```
+Jira label filter — current: {label name or "off"}
+Only pick up tickets with this label. Useful for mixed backlogs
+where some tickets are not suitable for autonomous implementation.
+
+[1] Set label name
+[2] Off (pick up all assigned tickets regardless of label)
+[3] Cancel
+```
+
+If [1]: prompt `What label should Clancy filter by? (must already exist in Jira)` then write `CLANCY_LABEL=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_LABEL` from `.clancy/.env`.
+
+---
+
+### [4] Linear label filter (Linear only)
+
+```
+Linear label filter — current: {label name or "off"}
+Only pick up issues with this label. Useful for mixed backlogs
+where some issues are not suitable for autonomous implementation.
+
+[1] Set label name
+[2] Off (pick up all unstarted assigned issues regardless of label)
+[3] Cancel
+```
+
+If [1]: prompt `What label should Clancy filter by? (must already exist in your Linear team)` then write `CLANCY_LABEL=<value>` to `.clancy/.env`.
+If [2]: remove `CLANCY_LABEL` from `.clancy/.env`.
+
+---
+
+### Figma MCP
+
+```
+Figma MCP — current: {enabled / not set}
+
+[1] Set API key
+[2] Disable (remove key)
+[3] Cancel
+```
+
+If [1]: prompt `Paste your Figma API key: (create one at figma.com/settings → Personal access tokens)` then verify with the Figma `whoami` API before saving. If verification fails, tell the user and offer retry or skip — never save an unverified key.
+If [2]: remove `FIGMA_API_KEY` from `.clancy/.env`.
+
+---
+
+### Playwright
+
+```
+Playwright visual checks — current: {enabled / off}
+
+[1] Enable
+[2] Disable
+[3] Cancel
+```
+
+If [1] Enable selected and `PLAYWRIGHT_ENABLED` is already `true`: show `Playwright is already enabled. [1] Reconfigure [2] Cancel`. If Reconfigure, walk through the setup questions again. If Cancel, loop back.
+If [1] Enable selected and `PLAYWRIGHT_DEV_COMMAND` is not set: walk through the Playwright setup questions from the init workflow (dev server command, port, Storybook detection, startup wait).
+If [1] Enable selected and `PLAYWRIGHT_DEV_COMMAND` is already set: just set `PLAYWRIGHT_ENABLED=true`.
+If [2] Disable: set `PLAYWRIGHT_ENABLED=false` in `.clancy/.env`.
+
+---
+
+### Notifications
+
+```
+Notifications — current: {configured / not set}
+
+[1] Set webhook URL
+[2] Disable (remove webhook)
+[3] Cancel
+```
+
+If [1]: prompt `Paste your Slack or Teams webhook URL:` then write `CLANCY_NOTIFY_WEBHOOK=<url>` to `.clancy/.env`.
+If [2]: remove `CLANCY_NOTIFY_WEBHOOK` from `.clancy/.env`.
+
+---
+
+### Switch board
+
+Show which board is currently active, then offer the other two:
+
+```
+Switch board — currently: {Jira / GitHub Issues / Linear}
+
+[1] {board A}
+[2] {board B}
+[3] Cancel
+```
+
+Only show the two boards that are not currently active. If the user picks Cancel, loop back to the menu without changing anything.
+
+**Step 1: Collect new credentials**
+
+Ask each credential question individually and wait for an answer, exactly as in the init workflow Q2:
+
+Jira — ask in this order:
+1. `What's your Jira base URL? (e.g. https://your-org.atlassian.net)`
+2. `What's your Jira project key? (e.g. PROJ)`
+3. `What email address do you use to log in to Atlassian?`
+4. `Paste your Jira API token: (create one at id.atlassian.com/manage-profile/security/api-tokens)`
+
+GitHub Issues — ask in this order:
+1. `What's your GitHub repo? (owner/name, e.g. acme/my-app)`
+2. `Paste your GitHub personal access token: (needs repo scope)`
+
+After collecting GitHub credentials, remind the user:
+```
+Important: Clancy only picks up GitHub Issues that have the "clancy" label applied.
+Add this label to any issue you want Clancy to work on.
+```
+
+Linear — ask in this order:
+1. `Paste your Linear API key: (create one at linear.app/settings/api)`
+2. `What's your Linear team ID? (find it at linear.app/settings/teams — click your team, copy the ID from the URL)`
+
+**Step 2: Verify credentials**
+
+Verify the new credentials before making any changes — same checks as the init preflight and doctor workflow. Show the result:
+
+```
+Verifying...
+✓ Connected — {board-specific confirmation, e.g. "PROJ reachable" / "acme/my-app found" / "Linear authenticated"}
+```
+
+If verification fails, tell the user clearly and offer:
+
+```
+Could not connect. Check your credentials and try again.
+
+[1] Try again
+[2] Cancel
+```
+
+Never modify any files if verification fails.
+
+**Step 3: Confirm the switch**
+
+Once verified, show a single confirmation before making changes:
+
+```
+Ready to switch from {old board} to {new board}.
+Your other settings (model, iterations, branch, enhancements) will be kept.
+
+Confirm? [Y/n]
+```
+
+If no: print `Cancelled. No changes made.` and loop back to the menu.
+
+**Step 4: Apply the switch**
+
+1. Remove all vars belonging to the old board from `.clancy/.env`:
+   - Jira: `JIRA_BASE_URL`, `JIRA_USER`, `JIRA_API_TOKEN`, `JIRA_PROJECT_KEY`, `CLANCY_JQL_STATUS`, `CLANCY_JQL_SPRINT`
+   - GitHub: `GITHUB_TOKEN`, `GITHUB_REPO`
+   - Linear: `LINEAR_API_KEY`, `LINEAR_TEAM_ID`
+2. Write the new board credentials to `.clancy/.env`
+3. If switching to Jira: also ask the status filter question (same as init Q3) and write `CLANCY_JQL_STATUS` to `.clancy/.env`
+4. Write the correct `clancy-once.sh` variant for the new board to `.clancy/clancy-once.sh` — same script content as init Step 4 uses (Jira → `clancy-once.sh`, GitHub → `clancy-once-github.sh`, Linear → `clancy-once-linear.sh`). Make it executable: `chmod +x .clancy/clancy-once.sh`
+
+Print:
+
+```
+✓ Switched to {new board}.
+```
+
+Then loop back to the main settings menu.
+
+---
+
+### Exit
+
+Print nothing extra. Stop.
+
+---
+
+## Step 5 — Writing values to .clancy/.env
+
+When updating a value:
+
+- If the key already exists in `.clancy/.env`: replace its line in place
+- If the key does not exist: append it to the end of the file
+- If removing a key: delete its line from the file
+- Never touch any other lines in the file
+
+---
+
+## Notes
+
+- All changes are written to `.clancy/.env` immediately after confirmation
+- Switching boards verifies credentials before making any changes — nothing is written if verification fails
+- `/clancy:init` remains available for a full re-setup (re-scaffolds scripts and docs)
+- This command never restarts any servers or triggers any ticket processing

package/src/workflows/status.md

@@ -0,0 +1,120 @@
+# Clancy Status Workflow
+
+## Overview
+
+Read-only board check. Fetches the next 3 tickets Clancy would pick up and displays them. No side effects whatsoever — no git operations, no file writes, no ticket claiming.
+
+---
+
+## Step 1 — Preflight checks
+
+1. Check `.clancy/` exists and `.clancy/.env` is present.
+2. Source `.clancy/.env` and check board credentials are present.
+3. On any missing config, show a specific error and stop:
+   ```
+   Missing config. Run /clancy:init to set up Clancy.
+   ```
+
+---
+
+## Step 2 — Detect board and fetch tickets
+
+Detect board from `.clancy/.env`:
+
+**Jira:**
+
+Build the JQL string first using the same clauses as `clancy-once.sh`:
+- 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
+- `CLANCY_JQL_STATUS` defaults to `To Do` if not set
+
+Full JQL (with both optional clauses shown):
+`project=$JIRA_PROJECT_KEY [AND sprint in openSprints()] [AND labels = "$CLANCY_LABEL"] AND assignee=currentUser() AND status="$CLANCY_JQL_STATUS" ORDER BY priority ASC`
+
+```bash
+RESPONSE=$(curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/search/jql" \
+  -d '{"jql": "<jql as above>", "maxResults": 3, "fields": ["summary", "parent", "customfield_10014", "status"]}')
+```
+
+**GitHub Issues:**
+```bash
+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=@me&labels=clancy&per_page=3")
+# Filter out PRs (entries with pull_request key)
+```
+
+**Linear:**
+
+Build the filter — `CLANCY_LABEL` is optional:
+- Base filter: `state: { type: { eq: "unstarted" } }, team: { id: { eq: "$LINEAR_TEAM_ID" } }`
+- If `CLANCY_LABEL` is set: add `labels: { name: { eq: "$CLANCY_LABEL" } }` to the filter
+
+```graphql
+query {
+  viewer {
+    assignedIssues(
+      filter: { state: { type: { eq: "unstarted" } }, team: { id: { eq: "$LINEAR_TEAM_ID" } } [, labels: { name: { eq: "$CLANCY_LABEL" } }] }
+      first: 3
+      orderBy: priority
+    ) {
+      nodes { id identifier title parent { identifier title } }
+    }
+  }
+}
+```
+
+---
+
+## Step 3 — Display
+
+If tickets found, display:
+```
+Next up for Clancy:
+
+1. [{TICKET-KEY}] {Summary}
+   Epic: {epic key} — {epic title}
+   Status: {status}
+
+2. [{TICKET-KEY}] {Summary}
+   Epic: {epic key} — {epic title}
+   Status: {status}
+
+3. [{TICKET-KEY}] {Summary}
+   Epic: {epic key} — {epic title}
+   Status: {status}
+
+Run /clancy:once to pick up the first ticket.
+Run /clancy:run to process all tickets in the queue.
+```
+
+If no tickets found:
+```
+No tickets found in the current queue. Check your board or run /clancy:init
+to verify your configuration.
+```
+
+If API call fails, show the error clearly:
+```
+Board API error: {error message}
+
+Tips:
+- Check your credentials in .clancy/.env
+- For Jira: ensure you have VPN access if required
+- Run /clancy:init to reconfigure
+```
+
+---
+
+## Notes
+
+- Show up to 3 tickets. If only 1 or 2 are available, show those.
+- Omit "Epic:" line if no epic/parent data is present for that ticket.
+- This command is strictly read-only. No git ops, no file writes, no Claude invocation for analysis.
+- The query used here must be identical to the one used by `clancy-once.sh` — what status shows is exactly what run would pick up.

package/src/workflows/uninstall.md

@@ -0,0 +1,75 @@
+# Clancy Uninstall Workflow
+
+## Overview
+
+Remove Clancy's slash commands from the local project, globally, or both. Optionally remove the `.clancy/` project folder (which includes `.clancy/.env`). Never touch `CLAUDE.md` under any circumstances.
+
+---
+
+## Step 1 — Detect install locations
+
+Check both locations silently. Each install has two parts — commands and workflows:
+
+- **Project-local commands:** `.claude/commands/clancy/`
+- **Project-local workflows:** `.claude/clancy/`
+- **Global commands:** `~/.claude/commands/clancy/`
+- **Global workflows:** `~/.claude/clancy/`
+
+| Scenario | Action |
+|---|---|
+| Found in both | Ask: "Remove from project, globally, or both?" → `[1] Project only` `[2] Global only` `[3] Both` |
+| Found in project only | Proceed with project removal |
+| Found globally only | Proceed with global removal |
+| Found in neither | Print "Clancy commands not found. Nothing to remove." and stop |
+
+---
+
+## Step 2 — Confirm before removing commands
+
+Show exactly this message, filling in the detected location:
+
+```
+This will remove Clancy's slash commands from [location].
+Your .clancy/ folder will not be touched.
+Continue? (yes / no)
+```
+
+- `no` → print "Nothing removed." and stop
+- `yes` → delete both the commands directory and the workflows directory for the chosen location(s), print "✓ Clancy removed from [location]."
+
+If "Both" was chosen in Step 1: confirm once for both, remove all four directories, print two confirmation lines.
+
+---
+
+## Step 3 — Offer to remove .clancy/ (if present)
+
+Check whether `.clancy/` exists in the current project directory.
+
+If it does, ask separately:
+
+```
+.clancy/ contains your codebase docs, progress log, and credentials (.env).
+Remove it too? This cannot be undone. (yes / no)
+```
+
+- `no` → print "✓ .clancy/ kept — your docs and progress log are safe."
+- `yes` → delete `.clancy/` and print "✓ .clancy/ removed."
+
+If `.clancy/` does not exist, skip this step entirely.
+
+---
+
+## Step 4 — Final message
+
+```
+Clancy uninstalled. To reinstall: npx chief-clancy
+```
+
+---
+
+## Hard constraints
+
+- **Never touch any `.env` at the project root** — Clancy's credentials live in `.clancy/.env` and are only removed as part of `.clancy/` in Step 3
+- **Never touch `CLAUDE.md`** — under any circumstances, in any scenario
+- Steps 1–2 (commands removal) and Step 3 (`.clancy/` removal) are always asked separately — never bundle them into one confirmation
+- If the user says no to commands removal in Step 2, skip Step 3 entirely and stop

package/src/workflows/update-docs.md

@@ -0,0 +1,89 @@
+# Clancy Update-Docs Workflow
+
+## Overview
+
+Incrementally refresh `.clancy/docs/` by re-running only the agents covering areas that have changed. Faster than a full `map-codebase` when changes are targeted.
+
+---
+
+## Step 0 — Preflight
+
+Check `.clancy/` exists and `.clancy/.env` is present.
+
+If either is missing:
+```
+.clancy/ not found. Run /clancy:init to set up Clancy first.
+```
+Stop.
+
+---
+
+## Step 1 — Determine what changed
+
+Ask: "What changed since your last codebase scan? (or press Enter to auto-detect via git diff)"
+
+If the user describes changes, parse their description to identify affected areas.
+
+If Enter is pressed, run:
+```bash
+git diff --name-only HEAD~10 HEAD 2>/dev/null || git diff --name-only
+```
+
+---
+
+## Step 2 — Map changes to agents
+
+| Changed files / areas | Re-run agent |
+|---|---|
+| `package.json`, `*.lock`, deps, build config, env | tech |
+| `src/` structure, API routes, data models, services | arch |
+| test files, lint config, `.eslintrc`, `jest.config.*` | quality |
+| CSS, tokens, Figma, component library, a11y | design |
+| Security, performance, infra, known issues | concerns |
+
+Multiple agents may need to re-run — run them in parallel.
+
+If `PLAYWRIGHT_ENABLED=true` and the tech agent is re-running: verify `PLAYWRIGHT.md` ports/commands still match what `STACK.md` now says. Update `PLAYWRIGHT.md` if they differ.
+
+---
+
+## Step 3 — Confirm before running
+
+```
+Based on your changes, I'll re-run:
+  - {agent list}
+
+This will update:
+  - {file list}
+
+Continue? [Y/n]:
+```
+
+---
+
+## Step 4 — Re-run selected agents in parallel
+
+Same as map-codebase Step 3, but only for the selected agents.
+
+---
+
+## Step 5 — Verify and commit
+
+Verify each updated file is non-empty.
+
+```bash
+git add .clancy/docs/
+git commit -m "docs(clancy): update-docs — refresh .clancy/docs/"
+```
+
+---
+
+## Step 6 — Final message
+
+```
+Docs updated.
+
+Updated: {file list}
+
+Run /clancy:once or /clancy:run when ready.
+```

package/src/workflows/update.md

@@ -0,0 +1,67 @@
+# Clancy Update Workflow
+
+## Overview
+
+Update Clancy itself to the latest version via npx.
+
+---
+
+## Step 1 — Check current version
+
+Read current version from the installed package (check `~/.claude/commands/clancy/` or `./.claude/commands/clancy/` for a `VERSION` file, or from npm).
+
+```bash
+npm view chief-clancy version 2>/dev/null || echo "unknown"
+```
+
+---
+
+## Step 2 — Run the updater
+
+```
+Updating Clancy...
+```
+
+Run:
+```bash
+npx chief-clancy@latest
+```
+
+This re-runs the installer, which copies the latest command files into the correct `.claude/commands/clancy/` directory (global or local, matching the existing install location).
+
+The update only touches `.claude/commands/clancy/` (slash commands and workflows). It never modifies:
+- `.clancy/clancy-once.sh` or `.clancy/clancy-afk.sh` — shell scripts are not updated
+- `.clancy/docs/` codebase documentation
+- `.clancy/progress.txt` progress log
+- `.clancy/.env` credentials
+- `CLAUDE.md`
+
+**To update the shell scripts** (`.clancy/clancy-once.sh`, `.clancy/clancy-afk.sh`), re-run `/clancy:init` — it will detect the existing setup and re-scaffold the scripts without asking for credentials again.
+
+---
+
+## Step 3 — Show changelog diff
+
+After update, fetch and display the CHANGELOG section for any versions between old and new:
+
+```
+Updated Clancy from v{old} to v{new}.
+
+What's new:
+{relevant CHANGELOG entries}
+
+View full changelog: github.com/Pushedskydiver/clancy/blob/main/CHANGELOG.md
+```
+
+If version is already latest:
+```
+Clancy is already up to date (v{version}).
+```
+
+---
+
+## Notes
+
+- If the user installed globally, the update applies globally
+- If the user installed locally, the update applies locally
+- After updating, the new commands take effect immediately in Claude Code