diff --git a/reference/CLAUDE-project-automations.md b/reference/CLAUDE-project-automations.md new file mode 100644 index 0000000..caefa34 --- /dev/null +++ b/reference/CLAUDE-project-automations.md @@ -0,0 +1,179 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Salesforce workspace for 's VoIP business operations. Production org: ``, API version 66.0. + +| Directory | Purpose | +|-----------|---------| +| `salesforce/force-app/` | Core metadata — Apex, flows, objects, reports, permissions | +| `salesforce/scripts/` | Utilities: `health-check.sh`, `generate_lead_flow.py`, `sharepoint-upload.py` | +| `salesforce/destructive-deploy/` | Destructive change manifests for metadata removal | +| `n8n/` | Workflow JSONs (SolHub doc request, WLP training sync) | +| `docs/` | Plans, changelogs, design docs, announcements | +| `docs/runbooks/` | API/CLI quick-reference per service (auth, endpoints, IDs) | +| `.claude/personas/` | Active: , . 5 legacy personas retired 2026-04-28 | +| `.claude/rules/` | Path-scoped rules (brand, Lightning, SF dev patterns) | +| `services//` | EA bot — Python FastAPI core (Claude API, Supabase memory/audit) | +| `services/-teams/` | Teams adapter — TypeScript Bot Framework handler | +| `services/-connector/` | Claude.ai connector — Streamable HTTP MCP (Phase 7) | +| `infra//` | Bicep — ACA, Key Vault (``) | +| `services/hermes/` | Hermes Agent runtime ( persona) — local Mac orchestrator (Phase 1+) | +| `scripts/lead-dedup/` | `/lead-dedup` skill — transfer Contact+Account data to matching Lead, delete source records | +| `scripts/publish-kit/` | Sanitize + publish pipeline for public `/claude-kit` mirror | +| `.claude/publish-kit/` | Allowlist, sanitize rules, deny patterns, internal-refs config | + +Deployment commands → `docs/runbooks/salesforce-cli.md`. + +## Production Safety + +**NEVER deploy without explicit user confirmation.** This is a live production org. + +- Validate before deploy (`sf project deploy validate`) +- Don't modify: SLA fields (`First_New_to_RFD__c`, `First_RFD_to_InProgress__c`, `SLA_Risk_Score__c`), timezone automation (`UniversalTimezoneService`) +- Avoid major deployments 9 AM - 5 PM EST +- Rollback: `sf project deploy report` → retrieve previous version from Git → redeploy + +### Risk Audit Before Production Data-Writes + +Any plan that bulk-inserts or bulk-updates production records (Cases, EmailMessages, Accounts, etc.) MUST include an empirical risk audit BEFORE presenting the plan. Procedure + per-surface query table + severity classification: `docs/runbooks/salesforce-cli.md` "Risk Audit Before Production Data-Writes". + +## Apex Architecture + +Apex classes follow consistent naming patterns: + +| Suffix | Purpose | +|--------|---------| +| `Controller` | LWC/Aura backend | +| `Service` | Business logic | +| `Queueable` | Async processing | +| `Scheduler` | Scheduled jobs | +| `Batch` | Bulk operations | +| `Invocable` | Flow-callable | +| `Action` | Trigger actions (@future) | +| `Test` | Test class (paired 1:1) | + +CI/CD workflows → `docs/runbooks/github-api.md`. + +## PR Workflow + +The user-scope `~/.claude/commands/commit-push-pr.md` supersedes `commit-commands:commit-push-pr`. It auto-injects ClickUp task IDs into PR bodies, enabling `clickup-close-on-merge.yml` to close tasks on merge. + +### Branch Naming Convention + +All branches must follow: `/-` + +| Segment | Values | Example | +|---------|--------|---------| +| `type` | `feat`, `fix`, `chore`, `docs`, `refactor` | `feat` | +| `clickup-id` | ClickUp task ID (7+ lowercase alphanumeric chars) | `` | +| `slug` | Lowercase letters, digits, hyphens | `multi-session-hygiene` | + +Full example: `feat/-multi-session-hygiene` + +A `PreToolUse` hook (`~/.claude/hooks/enforce-branch-name.sh`) blocks branch creation that violates this pattern. To bypass: add `# skip-name-check` to the command. + +### Squash Merge Gotcha + +When GitHub squash-merges a PR, any commits pushed to the source branch AFTER the merge are orphaned — they don't land on main and the branch will conflict if reused. After a squash-merge, always cherry-pick any remaining commits onto a fresh branch from main. Never reuse the original branch for follow-up PRs. + +**Default rule (auto-merge in this repo):** treat any pushed branch as **frozen the moment the PR opens**. Auto-merge can land it within seconds. Any follow-up work — including responding to "also do X" mid-task — should start with `git fetch origin main && git checkout main && git pull && git worktree add -b main` BEFORE the first edit. If you've already made a follow-up commit on the old branch and the push is rejected ("stale info" / non-fast-forward), don't force-push — the PR is merged. Cherry-pick the orphan commit onto a fresh branch from main and open a new PR. + +**Dispatched orc PRs:** run codex against the local branch BEFORE `gh pr create` (auto-merge fires on `opened`, not `ready_for_review`). See `.claude/rules/dispatch-completion.md`. + +### Plan PR + ClickUp close-on-merge + +`clickup-close-on-merge.yml` closes any task referenced via a GitHub-style close keyword in the merged PR body. The supported forms (case-insensitive): + + Closes: https://app.clickup.com/t/ + Fixes # + Resolves https://app.clickup.com/t/ + +Plain URL mentions like `Companion to `, `Source ClickUp card: `, or a runbook prose link to `https://app.clickup.com/t/` do NOT close the task — only the keyword form does. `commit-push-pr` injects the `Closes:` line automatically for tasks the PR is meant to close. Plan-only / docs PRs simply omit the keyword and may reference the task by URL freely. + +The contract is locked by `scripts/clickup-close-regex/test_regex.sh` (positive + negative cases). Any change to the workflow regex must keep that harness passing. + +### Resumed Branches Need a Rebase Check + +A branch created hours/days ago (via `/start-task` during planning, or any worktree that survived intervening merges) may be behind main if other PRs landed in the interim. Before pushing or opening the PR, check: + + git -C fetch origin main + git -C rev-list --left-right --count origin/main...HEAD + # output: \t + +If `behind > 0`, rebase before push: + + git -C rebase origin/main + git -C push --force-with-lease + +Otherwise `git diff main --stat` (and the GitHub PR view) shows every intervening file as a deletion, which reads as a massive revert and hides the actual scope of the PR. + +## Bash Tool Gotchas + +cwd persistence, parallel-failure cascade, and guard-hook literal-string match: `docs/runbooks/claude-code-bash.md`. + +## macOS Shell Portability + +bash 3.2 vs newer-bash pitfalls + Python 3.13 SSL trust-store workaround: `docs/runbooks/macos-shell.md`. + +## macOS LaunchAgents + +PATH inheritance + `EnvironmentVariables` requirement for daemons reaching Homebrew CLIs: `docs/runbooks/launchd.md`. + +## Orchestrator pytest cross-directory caveat + +Pytest stub-conflict between `orchestrator/agent/tests/` and `orchestrator/functions/tests/` — run separately: `docs/runbooks/orchestrator.md` "pytest cross-directory caveat". + +## Worktree Gotchas + +`/start-task` race, mid-session worktree disappearance, stop-hook + intentional uncommitted files (daemon runtime, mid-session subagent commits, `docs/handoffs/`), and modify/delete conflict recovery: `docs/runbooks/git-worktrees.md`. + +## Subagent Dispatch (Interactive Sessions) + +Minimal-context prompt construction, model selection (Haiku/Sonnet/Opus), parent-side verification responsibility, runbook-edit accuracy, and DONE_WITH_CONCERNS handling: `docs/runbooks/subagent-dispatch.md`. + +## External Service Workflow + +All external service calls use direct API/CLI — no MCP servers (except context7, Notion, PAL). + +1. **Check runbook** — Read `docs/runbooks/.md` before any external API or CLI call. If no runbook exists, create from `docs/runbooks/_template.md`. **Also read at design time, not only execute time** — see `.claude/rules/runbook-citation.md`. Cite line refs inline when claiming API capability or limitation. +2. **Fetch credentials** — use `fetch-secrets.sh ` or `az keyvault secret show` per runbook auth section. +3. **Execute** — use the runbook's auth, endpoints, and patterns. +4. **On failure** — update the runbook with corrections, bump `Last verified`, retry — only report failure after that. + +**Browser-tool selection** → `.claude/rules/browser-automation.md` (Playwright vs browser-harness vs Browser Use Cloud, once the auth ladder lands you in browser-land). + +## Agent Runtime (Hermes/) + +Autonomous agents are dispatched by a Mac Studio `local-poller` daemon that polls ClickUp every 1s for `status=queued` tasks with `Executor=local-*`. No cloud surface; full architecture in `docs/runbooks/orchestrator.md`. + +**Executors:** +- `Executor=local-claude` → Claude Code session via ` --fg` +- `Executor=local-hermes` → Hermes Agent ( persona) via `python -m hermes `; multi-instance role-routed model selection from `orchestrator/config/routing.yaml`; cost + wall cap enforced by `services/hermes/hermes/watchdog.py`; events reported to Teams DM via HMAC-signed HTTPS. See `docs/runbooks/hermes.md` and `docs/runbooks/-hermes-integration.md`. +- `Executor=local-codex` → Codex CLI via `codex exec --full-auto` +- `Executor=local-mlx` → local MLX model via `local-llm.sh` (text-in/text-out only) + +**Dispatch triggers:** +- `plan` tag on a ClickUp task → planner preset +- Move task to `queued` status → dispatch per `Executor` field + +**Safety gates:** Plan Reviewed + Codex Reviewed checkboxes (unchanged). + +**Task status flow:** `backlog` → `planning` → `implementation` → `queued` → `in progress` → `qa` → `completed` (unchanged). + +Full lifecycle → `docs/runbooks/orchestrator.md`. + +All tasks in **ClickUp**, split across two lists by audience (`/todos` defaults to a combined view): + +- **A&E** (``, KV `CLICKUP-AE-LIST-ID`) — Salesforce / VoIP business automations: flows, Apex, reports, triage, n8n business workflows, support/dev work tied to the live org. Public intake (rnd@, `/request`, `/request` slash) lands here. +- **Automation Infrastructure** (``, KV `CLICKUP-INFRA-LIST-ID`) — platform / dev-loop machinery: , , orchestrator, MCP servers, Claude skills/commands, runbooks, Key Vault, CI/CD, publish-kit. Manual-only intake. + +Both lists share identical statuses + custom fields, so orchestrator + classifier code is list-agnostic. GH Issues disabled. ClickUp has no public Move Task endpoint — tasks stay where they're created. + +Public mirror → `docs/runbooks/publish-kit.md`. + +--- + +**Critical Reminder**: Production org. Prioritize safety, test thoroughly, get explicit confirmation before production changes. diff --git a/reference/CLAUDE-user-global.md b/reference/CLAUDE-user-global.md new file mode 100644 index 0000000..bc1d6bd --- /dev/null +++ b/reference/CLAUDE-user-global.md @@ -0,0 +1,140 @@ +# Global Claude Code Configuration + +## Communication Style +- Be direct. Execute > explain. No "I will now..." or "Should I?" preamble. +- No comments in code unless explicitly requested. +- Bullets > paragraphs. Short > long. +- When blocked, pivot strategy immediately — don't retry the same thing. + +## Evidence-Based Language +- Avoid: "best", "optimal", "faster", "secure", "better", "improved", "always", "never", "guaranteed" +- Use: "may", "could", "typically", "measured", "documented", "testing confirms" +- Back claims with evidence: metrics, benchmarks, documentation, or test results. + +## Development Practices +- KISS > YAGNI > SOLID. Simple first, abstract only when proven necessary. +- Search for existing patterns before creating new ones. +- Test: Red → Green → Refactor. Unit > Integration > E2E. +- Performance: Measure → Profile → Optimize. No premature optimization. + +## Security +- Detect patterns: `/api[_-]?key|token|secret/i` → block or warn. +- No secrets in code or config files. Use environment variables. +- Validate inputs at system boundaries. Escape arguments. +- Start with minimal permissions, escalate only when needed. + +## Feedback Style +- Point out flaws constructively with evidence-based alternatives. +- Challenge assumptions respectfully. "Consider X instead" > "That's wrong". +- No excessive agreement or unnecessary praise. + +## Task Management +- Use TodoWrite for 3+ step tasks. Single in-progress task at a time. +- Mark tasks complete immediately when done, not in batches. + +## Plan Execution Workflow + +When executing a plan (not just brainstorming): + +1. **ClickUp task** — Card must exist in A&E list (``). Create one if missing. +2. **Plan file** — Write to `docs/superpowers/plans/YYYY-MM-DD-.md` with `clickup:` in frontmatter and `codex_passes: 0`. Set "Plan File" custom field to GitHub URL. Plan MUST include `## Verification` with concrete test steps. +3. **Check "Plan Reviewed"** — Mark checkbox in ClickUp once plan is finalized. +3.5. **Execute-Pass review (MANDATORY for plans with runtime Verification)** — Spawn the `/execute-pass` slash skill against the plan file. It will write a `## Live Behavior` section back to the plan and set `execute_pass_status` in frontmatter. **DO NOT proceed to Codex review while `execute_pass_status` is `hard_fail` and `execute_passes < 3`** — revise the plan and re-run. After round 3 with `hard_fail`, escalate to a human regardless: the human decides whether to revise the plan, mark steps ``, or set `force: codex_only` (which lands as `execute_pass_status: bypassed_skill_bug` and proceeds to codex with the human's written justification). Plans whose Verification has no runtime steps return `skipped` and proceed normally. Round cap: 3. +4. **Codex review (MANDATORY)** — Spawn the `codex:codex-rescue` subagent via the Agent tool (never inline `codex:rescue`). Pass minimal context: plan file path + scope. Present findings. Check "Codex Reviewed". **DO NOT call ExitPlanMode without this.** +5. **Review summary + close planning** — Output the summary block below. + - **If you're in plan mode** (you called `EnterPlanMode` earlier in the session): call `ExitPlanMode` with `allowedPrompts: []`. + - **If you're not in plan mode** (default for `/start-task` sessions running `bypassPermissions`, where the brainstorming → writing-plans skill chain produced the plan): skip `ExitPlanMode`. Set ClickUp status to `implementation` and stop. Calling `ExitPlanMode` from outside plan mode errors with `"You are not in plan mode"`. + Either way, never list implementation steps in the summary. + ``` + ## Review Summary + - [x] Plan reviewed (Claude) + - [x] Execute-Pass Reviewed (N round(s), status: ) + - [x] Codex reviewed (N pass(es), findings: ) + - Plan: `docs/superpowers/plans/YYYY-MM-DD-.md` + - ClickUp: + - Next: Move to `queued` → cloud orchestrator dispatches immediately + ``` +6. **Create worktree** — Both checkboxes must be checked. Worktree BEFORE any implementation code. +7. **Delegate to agents** — One agent per independent task, minimal context. No inline implementation. +8. **QA** — Run plan's Verification steps. Open PR. +9. **Completed** — Merge PR. Update Plan File URL to `blob/main`. + +#### Execute-Pass + Codex Gate Rules +- Plan frontmatter MUST include `execute_passes: 0` and `execute_pass_status: pending` until execute-pass runs. +- Max 3 execute-pass rounds — same cap shape as codex. +- After round 3 with `hard_fail`, escalate to a human regardless. Codex review is gated on either `execute_pass_status ∈ {pass, advisory_only, skipped, bypassed_skill_bug}` OR a human-approved override at round 3. +- `bypassed_skill_bug` always escalates to human even on round 1 (the harness is broken; don't silently advance). +- Execute-pass round count does not consume codex's budget. After execute-pass passes, codex begins at `codex_passes: 0`. +- Plan frontmatter MUST include `codex_passes: 0`; increment after each round. +- Max 3 codex rounds — after round 3, present to human regardless of findings. +- If findings are minor after round 2, skip round 3 and present to human directly. +- Only successful completions count; crashed/timed-out runs do NOT count. + +**Gate rules**: Planning → Implementation requires Plan Reviewed + Execute-Pass Reviewed + Codex Reviewed + human approval. Implementation in worktree only, delegated to agents only. + +**User-scope ad-hoc exemption.** Small edits limited to `~/.claude/` (private hooks, CLAUDE.md, settings) and the symlinked `~/.claude/commands/` + `~/.claude/personas/` (claude-config repo) skip the full workflow: +- No ClickUp card required (it's not project work). +- Plan file may live at the harness-generated `~/.claude/plans/.md` instead of `docs/superpowers/plans/`. +- Execute-Pass + Codex review still recommended for non-trivial changes (>2 files OR shell scripts with side effects). Spawn `codex:codex-rescue` against the plan file before implementation, even ad-hoc, unless the user explicitly waives it. +- claude-config commits (commands/, personas/) MUST go through a PR — branch protection on main rejects direct pushes (see `feedback_claude_config_via_pr.md`). + +## iTerm2 Plan Phase Indicators + +**Main interactive session only** — never from subagents or worktree agents. Set silently; never ask the user about colors. + + ~/.claude/hooks/iterm-phase.sh [""] + +| Trigger | Command | +|---------|---------| +| Plan starts (pick 2-5 word title) | `iterm-phase.sh planning "<title>"` | +| Codex review | `iterm-phase.sh review` | +| Human approval | `iterm-phase.sh approval` | +| Worktree + agents | `iterm-phase.sh implementing` | +| Completed | `iterm-phase.sh closed` | +| ClickUp title differs (title only, no color) | `iterm-phase.sh --title "<task-name>"` | + +## Auto Session Naming + +On your first response in a new conversation — when no `/start-task` or `/rename` has been used — silently run: + + ~/.claude/hooks/rename-session.sh "<title>" + +Title rules: 2–5 lowercase words, hyphens between words, no special characters (e.g. `webhook-rotation-status`). Generate from the conversation topic. Skip from subagents, worktree agents, or plan mode (where `iterm-phase.sh` handles naming). If a `/start-task` lock is in place (`~/.claude/state/rename-locks/<pane>.lock`), `rename-session.sh` will silently no-op — no LLM-side check needed. + +## Scheduling Follow-ups + +Never offer `/schedule` for follow-up work. CCR routines run in Anthropic cloud and have no access to <your-org> CLI tools (`sf`, `az`, `gh`, `wrangler`, `occ-*`), Azure Key Vault secrets, or local runbooks — which covers nearly all real work in this workspace. + +Instead, offer a ClickUp task with **Dispatch At**: + +> "Want me to create a ClickUp card in A&E with Dispatch At=`<date>` so the cloud orchestrator picks it up then?" + +The cloud orchestrator has vault + CLI access and is the correct execution surface for scheduled <your-org> work. Only offer `/schedule` for work that is genuinely pure-cloud (e.g. WebFetch a public URL, summarize a public repo) — and even then, prefer ClickUp + orchestrator for consistency. + +## Error Recovery +- Failure → try alternative → explain clearly → suggest next steps. +- Never give up silently. Always communicate what failed and why. +- MCP server failure → fall back to native tools. + +## Project Glossary + +| Acronym | Full Name | GitHub Repo | +|---------|-----------|-------------| +| OCC | <your-org> Claude Code | `<your-org>/claude-config` | +| CCA | Cloud Communications Automations | `<your-org>/automations` | + +## Agent Runtime (Hermes/<internal-bot>) + +Autonomous agents dispatched via the Mac Studio `local-poller` daemon. Key executors: + +- `Executor=local-claude` → Claude Code via `<orchestrator-cli> --fg` +- `Executor=local-hermes` → Hermes Agent (<internal-bot> persona) via `python -m hermes <task-json>`; multi-instance role-routed model from `orchestrator/config/routing.yaml`; cost + wall caps via Watchdog; events → <internal-bot> Teams DM via HMAC-signed HTTPS +- `Executor=local-codex` → Codex CLI +- `Executor=local-mlx` → local MLX model (text-in/text-out only) + +Runbooks: `docs/runbooks/hermes.md` (runtime), `docs/runbooks/<internal-bot>-hermes-integration.md` (bridge), `docs/runbooks/maestro-local-dispatch.md` (executor matrix). + +## Building Things +- `/build` or "build X" → choose the right primitive: **Persona** (behavior/tone), **Command** (workflow via `/name`), **Memory** (persistent fact/preference), **MCP Server** (external API, frequent use). +- User never needs to specify the primitive type — you decide. +- State your choice and rationale in one line before building. diff --git a/reference/CLAUDE-workspace-projects.md b/reference/CLAUDE-workspace-projects.md new file mode 100644 index 0000000..a8f6a02 --- /dev/null +++ b/reference/CLAUDE-workspace-projects.md @@ -0,0 +1,34 @@ +# CLAUDE.md — <your-org> Projects Workspace + +Multi-project workspace: `automations`, `CloudieMcCloudieBot`, `<voip-mcp>-mcp-server`, `<knowledge-base>-mcp`, `apollo-io-mcp-server`, `calendly-mcp-server`, `clickup-mcp-server`, `wordpress-mcp`, `nsapiv2-mcp`, `claude-code-team-commander`. + +## Cross-Project Standards + +### Release Notes +- Max 2 paragraphs: technical fix/feature + business impact +- Include date/timestamp, quantify time savings, write for staff audience + +### MCP Server Pattern +All MCP servers follow: +- TypeScript + MCP SDK, ES2022/Node16, build to `build/` +- Env vars via Azure Key Vault (`<credential-vault>`) + `fetch-secrets.sh` — no `.env` files +- JSON schema validation on tool inputs, rate limiting, HTTPS-only + +### Security +- All secrets in Azure Key Vault — requires `az login` +- Validate inputs at boundaries, escape arguments, minimal permissions +- No secrets in code or config + +## AI Agents & Routing + +| Agent | Domain | Trigger | +|-------|--------|---------| +| Flo Rivers | Salesforce automation/flows | GSD Record Type | +| Holly Helpdesk | Technical support | Support Request RT | +| Paige Turner | Documentation | Doc tasks | +| Stan Dardson | Standards/compliance | Quality/SOP tasks | +| Stella Fullstack | Dev/APIs/MCP | Programming tasks | + +### Salesforce CLI +- Installed: `/usr/local/bin/sf`, org: `<your-email>` (Production) +- All agents can query SF via CLI