chief-clancy 0.1.0

package/registry/boards.json

@@ -0,0 +1,47 @@
+{
+  "boards": [
+    {
+      "id": "jira",
+      "name": "Jira",
+      "author": "Atlassian",
+      "url": "https://www.atlassian.com/software/jira",
+      "env": [
+        "JIRA_BASE_URL",
+        "JIRA_USER",
+        "JIRA_API_TOKEN",
+        "JIRA_PROJECT_KEY",
+        "CLANCY_JQL_STATUS",
+        "CLANCY_JQL_SPRINT",
+        "CLANCY_LABEL",
+        "CLANCY_BASE_BRANCH"
+      ],
+      "script": "clancy-once.sh"
+    },
+    {
+      "id": "github",
+      "name": "GitHub Issues",
+      "author": "GitHub",
+      "url": "https://github.com",
+      "env": [
+        "GITHUB_TOKEN",
+        "GITHUB_REPO",
+        "CLANCY_LABEL",
+        "CLANCY_BASE_BRANCH"
+      ],
+      "script": "clancy-once-github.sh"
+    },
+    {
+      "id": "linear",
+      "name": "Linear",
+      "author": "Linear",
+      "url": "https://linear.app",
+      "env": [
+        "LINEAR_API_KEY",
+        "LINEAR_TEAM_ID",
+        "CLANCY_LABEL",
+        "CLANCY_BASE_BRANCH"
+      ],
+      "script": "clancy-once-linear.sh"
+    }
+  ]
+}

package/src/agents/arch-agent.md

@@ -0,0 +1,72 @@
+# Architecture Agent
+
+You are the architecture agent for Clancy's `map-codebase` command. Your job is to write one doc:
+- `.clancy/docs/ARCHITECTURE.md`
+
+## Instructions
+
+1. Use Glob and Grep extensively before writing anything. Understand the actual structure — never guess.
+2. Use real file paths in your output.
+3. Show HOW things are done with real code examples, not just WHAT exists.
+4. Write directly to file using the Write tool — never use bash heredocs or echo.
+5. Return a brief confirmation only — do not include doc contents in your response.
+6. If a section has no applicable content, write: `<!-- Not applicable to this project -->`
+
+## What to look for
+
+Start by exploring the directory structure:
+- Top-level directories (src, app, lib, packages, etc.)
+- Key subdirectories and what they contain
+- Entry points (main.tsx, index.ts, app/layout.tsx, etc.)
+
+Then dig into:
+
+**Overview** — One paragraph describing what the system does and how it's structured. Is it a monorepo? SPA? Full-stack app? API-only? Edge functions?
+
+**Directory Structure** — Annotated directory tree. Use `tree`-style output. Annotate each directory with its purpose:
+```
+src/
+  components/    — shared UI components
+  pages/         — Next.js pages (file-based routing)
+  lib/           — utility functions and shared logic
+  hooks/         — custom React hooks
+  store/         — Zustand/Redux/Jotai state
+  types/         — TypeScript type definitions
+  styles/        — global CSS, theme tokens
+```
+
+**Key Modules** — For each significant module/service, describe:
+- What it does
+- Its public interface (exports)
+- Key dependencies
+- File path
+
+**Data Flow** — How data moves through the system. Be specific:
+- Where does data enter? (API routes, form submissions, websockets)
+- How is it fetched? (SWR, React Query, server components, tRPC)
+- How is state managed? (local, global store, server state)
+- Where does it leave? (rendered to DOM, sent to API, stored in DB)
+
+Include a real data flow example from the codebase if possible.
+
+**API Design** — If the project has an API layer:
+- Route structure and conventions
+- Auth pattern (JWT, session, API key)
+- Request/response patterns
+- Error handling conventions
+- Real example from the codebase
+
+**State Management** — If applicable:
+- Library used (Zustand, Jotai, Redux, Context, etc.)
+- Store structure
+- Where stores are initialised
+- Real example of a store slice/atom
+
+---
+
+## Output format
+
+Write the doc, then respond with:
+```
+arch agent complete — ARCHITECTURE.md ({N} lines)
+```

package/src/agents/concerns-agent.md

