chief-clancy 0.1.0

package/src/workflows/init.md

@@ -0,0 +1,423 @@
+# Clancy Init Workflow
+
+## Overview
+
+Full wizard for setting up Clancy in a project. Follow every step exactly. Do not skip steps or reorder them.
+
+---
+
+## Step 1 — Detect project state
+
+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
+
+If `.clancy/` exists, output:
+
+It looks like Clancy is already set up in this project.
+
+[1] Re-run init (update config, re-scaffold)
+[2] Abort (keep existing setup)
+
+---
+
+## Step 1b — Prerequisite check
+
+Before proceeding, silently run `command -v` for each required binary:
+
+| Binary | Install hint |
+|---|---|
+| `jq` | `brew install jq` / `apt install jq` |
+| `curl` | pre-installed on macOS and most Linux |
+| `git` | `brew install git` / `apt install git` |
+
+If all are present: continue silently.
+
+If any are missing, output:
+
+```
+⚠ Missing prerequisites:
+
+  ✗ jq — brew install jq  (or apt install jq on Linux)
+
+Clancy's shell scripts require these binaries to run. Install them, then re-run /clancy:init.
+```
+
+List only the missing ones. Then stop — do not proceed with setup until prerequisites are satisfied.
+
+---
+
+## Step 2 — Welcome message
+
+Output:
+
+Clancy pulls tickets from your Kanban board, implements them, commits, and squash-merges — one ticket per run, fresh context every time.
+
+Let's get you set up.
+
+---
+
+## Step 3 — Questions (board-dependent)
+
+### Q1: Board selection
+
+Output:
+
+Which Kanban board are you using?
+
+[1] Jira
+[2] GitHub Issues
+[3] Linear
+[4] My board isn't listed
+
+If the user selects [4], output the dead-end message and stop:
+
+Clancy currently supports Jira, GitHub Issues, and Linear out of the box.
+
+Your board isn't supported yet — but you can add it:
+  · Open an issue:   github.com/Pushedskydiver/clancy/issues
+  · Contribute one:  see CONTRIBUTING.md — adding a board is just a script template + a boards.json entry
+
+In the meantime, you can still use Clancy manually:
+  · Run /clancy:map-codebase to scan and document your codebase
+  · Use the clancy-once.sh template from the GitHub repo as a starting point
+  · Implement your board's API fetch, store credentials in .clancy/.env
+  · Point clancy-afk.sh at your custom script via CLANCY_ONCE_SCRIPT in .clancy/.env
+
+Do not scaffold anything after this message. Stop completely.
+
+---
+
+### Q2: Board-specific config
+
+Ask each question individually and wait for an answer before moving to the next.
+
+**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, show:
+```
+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)`
+3. `What label should Clancy filter by? Create a "clancy" label in your Linear team and apply it to issues you want Clancy to implement. [clancy]`
+
+If a label is entered: store as `CLANCY_LABEL` in `.clancy/.env`. Always wrap the value in double quotes (e.g. `CLANCY_LABEL="clancy"`).
+If enter is pressed with no value: skip — omit the label clause entirely (Clancy will pick up all unstarted assigned issues).
+
+---
+
+### Q3 (Jira only): Status name
+
+Output:
+
+Which Jira status should Clancy pick tickets from?
+Common values: To Do, Selected for Development, Ready, Open
+
+[1] To Do (default)
+[2] Enter a different value
+
+Store as `CLANCY_JQL_STATUS` in `.clancy/.env`. Always wrap the value in double quotes — status names often contain spaces (e.g. `CLANCY_JQL_STATUS="Selected for Development"`) and unquoted values with spaces cause bash parse errors when the file is sourced.
+
+---
+
+### Q3b (Jira only): Sprints
+
+Output: `Does your Jira project use sprints? (Requires Jira Software — not available on all plans) [y/N]:`
+
+If yes: add `CLANCY_JQL_SPRINT=true` to `.clancy/.env`.
+If no: omit the sprint clause from JQL entirely.
+
+---
+
+### Q3c (Jira only): Label filter
+
+Output: `What label should Clancy filter by? Create a "clancy" label in your Jira project and apply it to tickets you want Clancy to implement. [clancy]`
+
+If a label is entered: store as `CLANCY_LABEL` in `.clancy/.env`. Always wrap the value in double quotes (e.g. `CLANCY_LABEL="clancy"`).
+If enter is pressed with no value: skip — omit the label clause entirely (Clancy will pick up all assigned tickets in the queue).
+
+---
+
+### Q4: Base branch (auto-detect)
+
+Silently detect the base branch — do not ask unless detection fails:
+
+1. Run `git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null` and strip the `refs/remotes/origin/` prefix
+2. If that fails, check whether `main`, `master`, or `develop` exist as local branches (in that order)
+3. If still unresolved, default to `main`
+
+Only if detection produces an unexpected result (e.g. something other than main/master/develop), confirm with the user:
+
+Detected base branch: `{branch}` — is this correct? [Y/n]
+
+Store the detected (or confirmed) value as `CLANCY_BASE_BRANCH` in `.clancy/.env`.
+
+---
+
+## Step 4 — Scaffold
+
+Create `.clancy/` directory and the following:
+
+1. Copy the correct `clancy-once.sh` variant for the chosen board to `.clancy/clancy-once.sh`
+2. Copy `clancy-afk.sh` to `.clancy/clancy-afk.sh`
+3. Make both scripts executable: `chmod +x .clancy/*.sh`
+4. Create `.clancy/docs/` with 10 empty template files (UPPERCASE.md with section headings only):
+   - STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, CONVENTIONS.md, TESTING.md
+   - GIT.md, DESIGN-SYSTEM.md, ACCESSIBILITY.md, DEFINITION-OF-DONE.md, CONCERNS.md
+5. Copy the correct `.env.example` variant to `.clancy/.env.example`
+6. Write collected credentials to `.clancy/.env` (if the user provided them)
+7. Handle `CLAUDE.md` — follow the merge logic in scaffold.md exactly:
+   - If no CLAUDE.md: write the full template as `CLAUDE.md`
+   - If CLAUDE.md exists without `<!-- clancy:start -->`: append the Clancy section to the end
+   - If CLAUDE.md exists with `<!-- clancy:start -->`: replace only the content between the markers
+   - Never overwrite the entire file
+8. Check `.gitignore` — if `.clancy/.env` is not listed, append it
+
+---
+
+## Step 4b — Commit scaffold
+
+After scaffolding, commit everything created (excluding `.clancy/.env` which contains credentials):
+
+```bash
+git add .clancy/clancy-once.sh .clancy/clancy-afk.sh .clancy/.env.example .clancy/docs/ CLAUDE.md .gitignore
+git commit -m "chore(clancy): initialise — scaffold scripts, docs templates, and config"
+```
+
+If `CLAUDE.md` was not modified (it already existed and was not changed), omit it from the `git add`. If `.gitignore` was not modified, omit it too. Only stage files that actually changed.
+
+---
+
+## Step 5 — Optional enhancements
+
+Output:
+
+```
+Clancy is set up. A few optional enhancements are available:
+
+  1. Figma MCP        — fetch design specs when tickets include a Figma URL
+  2. Playwright       — screenshot and verify UI after implementing tickets
+  3. Notifications    — post to Slack or Teams when a ticket completes or errors
+  4. Max iterations   — set how many tickets /clancy:run processes per session
+
+Each takes about 2 minutes to configure, or skip any for now.
+You can always add them later by editing .clancy/.env.
+
+Set up optional enhancements? [y/N]
+```
+
+If no: skip to Step 6.
+
+If yes, walk through each in order. After each enhancement (whether configured or skipped), ask before starting the next one: `Set up [enhancement name]? [y/N]`
+
+### Enhancement 1: Figma MCP
+
+Output: `Fetch design context from Figma when tickets include a Figma URL. Set up Figma MCP? [y/N]`
+
+If no: skip to Enhancement 2.
+
+If yes: `Paste your Figma API key: (create one at figma.com/settings → Personal access tokens)`
+
+If a key is entered:
+1. Verify the key by calling `GET https://api.figma.com/v1/me` with `X-Figma-Token: {key}`
+2. On success, show:
+   ```
+   ✓ Figma connected: {email}
+
+   Note: Figma's API does not expose plan information.
+   Clancy uses 3 MCP calls per ticket (metadata, design context, screenshot).
+   Check your plan at figma.com/settings to confirm you have enough MCP calls for your usage.
+   Pro plans: 200 calls/day (~66 tickets). Starter: 6 calls/month (not suitable for AFK use).
+
+   Figma MCP enabled.
+   ```
+
+If `GET /v1/me` fails (non-200), show:
+```
+✗ Couldn't verify Figma API key (HTTP {status}).
+Double-check it at figma.com/settings → Personal access tokens.
+
+[1] Try a different key
+[2] Skip Figma for now
+```
+Never silently continue with an unverified key. If the user picks [1], re-prompt for the key and repeat the verification. If [2], skip to Enhancement 2.
+
+Write `FIGMA_API_KEY` to `.clancy/.env`. Add usage note to CLAUDE.md Clancy section.
+
+---
+
+### Enhancement 2: Playwright visual checks
+
+If Figma was configured in Enhancement 1, output:
+`Screenshot and verify UI after implementing tickets — and compare against the Figma design when one was fetched. Set up Playwright visual checks? [y/N]`
+
+Otherwise output:
+`Screenshot and verify UI after implementing tickets. Set up Playwright visual checks? [y/N]`
+
+If no: skip to Enhancement 3.
+
+If yes, continue:
+
+**Step 1: Storybook detection**
+
+Check `package.json` for `@storybook/` dependencies and `.storybook/` directory.
+If detected: "This project appears to use Storybook. Is that right? [Y/n]"
+
+**Step 2: (If Storybook confirmed) Storybook content**
+```
+What does your project keep in Storybook?
+[a] Individual components only (atoms, molecules, organisms)
+[b] Components and some pages
+[c] Everything — all UI is previewed in Storybook
+[d] Let me describe it
+```
+
+**Step 3: (If Storybook confirmed) Dev server scope**
+```
+What UI work requires the full dev server instead of Storybook?
+[a] Full pages and routes
+[b] Nothing — everything is in Storybook
+[c] Let me describe it
+```
+
+**Step 4: Dev server command**
+Auto-detect from `package.json` scripts (priority: `dev`, `start`, `serve`).
+```
+What command starts your dev server?
+  Detected: {value}
+
+[1] Yes, use this
+[2] Enter a different command
+```
+
+**Step 5: Dev server port**
+Auto-detect from `vite.config.*`, `next.config.*`, or common defaults (5173, 3000, 8080).
+```
+What port does your dev server run on?
+  Detected: {value}
+
+[1] Yes, use this
+[2] Enter a different port
+```
+
+**Step 6: (If Storybook confirmed) Storybook command**
+Auto-detect from `package.json` scripts (`storybook`, `storybook:dev`).
+```
+What command starts Storybook?
+  Detected: {value}
+
+[1] Yes, use this
+[2] Enter a different command
+```
+
+**Step 7: (If Storybook confirmed) Storybook port**
+Auto-detect from `.storybook/main.js|ts` or default to 6006.
+```
+What port does Storybook run on?
+  Detected: {value}
+
+[1] Yes, use this
+[2] Enter a different port
+```
+
+**Step 8: Startup wait**
+```
+How many seconds should Clancy wait for a server to be ready?
+
+[1] 15 seconds (default)
+[2] Enter a different value
+```
+
+Write to `.clancy/.env`. Wrap command values in double quotes — they often contain spaces:
+```
+PLAYWRIGHT_ENABLED=true
+PLAYWRIGHT_DEV_COMMAND="<value>"
+PLAYWRIGHT_DEV_PORT=<value>
+PLAYWRIGHT_STORYBOOK_COMMAND="<value>"   # only if Storybook confirmed
+PLAYWRIGHT_STORYBOOK_PORT=<value>        # only if Storybook confirmed
+PLAYWRIGHT_STARTUP_WAIT=<value>
+```
+
+Create `.clancy/docs/PLAYWRIGHT.md` — see PLAYWRIGHT.md template in scaffold.md.
+
+---
+
+### Enhancement 3: Slack / Teams notifications
+
+Output: `Post to a channel when a ticket completes or Clancy hits an error. Set up notifications? [y/N]`
+
+If no: skip to Enhancement 4.
+
+If yes: `Paste your Slack or Teams webhook URL:`
+
+Auto-detect platform from URL:
+- `https://hooks.slack.com/` → Slack → sends `{"text": "..."}` payload
+- `https://prod-*.logic.azure.com/` or `https://*.webhook.office.com/` → Teams → sends Adaptive Card
+
+If Teams URL entered, show:
+```
+Ensure you've set up the "Post to a channel when a webhook request is received"
+workflow via Teams → channel → ... → Workflows. The URL must come from that
+workflow's trigger, not from the old Office 365 Connectors setup (retired April 2026).
+```
+
+Write `CLANCY_NOTIFY_WEBHOOK=<url>` to `.clancy/.env`.
+
+---
+
+### Enhancement 4: Max iterations
+
+Output:
+
+```
+How many tickets should /clancy:run process before stopping? [5]
+(You can override this per-session with /clancy:run 20)
+```
+
+Write `MAX_ITERATIONS=<value>` to `.clancy/.env`.
+
+---
+
+## Step 6 — Offer map-codebase
+
+Output:
+
+One last step — Clancy can scan your codebase now and populate `.clancy/docs/` with structured context it reads before every ticket. This takes about 2 minutes.
+
+Scan codebase now? [Y/n]
+
+If yes: run the map-codebase workflow.
+If no: output "Run /clancy:map-codebase when you're ready." then continue to final output.
+
+---
+
+## Final output
+
+Output:
+
+Clancy is ready.
+
+- Scripts: `.clancy/clancy-once.sh`, `.clancy/clancy-afk.sh`
+- Docs: `.clancy/docs/` (10 files)
+- Config: `.clancy/.env`
+- CLAUDE.md: updated
+
+Run `/clancy:once` to pick up your first ticket, or `/clancy:run` to process the full queue.

