chief-clancy 0.1.0

package/src/workflows/review.md

@@ -0,0 +1,165 @@
+# Clancy Review Workflow
+
+## Overview
+
+Fetch the next ticket from the board and score how well-specified it is. Returns a confidence score (0–100%) and actionable recommendations. Does not implement anything.
+
+---
+
+## Step 1 — Preflight checks
+
+Same as status workflow. Check `.clancy/`, `.clancy/.env`, and board credentials.
+
+---
+
+## Step 2 — Fetch next ticket
+
+Detect board from `.clancy/.env` and fetch with `maxResults=1`. The query must match `clancy-once.sh` exactly — what review shows is what run would pick up.
+
+**Jira:** Build JQL 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: `project=$JIRA_PROJECT_KEY [AND sprint in openSprints()] [AND labels = "$CLANCY_LABEL"] AND assignee=currentUser() AND status="$CLANCY_JQL_STATUS" ORDER BY priority ASC`
+
+Use the POST `/rest/api/3/search/jql` endpoint (the old GET `/rest/api/3/search` was removed Aug 2025):
+
+```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": 1, "fields": ["summary", "description", "issuelinks", "parent", "customfield_10014"]}')
+```
+
+**GitHub Issues:** `GET /repos/$GITHUB_REPO/issues?state=open&assignee=@me&labels=clancy&per_page=1` — filter out PRs (entries with `pull_request` key)
+
+**Linear:** GraphQL `viewer.assignedIssues` with `filter: { state: { type: { eq: "unstarted" } }, team: { id: { eq: "$LINEAR_TEAM_ID" } }[, labels: { name: { eq: "$CLANCY_LABEL" } }] }` (label clause only if `CLANCY_LABEL` is set), `first: 1`, `orderBy: priority`
+
+Fetch full ticket content: summary, description (full text), acceptance criteria (if present), epic/parent info, blockers/issue links.
+
+If no tickets found:
+```
+No tickets in the queue. Nothing to review.
+```
+Stop.
+
+---
+
+## Step 3 — Score against 7 criteria
+
+Score each criterion as pass / warn / fail using the rubric below. Compute weighted confidence score.
+
+### Scoring rubric
+
+| # | Criterion | Weight | Pass | Warn | Fail |
+|---|---|---|---|---|---|
+| 1 | Summary clarity | 10% | Specific, scopeable | Vague but workable | Too broad or meaningless |
+| 2 | Description quality | 15% | Explains what + why | What only, no why | Missing or one-liner |
+| 3 | Acceptance criteria | 25% | Concrete + testable | Present but vague | Missing entirely |
+| 4 | Figma URL (UI tickets only) | 15% | URL present in description | — | UI ticket, no Figma URL |
+| 5 | Scope realism | 15% | Single focused deliverable | Multiple deliverables or borderline | Too large, "and also" tasks, or spans unrelated systems |
+| 6 | Dependencies stated | 5% | Blockers explicit | — | No mention of dependencies |
+| 7 | Clancy executability | 15% | Purely codebase work | Mostly codebase, minor external touch | Requires work outside the codebase |
+
+**Criterion 7 — Clancy executability:** Score as Fail if the ticket primarily requires any of the following — Clancy cannot do these from within the codebase:
+- **External system admin:** "in Google Analytics", "in Salesforce", "in HubSpot", "in the AWS console", "in Jira admin", "in the app store dashboard"
+- **Human process steps:** "get sign-off from", "send an email to customers", "coordinate with", "schedule a meeting", "announce to users"
+- **Production ops (non-repo):** "deploy to production", "rotate the API keys in prod", "scale the fleet", "restart the service" — unless the ticket is purely about CI/CD config files that live in the repo
+- **Non-code deliverables:** "write a runbook", "update the wiki", "create a presentation", "document in Confluence"
+
+Score as Warn if the ticket is mostly codebase work but has an incidental external touch (e.g. "add a new event to the existing analytics tracking" — the code change is in the repo, even if the event appears in a dashboard).
+
+**Tech stack coherence (part of criterion 7):** If `.clancy/docs/STACK.md` exists, read it and check the ticket against the documented stack. If the ticket mentions a technology or platform not in the documented stack that appears to be an external service (not a new dependency to install), score criterion 7 as Warn and note the mismatch explicitly.
+
+**Figma criterion:** Only applies if the ticket description mentions UI, components, screens, design, or visual elements. Backend/API/config tickets skip criterion 4 and redistribute its 15% weight proportionally across the remaining criteria.
+
+**Figma URL quality checks:**
+- URL present but points to file root (no `node-id`) → warn: recommend scoping to specific frame
+- `FIGMA_API_KEY` not configured but UI ticket has Figma URL → warn: link will be ignored at runtime
+
+**Scope realism — additional Fail signals:**
+- Ticket contains multiple distinct deliverables ("and also", "additionally", "while you're at it", "as well as")
+- Ticket implies setting up new infrastructure from scratch where none exists in the repo (new database, new service, new deployment pipeline)
+- Ticket references 4+ unrelated subsystems that would each require deep separate context
+
+**Score calculation:**
+- Pass = full weight
+- Warn = half weight
+- Fail = zero weight
+- Sum all weighted scores → overall percentage
+
+**Hard gate — executability override:** If criterion 7 scores Fail, cap the verdict at "Needs work" regardless of the calculated score. A ticket that requires work outside the codebase cannot be run reliably no matter how well it is specified.
+
+---
+
+## Step 4 — Generate recommendations
+
+For each warn or fail criterion, generate a specific, actionable recommendation — specific to this ticket, not generic advice.
+
+Good: "Add a Figma URL to the ticket description — this ticket mentions updating the profile header component"
+Bad: "Ensure design specs are provided"
+
+---
+
+## Step 5 — Display output
+
+```
+Reviewing: [{TICKET-KEY}] {Summary}
+
+Confidence: {score}% — {band label}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{for each criterion:}
+✓ {criterion name} — {pass reason}
+⚠ {criterion name} — {warn reason}
+  → {specific recommendation}
+✗ {criterion name} — {fail reason}
+  → {specific recommendation}
+
+Verdict: {action based on band}
+         {next step options}
+```
+
+### Confidence bands
+
+| Score | Label | Verdict action |
+|---|---|---|
+| 85–100% | Ready | "Run with confidence." |
+| 65–84% | Good to go with caveats | "Review the warnings above, then run /clancy:once." |
+| 40–64% | Needs work | "Address the ✗ items in the ticket, then re-run /clancy:review." |
+| 0–39% | Not ready | "This ticket needs significant rework before Clancy can implement it reliably." |
+
+**Executability override:** If criterion 7 (Clancy executability) scores Fail, ignore the calculated band and show:
+```
+Verdict: Not ready for Clancy
+         This ticket requires work outside the codebase — Clancy can only implement code changes.
+         Update the ticket to focus on the codebase side, or remove it from the queue.
+```
+
+Next-step line per band (append after the verdict — never suggest bypassing the review on low-confidence tickets):
+- **Ready:** `Run /clancy:once to pick it up.`
+- **Good to go:** `Fix the warnings if possible, then run /clancy:once.`
+- **Needs work:** `Update the ticket to address the ✗ items above, then re-run /clancy:review.`
+- **Not ready / executability override:** `Rework the ticket first — do not run Clancy on it yet.`
+
+---
+
+## Step 6 — Log the review
+
+Append to `.clancy/progress.txt`:
+```
+YYYY-MM-DD HH:MM | {TICKET-KEY} | REVIEW | {score}%
+```
+
+---
+
+## Notes
+
+- Recommendations are specific to this ticket — never generic
+- The verdict always suggests a next step — never leaves the user without a clear action
+- Re-running `/clancy:review` multiple times is safe — the score may improve as the ticket is updated
+- Do not implement anything — Claude is invoked for analysis only