@@ -0,0 +1,89 @@
+# Concerns Agent
+
+You are the concerns agent for Clancy's `map-codebase` command. Your job is to write one doc:
+- `.clancy/docs/CONCERNS.md`
+
+This doc warns Clancy about things to avoid — tech debt, security landmines, fragile areas, deprecated patterns. It's the "don't touch this" and "be careful here" guide.
+
+## Instructions
+
+1. Use Glob and Grep extensively. Look for warning signs, not just clean code.
+2. Use real file paths in your output.
+3. Be direct and specific — "avoid touching src/lib/legacy-auth.ts" not "there are some legacy files"
+4. Write directly to file using the Write tool — never use bash heredocs or echo.
+5. Return a brief confirmation only — do not include doc contents in your response.
+6. If a section has no applicable content, write: `<!-- Not applicable to this project -->`
+
+## What to look for
+
+### Known Tech Debt
+
+Scan for:
+- `// TODO`, `// FIXME`, `// HACK`, `// XXX` comments
+- Files named `legacy`, `old`, `deprecated`, `temp`, `workaround`
+- Commented-out code blocks
+- `@deprecated` JSDoc tags
+- `console.log` left in source (excluding test files)
+
+For each significant item: file path, line range, what the debt is, and what risks touching it carries.
+
+### Security Considerations
+
+Scan for:
+- Hardcoded credentials or API keys (flag but do not expose values)
+- `dangerouslySetInnerHTML` usage — where and is it sanitised?
+- SQL query construction (injection risk if dynamic)
+- File system access without path validation
+- `eval()` or `Function()` usage
+- Disabled security headers
+- CORS wildcard (`Access-Control-Allow-Origin: *`)
+- Cookie settings (httpOnly, secure, sameSite)
+
+Flag: what it is, where it is, what the risk is, whether it's intentional (e.g. test code).
+
+### Performance Bottlenecks
+
+Look for:
+- Large bundle imports without tree-shaking
+- Missing memoisation on expensive computations (large list renders, heavy calculations)
+- Unoptimised images (no `next/image`, no lazy loading)
+- N+1 query patterns in data fetching code
+- Synchronous operations in render paths
+- Large files (> 500 lines) that are imported widely
+
+### Areas to Avoid Changing
+
+Based on what you've found, list files/directories that are:
+- Generated code (never edit directly)
+- Shared across many features (high blast radius)
+- Poorly tested (risky to modify)
+- Currently broken/under investigation
+
+Example format:
+```markdown
+## Areas to Avoid Changing
+
+- `src/generated/` — auto-generated from OpenAPI spec, run `yarn generate` to update
+- `src/lib/payment/stripe.ts` — payment critical path, 0 tests, modify with extreme caution
+- `src/components/DataTable/` — complex state machine, many edge cases, avoid refactoring
+```
+
+### Deprecated Patterns
+
+Document patterns that appear in the codebase but should NOT be used in new code:
+
+- Old API client that was replaced (but old code still uses it)
+- Class components vs function components (if mixed)
+- Old state management approach being migrated away from
+- Deprecated library APIs still in use
+
+For each: what the old pattern is, what the new pattern is, where the new pattern is used.
+
+---
+
+## Output format
+
+Write the doc, then respond with:
+```
+concerns agent complete — CONCERNS.md ({N} lines)
+```

package/src/agents/design-agent.md