package/src/workflows/logs.md

@@ -0,0 +1,82 @@
+# Clancy Logs Workflow
+
+## Overview
+
+Read `.clancy/progress.txt` and present a formatted summary.
+
+---
+
+## Step 1 — Check file exists
+
+If `.clancy/progress.txt` does not exist:
+```
+No progress logged yet. Run /clancy:once or /clancy:run to get started.
+```
+Stop.
+
+---
+
+## Step 2 — Parse progress.txt
+
+Each line format: `YYYY-MM-DD HH:MM | TICKET-KEY | Summary | DONE`
+Review lines format: `YYYY-MM-DD HH:MM | TICKET-KEY | REVIEW | {score}%`
+
+Parse each line:
+- Date (YYYY-MM-DD)
+- Time (HH:MM)
+- Ticket key (e.g. PROJ-42)
+- Summary or "REVIEW"
+- Status ("DONE" or score)
+
+Extract:
+- Total DONE tickets
+- First and latest run dates
+- All DONE tickets from the current calendar week (Mon–Sun)
+- Epic key from ticket key — e.g. PROJ-42 → epic likely PROJ-10 (use parent field if logged, otherwise group by project prefix)
+
+---
+
+## Step 3 — Display
+
+If only 1–3 DONE entries: show a flat list, skip grouping.
+
+If 4+ entries, show the full grouped display:
+
+```
+Clancy Progress Log
+───────────────────────────────────────
+Total tickets completed: {count}
+First run: {YYYY-MM-DD}
+Latest run: {YYYY-MM-DD}
+
+This week ({Mon date}–{Sun date or today}):
+  ✓ {TICKET-KEY}  {Summary}
+  ✓ {TICKET-KEY}  {Summary}
+  ...
+
+By epic:
+  {EPIC-KEY} {Epic name or prefix}  {bar}  {count} tickets
+  {EPIC-KEY} {Epic name or prefix}  {bar}  {count} tickets
+  (other)                           {bar}  {count} tickets
+
+Full log: .clancy/progress.txt
+
+Reviews run: {N}
+```
+
+### Display rules
+
+- Show "this week" at the top — most recent activity is most relevant
+- Cap "this week" at 10 entries. If more: "...and {n} more this week"
+- 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 lines: shown separately at the end as "Reviews run: N" — not included in ticket count
+
+---
+
+## Notes
+
+- No external dependencies — all ASCII, all bash-parseable
+- The full log is always available at `.clancy/progress.txt` for raw access
+- `--all` flag to remove the "this week" cap is a v2 addition — do not implement in v1