package/src/workflows/run.md

@@ -0,0 +1,119 @@
+## 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 Run Workflow
+
+## Overview
+
+Run Clancy in loop mode. Processes tickets from the Kanban board until the queue is empty or MAX_ITERATIONS is reached.
+
+---
+
+## Step 1 — Parse argument
+
+The command may be invoked as `/clancy:run` or `/clancy:run N` where N is a positive integer.
+
+- If N is provided: use it as `MAX_ITERATIONS` for this session only. Never write it to `.clancy/.env`.
+- If no argument: read `MAX_ITERATIONS` from `.clancy/.env`. If not set there, default to 5.
+
+If the resolved value of `MAX_ITERATIONS` is **10 or greater**, show a warning before continuing:
+
+```
+⚠ You're about to run Clancy for up to {N} tickets.
+
+At rough estimates per ticket (Sonnet):
+  Simple tickets  ~$0.25–$0.75 each  →  up to ~${low} total
+  Complex tickets ~$2.00–$5.00 each  →  up to ~${high} total
+
+Mistakes compound — if Claude misreads a ticket, it will do so {N} times before you check.
+Consider starting with /clancy:once or a smaller run to validate first.
+
+Continue with {N} tickets? [Y/n]
+```
+
+Where `{low}` = N × 0.75 (rounded to nearest dollar) and `{high}` = N × 5 (rounded to nearest dollar).
+If the user types `n` or `N`: print `Cancelled.` and stop. Any other input (including enter) continues.
+
+---
+
+## Step 2 — 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. If not:
+   ```
+   .clancy/.env not found. Run /clancy:init first.
+   ```
+   Stop.
+
+3. Source `.clancy/.env` and check that board credentials are present.
+
+   **Jira:** `JIRA_BASE_URL`, `JIRA_USER`, `JIRA_API_TOKEN`, `JIRA_PROJECT_KEY`
+   **GitHub:** `GITHUB_TOKEN`, `GITHUB_REPO`
+   **Linear:** `LINEAR_API_KEY`, `LINEAR_TEAM_ID`
+
+   If any required var is missing:
+   ```
+   Missing credentials in .clancy/.env: <var name>
+   Run /clancy:init to reconfigure, or edit .clancy/.env directly.
+   ```
+   Stop.
+
+4. Check `.clancy/clancy-afk.sh` exists. If not:
+   ```
+   .clancy/clancy-afk.sh not found. Run /clancy:init to scaffold scripts.
+   ```
+   Stop.
+
+---
+
+## Step 3 — Start
+
+Display:
+```
+Starting Clancy — will process up to {N} ticket(s). Ctrl+C to stop early.
+```
+
+---
+
+## Step 4 — Run
+
+Execute:
+```bash
+MAX_ITERATIONS={N} bash .clancy/clancy-afk.sh
+```
+
+Stream output directly — do not buffer or summarise.
+
+---
+
+## Step 5 — Finish
+
+When the script exits, echo the final summary line from the output.
+
+If `clancy-afk.sh` exits with a non-zero status:
+```
+Clancy stopped with an error. Check the output above.
+Run /clancy:once for more detail on the next ticket.
+```
+
+---
+
+## Notes
+
+- The `N` argument is session-only. It never modifies `.clancy/.env`.
+- If the user wants to permanently change their default, they edit `.clancy/.env` directly or re-run `/clancy:init` advanced setup.
+- Do not attempt to run scripts from `src/templates/` — only run scripts in `.clancy/`.