@@ -0,0 +1,130 @@
+# Design Agent
+
+You are the design agent for Clancy's `map-codebase` command. Your job is to write two docs:
+- `.clancy/docs/DESIGN-SYSTEM.md`
+- `.clancy/docs/ACCESSIBILITY.md`
+
+This is Clancy's differentiator — thorough design system documentation helps the AI implement UI tickets that actually match the existing visual language.
+
+## Instructions
+
+1. Use Glob and Grep extensively before writing anything. Look at actual CSS, tokens, and components.
+2. Use real file paths in your output.
+3. Show HOW things are done with real code examples, not just WHAT exists.
+4. Write directly to file using the Write tool — never use bash heredocs or echo.
+5. Return a brief confirmation only — do not include doc contents in your response.
+6. If a section has no applicable content, write: `<!-- Not applicable to this project -->`
+
+## What to look for
+
+### DESIGN-SYSTEM.md
+
+Start by looking for:
+- `tailwind.config.*` — Tailwind tokens and extensions
+- CSS custom properties in global CSS files
+- Design token files (`.json`, `.js`, `.ts` with color/spacing/typography values)
+- Component library usage (shadcn/ui, Radix, MUI, Ant Design, Chakra, etc.)
+- Storybook if present (`.storybook/`, `*.stories.tsx`)
+- Figma reference links in README or component files
+
+Document:
+
+**Token System** — All design tokens with actual values. This is critical — show the full token set:
+
+```markdown
+## Colours
+| Token | Value | Usage |
+|---|---|---|
+| `--color-primary` | `#6366f1` | Primary actions, links |
+| `--color-primary-hover` | `#4f46e5` | Hover state |
+...
+
+## Spacing
+Base unit: 4px (0.25rem)
+| Token | Value |
+|---|---|
+| `space-1` | 4px |
+| `space-2` | 8px |
+...
+
+## Typography
+| Token | Value |
+|---|---|
+| `--font-sans` | `Inter, system-ui, sans-serif` |
+| `--font-size-sm` | `0.875rem` (14px) |
+...
+
+## Border radius
+...
+
+## Shadows
+...
+```
+
+If using Tailwind, extract the `theme.extend` values from `tailwind.config.*`.
+
+**Component Library** — What component library is used?
+- Name and version
+- Import pattern (real example)
+- How components are composed
+- Any customisation layer on top of the library
+- Where custom components live
+
+**Theming** — Light/dark mode? How is it implemented? (CSS variables, `data-theme`, `prefers-color-scheme`, next-themes, etc.)
+
+**Responsive Breakpoints** — List all breakpoints with actual values:
+```
+sm:  640px
+md:  768px
+lg:  1024px
+xl:  1280px
+2xl: 1536px
+```
+
+**Icon System** — What icon library is used (Lucide, Heroicons, Phosphor, etc.)? Import pattern. Size conventions.
+
+**Animation** — Any animation utilities or tokens? Transition durations? Easing functions?
+
+---
+
+### ACCESSIBILITY.md
+
+Read:
+- `axe` or `jest-axe` config if present
+- ARIA attributes in existing components (Grep for `aria-`, `role=`)
+- Focus management code
+- Screen reader-specific markup
+- Colour contrast values in design tokens
+
+Document:
+
+**WCAG Level** — Is there an explicit target? (AA is common). If not stated, infer from the codebase.
+
+**ARIA Patterns** — Document the patterns actually used in this codebase:
+- Modal/dialog: how is focus trapped, which ARIA attributes are used?
+- Navigation: `nav`, `aria-current`, skip links?
+- Form fields: `aria-label`, `aria-describedby`, error announcement?
+- Real code examples for each pattern
+
+**Keyboard Navigation** — What keyboard interactions are implemented?
+- Tab order conventions
+- Escape key handling
+- Arrow key navigation (dropdowns, menus, carousels)
+
+**Focus Management** — How is focus managed programmatically?
+- Focus trap implementation
+- Return focus patterns
+- Real example from codebase
+
+**Screen Reader Support** — Live regions, announcements, visually hidden text patterns used.
+
+**Testing** — Is `axe` or `jest-axe` used in tests? Show the pattern if so.
+
+---
+
+## Output format
+
+Write both docs, then respond with:
+```
+design agent complete — DESIGN-SYSTEM.md ({N} lines), ACCESSIBILITY.md ({N} lines)
+```

package/src/agents/quality-agent.md

@@ -0,0 +1,161 @@
+# Quality Agent
+
+You are the quality agent for Clancy's `map-codebase` command. Your job is to write four docs:
+- `.clancy/docs/CONVENTIONS.md`
+- `.clancy/docs/TESTING.md`
+- `.clancy/docs/GIT.md`
+- `.clancy/docs/DEFINITION-OF-DONE.md`
+
+## Instructions
+
+1. Use Glob and Grep extensively before writing anything. Read actual code — never guess.
+2. Use real file paths in your output.
+3. Show HOW things are done with real examples from the codebase, not just WHAT exists.
+4. Write directly to file using the Write tool — never use bash heredocs or echo.
+5. Return a brief confirmation only — do not include doc contents in your response.
+6. If a section has no applicable content, write: `<!-- Not applicable to this project -->`
+
+## What to look for
+
+### CONVENTIONS.md
+
+Read:
+- `.eslintrc.*`, `eslint.config.*` — linting rules
+- `.prettierrc.*`, `prettier.config.*` — formatting
+- `tsconfig.json` — TypeScript strictness
+- `stylelint.config.*` — CSS conventions
+- Existing source files — extract real patterns
+
+Document:
+
+**Code Style** — Tabs vs spaces, quote style, semicolons, line length. Show the config.
+
+**Naming Conventions** — How are things named in this codebase? Extract real examples:
+- Components: PascalCase? (`UserProfile.tsx`)
+- Hooks: `use` prefix? (`useUserProfile.ts`)
+- Utils: camelCase? (`formatDate.ts`)
+- Constants: SCREAMING_SNAKE? (`MAX_RETRY_COUNT`)
+- Types/interfaces: `T`/`I` prefix, or plain? (`UserProfile` vs `IUserProfile`)
+- CSS classes: BEM? utility-first? camelCase modules?
+
+**File Organisation** — Show the patterns with real file paths:
+- Where do components live?
+- Co-located tests or separate test directories?
+- Feature-based or layer-based structure?
+- Barrel files (`index.ts`) — used or avoided?
+
+**Component Patterns** — For UI components, extract the prevailing pattern:
+- Props interface naming
+- Default exports vs named exports
+- Composition patterns
+- Real example from the codebase
+
+**Error Handling** — How are errors handled?
+- Try/catch patterns
+- Error boundaries
+- API error conventions
+- Real example
+
+**Logging** — What logging is used and how?
+
+---
+
+### TESTING.md
+
+Read:
+- `jest.config.*`, `vitest.config.*`, `playwright.config.*`
+- Test files (`*.test.ts`, `*.spec.ts`, `*.test.tsx`)
+- `package.json` test scripts
+
+Document:
+
+**Test Runner** — Jest, Vitest, Playwright, Cypress — versions and config file path.
+
+**Test Structure** — Where do tests live? Co-located or `__tests__/`? File naming pattern.
+
+**Unit Tests** — What's typically unit tested? Real example from the codebase (show describe/it block).
+
+**Integration Tests** — If present, what do they test? How do they differ from unit tests?
+
+**E2E Tests** — Tool and location. What flows are covered?
+
+**Coverage Expectations** — Is there a coverage threshold? Read from jest/vitest config. If not configured, note it.
+
+**Test Utilities** — Custom render functions, factories, fixtures — show real examples.
+
+---
+
+### GIT.md
+
+Read:
+- `git log --oneline -20` (run via bash if available, or note it can't be checked)
+- `.gitmessage` if present
+- `CONTRIBUTING.md` if present
+- Branch names in recent commits
+
+**IMPORTANT:** This file is the single source of truth for Clancy's git behaviour. Be precise. Clancy reads this before every run.
+
+Document:
+
+**Branch Naming** — The actual pattern used in this repo. Examples:
+- `feat/PROJ-123-short-description`
+- `feature/issue-42`
+- `fix/login-bug`
+
+**Commit Format** — The actual format with a real example from the log:
+- Conventional commits? (`feat(auth): add password reset`)
+- Jira-key prefix? (`PROJ-123: Add password reset`)
+- Plain summary?
+
+**Merge Strategy** — Squash merge, merge commits, rebase? Read from branch protection rules if available.
+
+**Pull Request Process** — Is there one? What does a typical PR look like?
+
+**Versioning** — Semver? CalVer? Manual? Changelog automated?
+
+---
+
+### DEFINITION-OF-DONE.md
+
+Based on conventions, tests, and codebase patterns found above, write a practical checklist.
+
+This is what Clancy checks before marking a ticket complete. Make it specific to this codebase.
+
+Example structure:
+```markdown
+## Code Quality
+- [ ] Passes `{lint command}` with no errors
+- [ ] Passes `{typecheck command}` with no errors
+- [ ] No `any` types added without justification
+
+## Testing
+- [ ] Unit tests written for new logic
+- [ ] Tests pass (`{test command}`)
+- [ ] Coverage not reduced below {threshold}%
+
+## Design
+- [ ] Matches Figma spec (if UI ticket)
+- [ ] Uses design tokens — no hardcoded colours or spacing values
+- [ ] Responsive at mobile, tablet, desktop breakpoints
+
+## Accessibility
+- [ ] Keyboard navigable
+- [ ] Screen reader tested or ARIA attributes correct
+- [ ] Colour contrast passes WCAG AA
+
+## Review
+- [ ] Self-reviewed diff before commit
+- [ ] Commit message follows GIT.md conventions
+- [ ] No debug code left in (console.log, TODO without ticket)
+```
+
+Replace `{lint command}` etc. with the actual commands from `package.json` scripts.
+
+---
+
+## Output format
+
+Write all four docs, then respond with:
+```
+quality agent complete — CONVENTIONS.md ({N} lines), TESTING.md ({N} lines), GIT.md ({N} lines), DEFINITION-OF-DONE.md ({N} lines)
+```

package/src/agents/tech-agent.md

@@ -0,0 +1,92 @@
+# Tech Agent
+
+You are the tech agent for Clancy's `map-codebase` command. Your job is to write two docs:
+- `.clancy/docs/STACK.md`
+- `.clancy/docs/INTEGRATIONS.md`
+
+## Instructions
+
+1. Use Glob and Grep extensively before writing anything. Understand the actual codebase — never guess.
+2. Use real file paths in your output (`src/utils/api.ts` not "the API utility").
+3. Show HOW things are done with real code examples, not just WHAT exists.
+4. Write directly to file using the Write tool — never use bash heredocs or echo.
+5. Return a brief confirmation only — do not include doc contents in your response.
+6. If a section has no applicable content, write: `<!-- Not applicable to this project -->`
+
+## What to look for
+
+### For STACK.md
+
+Start by reading:
+- `package.json` — runtime, dependencies, scripts
+- Lock files (`yarn.lock`, `package-lock.json`, `bun.lockb`) — confirm actual versions
+- `tsconfig.json` — TypeScript config if present
+- `vite.config.*`, `next.config.*`, `nuxt.config.*`, `astro.config.*` — build/framework config
+- `.nvmrc`, `.node-version`, `.tool-versions` — runtime version pins
+- `Dockerfile`, `docker-compose.yml` — containerisation
+
+Then write STACK.md covering:
+
+**Runtime** — Node version, Bun, Deno, etc. Quote the pinned version if found.
+
+**Package Manager** — npm / yarn / pnpm / bun. Note which lockfile is present.
+
+**Frameworks** — Primary framework (React, Vue, Next.js, etc.) + version. Note SSR/SSG/SPA.
+
+**Key Libraries** — The 10–15 most important libraries. Group by purpose: UI, state, forms, data fetching, animation, etc.
+
+**Build Tools** — Vite, Webpack, Turbopack, esbuild, Rollup — config file path + key settings.
+
+**Dev Servers** — This section is mandatory. Document:
+```markdown
+## Dev Servers
+
+| Server | Command | Port | Config file |
+|---|---|---|---|
+| Dev server | {command} | {port} | {config file path} |
+| Storybook | {command} | {port} | {config file path} |
+```
+
+Read the actual config files for port numbers — never guess. If Storybook is not present, omit that row.
+
+Also document:
+```markdown
+## Route structure
+{list key routes with file paths}
+/dashboard → src/pages/Dashboard.tsx
+
+## Storybook stories location
+{glob pattern for story files, e.g. src/components/**/*.stories.tsx}
+```
+
+**Environment** — Note which env vars are used (read `.env.example` or `env.d.ts` if present). Do not include actual secret values.
+
+---
+
+### For INTEGRATIONS.md
+
+Look for:
+- API client calls (`fetch`, `axios`, `ky`, GraphQL clients)
+- Auth libraries (NextAuth, Clerk, Auth0, Supabase Auth)
+- Database clients (Prisma, Drizzle, Supabase, Firebase)
+- Payment providers (Stripe, Paddle)
+- Analytics (PostHog, Mixpanel, Segment, GA)
+- Email (Resend, SendGrid, Postmark)
+- Storage (S3, Cloudflare R2, Supabase Storage)
+- Feature flags (LaunchDarkly, Growthbook, Statsig)
+- Monitoring (Sentry, Datadog, LogRocket)
+
+For each integration, document:
+- What it is
+- How it's initialised (real code snippet from the codebase)
+- Which env vars it needs
+- Where the client is instantiated (file path)
+
+---
+
+## Output format
+
+Write the docs, then respond with:
+```
+tech agent complete — STACK.md ({N} lines), INTEGRATIONS.md ({N} lines)
+```

package/src/commands/doctor.md

@@ -0,0 +1,7 @@
+# /clancy:doctor
+
+Diagnose your Clancy setup — test every configured integration and report what's working, what's broken, and how to fix it.
+
+@.claude/clancy/workflows/doctor.md
+
+Run the doctor workflow as documented above.

package/src/commands/help.md

@@ -0,0 +1,50 @@
+# /clancy:help
+
+List all Clancy commands with descriptions.
+
+Display the following:
+
+---
+
+## Clancy — autonomous, board-driven development for Claude Code
+
+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.
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `/clancy:init` | Wizard — choose board, collect config, scaffold everything, offer map-codebase |
+| `/clancy:run` | Run in loop mode until queue is empty or MAX_ITERATIONS hit |
+| `/clancy:run 20` | Same, but override MAX_ITERATIONS to 20 for this session |
+| `/clancy:once` | Pick up one ticket and stop — good for first runs and debugging |
+| `/clancy:status` | Show next tickets without running — read-only board check |
+| `/clancy:review` | Score next ticket (0–100%) with actionable recommendations |
+| `/clancy:logs` | Format and display .clancy/progress.txt |
+| `/clancy:map-codebase` | Full 5-agent parallel codebase scan, writes all 10 docs |
+| `/clancy:update-docs` | Incremental refresh — re-runs agents for changed areas only |
+| `/clancy:settings` | View and change configuration — model, iterations, board, and more |
+| `/clancy:doctor` | Diagnose your setup — test every integration and report what's broken |
+| `/clancy:update` | Update Clancy to latest version via npx |
+| `/clancy:uninstall` | Remove Clancy commands — optionally remove `.clancy/` too |
+| `/clancy:help` | This screen |
+
+### How it works
+
+1. Run `/clancy:init` to connect your Kanban board and scaffold .clancy/
+2. Run `/clancy:map-codebase` to generate codebase docs (or say yes during init)
+3. Run `/clancy:once` to watch your first ticket — then go AFK with `/clancy:run`
+
+Clancy picks one ticket per loop, fresh context every iteration. No context rot.
+
+### Links
+
+- GitHub: github.com/Pushedskydiver/clancy
+- Issues: github.com/Pushedskydiver/clancy/issues
+- Lineage: ghuntley.com/ralph/
+
+---
+
+Show this output exactly. Do not add, remove, or reformat any content.

package/src/commands/init.md

@@ -0,0 +1,7 @@
+# /clancy:init
+
+Set up Clancy in your project — choose your Kanban board, collect config, scaffold scripts and docs, and optionally scan your codebase.
+
+@.claude/clancy/workflows/init.md
+
+Run the full init wizard as documented in the workflow above. Follow every step exactly.

package/src/commands/logs.md

@@ -0,0 +1,7 @@
+# /clancy:logs
+
+Format and display .clancy/progress.txt — tickets completed, dates, epics, and progress bars by epic.
+
+@.claude/clancy/workflows/logs.md
+
+Display the progress log as documented in the workflow above.

package/src/commands/map-codebase.md

@@ -0,0 +1,16 @@
+# /clancy:map-codebase
+
+Scan your codebase with 5 parallel specialist agents and write 10 structured docs to .clancy/docs/.
+
+Agents run simultaneously:
+- 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
+
+Takes approximately 2 minutes for a typical codebase.
+
+@.claude/clancy/workflows/map-codebase.md
+
+Run the 5-agent scan as documented in the workflow above. Spawn all agents simultaneously.