package/src/workflows/map-codebase.md

@@ -0,0 +1,124 @@
+# Clancy Map-Codebase Workflow
+
+## Overview
+
+Scan the codebase with 5 parallel specialist agents, each writing their assigned docs to `.clancy/docs/`. All 5 agents run simultaneously.
+
+---
+
+## Step 1 — Check existing docs
+
+If `.clancy/docs/` already has non-empty files:
+```
+.clancy/docs/ already has content.
+
+[1] Refresh all — re-run all 5 agents
+[2] Update changed — detect what changed and re-run relevant agents
+[3] Skip — keep existing docs
+```
+
+If no content exists, proceed directly to Step 2.
+
+---
+
+## Step 2 — Create docs directory
+
+Create `.clancy/docs/` if it doesn't exist.
+
+---
+
+## Step 3 — Spawn all 5 agents simultaneously
+
+Launch all agents in parallel. Do not wait for one before starting the next.
+
+Each agent is defined in `src/agents/`. Pass the agent the full path to the docs directory and the project root.
+
+| Agent | Prompt file | Docs written |
+|---|---|---|
+| tech | `src/agents/tech-agent.md` | `STACK.md`, `INTEGRATIONS.md` |
+| arch | `src/agents/arch-agent.md` | `ARCHITECTURE.md` |
+| quality | `src/agents/quality-agent.md` | `CONVENTIONS.md`, `TESTING.md`, `GIT.md`, `DEFINITION-OF-DONE.md` |
+| design | `src/agents/design-agent.md` | `DESIGN-SYSTEM.md`, `ACCESSIBILITY.md` |
+| concerns | `src/agents/concerns-agent.md` | `CONCERNS.md` |
+
+Tell the user agents are running:
+```
+Scanning codebase with 5 parallel agents...
+  tech     → STACK.md, INTEGRATIONS.md
+  arch     → ARCHITECTURE.md
+  quality  → CONVENTIONS.md, TESTING.md, GIT.md, DEFINITION-OF-DONE.md
+  design   → DESIGN-SYSTEM.md, ACCESSIBILITY.md
+  concerns → CONCERNS.md
+```
+
+---
+
+## Step 4 — Collect confirmations
+
+Each agent returns a brief confirmation when done. Display as they complete:
+```
+  ✓ tech agent complete
+  ✓ arch agent complete
+  ✓ quality agent complete
+  ✓ design agent complete
+  ✓ concerns agent complete
+```
+
+---
+
+## Step 5 — Verify
+
+Check that all 10 files exist and are non-empty:
+- `.clancy/docs/STACK.md`
+- `.clancy/docs/INTEGRATIONS.md`
+- `.clancy/docs/ARCHITECTURE.md`
+- `.clancy/docs/CONVENTIONS.md`
+- `.clancy/docs/TESTING.md`
+- `.clancy/docs/GIT.md`
+- `.clancy/docs/DEFINITION-OF-DONE.md`
+- `.clancy/docs/DESIGN-SYSTEM.md`
+- `.clancy/docs/ACCESSIBILITY.md`
+- `.clancy/docs/CONCERNS.md`
+
+If any file is missing or empty, report which agent failed and suggest re-running:
+```
+Warning: {filename} is missing or empty. The {agent} agent may have failed.
+Run /clancy:update-docs to re-run only that agent.
+```
+
+Also check: if `PLAYWRIGHT_ENABLED=true` in `.clancy/.env`, verify `.clancy/docs/PLAYWRIGHT.md` exists. If not, create it from the template (see scaffold.md).
+
+---
+
+## Step 6 — Commit
+
+```bash
+git add .clancy/docs/
+git commit -m "docs(clancy): map codebase — generate .clancy/docs/"
+```
+
+---
+
+## Step 7 — Final message
+
+```
+Codebase mapped. Clancy is ready.
+
+Docs written to .clancy/docs/ (10 files)
+
+Run /clancy:once to pick up your first ticket.
+Run /clancy:run to process the full queue.
+```
+
+---
+
+## Agent instructions (apply to all 5 agents)
+
+When writing agent prompts, embed these instructions:
+
+- Use actual file paths (`src/components/Button.tsx` not "the Button component")
+- Show HOW things are done with real code examples, not just WHAT exists
+- Use Glob and Grep liberally before writing — understand the codebase, don't guess
+- Write directly to file using the Write tool — never use bash heredocs
+- Return a brief confirmation only — do not include doc contents in the response
+- If a section has no content (e.g. no design system exists), write: `<!-- Not applicable to this project -->`