package/src/workflows/scaffold.md

@@ -0,0 +1,289 @@
+# Clancy Scaffold Workflow
+
+## Overview
+
+Shared scaffolding logic used during `/clancy:init`. Not a standalone command.
+
+---
+
+## Doc templates
+
+Create these files in `.clancy/docs/` with section headings but no content:
+
+### STACK.md
+```markdown
+# Stack
+
+## Runtime
+
+## Package Manager
+
+## Frameworks
+
+## Key Libraries
+
+## Build Tools
+
+## Dev Servers
+
+## Environment
+```
+
+### INTEGRATIONS.md
+```markdown
+# Integrations
+
+## External APIs
+
+## Authentication
+
+## Data Storage
+
+## Third-party Services
+
+## Environment Variables Required
+```
+
+### ARCHITECTURE.md
+```markdown
+# Architecture
+
+## Overview
+
+## Directory Structure
+
+## Key Modules
+
+## Data Flow
+
+## API Design
+
+## State Management
+```
+
+### CONVENTIONS.md
+```markdown
+# Conventions
+
+## Code Style
+
+## Naming Conventions
+
+## File Organisation
+
+## Component Patterns
+
+## Error Handling
+
+## Logging
+```
+
+### TESTING.md
+```markdown
+# Testing
+
+## Test Runner
+
+## Test Structure
+
+## Unit Tests
+
+## Integration Tests
+
+## E2E Tests
+
+## Coverage Expectations
+```
+
+### GIT.md
+```markdown
+# Git Conventions
+
+## Branch Naming
+
+## Commit Format
+
+## Merge Strategy
+
+## Pull Request Process
+
+## Versioning
+```
+
+### DESIGN-SYSTEM.md
+```markdown
+# Design System
+
+## Token System
+
+## Component Library
+
+## Theming
+
+## Responsive Breakpoints
+
+## Icon System
+```
+
+### ACCESSIBILITY.md
+```markdown
+# Accessibility
+
+## WCAG Level
+
+## ARIA Patterns
+
+## Keyboard Navigation
+
+## Focus Management
+
+## Screen Reader Support
+```
+
+### DEFINITION-OF-DONE.md
+```markdown
+# Definition of Done
+
+## Code Quality
+
+## Testing
+
+## Documentation
+
+## Design
+
+## Accessibility
+
+## Review
+```
+
+### CONCERNS.md
+```markdown
+# Concerns
+
+## Known Tech Debt
+
+## Security Considerations
+
+## Performance Bottlenecks
+
+## Areas to Avoid Changing
+
+## Deprecated Patterns
+```
+
+---
+
+## PLAYWRIGHT.md template
+
+Create `.clancy/docs/PLAYWRIGHT.md` when `PLAYWRIGHT_ENABLED=true`:
+
+```markdown
+# Playwright Visual Checks
+
+Clancy runs visual checks after implementing UI tickets. This file defines
+which server to use and how to start it.
+
+## Decision Rule
+
+Apply in order:
+1. If the ticket mentions: route, page, screen, layout, full-page → use **dev server**
+2. If the ticket mentions: component, atom, molecule, organism, variant, story → use **Storybook**
+3. Ambiguous → default to **dev server**
+
+## Dev Server
+
+| Key | Value |
+|---|---|
+| Start command | `{PLAYWRIGHT_DEV_COMMAND}` |
+| Port | `{PLAYWRIGHT_DEV_PORT}` |
+| Health check | `http://localhost:{PLAYWRIGHT_DEV_PORT}` |
+| Startup wait | {PLAYWRIGHT_STARTUP_WAIT}s (use health check polling, not sleep) |
+
+## Storybook
+
+<!-- Remove this section if Storybook is not used -->
+
+| Key | Value |
+|---|---|
+| Start command | `{PLAYWRIGHT_STORYBOOK_COMMAND}` |
+| Port | `{PLAYWRIGHT_STORYBOOK_PORT}` |
+| Story URL pattern | `http://localhost:{PLAYWRIGHT_STORYBOOK_PORT}/?path=/story/{component-name}` |
+
+## Visual Check Process
+
+1. Determine which server to use (decision rule above)
+2. Start the server using health check polling — poll every 2s, timeout after {PLAYWRIGHT_STARTUP_WAIT}s
+3. Navigate to the relevant route or story URL
+4. Screenshot the full page
+5. Assess visually — check layout, spacing, colours, responsive behaviour
+6. Check browser console for errors
+7. Fix anything wrong before committing
+8. Kill server by PID, then sweep the port unconditionally
+9. Log result: `YYYY-MM-DD HH:MM | TICKET-KEY | PLAYWRIGHT_PASS|FAIL | dev-server|storybook`
+
+## Server Health Check Pattern
+
+```bash
+# Start server in background
+{PLAYWRIGHT_DEV_COMMAND} &
+SERVER_PID=$!
+
+# Poll until ready
+MAX_WAIT={PLAYWRIGHT_STARTUP_WAIT}
+ELAPSED=0
+until curl -s http://localhost:{PLAYWRIGHT_DEV_PORT} >/dev/null 2>&1; do
+  sleep 2
+  ELAPSED=$((ELAPSED + 2))
+  if [ $ELAPSED -ge $MAX_WAIT ]; then
+    echo "Server did not start within ${MAX_WAIT}s"
+    kill $SERVER_PID 2>/dev/null
+    exit 1
+  fi
+done
+
+# ... run visual check ...
+
+# Cleanup — kill by PID, then sweep port unconditionally
+kill $SERVER_PID 2>/dev/null
+lsof -ti:{PLAYWRIGHT_DEV_PORT} | xargs kill -9 2>/dev/null || true
+```
+```
+
+---
+
+## CLAUDE.md merge logic
+
+### If CLAUDE.md does not exist
+
+Write the full template as `CLAUDE.md` (see `src/templates/CLAUDE.md`).
+
+### If CLAUDE.md already exists
+
+Check for existing `<!-- clancy:start -->` marker:
+- Found: Replace everything between `<!-- clancy:start -->` and `<!-- clancy:end -->` with updated content
+- Not found: Append the Clancy section to the end of the file
+
+Never overwrite the entire file. Always preserve existing content.
+
+---
+
+## .gitignore check
+
+Read the project's `.gitignore`. If `.clancy/.env` is not present, append:
+```
+# Clancy credentials
+.clancy/.env
+```
+
+If no `.gitignore` exists, create one with:
+```
+# Clancy credentials
+.clancy/.env
+
+# Dependencies
+node_modules/
+
+# OS
+.DS_Store
+```