package/src/workflows/once.md

@@ -0,0 +1,80 @@
+## Update check
+
+Before doing anything else, check for updates:
+
+1. Run: `npm show chief-clancy version`
+2. Read the installed version from the Clancy `package.json`
+3. If a newer version exists, print: `ℹ Clancy v{current} → v{latest} available. Run /clancy:update to upgrade.` then continue normally.
+4. If already on latest, continue silently.
+5. If the npm check fails for any reason (offline, network error), continue silently. Never block on this.
+
+---
+
+# Clancy Once Workflow
+
+## Overview
+
+Pick up exactly one ticket from the Kanban board, implement it, commit, squash-merge, and stop. Does not loop.
+
+---
+
+## Step 1 — Preflight checks
+
+1. Check `.clancy/` exists. If not:
+   ```
+   .clancy/ not found. Run /clancy:init first to set up Clancy.
+   ```
+   Stop.
+
+2. Check `.clancy/.env` exists and board credentials are present. If not:
+   ```
+   Missing credentials in .clancy/.env. Run /clancy:init to reconfigure.
+   ```
+   Stop.
+
+3. The script to run is always `.clancy/clancy-once.sh` regardless of board.
+   `/clancy:init` copies the correct board variant as `clancy-once.sh` during setup.
+
+4. Check `.clancy/clancy-once.sh` exists. If not:
+   ```
+   .clancy/clancy-once.sh not found. Run /clancy:init to scaffold scripts.
+   ```
+   Stop.
+
+---
+
+## Step 2 — Run
+
+Display:
+```
+Running Clancy for one ticket.
+```
+
+Execute:
+```bash
+bash .clancy/clancy-once.sh
+```
+
+Stream output directly — do not buffer or summarise.
+
+---
+
+## Step 3 — Result
+
+On success, echo the result line from the script output:
+```
+✓ {TICKET-KEY} complete.
+```
+
+On failure:
+```
+Clancy stopped. See output above for details.
+Run /clancy:status to check the board, or /clancy:review to inspect the ticket.
+```
+
+---
+
+## Notes
+
+- Do not loop. This command runs the script exactly once and stops.
+- Do not attempt to run scripts from `src/templates/` — only scripts in `.clancy/`.