john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge step (b): carry in local-only files at original paths
Some checks failed
CI / pr-title (push) Has been cancelled
Details
CI / test (push) Has been cancelled
Details
Release PR / release-pr (push) Has been cancelled
Details
Release PR / publish-cli (push) Has been cancelled
Details

Browse Source 
Brings 47 local-only files from backup-local-main into the merge-upstream
branch at their pre-rename paths. Subsequent steps will rename these to
the ce-* convention and port shared-file merges.

Includes:
- Custom skills: john-voice, jira-ticket-writer, hugo-blog-publisher,
  weekly-shipped, proof-push, ship-it, story-lens, sync-confluence,
  excalidraw-png-export, python-package-writer, fastapi-style,
  upstream-merge
- Custom agents: design-conformance-reviewer, tiangolo-fastapi-reviewer,
  zip-agent-validator, python-package-readme-writer, lint
- Custom commands: essay-edit, essay-outline, pr-comments-to-todos,
  resolve_todo_parallel, workflows/{plan,review,work}
- Local mods to ce-review/SKILL.md + review-output-template.md (will be
  ported to ce-code-review in a later step)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
John Lamb
2026-04-24 12:40:27 -05:00
parent bc3709fc53
commit a7b15298e0
47 changed files with 7422 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

746
plugins/compound-engineering/skills/ce-review/SKILL.md Normal file
View File

@@ -0,0 +1,746 @@
---
name: ce:review
description: "Structured code review using tiered persona agents, confidence-gated findings, and a merge/dedup pipeline. Use when reviewing code changes before creating a PR."
argument-hint: "[blank to review current branch, or provide PR link]"
---
# Code Review
Reviews code changes using dynamically selected reviewer personas. Spawns parallel sub-agents that return structured JSON, then merges and deduplicates findings into a single report.
## When to Use
- Before creating a PR
- After completing a task during iterative implementation
- When feedback is needed on any code changes
- Can be invoked standalone
- Can run as a read-only or autofix review step inside larger workflows
## Argument Parsing
Parse `$ARGUMENTS` for the following optional tokens. Strip each recognized token before interpreting the remainder as the PR number, GitHub URL, or branch name.
| Token | Example | Effect |
|-------|---------|--------|
| `mode:autofix` | `mode:autofix` | Select autofix mode (see Mode Detection below) |
| `mode:report-only` | `mode:report-only` | Select report-only mode |
| `mode:headless` | `mode:headless` | Select headless mode for programmatic callers (see Mode Detection below) |
| `base:<sha-or-ref>` | `base:abc1234` or `base:origin/main` | Skip scope detection — use this as the diff base directly |
| `plan:<path>` | `plan:docs/plans/2026-03-25-001-feat-foo-plan.md` | Load this plan for requirements verification |
All tokens are optional. Each one present means one less thing to infer. When absent, fall back to existing behavior for that stage.
**Conflicting mode flags:** If multiple mode tokens appear in arguments, stop and do not dispatch agents. If `mode:headless` is one of the conflicting tokens, emit the headless error envelope: `Review failed (headless mode). Reason: conflicting mode flags — <mode_a> and <mode_b> cannot be combined.` Otherwise emit the generic form: `Review failed. Reason: conflicting mode flags — <mode_a> and <mode_b> cannot be combined.`
## Mode Detection
| Mode | When | Behavior |
|------|------|----------|
| **Interactive** (default) | No mode token present | Review, apply safe_auto fixes automatically, present findings, ask for policy decisions on gated/manual findings, and optionally continue into fix/push/PR next steps |
| **Autofix** | `mode:autofix` in arguments | No user interaction. Review, apply only policy-allowed `safe_auto` fixes, re-review in bounded rounds, write a run artifact, and emit residual downstream work when needed |
| **Report-only** | `mode:report-only` in arguments | Strictly read-only. Review and report only, then stop with no edits, artifacts, todos, commits, pushes, or PR actions |
| **Headless** | `mode:headless` in arguments | Programmatic mode for skill-to-skill invocation. Apply `safe_auto` fixes silently (single pass), return all other findings as structured text output, write run artifacts, skip todos, and return "Review complete" signal. No interactive prompts. |
### Autofix mode rules
- **Skip all user questions.** Never pause for approval or clarification once scope has been established.
- **Apply only `safe_auto -> review-fixer` findings.** Leave `gated_auto`, `manual`, `human`, and `release` work unresolved.
- **Write a run artifact** under `.context/compound-engineering/ce-review/<run-id>/` summarizing findings, applied fixes, residual actionable work, and advisory outputs.
- **Create durable todo files only for unresolved actionable findings** whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path and naming convention.
- **Never commit, push, or create a PR** from autofix mode. Parent workflows own those decisions.
### Report-only mode rules
- **Skip all user questions.** Infer intent conservatively if the diff metadata is thin.
- **Never edit files or externalize work.** Do not write `.context/compound-engineering/ce-review/<run-id>/`, do not create todo files, and do not commit, push, or create a PR.
- **Safe for parallel read-only verification.** `mode:report-only` is the only mode that is safe to run concurrently with browser testing on the same checkout.
- **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`.
- **Do not overlap mutating review with browser testing on the same checkout.** If a future orchestrator wants fixes, run the mutating review phase after browser testing or in an isolated checkout/worktree.
### Headless mode rules
- **Skip all user questions.** Never use the platform question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini) or other interactive prompts. Infer intent conservatively if the diff metadata is thin.
- **Require a determinable diff scope.** If headless mode cannot determine a diff scope (no branch, PR, or `base:` ref determinable without user interaction), emit `Review failed (headless mode). Reason: no diff scope detected. Re-invoke with a branch name, PR number, or base:<ref>.` and stop without dispatching agents.
- **Apply only `safe_auto -> review-fixer` findings in a single pass.** No bounded re-review rounds. Leave `gated_auto`, `manual`, `human`, and `release` work unresolved and return them in the structured output.
- **Return all non-auto findings as structured text output.** Use the headless output envelope format (see Stage 6 below) preserving severity, autofix_class, owner, requires_verification, confidence, pre_existing, and suggested_fix per finding. Enrich with detail-tier fields (why_it_matters, evidence[]) from the per-agent artifact files on disk (see Detail enrichment in Stage 6).
- **Write a run artifact** under `.context/compound-engineering/ce-review/<run-id>/` summarizing findings, applied fixes, and advisory outputs. Include the artifact path in the structured output.
- **Do not create todo files.** The caller receives structured findings and routes downstream work itself.
- **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:headless` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. When stopping, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.`
- **Not safe for concurrent use on a shared checkout.** Unlike `mode:report-only`, headless mutates files (applies `safe_auto` fixes). Callers must not run headless concurrently with other mutating operations on the same checkout.
- **Never commit, push, or create a PR** from headless mode. The caller owns those decisions.
- **End with "Review complete" as the terminal signal** so callers can detect completion. If all reviewers fail or time out, emit `Code review degraded (headless mode). Reason: 0 of N reviewers returned results.` followed by "Review complete".
## Severity Scale
All reviewers use P0-P3:
| Level | Meaning | Action |
|-------|---------|--------|
| **P0** | Critical breakage, exploitable vulnerability, data loss/corruption | Must fix before merge |
| **P1** | High-impact defect likely hit in normal usage, breaking contract | Should fix |
| **P2** | Moderate issue with meaningful downside (edge case, perf regression, maintainability trap) | Fix if straightforward |
| **P3** | Low-impact, narrow scope, minor improvement | User's discretion |
## Action Routing
Severity answers **urgency**. Routing answers **who acts next** and **whether this skill may mutate the checkout**.
| `autofix_class` | Default owner | Meaning |
|-----------------|---------------|---------|
| `safe_auto` | `review-fixer` | Local, deterministic fix suitable for the in-skill fixer when the current mode allows mutation |
| `gated_auto` | `downstream-resolver` or `human` | Concrete fix exists, but it changes behavior, contracts, permissions, or another sensitive boundary that should not be auto-applied by default |
| `manual` | `downstream-resolver` or `human` | Actionable work that should be handed off rather than fixed in-skill |
| `advisory` | `human` or `release` | Report-only output such as learnings, rollout notes, or residual risk |
Routing rules:
- **Synthesis owns the final route.** Persona-provided routing metadata is input, not the last word.
- **Choose the more conservative route on disagreement.** A merged finding may move from `safe_auto` to `gated_auto` or `manual`, but never the other way without stronger evidence.
- **Only `safe_auto -> review-fixer` enters the in-skill fixer queue automatically.**
- **`requires_verification: true` means a fix is not complete without targeted tests, a focused re-review, or operational validation.**
## Reviewers
17 reviewer personas in layered conditionals, plus CE-specific agents. See the persona catalog included below for the full catalog.
**Always-on (every review):**
| Agent | Focus |
|-------|-------|
| `compound-engineering:review:correctness-reviewer` | Logic errors, edge cases, state bugs, error propagation |
| `compound-engineering:review:testing-reviewer` | Coverage gaps, weak assertions, brittle tests |
| `compound-engineering:review:maintainability-reviewer` | Coupling, complexity, naming, dead code, abstraction debt |
| `compound-engineering:review:project-standards-reviewer` | CLAUDE.md and AGENTS.md compliance -- frontmatter, references, naming, portability |
| `compound-engineering:review:agent-native-reviewer` | Verify new features are agent-accessible |
| `compound-engineering:research:learnings-researcher` | Search docs/solutions/ for past issues related to this PR |
**Cross-cutting conditional (selected per diff):**
| Agent | Select when diff touches... |
|-------|---------------------------|
| `compound-engineering:review:security-reviewer` | Auth, public endpoints, user input, permissions |
| `compound-engineering:review:performance-reviewer` | DB queries, data transforms, caching, async |
| `compound-engineering:review:api-contract-reviewer` | Routes, serializers, type signatures, versioning |
| `compound-engineering:review:data-migrations-reviewer` | Migrations, schema changes, backfills |
| `compound-engineering:review:reliability-reviewer` | Error handling, retries, timeouts, background jobs |
| `compound-engineering:review:adversarial-reviewer` | Diff >=50 changed non-test/non-generated/non-lockfile lines, or auth, payments, data mutations, external APIs |
| `compound-engineering:review:cli-readiness-reviewer` | CLI command definitions, argument parsing, CLI framework usage, command handler implementations |
| `compound-engineering:review:previous-comments-reviewer` | Reviewing a PR that has existing review comments or threads |
**Stack-specific conditional (selected per diff):**
| Agent | Select when diff touches... |
|-------|---------------------------|
| `compound-engineering:review:dhh-rails-reviewer` | Rails architecture, service objects, session/auth choices, or Hotwire-vs-SPA boundaries |
| `compound-engineering:review:kieran-rails-reviewer` | Rails application code where conventions, naming, and maintainability are in play |
| `compound-engineering:review:kieran-python-reviewer` | Python modules, endpoints, scripts, or services |
| `compound-engineering:review:kieran-typescript-reviewer` | TypeScript components, services, hooks, utilities, or shared types |
| `compound-engineering:review:julik-frontend-races-reviewer` | Stimulus/Turbo controllers, DOM events, timers, animations, or async UI flows |
**CE conditional (migration & external review):**
| Agent | Select when... |
|-------|----------------|
| `compound-engineering:review:design-conformance-reviewer` | Repo contains design documents or active plan matching current branch |
| `compound-engineering:review:schema-drift-detector` | Diff includes migration files -- cross-references schema.rb against included migrations |
| `compound-engineering:review:deployment-verification-agent` | Diff includes migration files -- produces deployment checklist with SQL verification queries |
| `compound-engineering:review:zip-agent-validator` | PR URL contains `git.zoominfo.com` -- pressure-tests zip-agent comments for validity |
## Review Scope
Every review spawns all 4 always-on personas plus the 2 CE always-on agents, then adds whichever cross-cutting and stack-specific conditionals fit the diff. The model naturally right-sizes: a small config change triggers 0 conditionals = 6 reviewers. A Rails auth feature might trigger security + reliability + kieran-rails + dhh-rails = 10 reviewers.
## Protected Artifacts
The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any reviewer:
- `docs/brainstorms/*` -- requirements documents created by ce:brainstorm
- `docs/plans/*.md` -- plan files created by ce:plan (living documents with progress checkboxes)
- `docs/solutions/*.md` -- solution documents created during the pipeline
If a reviewer flags any file in these directories for cleanup or removal, discard that finding during synthesis.
## How to Run
### Stage 1: Determine scope
Compute the diff range, file list, and diff. Minimize permission prompts by combining into as few commands as possible.
**If `base:` argument is provided (fast path):**
The caller already knows the diff base. Skip all base-branch detection, remote resolution, and merge-base computation. Use the provided value directly:
```
BASE_ARG="{base_arg}"
BASE=$(git merge-base HEAD "$BASE_ARG" 2>/dev/null) || BASE="$BASE_ARG"
```
Then produce the same output as the other paths:
```
echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard
```
This path works with any ref — a SHA, `origin/main`, a branch name. Automated callers (ce:work, lfg, slfg) should prefer this to avoid the detection overhead. **Do not combine `base:` with a PR number or branch target.** If both are present, stop with an error: "Cannot use `base:` with a PR number or branch target — `base:` implies the current checkout is already the correct branch. Pass `base:` alone, or pass the target alone and let scope detection resolve the base." This avoids scope/intent mismatches where the diff base comes from one source but the code and metadata come from another.
**If a PR number or GitHub URL is provided as an argument:**
If `mode:report-only` or `mode:headless` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
First, verify the worktree is clean before switching branches:
```
git status --porcelain
```
If the output is non-empty, inform the user: "You have uncommitted changes on the current branch. Stash or commit them before reviewing a PR, or use standalone mode (no argument) to review the current branch as-is." Do not proceed with checkout until the worktree is clean.
Then check out the PR branch so persona agents can read the actual code (not the current checkout):
```
gh pr checkout <number-or-url>
```
Then fetch PR metadata. Capture the base branch name and the PR base repository identity, not just the branch name:
```
gh pr view <number-or-url> --json title,body,baseRefName,headRefName,url
```
Use the repository portion of the returned PR URL as `<base-repo>` (for example, `EveryInc/compound-engineering-plugin` from `https://github.com/EveryInc/compound-engineering-plugin/pull/348`).
Then compute a local diff against the PR's base branch so re-reviews also include local fix commits and uncommitted edits. Substitute the PR base branch from metadata (shown here as `<base>`) and the PR base repository identity derived from the PR URL (shown here as `<base-repo>`). Resolve the base ref from the PR's actual base repository, not by assuming `origin` points at that repo:
```
PR_BASE_REMOTE=$(git remote -v | awk 'index($2, "github.com:<base-repo>") || index($2, "github.com/<base-repo>") {print $1; exit}')
if [ -n "$PR_BASE_REMOTE" ]; then PR_BASE_REMOTE_REF="$PR_BASE_REMOTE/<base>"; else PR_BASE_REMOTE_REF=""; fi
PR_BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE_REF" 2>/dev/null || git rev-parse --verify <base> 2>/dev/null || true)
if [ -z "$PR_BASE_REF" ]; then
if [ -n "$PR_BASE_REMOTE_REF" ]; then
git fetch --no-tags "$PR_BASE_REMOTE" <base>:refs/remotes/"$PR_BASE_REMOTE"/<base> 2>/dev/null || git fetch --no-tags "$PR_BASE_REMOTE" <base> 2>/dev/null || true
PR_BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE_REF" 2>/dev/null || git rev-parse --verify <base> 2>/dev/null || true)
else
if git fetch --no-tags https://github.com/<base-repo>.git <base> 2>/dev/null; then
PR_BASE_REF=$(git rev-parse --verify FETCH_HEAD 2>/dev/null || true)
fi
if [ -z "$PR_BASE_REF" ]; then PR_BASE_REF=$(git rev-parse --verify <base> 2>/dev/null || true); fi
fi
fi
if [ -n "$PR_BASE_REF" ]; then BASE=$(git merge-base HEAD "$PR_BASE_REF" 2>/dev/null) || BASE=""; else BASE=""; fi
```
```
if [ -n "$BASE" ]; then echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard; else echo "ERROR: Unable to resolve PR base branch <base> locally. Fetch the base branch and rerun so the review scope stays aligned with the PR."; fi
```
Extract PR title/body, base branch, and PR URL from `gh pr view`, then extract the base marker, file list, diff content, and `UNTRACKED:` list from the local command. Do not use `gh pr diff` as the review scope after checkout -- it only reflects the remote PR state and will miss local fix commits until they are pushed. If the base ref still cannot be resolved from the PR's actual base repository after the fetch attempt, stop instead of falling back to `git diff HEAD`; a PR review without the PR base branch is incomplete.
**If a branch name is provided as an argument:**
Check out the named branch, then diff it against the base branch. Substitute the provided branch name (shown here as `<branch>`).
If `mode:report-only` or `mode:headless` is active, do **not** run `git checkout <branch>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
First, verify the worktree is clean before switching branches:
```
git status --porcelain
```
If the output is non-empty, inform the user: "You have uncommitted changes on the current branch. Stash or commit them before reviewing another branch, or provide a PR number instead." Do not proceed with checkout until the worktree is clean.
```
git checkout <branch>
```
Then detect the review base branch and compute the merge-base. Run the `references/resolve-base.sh` script, which handles fork-safe remote resolution with multi-fallback detection (PR metadata -> `origin/HEAD` -> `gh repo view` -> common branch names):
```
RESOLVE_OUT=$(bash references/resolve-base.sh) || { echo "ERROR: resolve-base.sh failed"; exit 1; }
if [ -z "$RESOLVE_OUT" ] || echo "$RESOLVE_OUT" | grep -q '^ERROR:'; then echo "${RESOLVE_OUT:-ERROR: resolve-base.sh produced no output}"; exit 1; fi
BASE=$(echo "$RESOLVE_OUT" | sed 's/^BASE://')
```
If the script outputs an error, stop instead of falling back to `git diff HEAD`; a branch review without the base branch would only show uncommitted changes and silently miss all committed work.
On success, produce the diff:
```
echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard
```
You may still fetch additional PR metadata with `gh pr view` for title, body, and linked issues, but do not fail if no PR exists.
**If no argument (standalone on current branch):**
Detect the review base branch and compute the merge-base using the same `references/resolve-base.sh` script as branch mode:
```
RESOLVE_OUT=$(bash references/resolve-base.sh) || { echo "ERROR: resolve-base.sh failed"; exit 1; }
if [ -z "$RESOLVE_OUT" ] || echo "$RESOLVE_OUT" | grep -q '^ERROR:'; then echo "${RESOLVE_OUT:-ERROR: resolve-base.sh produced no output}"; exit 1; fi
BASE=$(echo "$RESOLVE_OUT" | sed 's/^BASE://')
```
If the script outputs an error, stop instead of falling back to `git diff HEAD`; a standalone review without the base branch would only show uncommitted changes and silently miss all committed work on the branch.
On success, produce the diff:
```
echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard
```
Using `git diff $BASE` (without `..HEAD`) diffs the merge-base against the working tree, which includes committed, staged, and unstaged changes together.
**Untracked file handling:** Always inspect the `UNTRACKED:` list, even when `FILES:`/`DIFF:` are non-empty. Untracked files are outside review scope until staged. If the list is non-empty, tell the user which files are excluded. If any of them should be reviewed, stop and tell the user to `git add` them first and rerun. Only continue when the user is intentionally reviewing tracked changes only. In `mode:headless` or `mode:autofix`, do not stop to ask — proceed with tracked changes only and note the excluded untracked files in the Coverage section of the output.
### Stage 2: Intent discovery
Understand what the change is trying to accomplish. The source of intent depends on which Stage 1 path was taken:
**PR/URL mode:** Use the PR title, body, and linked issues from `gh pr view` metadata. Supplement with commit messages from the PR if the body is sparse.
**Branch mode:** Run `git log --oneline ${BASE}..<branch>` using the resolved merge-base from Stage 1.
**Standalone (current branch):** Run:
```
echo "BRANCH:" && git rev-parse --abbrev-ref HEAD && echo "COMMITS:" && git log --oneline ${BASE}..HEAD
```
Combined with conversation context (plan section summary, PR description), write a 2-3 line intent summary:
```
Intent: Simplify tax calculation by replacing the multi-tier rate lookup
with a flat-rate computation. Must not regress edge cases in tax-exempt handling.
```
Pass this to every reviewer in their spawn prompt. Intent shapes *how hard each reviewer looks*, not which reviewers are selected.
**When intent is ambiguous:**
- **Interactive mode:** Ask one question using the platform's interactive question tool (AskUserQuestion in Claude Code, request_user_input in Codex): "What is the primary goal of these changes?" Do not spawn reviewers until intent is established.
- **Autofix/report-only/headless modes:** Infer intent conservatively from the branch name, diff, PR metadata, and caller context. Note the uncertainty in Coverage or Verdict reasoning instead of blocking.
### Stage 2b: Plan discovery (requirements verification)
Locate the plan document so Stage 6 can verify requirements completeness. Check these sources in priority order — stop at the first hit:
1. **`plan:` argument.** If the caller passed a plan path, use it directly. Read the file to confirm it exists.
2. **PR body.** If PR metadata was fetched in Stage 1, scan the body for paths matching `docs/plans/*.md`. If exactly one match is found and the file exists, use it as `plan_source: explicit`. If multiple plan paths appear, treat as ambiguous — demote to `plan_source: inferred` for the most recent match that exists on disk, or skip if none exist or none clearly relate to the PR title/intent. Always verify the selected file exists before using it — stale or copied plan links in PR descriptions are common.
3. **Auto-discover.** Extract 2-3 keywords from the branch name (e.g., `feat/onboarding-skill` -> `onboarding`, `skill`). Glob `docs/plans/*` and filter filenames containing those keywords. If exactly one match, use it. If multiple matches or the match looks ambiguous (e.g., generic keywords like `review`, `fix`, `update` that could hit many plans), **skip auto-discovery** — a wrong plan is worse than no plan. If zero matches, skip.
**Confidence tagging:** Record how the plan was found:
- `plan:` argument -> `plan_source: explicit` (high confidence)
- Single unambiguous PR body match -> `plan_source: explicit` (high confidence)
- Multiple/ambiguous PR body matches -> `plan_source: inferred` (lower confidence)
- Auto-discover with single unambiguous match -> `plan_source: inferred` (lower confidence)
If a plan is found, read its **Requirements Trace** (R1, R2, etc.) and **Implementation Units** (checkbox items). Store the extracted requirements list and `plan_source` for Stage 6. Do not block the review if no plan is found — requirements verification is additive, not required.
### Stage 3: Select reviewers
Read the diff and file list from Stage 1. The 4 always-on personas and 2 CE always-on agents are automatic. For each cross-cutting and stack-specific conditional persona in the persona catalog included below, decide whether the diff warrants it. This is agent judgment, not keyword matching.
**File-type awareness for conditional selection:** Instruction-prose files (Markdown skill definitions, JSON schemas, config files) are product code but do not benefit from runtime-focused reviewers. The adversarial reviewer's techniques (race conditions, cascade failures, abuse cases) target executable code behavior. For diffs that only change instruction-prose files, skip adversarial unless the prose describes auth, payment, or data-mutation behavior. Count only executable code lines toward line-count thresholds.
**`previous-comments` is PR-only.** Only select this persona when Stage 1 gathered PR metadata (PR number or URL was provided as an argument, or `gh pr view` returned metadata for the current branch). Skip it entirely for standalone branch reviews with no associated PR -- there are no prior comments to check.
Stack-specific personas are additive. A Rails UI change may warrant `kieran-rails` plus `julik-frontend-races`; a TypeScript API diff may warrant `kieran-typescript` plus `api-contract` and `reliability`.
For CE conditional agents, check if the diff includes files matching `db/migrate/*.rb`, `db/schema.rb`, or data backfill scripts. If the repo contains design documents (`docs/`, `docs/design/`, `docs/architecture/`, `docs/specs/`) or an active plan matching the current branch, select `design-conformance-reviewer`. If the PR URL contains `git.zoominfo.com`, select `zip-agent-validator`.
Announce the team before spawning:
```
Review team:
- correctness (always)
- testing (always)
- maintainability (always)
- project-standards (always)
- agent-native-reviewer (always)
- learnings-researcher (always)
- security -- new endpoint in routes.rb accepts user-provided redirect URL
- kieran-rails -- controller and Turbo flow changed in app/controllers and app/views
- dhh-rails -- diff adds service objects around ordinary Rails CRUD
- data-migrations -- adds migration 20260303_add_index_to_orders
- schema-drift-detector -- migration files present
```
This is progress reporting, not a blocking confirmation.
### Stage 3b: Discover project standards paths
Before spawning sub-agents, find the file paths (not contents) of all relevant standards files for the `project-standards` persona. Use the native file-search/glob tool to locate:
1. Use the native file-search tool (e.g., Glob in Claude Code) to find all `**/CLAUDE.md` and `**/AGENTS.md` in the repo.
2. Filter to those whose directory is an ancestor of at least one changed file. A standards file governs all files below it (e.g., `plugins/compound-engineering/AGENTS.md` applies to everything under `plugins/compound-engineering/`).
Pass the resulting path list to the `project-standards` persona inside a `<standards-paths>` block in its review context (see Stage 4). The persona reads the files itself, targeting only the sections relevant to the changed file types. This keeps the orchestrator's work cheap (path discovery only) and avoids bloating the subagent prompt with content the reviewer may not fully need.
### Stage 4: Spawn sub-agents
#### Model tiering
Persona sub-agents do focused, scoped work and should use a fast mid-tier model to reduce cost and latency without sacrificing review quality. The orchestrator itself stays on the default (most capable) model.
Use the platform's mid-tier model for all persona and CE sub-agents. In Claude Code, pass `model: "sonnet"` in the Agent tool call. On other platforms, use the equivalent mid-tier (e.g., `gpt-4o` in Codex). If the platform has no model override mechanism or the available model names are unknown, omit the model parameter and let agents inherit the default -- a working review on the parent model is better than a broken dispatch from an unrecognized model name.
CE always-on agents (agent-native-reviewer, learnings-researcher) and CE conditional agents (design-conformance-reviewer, schema-drift-detector, deployment-verification-agent, zip-agent-validator) also use the mid-tier model since they perform scoped, focused work.
The orchestrator (this skill) stays on the default model because it handles intent discovery, reviewer selection, finding merge/dedup, and synthesis -- tasks that benefit from stronger reasoning.
#### Run ID
Generate a unique run identifier before dispatching any agents. This ID scopes all agent artifact files and the post-review run artifact to the same directory.
```bash
RUN_ID=$(date +%Y%m%d-%H%M%S)-$(head -c4 /dev/urandom | od -An -tx1 | tr -d ' ')
mkdir -p ".context/compound-engineering/ce-review/$RUN_ID"
```
Pass `{run_id}` to every persona sub-agent so they can write their full analysis to `.context/compound-engineering/ce-review/{run_id}/{reviewer_name}.json`.
**Report-only mode:** Skip run-id generation and directory creation. Do not pass `{run_id}` to agents. Agents return compact JSON only with no file write, consistent with report-only's no-write contract.
#### Spawning
Omit the `mode` parameter when dispatching sub-agents so the user's configured permission settings apply. Do not pass `mode: "auto"`.
Spawn each selected persona reviewer as a parallel sub-agent using the subagent template included below. Each persona sub-agent receives:
1. Their persona file content (identity, failure modes, calibration, suppress conditions)
2. Shared diff-scope rules from the diff-scope reference included below
3. The JSON output contract from the findings schema included below
4. PR metadata: title, body, and URL when reviewing a PR (empty string otherwise). Passed in a `<pr-context>` block so reviewers can verify code against stated intent
5. Review context: intent summary, file list, diff
6. Run ID and reviewer name for the artifact file path
7. **For `project-standards` only:** the standards file path list from Stage 3b, wrapped in a `<standards-paths>` block appended to the review context
Persona sub-agents are **read-only** with respect to the project: they review and return structured JSON. They do not edit project files or propose refactors. The one permitted write is saving their full analysis to the `.context/` artifact path specified in the output contract.
Read-only here means **non-mutating**, not "no shell access." Reviewer sub-agents may use non-mutating inspection commands when needed to gather evidence or verify scope, including read-oriented `git` / `gh` usage such as `git diff`, `git show`, `git blame`, `git log`, and `gh pr view`. They must not edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
Each persona sub-agent writes full JSON (all schema fields) to `.context/compound-engineering/ce-review/{run_id}/{reviewer_name}.json` and returns compact JSON with merge-tier fields only:
```json
{
"reviewer": "security",
"findings": [
{
"title": "User-supplied ID in account lookup without ownership check",
"severity": "P0",
"file": "orders_controller.rb",
"line": 42,
"confidence": 0.92,
"autofix_class": "gated_auto",
"owner": "downstream-resolver",
"requires_verification": true,
"pre_existing": false,
"suggested_fix": "Add current_user.owns?(account) guard before lookup"
}
],
"residual_risks": [...],
"testing_gaps": [...]
}
```
Detail-tier fields (`why_it_matters`, `evidence`) are in the artifact file only. `suggested_fix` is optional in both tiers -- included in compact returns when present so the orchestrator has fix context for auto-apply decisions. If the file write fails, the compact return still provides everything the merge needs.
**CE always-on agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls in parallel with the persona agents. Give them the same review context bundle the personas receive: entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, `BASE:` marker, file list, diff, and `UNTRACKED:` scope notes. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6.
**CE conditional agents** (design-conformance-reviewer, schema-drift-detector, deployment-verification-agent, zip-agent-validator) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle plus the applicability reason (for example, which migration files triggered the agent, which design docs were found, or that the PR URL matched `git.zoominfo.com`). For schema-drift-detector specifically, pass the resolved review base branch explicitly so it never assumes `main`. For zip-agent-validator, pass the full PR URL and the PR number so it can fetch comments from the GHE API. Their output is unstructured and must be preserved for Stage 6 synthesis just like the CE always-on agents.
### Stage 5: Merge findings
Convert multiple reviewer compact JSON returns into one deduplicated, confidence-gated finding set. The compact returns contain merge-tier fields (title, severity, file, line, confidence, autofix_class, owner, requires_verification, pre_existing) plus the optional suggested_fix. Detail-tier fields (why_it_matters, evidence) are on disk in the per-agent artifact files and are not loaded at this stage.
1. **Validate.** Check each compact return for required top-level and per-finding fields, plus value constraints. Drop malformed returns or findings. Record the drop count.
- **Top-level required:** reviewer (string), findings (array), residual_risks (array), testing_gaps (array). Drop the entire return if any are missing or wrong type.
- **Per-finding required:** title, severity, file, line, confidence, autofix_class, owner, requires_verification, pre_existing
- **Value constraints:**
- severity: P0 | P1 | P2 | P3
- autofix_class: safe_auto | gated_auto | manual | advisory
- owner: review-fixer | downstream-resolver | human | release
- confidence: numeric, 0.0-1.0
- line: positive integer
- pre_existing, requires_verification: boolean
- Do not validate against the full schema here -- the full schema (including why_it_matters and evidence) applies to the artifact files on disk, not the compact returns.
2. **Confidence gate.** Suppress findings below 0.60 confidence. Exception: P0 findings at 0.50+ confidence survive the gate -- critical-but-uncertain issues must not be silently dropped. Record the suppressed count. This matches the persona instructions and the schema's confidence thresholds.
3. **Deduplicate.** Compute fingerprint: `normalize(file) + line_bucket(line, +/-3) + normalize(title)`. When fingerprints match, merge: keep highest severity, keep highest confidence, note which reviewers flagged it.
4. **Cross-reviewer agreement.** When 2+ independent reviewers flag the same issue (same fingerprint), boost the merged confidence by 0.10 (capped at 1.0). Cross-reviewer agreement is strong signal -- independent reviewers converging on the same issue is more reliable than any single reviewer's confidence. Note the agreement in the Reviewer column of the output (e.g., "security, correctness").
5. **Separate pre-existing.** Pull out findings with `pre_existing: true` into a separate list.
6. **Resolve disagreements.** When reviewers flag the same code region but disagree on severity, autofix_class, or owner, annotate the Reviewer column with the disagreement (e.g., "security (P0), correctness (P1) -- kept P0"). This transparency helps the user understand why a finding was routed the way it was.
7. **Normalize routing.** For each merged finding, set the final `autofix_class`, `owner`, and `requires_verification`. If reviewers disagree, keep the most conservative route. Synthesis may narrow a finding from `safe_auto` to `gated_auto` or `manual`, but must not widen it without new evidence.
8. **Partition the work.** Build three sets:
- in-skill fixer queue: only `safe_auto -> review-fixer`
- residual actionable queue: unresolved `gated_auto` or `manual` findings whose owner is `downstream-resolver`
- report-only queue: `advisory` findings plus anything owned by `human` or `release`
9. **Sort.** Order by severity (P0 first) -> confidence (descending) -> file path -> line number.
10. **Collect coverage data.** Union residual_risks and testing_gaps across reviewers.
11. **Preserve CE agent artifacts.** Keep the learnings, agent-native, design-conformance, schema-drift, deployment-verification, and zip-agent-validator outputs alongside the merged finding set. Do not drop unstructured agent output just because it does not match the persona JSON schema. For zip-agent-validator specifically, its validated findings use the standard findings schema and enter the merge pipeline (steps 1-7) like persona findings. Its `residual_risks` entries (collapsed zip-agent comments) are preserved separately for the Zip Agent Validation section in Stage 6.
### Stage 6: Synthesize and present
Assemble the final report using **pipe-delimited markdown tables for findings** from the review output template included below. The table format is mandatory for finding rows in interactive mode — do not render findings as freeform text blocks or horizontal-rule-separated prose. Other report sections (Applied Fixes, Learnings, Coverage, etc.) use bullet lists and the `---` separator before the verdict, as shown in the template.
1. **Header.** Scope, intent, mode, reviewer team with per-conditional justifications.
2. **Findings.** Rendered as pipe-delimited tables grouped by severity (`### P0 -- Critical`, `### P1 -- High`, `### P2 -- Moderate`, `### P3 -- Low`). Each finding row shows `#`, file, issue, reviewer(s), confidence, and synthesized route. Omit empty severity levels. Never render findings as freeform text blocks or numbered lists.
3. **Requirements Completeness.** Include only when a plan was found in Stage 2b. For each requirement (R1, R2, etc.) and implementation unit in the plan, report whether corresponding work appears in the diff. Use a simple checklist: met / not addressed / partially addressed. Routing depends on `plan_source`:
- **`explicit`** (caller-provided or PR body): Flag unaddressed requirements as P1 findings with `autofix_class: manual`, `owner: downstream-resolver`. These enter the residual actionable queue and can become todos.
- **`inferred`** (auto-discovered): Flag unaddressed requirements as P3 findings with `autofix_class: advisory`, `owner: human`. These stay in the report only — no todos, no autonomous follow-up. An inferred plan match is a hint, not a contract.
Omit this section entirely when no plan was found — do not mention the absence of a plan.
4. **Applied Fixes.** Include only if a fix phase ran in this invocation.
5. **Residual Actionable Work.** Include when unresolved actionable findings were handed off or should be handed off.
6. **Pre-existing.** Separate section, does not count toward verdict.
7. **Learnings & Past Solutions.** Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files.
8. **Agent-Native Gaps.** Surface agent-native-reviewer results. Omit section if no gaps found.
9. **Schema Drift Check.** If schema-drift-detector ran, summarize whether drift was found. If drift exists, list the unrelated schema objects and the required cleanup command. If clean, say so briefly.
10. **Deployment Notes.** If deployment-verification-agent ran, surface the key Go/No-Go items: blocking pre-deploy checks, the most important verification queries, rollback caveats, and monitoring focus areas. Keep the checklist actionable rather than dropping it into Coverage.
11. **Zip Agent Validation.** If zip-agent-validator ran, summarize the results: how many zip-agent comments were evaluated, how many validated (these appear as findings in the severity-grouped tables above), and how many collapsed with reasons. This section provides traceability -- reviewers can see that zip-agent comments were evaluated, not ignored.
12. **Coverage.** Suppressed count, residual risks, testing gaps, failed/timed-out reviewers, and any intent uncertainty carried by non-interactive modes.
13. **Verdict.** Ready to merge / Ready with fixes / Not ready. Fix order if applicable. When an `explicit` plan has unaddressed requirements, the verdict must reflect it — a PR that's code-clean but missing planned requirements is "Not ready" unless the omission is intentional. When an `inferred` plan has unaddressed requirements, note it in the verdict reasoning but do not block on it alone.
Do not include time estimates.
**Format verification:** Before delivering the report, verify the findings sections use pipe-delimited table rows (`| # | File | Issue | ... |`) not freeform text. If you catch yourself rendering findings as prose blocks separated by horizontal rules or bullet points, stop and reformat into tables.
### Headless output format
In `mode:headless`, replace the interactive pipe-delimited table report with a structured text envelope. The envelope follows the same structural pattern as document-review's headless output (completion header, metadata block, findings grouped by autofix_class, trailing sections) while using ce:review's own section headings and per-finding fields.
```
Code review complete (headless mode).
Scope: <scope-line>
Intent: <intent-summary>
Reviewers: <reviewer-list with conditional justifications>
Verdict: <Ready to merge | Ready with fixes | Not ready>
Artifact: .context/compound-engineering/ce-review/<run-id>/
Applied N safe_auto fixes.
Gated-auto findings (concrete fix, changes behavior/contracts):
[P1][gated_auto -> downstream-resolver][needs-verification] File: <file:line> -- <title> (<reviewer>, confidence <N>)
Why: <why_it_matters>
Suggested fix: <suggested_fix or "none">
Evidence: <evidence[0]>
Evidence: <evidence[1]>
Manual findings (actionable, needs handoff):
[P1][manual -> downstream-resolver] File: <file:line> -- <title> (<reviewer>, confidence <N>)
Why: <why_it_matters>
Evidence: <evidence[0]>
Advisory findings (report-only):
[P2][advisory -> human] File: <file:line> -- <title> (<reviewer>, confidence <N>)
Why: <why_it_matters>
Pre-existing issues:
[P2][gated_auto -> downstream-resolver] File: <file:line> -- <title> (<reviewer>, confidence <N>)
Why: <why_it_matters>
Residual risks:
- <risk>
Learnings & Past Solutions:
- <learning>
Agent-Native Gaps:
- <gap description>
Schema Drift Check:
- <drift status>
Deployment Notes:
- <deployment note>
Testing gaps:
- <gap>
Coverage:
- Suppressed: <N> findings below 0.60 confidence (P0 at 0.50+ retained)
- Untracked files excluded: <file1>, <file2>
- Failed reviewers: <reviewer>
Review complete
```
**Detail enrichment (headless only):** The headless envelope includes `Why:`, `Evidence:`, and `Suggested fix:` lines. After merge (Stage 5), read the per-agent artifact files from `.context/compound-engineering/ce-review/{run_id}/` for only the findings that survived dedup and confidence gating.
- **Field tiers:** `Why:` and `Evidence:` are detail-tier -- load from per-agent artifact files. `Suggested fix:` is merge-tier -- use it directly from the compact return without artifact lookup.
- **Artifact matching:** For each surviving finding, look up its detail-tier fields in the artifact files of the contributing reviewers. Match on `file + line_bucket(line, +/-3)` (the same tolerance used in Stage 5 dedup) within each contributing reviewer's artifact. When multiple artifact entries fall within the line bucket, apply `normalize(title)` to both the merged finding's title and each candidate entry's title as a tie-breaker.
- **Reviewer order:** Try contributing reviewers in the order they appear in the merged finding's reviewer list; use the first match.
- **No-match fallback:** If no artifact file contains a match (all writes failed, or the finding was synthesized during merge), omit the `Why:` and `Evidence:` lines for that finding and note the gap in Coverage. The `Suggested fix:` line can still be populated from the compact return since it is merge-tier.
**Formatting rules:**
- The `[needs-verification]` marker appears only on findings where `requires_verification: true`.
- The `Artifact:` line gives callers the path to the full run artifact for machine-readable access to the complete findings schema. The text envelope is the primary handoff; the artifact is for debugging and full-fidelity access.
- Findings with `owner: release` appear in the Advisory section (they are operational/rollout items, not code fixes).
- Findings with `pre_existing: true` appear in the Pre-existing section regardless of autofix_class.
- The Verdict appears in the metadata header (deliberately reordered from the interactive format where it appears at the bottom) so programmatic callers get the verdict first.
- Omit any section with zero items.
- If all reviewers fail or time out, emit `Code review degraded (headless mode). Reason: 0 of N reviewers returned results.` followed by "Review complete".
- End with "Review complete" as the terminal signal so callers can detect completion.
## Quality Gates
Before delivering the review, verify:
1. **Every finding is actionable.** Re-read each finding. If it says "consider", "might want to", or "could be improved" without a concrete fix, rewrite it with a specific action. Vague findings waste engineering time.
2. **No false positives from skimming.** For each finding, verify the surrounding code was actually read. Check that the "bug" isn't handled elsewhere in the same function, that the "unused import" isn't used in a type annotation, that the "missing null check" isn't guarded by the caller.
3. **Severity is calibrated.** A style nit is never P0. A SQL injection is never P3. Re-check every severity assignment.
4. **Line numbers are accurate.** Verify each cited line number against the file content. A finding pointing to the wrong line is worse than no finding.
5. **Protected artifacts are respected.** Discard any findings that recommend deleting or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/`.
6. **Findings don't duplicate linter output.** Don't flag things the project's linter/formatter would catch (missing semicolons, wrong indentation). Focus on semantic issues.
## Language-Aware Conditionals
This skill uses stack-specific reviewer agents when the diff clearly warrants them. Keep those agents opinionated. They are not generic language checkers; they add a distinct review lens on top of the always-on and cross-cutting personas.
Do not spawn them mechanically from file extensions alone. The trigger is meaningful changed behavior, architecture, or UI state in that stack.
## After Review
### Mode-Driven Post-Review Flow
After presenting findings and verdict (Stage 6), route the next steps by mode. Review and synthesis stay the same in every mode; only mutation and handoff behavior changes.
#### Step 1: Build the action sets
- **Clean review** means zero findings after suppression and pre-existing separation. Skip the fix/handoff phase when the review is clean.
- **Fixer queue:** final findings routed to `safe_auto -> review-fixer`.
- **Residual actionable queue:** unresolved `gated_auto` or `manual` findings whose final owner is `downstream-resolver`.
- **Report-only queue:** `advisory` findings and any outputs owned by `human` or `release`.
- **Never convert advisory-only outputs into fix work or todos.** Deployment notes, residual risks, and release-owned items stay in the report.
#### Step 2: Choose policy by mode
**Interactive mode**
- Apply `safe_auto -> review-fixer` findings automatically without asking. These are safe by definition.
- Ask a policy question **using the platform's blocking question tool** (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini) only when `gated_auto` or `manual` findings remain after safe fixes. Do not replace with a conversational open-ended question. Adapt the options to match what actually remains:
**When `gated_auto` findings are present** (with or without `manual`):
```
Safe fixes have been applied. What should I do with the remaining findings?
1. Review and approve specific gated fixes (Recommended)
2. Leave as residual work
3. Report only -- no further action
```
**When only `manual` findings remain** (no `gated_auto`):
```
Safe fixes have been applied. The remaining findings need manual resolution. What should I do?
1. Leave as residual work (Recommended)
2. Report only -- no further action
```
If no blocking question tool is available, present the applicable numbered options as text and wait for the user's selection before proceeding.
- If no `gated_auto` or `manual` findings remain after safe fixes, skip the policy question entirely — report what was fixed and proceed to next steps.
- Only include `gated_auto` findings in the fixer queue after the user explicitly approves the specific items. Do not widen the queue based on severity alone.
**Autofix mode**
- Ask no questions.
- Apply only the `safe_auto -> review-fixer` queue.
- Leave `gated_auto`, `manual`, `human`, and `release` items unresolved.
- Prepare residual work only for unresolved actionable findings whose final owner is `downstream-resolver`.
**Report-only mode**
- Ask no questions.
- Do not build a fixer queue.
- Do not create residual todos or `.context` artifacts.
- Stop after Stage 6. Everything remains in the report.
**Headless mode**
- Ask no questions.
- Apply only the `safe_auto -> review-fixer` queue in a single pass. Do not enter the bounded re-review loop (Step 3). Spawn one fixer subagent, apply fixes, then proceed directly to Step 4.
- Leave `gated_auto`, `manual`, `human`, and `release` items unresolved — they appear in the structured text output.
- Output the headless output envelope (see Stage 6) instead of the interactive report.
- Write a run artifact (Step 4) but do not create todo files.
- Stop after the structured text output and "Review complete" signal. No commit/push/PR.
#### Step 3: Apply fixes with one fixer and bounded rounds
- Spawn exactly one fixer subagent for the current fixer queue in the current checkout. That fixer applies all approved changes and runs the relevant targeted tests in one pass against a consistent tree.
- Do not fan out multiple fixers against the same checkout. Parallel fixers require isolated worktrees/branches and deliberate mergeback.
- Re-review only the changed scope after fixes land.
- Bound the loop with `max_rounds: 2`. If issues remain after the second round, stop and hand them off as residual work or report them as unresolved.
- If any applied finding has `requires_verification: true`, the round is incomplete until the targeted verification runs.
- Do not start a mutating review round concurrently with browser testing on the same checkout. Future orchestrators that want both must either run `mode:report-only` during the parallel phase or isolate the mutating review in its own checkout/worktree.
#### Step 4: Emit artifacts and downstream handoff
- In interactive, autofix, and headless modes, write a per-run artifact under `.context/compound-engineering/ce-review/<run-id>/` containing:
- synthesized findings (merged output from Stage 5)
- applied fixes
- residual actionable work
- advisory-only outputs
Per-agent full-detail JSON files (`{reviewer_name}.json`) are already present in this directory from Stage 4 dispatch.
- Also write `metadata.json` alongside the findings so downstream skills (e.g., `ce:polish-beta`) can verify the artifact matches the current branch and HEAD. Minimum fields:
```json
{
"run_id": "<run-id>",
"branch": "<git branch --show-current at dispatch time>",
"head_sha": "<git rev-parse HEAD at dispatch time>",
"verdict": "<Ready to merge | Ready with fixes | Not ready>",
"completed_at": "<ISO 8601 UTC timestamp>"
}
```
Capture `branch` and `head_sha` at dispatch time (before any autofixes land), and write the file after the verdict is finalized. This file is additive -- pre-existing artifacts that predate this field are still valid, and downstream skills fall back to file mtime when it is missing.
- In autofix mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path, naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
- Do not create todos for `advisory` findings, `owner: human`, `owner: release`, or protected-artifact cleanup suggestions.
- If only advisory outputs remain, create no todos.
- Interactive mode may offer to externalize residual actionable work after fixes, but it is not required to finish the review.
#### Step 5: Final next steps
**Interactive mode only:** after the fix-review cycle completes (clean verdict or the user chose to stop), offer next steps based on the entry mode. Reuse the resolved review base/default branch from Stage 1 when known; do not hard-code only `main`/`master`.
- **PR mode (entered via PR number/URL):**
- **Push fixes** -- push commits to the existing PR branch
- **Exit** -- done for now
- **Branch mode (feature branch with no PR, and not the resolved review base/default branch):**
- **Create a PR (Recommended)** -- push and open a pull request
- **Continue without PR** -- stay on the branch
- **Exit** -- done for now
- **On the resolved review base/default branch:**
- **Continue** -- proceed with next steps
- **Exit** -- done for now
If "Create a PR": first publish the branch with `git push --set-upstream origin HEAD`, then use `gh pr create` with a title and summary derived from the branch changes.
If "Push fixes": push the branch with `git push` to update the existing PR.
**Autofix, report-only, and headless modes:** stop after the report, artifact emission, and residual-work handoff. Do not commit, push, or create a PR.
## Fallback
If the platform doesn't support parallel sub-agents, run reviewers sequentially. Everything else (stages, output format, merge pipeline) stays the same.
---
## Included References
### Persona Catalog
@./references/persona-catalog.md
### Subagent Template
@./references/subagent-template.md
### Diff Scope Rules
@./references/diff-scope.md
### Findings Schema
@./references/findings-schema.json
### Review Output Template
@./references/review-output-template.md

168
plugins/compound-engineering/skills/ce-review/references/review-output-template.md Normal file
View File

@@ -0,0 +1,168 @@
# Code Review Output Template
Use this **exact format** when presenting synthesized review findings. Findings are grouped by severity, not by reviewer.
**IMPORTANT:** Use pipe-delimited markdown tables (`| col | col |`). Do NOT use ASCII box-drawing characters.
## Example
```markdown
## Code Review Results
**Scope:** merge-base with the review base branch -> working tree (14 files, 342 lines)
**Intent:** Add order export endpoint with CSV and JSON format support
**Mode:** autofix
**Reviewers:** correctness, testing, maintainability, security, api-contract
- security -- new public endpoint accepts user-provided format parameter
- api-contract -- new /api/orders/export route with response schema
### P0 -- Critical
| # | File | Issue | Reviewer | Confidence | Route |
|---|------|-------|----------|------------|-------|
| 1 | `orders_controller.rb:42` | User-supplied ID in account lookup without ownership check | security | 0.92 | `gated_auto -> downstream-resolver` |
### P1 -- High
| # | File | Issue | Reviewer | Confidence | Route |
|---|------|-------|----------|------------|-------|
| 2 | `export_service.rb:87` | Loads all orders into memory -- unbounded for large accounts | performance | 0.85 | `safe_auto -> review-fixer` |
| 3 | `export_service.rb:91` | No pagination -- response size grows linearly with order count | api-contract, performance | 0.80 | `manual -> downstream-resolver` |
### P2 -- Moderate
| # | File | Issue | Reviewer | Confidence | Route |
|---|------|-------|----------|------------|-------|
| 4 | `export_service.rb:45` | Missing error handling for CSV serialization failure | correctness | 0.75 | `safe_auto -> review-fixer` |
### P3 -- Low
| # | File | Issue | Reviewer | Confidence | Route |
|---|------|-------|----------|------------|-------|
| 5 | `export_helper.rb:12` | Format detection could use early return instead of nested conditional | maintainability | 0.70 | `advisory -> human` |
### Applied Fixes
- `safe_auto`: Added bounded export pagination guard and CSV serialization failure test coverage in this run
### Residual Actionable Work
| # | File | Issue | Route | Next Step |
|---|------|-------|-------|-----------|
| 1 | `orders_controller.rb:42` | Ownership check missing on export lookup | `gated_auto -> downstream-resolver` | Create residual todo and require explicit approval before behavior change |
| 2 | `export_service.rb:91` | Pagination contract needs a broader API decision | `manual -> downstream-resolver` | Create residual todo with contract and client impact details |
### Pre-existing Issues
| # | File | Issue | Reviewer |
|---|------|-------|----------|
| 1 | `orders_controller.rb:12` | Broad rescue masking failed permission check | correctness |
### Learnings & Past Solutions
- [Known Pattern] `docs/solutions/export-pagination.md` -- previous export pagination fix applies to this endpoint
### Agent-Native Gaps
- New export endpoint has no CLI/agent equivalent -- agent users cannot trigger exports
### Schema Drift Check
- Clean: schema.rb changes match the migrations in scope
### Deployment Notes
- Pre-deploy: capture baseline row counts before enabling the export backfill
- Verify: `SELECT COUNT(*) FROM exports WHERE status IS NULL;` should stay at `0`
- Rollback: keep the old export path available until the backfill has been validated
### Zip Agent Validation
- Evaluated: 8 zip-agent comments
- Validated: 2 (appear as findings #3 and #6 above)
- Collapsed: 6
- `app/services/order_service.rb:45`: "Missing error handling" -- handled by ApplicationService base class rescue
- `app/controllers/api/orders_controller.rb:18`: "Unbounded query" -- pagination enforced by ApiController concern
- _(4 more collapsed for stylistic/formatting concerns)_
### Coverage
- Suppressed: 2 findings below 0.60 confidence
- Residual risks: No rate limiting on export endpoint
- Testing gaps: No test for concurrent export requests
### Zip Agent Validation
- Evaluated: 8 zip-agent comments
- Validated: 2 (appear as findings #3 and #6 above)
- Collapsed: 6
- `app/services/order_service.rb:45`: "Missing error handling" -- handled by ApplicationService base class rescue
- `app/controllers/api/orders_controller.rb:18`: "Unbounded query" -- pagination enforced by ApiController concern
- _(4 more collapsed for stylistic/formatting concerns)_
---
> **Verdict:** Ready with fixes
>
> **Reasoning:** 1 critical auth bypass must be fixed. The memory/pagination issues (P1) should be addressed for production safety.
>
> **Fix order:** P0 auth bypass -> P1 memory/pagination -> P2 error handling if straightforward
```
## Anti-patterns
Do NOT produce output like this. The following is wrong:
```markdown
Findings
Sev: P1
File: foo.go:42
Issue: Some problem description
Reviewer(s): adversarial
Confidence: 0.85
Route: advisory -> human
────────────────────────────────────────
Sev: P2
File: bar.go:99
Issue: Another problem
```
This fails because: no pipe-delimited tables, no severity-grouped `###` headers, uses box-drawing horizontal rules, no numbered findings, no `## Code Review Results` title, and the verdict is not in a blockquote. Always use the table format from the example above.
## Formatting Rules
- **Pipe-delimited markdown tables** for findings -- never ASCII box-drawing characters or per-finding horizontal-rule separators between entries (the report-level `---` before the verdict is still required)
- **Severity-grouped sections** -- `### P0 -- Critical`, `### P1 -- High`, `### P2 -- Moderate`, `### P3 -- Low`. Omit empty severity levels.
- **Always include file:line location** for code review issues
- **Reviewer column** shows which persona(s) flagged the issue. Multiple reviewers = cross-reviewer agreement.
- **Confidence column** shows the finding's confidence score
- **Route column** shows the synthesized handling decision as ``<autofix_class> -> <owner>``.
- **Header includes** scope, intent, and reviewer team with per-conditional justifications
- **Mode line** -- include `interactive`, `autofix`, `report-only`, or `headless`
- **Applied Fixes section** -- include only when a fix phase ran in this review invocation
- **Residual Actionable Work section** -- include only when unresolved actionable findings were handed off for later work
- **Pre-existing section** -- separate table, no confidence column (these are informational)
- **Learnings & Past Solutions section** -- results from learnings-researcher, with links to docs/solutions/ files
- **Agent-Native Gaps section** -- results from agent-native-reviewer. Omit if no gaps found.
- **Schema Drift Check section** -- results from schema-drift-detector. Omit if the agent did not run.
- **Deployment Notes section** -- key checklist items from deployment-verification-agent. Omit if the agent did not run.
- **Zip Agent Validation section** -- summary of zip-agent comment evaluation: total, validated (with cross-references to findings table), collapsed (with reasons). Omit if the agent did not run.
- **Coverage section** -- suppressed count, residual risks, testing gaps, failed reviewers
- **Zip Agent Validation section** -- summary of zip-agent comment evaluation: total, validated (with cross-references to findings table), collapsed (with reasons). Omit if the agent did not run.
- **Summary uses blockquotes** for verdict, reasoning, and fix order
- **Horizontal rule** (`---`) separates findings from verdict
- **`###` headers** for each section -- never plain text headers
## Headless Mode Format
In `mode:headless`, replace the interactive pipe-delimited table report with a structured text envelope. The headless format is defined in the `### Headless output format` section of SKILL.md. Key differences from the interactive format:
- **No pipe-delimited tables.** Findings use `[severity][autofix_class -> owner] File: <file:line> -- <title>` line format with indented Why/Evidence/Suggested fix lines.
- **Findings grouped by autofix_class** (gated-auto, manual, advisory) instead of severity. Within each group, findings are sorted by severity.
- **Verdict in header** (top of output) instead of bottom, so programmatic callers get it first.
- **`Artifact:` line** in metadata header gives callers the path to the full run artifact.
- **`[needs-verification]` marker** on findings where `requires_verification: true`.
- **Evidence lines** included per finding.
- **Completion signal:** "Review complete" as the final line.

155
plugins/compound-engineering/skills/excalidraw-png-export/SKILL.md Normal file
View File

@@ -0,0 +1,155 @@
---
name: excalidraw-png-export
description: "This skill should be used when creating diagrams, architecture visuals, or flowcharts and exporting them as PNG files. It uses the Excalidraw MCP to render hand-drawn style diagrams locally and Playwright to export them to PNG without sending data to any remote server. Triggers on requests like 'create a diagram', 'make an architecture diagram', 'draw a flowchart and export as PNG', or any request that needs a visual diagram delivered as an image file."
---
# Excalidraw PNG Export
Create hand-drawn style diagrams with the Excalidraw MCP and export them locally to PNG files. All rendering happens on the local machine. Diagram data never leaves the user's computer.
## Prerequisites
### First-Time Setup
Run the setup script once per machine to install Playwright and Chromium headless:
```bash
bash <skill-path>/scripts/setup.sh
```
This creates a `.export-runtime` directory inside `scripts/` with the Node.js dependencies. The setup is idempotent and skips installation if already present.
### Required MCP
The Excalidraw MCP server must be configured. Verify availability by checking for `mcp__excalidraw__create_view` and `mcp__excalidraw__read_checkpoint` tools.
## File Location Convention
Save diagram source files alongside their PNG exports in the project's image directory. This enables re-exporting diagrams when content or styling changes.
**Standard pattern:**
```
docs/images/my-diagram.excalidraw # source (commit this)
docs/images/my-diagram.png # rendered output (commit this)
```
**When updating an existing diagram**, look for a `.excalidraw` file next to the PNG. If one exists, edit it and re-export rather than rebuilding from scratch.
**Temporary files** (raw checkpoint JSON) go in `/tmp/excalidraw-export/` and are discarded after conversion.
## Workflow
### Step 1: Design the Diagram Elements
Translate the user's request into Excalidraw element JSON. Load [excalidraw-element-format.md](./references/excalidraw-element-format.md) for the full element specification, color palette, and sizing guidelines.
Key design decisions:
- Choose appropriate colors from the palette to distinguish different components
- Use `label` on shapes instead of separate text elements
- Use `roundness: { type: 3 }` for rounded corners on rectangles
- Include `cameraUpdate` as the first element to frame the view (MCP rendering only)
- Use arrow bindings (`startBinding`/`endBinding`) to connect shapes
### Step 2: Render with Excalidraw MCP
Call `mcp__excalidraw__create_view` with the element JSON array. This renders an interactive preview in the Claude Code UI.
```
mcp__excalidraw__create_view({ elements: "<JSON array string>" })
```
The response includes a `checkpointId` for retrieving the rendered state.
### Step 3: Extract the Checkpoint Data
Call `mcp__excalidraw__read_checkpoint` with the checkpoint ID to get the full element JSON back.
```
mcp__excalidraw__read_checkpoint({ id: "<checkpointId>" })
```
### Step 4: Convert Checkpoint to .excalidraw File
Use the `convert.mjs` script to transform raw MCP checkpoint JSON into a valid `.excalidraw` file. This handles all the tedious parts automatically:
- Filters out pseudo-elements (`cameraUpdate`, `delete`, `restoreCheckpoint`)
- Adds required Excalidraw defaults (`seed`, `version`, `fontFamily`, etc.)
- Expands `label` properties on shapes/arrows into proper bound text elements
```bash
# Save checkpoint JSON to a temp file, then convert to the project's image directory:
node <skill-path>/scripts/convert.mjs /tmp/excalidraw-export/raw.json docs/images/my-diagram.excalidraw
```
The input JSON should be the raw checkpoint data from `mcp__excalidraw__read_checkpoint` (the `{"elements": [...]}` object). The output `.excalidraw` file goes in the project's image directory (see File Location Convention above).
**For batch exports**: Write each checkpoint to a separate raw JSON file, then convert each one:
```bash
node <skill-path>/scripts/convert.mjs raw1.json diagram1.excalidraw
node <skill-path>/scripts/convert.mjs raw2.json diagram2.excalidraw
```
**Manual alternative**: If you need to write the `.excalidraw` file by hand (e.g., without the convert script), each element needs these defaults:
```
angle: 0, roughness: 1, opacity: 100, groupIds: [], seed: <unique int>,
version: 1, versionNonce: <unique int>, isDeleted: false,
boundElements: null, link: null, locked: false
```
Text elements also need: `fontFamily: 1, textAlign: "left", verticalAlign: "top", baseline: 14, containerId: null, originalText: "<same as text>"`
Bound text (labels on shapes/arrows) needs: `containerId: "<parent-id>"`, `textAlign: "center"`, `verticalAlign: "middle"`, and the parent needs `boundElements: [{"id": "<text-id>", "type": "text"}]`.
### Step 5: Export to PNG
Run the export script. Determine the runtime path relative to this skill's scripts directory:
```bash
cd <skill-path>/scripts/.export-runtime && node <skill-path>/scripts/export_png.mjs docs/images/my-diagram.excalidraw docs/images/my-diagram.png
```
The script:
1. Starts a local HTTP server serving the `.excalidraw` file and an HTML page
2. Launches headless Chromium via Playwright
3. The HTML page loads the Excalidraw library from esm.sh (library code only, not user data)
4. Calls `exportToBlob` on the local diagram data
5. Extracts the base64 PNG and writes it to disk
6. Cleans up temp files and exits
The script prints the output path on success. Verify the result with `file <output.png>`.
### Step 5.5: Validate and Iterate
Run the validation script on the `.excalidraw` file to catch spatial issues:
```bash
node <skill-path>/scripts/validate.mjs docs/images/my-diagram.excalidraw
```
Then read the exported PNG back using the Read tool to visually inspect:
1. All label text fits within its container (no overflow/clipping)
2. No arrows cross over text labels
3. Spacing between elements is consistent
4. Legend and titles are properly positioned
If the validation script or visual inspection reveals issues:
1. Identify the specific elements that need adjustment
2. Edit the `.excalidraw` file (adjust coordinates, box sizes, or arrow waypoints)
3. Re-run the export script (Step 5)
4. Re-validate
### Step 6: Deliver the Result
Read the PNG file to display it to the user. Provide the file path so the user can access it directly.
## Troubleshooting
**Setup fails**: Verify Node.js v18+ is installed (`node --version`). Ensure npm has network access for the initial Playwright/Chromium download.
**Export times out**: The HTML page has a 30-second timeout. If it fails, check browser console output in the script's error messages. Common cause: esm.sh CDN is temporarily slow on first load.
**Blank PNG**: Ensure elements include all required properties (see Step 4 defaults). Missing `seed`, `version`, or `fontFamily` on text elements can cause silent render failures.
**"READY" never fires**: The `exportToBlob` call requires valid elements. Filter out `cameraUpdate` and other pseudo-elements before writing the `.excalidraw` file.

149
plugins/compound-engineering/skills/excalidraw-png-export/references/excalidraw-element-format.md Normal file
View File

@@ -0,0 +1,149 @@
# Excalidraw Element Format Reference
This reference documents the element JSON format accepted by the Excalidraw MCP `create_view` tool and the `export_png.mjs` script.
## Color Palette
### Primary Colors
| Name | Hex | Use |
|------|-----|-----|
| Blue | `#4a9eed` | Primary actions, links |
| Amber | `#f59e0b` | Warnings, highlights |
| Green | `#22c55e` | Success, positive |
| Red | `#ef4444` | Errors, negative |
| Purple | `#8b5cf6` | Accents, special |
| Pink | `#ec4899` | Decorative |
| Cyan | `#06b6d4` | Info, secondary |
### Fill Colors (pastel, for shape backgrounds)
| Color | Hex | Good For |
|-------|-----|----------|
| Light Blue | `#a5d8ff` | Input, sources, primary |
| Light Green | `#b2f2bb` | Success, output |
| Light Orange | `#ffd8a8` | Warning, pending |
| Light Purple | `#d0bfff` | Processing, middleware |
| Light Red | `#ffc9c9` | Error, critical |
| Light Yellow | `#fff3bf` | Notes, decisions |
| Light Teal | `#c3fae8` | Storage, data |
## Element Types
### Required Fields (all elements)
`type`, `id` (unique string), `x`, `y`, `width`, `height`
### Defaults (skip these)
strokeColor="#1e1e1e", backgroundColor="transparent", fillStyle="solid", strokeWidth=2, roughness=1, opacity=100
### Shapes
**Rectangle**: `{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }`
- `roundness: { type: 3 }` for rounded corners
- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` for filled
**Ellipse**: `{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }`
**Diamond**: `{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }`
### Labels
**Labeled shape (preferred)**: Add `label` to any shape for auto-centered text.
```json
{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80, "label": { "text": "Hello", "fontSize": 20 } }
```
**Standalone text** (titles, annotations only):
```json
{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20 }
```
### Arrows
```json
{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, "points": [[0,0],[200,0]], "endArrowhead": "arrow" }
```
**Bindings** connect arrows to shapes:
```json
"startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] }
```
fixedPoint: top=[0.5,0], bottom=[0.5,1], left=[0,0.5], right=[1,0.5]
**Labeled arrow**: `"label": { "text": "connects" }`
### Camera (MCP only, not exported to PNG)
```json
{ "type": "cameraUpdate", "width": 800, "height": 600, "x": 0, "y": 0 }
```
Camera sizes must be 4:3 ratio. The export script filters these out automatically.
## Sizing Rules
### Container-to-text ratios
- Box width >= estimated_text_width * 1.4 (40% horizontal margin)
- Box height >= estimated_text_height * 1.5 (50% vertical margin)
- Minimum box size: 150x60 for single-line labels, 200x80 for multi-line
### Font size constraints
- Labels inside containers: max fontSize 14
- Service/zone titles: fontSize 18-22
- Standalone annotations: fontSize 12-14
- Never exceed fontSize 16 inside a box smaller than 300px wide
### Padding
- Minimum 15px padding on each side between text and container edge
- For multi-line text, add 8px vertical padding per line beyond the first
### General
- Leave 20-30px gaps between elements
## Label Content Guidelines
### Keep labels short
- Maximum 2 lines per label inside shapes
- Maximum 25 characters per line
- If label needs 3+ lines, split: short name in box, details as annotation below
### Label patterns
- Service box: "Service Name" (1 line) or "Service Name\nBrief role" (2 lines)
- Component box: "Component Name" (1 line)
- Detail text: Use standalone text elements positioned below/beside the box
### Bad vs Good
BAD: label "Auth-MS\nOAuth tokens, credentials\n800-1K req/s, <100ms" (3 lines, 30+ chars)
GOOD: label "Auth-MS\nOAuth token management" (2 lines, 22 chars max)
+ standalone text below: "800-1K req/s, <100ms p99"
## Arrow Routing Rules
### Gutter-based routing
- Define horizontal and vertical gutters (20-30px gaps between service zones)
- Route arrows through gutters, never over content areas
- Use right-angle waypoints along zone edges
### Waypoint placement
- Start/end points: attach to box edges using fixedPoint bindings
- Mid-waypoints: offset 20px from nearest box edge
- For crossing traffic: stagger parallel arrows by 10px
### Vertical vs horizontal preference
- Prefer horizontal arrows for same-tier connections
- Prefer vertical arrows for cross-tier flows (consumer -> service -> external)
- Diagonal arrows only when routing around would add 3+ waypoints
### Label placement on arrows
- Arrow labels should sit in empty space, not over boxes
- For vertical arrows: place label to the left or right, offset 15px
- For horizontal arrows: place label above, offset 10px
## Example: Two Connected Boxes
```json
[
{ "type": "cameraUpdate", "width": 800, "height": 600, "x": 50, "y": 50 },
{ "type": "rectangle", "id": "b1", "x": 100, "y": 100, "width": 200, "height": 100, "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid", "label": { "text": "Start", "fontSize": 20 } },
{ "type": "rectangle", "id": "b2", "x": 450, "y": 100, "width": 200, "height": 100, "roundness": { "type": 3 }, "backgroundColor": "#b2f2bb", "fillStyle": "solid", "label": { "text": "End", "fontSize": 20 } },
{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0, "points": [[0,0],[150,0]], "endArrowhead": "arrow", "startBinding": { "elementId": "b1", "fixedPoint": [1, 0.5] }, "endBinding": { "elementId": "b2", "fixedPoint": [0, 0.5] } }
]
```

2
plugins/compound-engineering/skills/excalidraw-png-export/scripts/.gitignore vendored Normal file
View File

@@ -0,0 +1,2 @@
.export-runtime/
.export-tmp/

178
plugins/compound-engineering/skills/excalidraw-png-export/scripts/convert.mjs Executable file
View File

@@ -0,0 +1,178 @@
#!/usr/bin/env node
/**
* Convert raw Excalidraw MCP checkpoint JSON into a valid .excalidraw file.
* Filters pseudo-elements, adds required defaults, expands labels into bound text.
*/
import { readFileSync, writeFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { createRequire } from 'module';
const __dirname = dirname(fileURLToPath(import.meta.url));
const runtimeRequire = createRequire(join(__dirname, '.export-runtime', 'package.json'));
// Canvas-based text measurement with graceful fallback to heuristic.
// Excalidraw renders with Virgil (hand-drawn font); system sans-serif
// is a reasonable proxy. The 1.1x multiplier accounts for Virgil being wider.
let measureText;
try {
const canvas = runtimeRequire('canvas');
const { createCanvas } = canvas;
const cvs = createCanvas(1, 1);
const ctx = cvs.getContext('2d');
measureText = (text, fontSize) => {
ctx.font = `${fontSize}px sans-serif`;
const lines = text.split('\n');
const widths = lines.map(line => ctx.measureText(line).width * 1.1);
return {
width: Math.max(...widths),
height: lines.length * (fontSize * 1.25),
};
};
} catch {
console.warn('WARN: canvas not available, using heuristic text sizing (install canvas for accurate measurement)');
measureText = (text, fontSize) => {
const lines = text.split('\n');
return {
width: Math.max(...lines.map(l => l.length)) * fontSize * 0.55,
height: lines.length * (fontSize + 4),
};
};
}
const [,, inputFile, outputFile] = process.argv;
if (!inputFile || !outputFile) {
console.error('Usage: node convert.mjs <input.json> <output.excalidraw>');
process.exit(1);
}
const raw = JSON.parse(readFileSync(inputFile, 'utf8'));
const elements = raw.elements || raw;
let seed = 1000;
const nextSeed = () => seed++;
const processed = [];
for (const el of elements) {
if (['cameraUpdate', 'delete', 'restoreCheckpoint'].includes(el.type)) continue;
const base = {
angle: 0,
roughness: 1,
opacity: el.opacity ?? 100,
groupIds: [],
seed: nextSeed(),
version: 1,
versionNonce: nextSeed(),
isDeleted: false,
boundElements: null,
link: null,
locked: false,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: el.backgroundColor || 'transparent',
fillStyle: el.fillStyle || 'solid',
strokeWidth: el.strokeWidth ?? 2,
strokeStyle: el.strokeStyle || 'solid',
};
if (el.type === 'text') {
const fontSize = el.fontSize || 16;
const measured = measureText(el.text, fontSize);
processed.push({
...base,
type: 'text',
id: el.id,
x: el.x,
y: el.y,
width: measured.width,
height: measured.height,
text: el.text,
fontSize, fontFamily: 1,
textAlign: 'left',
verticalAlign: 'top',
baseline: fontSize,
containerId: null,
originalText: el.text,
});
} else if (el.type === 'arrow') {
const arrowEl = {
...base,
type: 'arrow',
id: el.id,
x: el.x,
y: el.y,
width: el.width || 0,
height: el.height || 0,
points: el.points || [[0, 0]],
startArrowhead: el.startArrowhead || null,
endArrowhead: el.endArrowhead ?? 'arrow',
startBinding: el.startBinding ? { ...el.startBinding, focus: 0, gap: 5 } : null,
endBinding: el.endBinding ? { ...el.endBinding, focus: 0, gap: 5 } : null,
roundness: { type: 2 },
boundElements: [],
};
processed.push(arrowEl);
if (el.label) {
const labelId = el.id + '_label';
const text = el.label.text || '';
const fontSize = el.label.fontSize || 14;
const { width: w, height: h } = measureText(text, fontSize);
const midPt = el.points[Math.floor(el.points.length / 2)] || [0, 0];
processed.push({
...base,
type: 'text', id: labelId,
x: el.x + midPt[0] - w / 2,
y: el.y + midPt[1] - h / 2 - 12,
width: w, height: h,
text, fontSize, fontFamily: 1,
textAlign: 'center', verticalAlign: 'middle',
baseline: fontSize, containerId: el.id, originalText: text,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: 'transparent',
});
arrowEl.boundElements = [{ id: labelId, type: 'text' }];
}
} else if (['rectangle', 'ellipse', 'diamond'].includes(el.type)) {
const shapeEl = {
...base,
type: el.type, id: el.id,
x: el.x, y: el.y, width: el.width, height: el.height,
roundness: el.roundness || null,
boundElements: [],
};
processed.push(shapeEl);
if (el.label) {
const labelId = el.id + '_label';
const text = el.label.text || '';
const fontSize = el.label.fontSize || 16;
const { width: w, height: h } = measureText(text, fontSize);
processed.push({
...base,
type: 'text', id: labelId,
x: el.x + (el.width - w) / 2,
y: el.y + (el.height - h) / 2,
width: w, height: h,
text, fontSize, fontFamily: 1,
textAlign: 'center', verticalAlign: 'middle',
baseline: fontSize, containerId: el.id, originalText: text,
strokeColor: el.strokeColor || '#1e1e1e',
backgroundColor: 'transparent',
});
shapeEl.boundElements = [{ id: labelId, type: 'text' }];
}
}
}
writeFileSync(outputFile, JSON.stringify({
type: 'excalidraw', version: 2, source: 'claude-code',
elements: processed,
appState: { exportBackground: true, viewBackgroundColor: '#ffffff' },
files: {},
}, null, 2));
console.log(`Wrote ${processed.length} elements to ${outputFile}`);

61
plugins/compound-engineering/skills/excalidraw-png-export/scripts/export.html Normal file
View File

@@ -0,0 +1,61 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body { margin: 0; background: white; }
#root { width: 900px; height: 400px; }
</style>
<script>
window.EXCALIDRAW_ASSET_PATH = "https://esm.sh/@excalidraw/excalidraw/dist/prod/";
</script>
</head>
<body>
<div id="root"></div>
<script type="importmap">
{
"imports": {
"react": "https://esm.sh/react@18",
"react-dom": "https://esm.sh/react-dom@18",
"react-dom/client": "https://esm.sh/react-dom@18/client",
"react/jsx-runtime": "https://esm.sh/react@18/jsx-runtime",
"@excalidraw/excalidraw": "https://esm.sh/@excalidraw/excalidraw@0.18.0?external=react,react-dom"
}
}
</script>
<script type="module">
import { exportToBlob } from "@excalidraw/excalidraw";
async function run() {
const resp = await fetch("./diagram.excalidraw");
const data = await resp.json();
const validTypes = ["rectangle","ellipse","diamond","text","arrow","line","freedraw","image","frame"];
const elements = data.elements.filter(el => validTypes.includes(el.type));
const blob = await exportToBlob({
elements,
appState: {
exportBackground: true,
viewBackgroundColor: data.appState?.viewBackgroundColor || "#ffffff",
exportWithDarkMode: data.appState?.exportWithDarkMode || false,
},
files: data.files || {},
getDimensions: (w, h) => ({ width: w * 2, height: h * 2, scale: 2 }),
});
const reader = new FileReader();
reader.onload = () => {
window.__PNG_DATA__ = reader.result;
document.title = "READY";
};
reader.readAsDataURL(blob);
}
run().catch(e => {
console.error("EXPORT ERROR:", e);
document.title = "ERROR:" + e.message;
});
</script>
</body>
</html>

90
plugins/compound-engineering/skills/excalidraw-png-export/scripts/export_png.mjs Executable file
View File

@@ -0,0 +1,90 @@
#!/usr/bin/env node
/**
* Export an Excalidraw JSON file to PNG using Playwright + the official Excalidraw library.
*
* Usage: node export_png.mjs <input.excalidraw> [output.png]
*
* All rendering happens locally. Diagram data never leaves the machine.
* The Excalidraw JS library is fetched from esm.sh CDN (code only, not user data).
*/
import { createRequire } from "module";
import { readFileSync, writeFileSync, copyFileSync } from "fs";
import { createServer } from "http";
import { join, extname, dirname } from "path";
import { fileURLToPath } from "url";
const __dirname = dirname(fileURLToPath(import.meta.url));
const RUNTIME_DIR = join(__dirname, ".export-runtime");
const HTML_PATH = join(__dirname, "export.html");
// Resolve playwright from the runtime directory, not the script's location
const require = createRequire(join(RUNTIME_DIR, "node_modules", "playwright", "index.mjs"));
const { chromium } = await import(join(RUNTIME_DIR, "node_modules", "playwright", "index.mjs"));
const inputPath = process.argv[2];
if (!inputPath) {
console.error("Usage: node export_png.mjs <input.excalidraw> [output.png]");
process.exit(1);
}
const outputPath = process.argv[3] || inputPath.replace(/\.excalidraw$/, ".png");
// Set up a temp serving directory
const SERVE_DIR = join(__dirname, ".export-tmp");
const { mkdirSync, rmSync } = await import("fs");
mkdirSync(SERVE_DIR, { recursive: true });
copyFileSync(HTML_PATH, join(SERVE_DIR, "export.html"));
copyFileSync(inputPath, join(SERVE_DIR, "diagram.excalidraw"));
const MIME = {
".html": "text/html",
".json": "application/json",
".excalidraw": "application/json",
};
const server = createServer((req, res) => {
const file = join(SERVE_DIR, req.url === "/" ? "export.html" : req.url);
try {
const data = readFileSync(file);
res.writeHead(200, { "Content-Type": MIME[extname(file)] || "application/octet-stream" });
res.end(data);
} catch {
res.writeHead(404);
res.end("Not found");
}
});
server.listen(0, "127.0.0.1", async () => {
const port = server.address().port;
let browser;
try {
browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
page.on("pageerror", err => console.error("Page error:", err.message));
await page.goto(`http://127.0.0.1:${port}`);
await page.waitForFunction(
() => document.title.startsWith("READY") || document.title.startsWith("ERROR"),
{ timeout: 30000 }
);
const title = await page.title();
if (title.startsWith("ERROR")) {
console.error("Export failed:", title);
process.exit(1);
}
const dataUrl = await page.evaluate(() => window.__PNG_DATA__);
const base64 = dataUrl.replace(/^data:image\/png;base64,/, "");
writeFileSync(outputPath, Buffer.from(base64, "base64"));
console.log(outputPath);
} finally {
if (browser) await browser.close();
server.close();
rmSync(SERVE_DIR, { recursive: true, force: true });
}
});

37
plugins/compound-engineering/skills/excalidraw-png-export/scripts/setup.sh Executable file
View File

@@ -0,0 +1,37 @@
#!/bin/bash
# First-time setup for excalidraw-png-export skill.
# Installs playwright and chromium headless into a dedicated directory.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
EXPORT_DIR="$SCRIPT_DIR/.export-runtime"
if [ -d "$EXPORT_DIR/node_modules/playwright" ]; then
echo "Runtime already installed at $EXPORT_DIR"
exit 0
fi
echo "Installing excalidraw-png-export runtime..."
mkdir -p "$EXPORT_DIR"
cd "$EXPORT_DIR"
# Initialize package.json with ESM support
cat > package.json << 'PACKAGEEOF'
{
"name": "excalidraw-export-runtime",
"version": "1.0.0",
"type": "module",
"private": true
}
PACKAGEEOF
npm install playwright 2>&1
npx playwright install chromium 2>&1
# canvas provides accurate text measurement for convert.mjs.
# Requires Cairo native library: brew install pkg-config cairo pango libpng jpeg giflib librsvg
# Falls back to heuristic sizing if unavailable.
npm install canvas 2>&1 || echo "WARN: canvas install failed (missing Cairo?). Heuristic text sizing will be used."
echo "Setup complete. Runtime installed at $EXPORT_DIR"

173
plugins/compound-engineering/skills/excalidraw-png-export/scripts/validate.mjs Executable file
View File

@@ -0,0 +1,173 @@
#!/usr/bin/env node
/**
* Spatial validation for .excalidraw files.
* Checks text overflow, arrow-text collisions, and element overlap.
* Usage: node validate.mjs <input.excalidraw>
*/
import { readFileSync } from 'fs';
const MIN_PADDING = 15;
const inputFile = process.argv[2];
if (!inputFile) {
console.error('Usage: node validate.mjs <input.excalidraw>');
process.exit(1);
}
const data = JSON.parse(readFileSync(inputFile, 'utf8'));
const elements = data.elements || data;
// Build element map
const elMap = new Map();
for (const el of elements) {
if (el.isDeleted) continue;
elMap.set(el.id, el);
}
let warnings = 0;
let errors = 0;
const checked = elements.filter(el => !el.isDeleted).length;
// --- Check 1: Text overflow within containers ---
// Skip arrow-bound labels — arrows are lines, not spatial containers.
for (const el of elements) {
if (el.isDeleted || el.type !== 'text' || !el.containerId) continue;
const parent = elMap.get(el.containerId);
if (!parent || parent.type === 'arrow') continue;
const textRight = el.x + el.width;
const textBottom = el.y + el.height;
const parentRight = parent.x + parent.width;
const parentBottom = parent.y + parent.height;
const paddingLeft = el.x - parent.x;
const paddingRight = parentRight - textRight;
const paddingTop = el.y - parent.y;
const paddingBottom = parentBottom - textBottom;
const overflows = [];
if (paddingLeft < MIN_PADDING) overflows.push(`left=${paddingLeft.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingRight < MIN_PADDING) overflows.push(`right=${paddingRight.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingTop < MIN_PADDING) overflows.push(`top=${paddingTop.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (paddingBottom < MIN_PADDING) overflows.push(`bottom=${paddingBottom.toFixed(1)}px (need ${MIN_PADDING}px)`);
if (overflows.length > 0) {
const label = (el.text || '').replace(/\n/g, '\\n');
const truncated = label.length > 40 ? label.slice(0, 37) + '...' : label;
console.log(`WARN: text "${truncated}" (id=${el.id}) tight/overflow in container (id=${el.containerId})`);
console.log(` text_bbox=[${el.x.toFixed(0)},${el.y.toFixed(0)}]->[${textRight.toFixed(0)},${textBottom.toFixed(0)}]`);
console.log(` container_bbox=[${parent.x.toFixed(0)},${parent.y.toFixed(0)}]->[${parentRight.toFixed(0)},${parentBottom.toFixed(0)}]`);
console.log(` insufficient padding: ${overflows.join(', ')}`);
console.log();
warnings++;
}
}
// --- Check 2: Arrow-text collisions ---
/** Check if line segment (p1->p2) intersects axis-aligned rectangle. */
function segmentIntersectsRect(p1, p2, rect) {
// rect = {x, y, w, h} -> min/max
const rxMin = rect.x;
const rxMax = rect.x + rect.w;
const ryMin = rect.y;
const ryMax = rect.y + rect.h;
// Cohen-Sutherland-style clipping
let [x1, y1] = [p1[0], p1[1]];
let [x2, y2] = [p2[0], p2[1]];
function outcode(x, y) {
let code = 0;
if (x < rxMin) code |= 1;
else if (x > rxMax) code |= 2;
if (y < ryMin) code |= 4;
else if (y > ryMax) code |= 8;
return code;
}
let code1 = outcode(x1, y1);
let code2 = outcode(x2, y2);
for (let i = 0; i < 20; i++) {
if (!(code1 | code2)) return true; // both inside
if (code1 & code2) return false; // both outside same side
const codeOut = code1 || code2;
let x, y;
if (codeOut & 8) { y = ryMax; x = x1 + (x2 - x1) * (ryMax - y1) / (y2 - y1); }
else if (codeOut & 4) { y = ryMin; x = x1 + (x2 - x1) * (ryMin - y1) / (y2 - y1); }
else if (codeOut & 2) { x = rxMax; y = y1 + (y2 - y1) * (rxMax - x1) / (x2 - x1); }
else { x = rxMin; y = y1 + (y2 - y1) * (rxMin - x1) / (x2 - x1); }
if (codeOut === code1) { x1 = x; y1 = y; code1 = outcode(x1, y1); }
else { x2 = x; y2 = y; code2 = outcode(x2, y2); }
}
return false;
}
// Collect text bounding boxes (excluding arrow-bound labels for their own arrow)
const textBoxes = [];
for (const el of elements) {
if (el.isDeleted || el.type !== 'text') continue;
textBoxes.push({
id: el.id,
containerId: el.containerId,
text: (el.text || '').replace(/\n/g, '\\n'),
rect: { x: el.x, y: el.y, w: el.width, h: el.height },
});
}
for (const el of elements) {
if (el.isDeleted || el.type !== 'arrow') continue;
if (!el.points || el.points.length < 2) continue;
// Compute absolute points
const absPoints = el.points.map(p => [el.x + p[0], el.y + p[1]]);
for (const tb of textBoxes) {
// Skip this arrow's own label
if (tb.containerId === el.id) continue;
for (let i = 0; i < absPoints.length - 1; i++) {
if (segmentIntersectsRect(absPoints[i], absPoints[i + 1], tb.rect)) {
const truncated = tb.text.length > 30 ? tb.text.slice(0, 27) + '...' : tb.text;
const seg = `[${absPoints[i].map(n => n.toFixed(0)).join(',')}]->[${absPoints[i + 1].map(n => n.toFixed(0)).join(',')}]`;
console.log(`WARN: arrow (id=${el.id}) segment ${seg} crosses text "${truncated}" (id=${tb.id})`);
console.log(` text_bbox=[${tb.rect.x.toFixed(0)},${tb.rect.y.toFixed(0)}]->[${(tb.rect.x + tb.rect.w).toFixed(0)},${(tb.rect.y + tb.rect.h).toFixed(0)}]`);
console.log();
warnings++;
break; // one warning per arrow-text pair
}
}
}
}
// --- Check 3: Element overlap (non-child, same depth) ---
const topLevel = elements.filter(el =>
!el.isDeleted && !el.containerId && el.type !== 'text' && el.type !== 'arrow'
);
for (let i = 0; i < topLevel.length; i++) {
for (let j = i + 1; j < topLevel.length; j++) {
const a = topLevel[i];
const b = topLevel[j];
const aRight = a.x + a.width;
const aBottom = a.y + a.height;
const bRight = b.x + b.width;
const bBottom = b.y + b.height;
if (a.x < bRight && aRight > b.x && a.y < bBottom && aBottom > b.y) {
const overlapX = Math.min(aRight, bRight) - Math.max(a.x, b.x);
const overlapY = Math.min(aBottom, bBottom) - Math.max(a.y, b.y);
console.log(`WARN: overlap between (id=${a.id}) and (id=${b.id}): ${overlapX.toFixed(0)}x${overlapY.toFixed(0)}px`);
console.log();
warnings++;
}
}
}
// --- Summary ---
console.log(`OK: ${checked} elements checked, ${warnings} warning(s), ${errors} error(s)`);
process.exit(warnings > 0 ? 1 : 0);

221
plugins/compound-engineering/skills/fastapi-style/SKILL.md Normal file
View File

@@ -0,0 +1,221 @@
---
name: fastapi-style
description: This skill should be used when writing Python and FastAPI code following opinionated best practices. It applies when building APIs, creating Pydantic models, working with SQLAlchemy, or any FastAPI application. Triggers on FastAPI code generation, API design, refactoring requests, code review, or when discussing async Python patterns. Embodies thin routers, rich Pydantic models, dependency injection, async-first design, and the "explicit is better than implicit" philosophy.
---
<objective>
Apply opinionated FastAPI conventions to Python API code. This skill provides comprehensive domain expertise for building maintainable, performant FastAPI applications following established patterns from production codebases.
</objective>
<essential_principles>
## Core Philosophy
"Explicit is better than implicit. Simple is better than complex."
**The FastAPI Way:**
- Thin routers, rich Pydantic models with validation
- Dependency injection for everything
- Async-first with SQLAlchemy 2.0
- Type hints everywhere - let the tools help you
- Settings via pydantic-settings, not raw env vars
- Database-backed solutions where possible
**What to deliberately avoid:**
- Flask patterns (global request context)
- Django ORM in FastAPI (use SQLAlchemy 2.0)
- Synchronous database calls (use async)
- Manual JSON serialization (Pydantic handles it)
- Global state (use dependency injection)
- `*` imports (explicit imports only)
- Circular imports (proper module structure)
**Development Philosophy:**
- Type everything - mypy should pass
- Fail fast with descriptive errors
- Write-time validation over read-time checks
- Database constraints complement Pydantic validation
- Tests are documentation
</essential_principles>
<intake>
What are you working on?
1. **Routers** - Route organization, dependency injection, response models
2. **Models** - Pydantic schemas, SQLAlchemy models, validation patterns
3. **Database** - SQLAlchemy 2.0 async, Alembic migrations, transactions
4. **Testing** - pytest, httpx TestClient, fixtures, async testing
5. **Security** - OAuth2, JWT, permissions, CORS, rate limiting
6. **Background Tasks** - Celery, ARQ, or FastAPI BackgroundTasks
7. **Code Review** - Review code against FastAPI best practices
8. **General Guidance** - Philosophy and conventions
**Specify a number or describe your task.**
</intake>
<routing>
| Response | Reference to Read |
|----------|-------------------|
| 1, router, route, endpoint | [routers.md](./references/routers.md) |
| 2, model, pydantic, schema, sqlalchemy | [models.md](./references/models.md) |
| 3, database, db, alembic, migration, transaction | [database.md](./references/database.md) |
| 4, test, testing, pytest, fixture | [testing.md](./references/testing.md) |
| 5, security, auth, oauth, jwt, permission | [security.md](./references/security.md) |
| 6, background, task, celery, arq, queue | [background_tasks.md](./references/background_tasks.md) |
| 7, review | Read all references, then review code |
| 8, general task | Read relevant references based on context |
**After reading relevant references, apply patterns to the user's code.**
</routing>
<quick_reference>
## Project Structure
```
app/
├── main.py # FastAPI app creation, middleware
├── config.py # Settings via pydantic-settings
├── dependencies.py # Shared dependencies
├── database.py # Database session, engine
├── models/ # SQLAlchemy models
│ ├── __init__.py
│ ├── base.py # Base model class
│ └── user.py
├── schemas/ # Pydantic models
│ ├── __init__.py
│ └── user.py
├── routers/ # API routers
│ ├── __init__.py
│ └── users.py
├── services/ # Business logic (if needed)
├── utils/ # Shared utilities
└── tests/
├── conftest.py # Fixtures
└── test_users.py
```
## Naming Conventions
**Pydantic Schemas:**
- `UserCreate` - input for creation
- `UserUpdate` - input for updates (all fields Optional)
- `UserRead` - output representation
- `UserInDB` - internal with hashed password
**SQLAlchemy Models:** Singular nouns (`User`, `Item`, `Order`)
**Routers:** Plural resource names (`users.py`, `items.py`)
**Dependencies:** Verb phrases (`get_current_user`, `get_db_session`)
## Type Hints
```python
# Always type function signatures
async def get_user(
user_id: int,
db: AsyncSession = Depends(get_db),
) -> User:
...
# Use Annotated for dependency injection
from typing import Annotated
CurrentUser = Annotated[User, Depends(get_current_user)]
DBSession = Annotated[AsyncSession, Depends(get_db)]
```
## Response Patterns
```python
# Explicit response_model
@router.get("/users/{user_id}", response_model=UserRead)
async def get_user(user_id: int, db: DBSession) -> User:
...
# Status codes
@router.post("/users", status_code=status.HTTP_201_CREATED)
async def create_user(...) -> UserRead:
...
# Multiple response types
@router.get("/users/{user_id}", responses={404: {"model": ErrorResponse}})
```
## Error Handling
```python
from fastapi import HTTPException, status
# Specific exceptions
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found",
)
# Custom exception handlers
@app.exception_handler(ValidationError)
async def validation_exception_handler(request, exc):
return JSONResponse(status_code=422, content={"detail": exc.errors()})
```
## Dependency Injection
```python
# Simple dependency
async def get_db() -> AsyncGenerator[AsyncSession, None]:
async with async_session() as session:
yield session
# Parameterized dependency
def get_pagination(
skip: int = Query(0, ge=0),
limit: int = Query(100, ge=1, le=1000),
) -> dict:
return {"skip": skip, "limit": limit}
# Class-based dependency
class CommonQueryParams:
def __init__(self, q: str | None = None, skip: int = 0, limit: int = 100):
self.q = q
self.skip = skip
self.limit = limit
```
</quick_reference>
<reference_index>
## Domain Knowledge
All detailed patterns in `references/`:
| File | Topics |
|------|--------|
| [routers.md](./references/routers.md) | Route organization, dependency injection, response models, middleware, versioning |
| [models.md](./references/models.md) | Pydantic schemas, SQLAlchemy models, validation, serialization, mixins |
| [database.md](./references/database.md) | SQLAlchemy 2.0 async, Alembic migrations, transactions, connection pooling |
| [testing.md](./references/testing.md) | pytest, httpx TestClient, fixtures, async testing, mocking patterns |
| [security.md](./references/security.md) | OAuth2, JWT, permissions, CORS, rate limiting, secrets management |
| [background_tasks.md](./references/background_tasks.md) | FastAPI BackgroundTasks, Celery, ARQ, task patterns |
</reference_index>
<success_criteria>
Code follows FastAPI best practices when:
- Routers are thin, focused on HTTP concerns only
- Pydantic models handle all validation and serialization
- SQLAlchemy 2.0 async patterns used correctly
- Dependencies injected, not imported as globals
- Type hints on all function signatures
- Settings via pydantic-settings
- Tests use pytest with async support
- Error handling is explicit and informative
- Security follows OAuth2/JWT standards
- Background tasks use appropriate tool for the job
</success_criteria>
<credits>
Based on FastAPI best practices from the official documentation, real-world production patterns, and the Python community's collective wisdom.
**Key Resources:**
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [SQLAlchemy 2.0 Documentation](https://docs.sqlalchemy.org/)
- [Pydantic V2 Documentation](https://docs.pydantic.dev/)
</credits>

112
plugins/compound-engineering/skills/hugo-blog-publisher/SKILL.md Normal file
View File

@@ -0,0 +1,112 @@
---
name: hugo-blog-publisher
description: This skill should be used when publishing a new post to John's Hugo blog on lambwire. It handles both post types — "links" (reposting something interesting with a quote and commentary) and "blog" (original essays) — creates the correctly formatted markdown file, and commits and pushes it to the remote repository. Triggers on "publish to my blog", "add a link post", "post to lambwire", "new blog post", or any request to create content on the Hugo blog.
---
# Hugo Blog Publisher
Publish new content to John's Hugo blog at `lambwire` (`/home/john/mine/scripts/hugo`). Two post types are supported: `links` and `blog`. All posts are committed directly to `main` and pushed.
## Post Types
### links
A "link post" reposts something interesting — a pull-quote from an article, the source metadata, and John's brief commentary.
**Required fields:**
- `title` — John's own title for the post (not necessarily the article title)
- `external_url` — Full URL of the source article
- `source_name` — Publication name (e.g. "Every", "Strange Loop Canon")
- `source_title` — Full title of the source article
- `source_author` — Author(s) of the source article
- `source_published` — Date the source was published (`YYYY-MM-DD`)
- `tags` — Relevant tags as a list
- `quote` — The excerpt to pull-quote
- `quote_attribution` — Who said the quote (usually same as `source_author`)
- `commentary` — John's own thoughts (1–3 paragraphs of prose, placed after the frontmatter)
**Exact format:**
```markdown
---
title: "{{ title }}"
date: {{ YYYY-MM-DDTHH:MM:SS-06:00 }}
draft: false
type: link
external_url: "{{ external_url }}"
source_name: "{{ source_name }}"
source_title: "{{ source_title }}"
source_author: "{{ source_author }}"
source_published: {{ YYYY-MM-DD }}
link_type: article
tags: ["tag1", "tag2"]
quote: |
"{{ quote }}"
quote_attribution: "{{ quote_attribution }}"
---
{{ commentary }}
```
**Date:** Current datetime in Central time with offset `-06:00` (e.g. `2026-03-15T14:30:00-06:00`).
**Filename:** Slugify the title — lowercase, hyphens for spaces, strip punctuation. E.g. `is-ai-about-craft-not-speed.md`.
---
### blog
An original essay. Content is freeform markdown after the frontmatter.
**Required fields:**
- `title` — Post title
- `date` — Today's date (`YYYY-MM-DD`)
- `content` — The full essay body in markdown
**Exact format:**
```markdown
---
title: '{{ title }}'
date: {{ YYYY-MM-DD }}
draft: false
aliases:
- /blog/{{ slug }}/
---
{{ content }}
```
**Filename:** Slugify the title. E.g. `keeping-it-simple.md`.
---
## Workflow
**Step 1 — Gather inputs.** Ask for all required fields for the chosen post type before writing anything. Don't proceed until everything is provided.
**Step 2 — Generate slug.** Lowercase the title, replace spaces with hyphens, strip punctuation. This becomes both the filename (without `.md`) and the `/blog/slug/` alias for blog posts.
**Step 3 — Compose the markdown.** Build the full file content using the exact format above.
**Step 4 — Write the file to the remote.** Use an SSH heredoc to write the file directly:
```bash
ssh lambwire "cat > /home/john/mine/scripts/hugo/content/{{ links|blog }}/{{ slug }}.md" << 'EOF'
{{ file_content }}
EOF
```
**Step 5 — Commit and push on the remote.**
```bash
ssh lambwire "cd /home/john/mine/scripts/hugo && git add content/ && git commit -m 'Add {{ links|blog }}: {{ title }}' && git push origin main"
```
**Step 6 — Confirm.** Report the remote path, the commit message, and that the push succeeded.
## Notes
- Never set `draft: true` — all posts go live immediately.
- For `links` posts, the body after the frontmatter is John's commentary only — do not repeat the quote there.
- For `blog` posts, use single quotes around the title in frontmatter (not double quotes).
- If `source_published` is not known for a links post, omit the field entirely rather than guessing.
- Tags for `links` posts are lowercase strings in a JSON array: `["ai", "writing"]`.

79
plugins/compound-engineering/skills/jira-ticket-writer/SKILL.md Normal file
View File

@@ -0,0 +1,79 @@
---
name: jira-ticket-writer
description: This skill should be used when the user wants to create a Jira ticket. It guides drafting, pressure-testing for tone and AI-isms, and getting user approval before creating the ticket via the Atlassian MCP. Triggers on "create a ticket", "write a Jira ticket", "file a ticket", "make a Jira issue", or any request to create work items in Jira.
---
# Jira Ticket Writer
Write Jira tickets that sound like a human wrote them. Drafts go through tone review before the user sees them, and nothing gets created without explicit approval.
## Workflow
### Phase 1: Validate Scope
Before drafting anything, confirm two things:
1. **What the ticket is about.** Gather the ticket contents from the conversation or the user's description. If the scope is unclear or too broad for a single ticket, ask the user to clarify before proceeding.
2. **Where it goes.** Determine the Jira project key and optional parent (epic). If the user provides a Jira URL or issue key, extract the project from it. If not specified, ask.
To look up the Jira project and validate the epic exists, use the Atlassian MCP tools:
- `mcp__atlassian__getAccessibleAtlassianResources` to get the cloudId
- `mcp__atlassian__getJiraIssue` to verify the parent epic exists and get its project key
Do not proceed to drafting until both the content scope and destination are clear.
### Phase 2: Draft
Write the ticket body in markdown. Follow these guidelines:
- **Summary line:** Under 80 characters. Imperative mood. No Jira-speak ("As a user, I want...").
- **Body structure:** Use whatever sections make sense for the ticket. Common patterns:
- "What's happening" / "What we need" / "Context" / "Done when"
- "Problem" / "Ask" / "Context"
- Just a clear description with acceptance criteria at the end
- **Code snippets:** Include relevant config, commands, or file references when they help the reader understand the current state and desired state.
- **Keep it specific:** Include file paths, line numbers, env names, config values. Vague tickets get deprioritized.
- **"Done when" over "Acceptance Criteria":** Use casual language for completion criteria. 2-4 items max.
### Phase 3: Pressure Test
Before showing the draft to the user, self-review against the tone guide.
Read `references/tone-guide.md` and apply every check to the draft. Specifically:
1. **Patronizing scan:** Read each sentence imagining you are the recipient, a specialist in their domain. Flag and rewrite anything that explains their own expertise back to them, tells them how to implement something in their own system, or preemptively argues against approaches they haven't proposed.
2. **AI-ism removal:** Hunt for em-dash overuse, bullet-point-everything formatting, rigid generated-feeling structure, spec-writing voice, and filler words (Additionally, Furthermore, Moreover, facilitates, leverages, streamlines, ensures).
3. **Human voice pass:** Read the whole thing as if reading it aloud. Does it sound like something a developer would type? Add moments of humility where appropriate ("you'd know better", "if we're missing something", "happy to chat").
4. **Kindness pass:** The reader is a human doing their job. Frame requests as requests. Acknowledge their expertise. Don't be demanding.
Revise the draft based on this review. Do not show the user the pre-review version.
### Phase 4: User Approval
Present the final draft to the user in chat. Include:
- The proposed **summary** (ticket title)
- The proposed **body** (formatted as it will appear)
- The **destination** (project key, parent epic if any, issue type)
Ask for sign-off using AskUserQuestion with three options:
- **Create it** — proceed to Phase 5
- **Changes needed** — user provides feedback, return to Phase 2 with their notes and loop until approved
- **Cancel** — stop without creating anything
### Phase 5: Create
Once approved, create the ticket:
1. Use `mcp__atlassian__getAccessibleAtlassianResources` to get the cloudId (if not already cached from Phase 1)
2. Use `mcp__atlassian__createJiraIssue` with:
- `cloudId`: from step 1
- `projectKey`: from Phase 1
- `issueTypeName`: "Task" unless the user specified otherwise
- `summary`: the approved title
- `description`: the approved body
- `parent`: the epic key if one was specified
3. Return the created ticket URL to the user: `https://discoverorg.atlassian.net/browse/<KEY>`

34
plugins/compound-engineering/skills/jira-ticket-writer/references/api_reference.md Normal file
View File

@@ -0,0 +1,34 @@
# Reference Documentation for Jira Ticket Writer
This is a placeholder for detailed reference documentation.
Replace with actual reference content or delete if not needed.
Example real reference docs from other skills:
- product-management/references/communication.md - Comprehensive guide for status updates
- product-management/references/context_building.md - Deep-dive on gathering context
- bigquery/references/ - API references and query examples
## When Reference Docs Are Useful
Reference docs are ideal for:
- Comprehensive API documentation
- Detailed workflow guides
- Complex multi-step processes
- Information too lengthy for main SKILL.md
- Content that's only needed for specific use cases
## Structure Suggestions
### API Reference Example
- Overview
- Authentication
- Endpoints with examples
- Error codes
- Rate limits
### Workflow Guide Example
- Prerequisites
- Step-by-step instructions
- Common patterns
- Troubleshooting
- Best practices

53
plugins/compound-engineering/skills/jira-ticket-writer/references/tone-guide.md Normal file
View File

@@ -0,0 +1,53 @@
# Tone Guide for Ticket Writing
## Core Principle
A human will read this ticket. Write like a teammate asking for help, not an AI generating a spec.
## Pressure Test Checklist
Review every sentence against these questions:
### 1. Patronizing language
- Does any sentence explain the reader's own domain back to them?
- Would you say this to a senior engineer's face without feeling awkward?
- Are you telling them HOW to implement something in their own system?
- Are you preemptively arguing against approaches they haven't proposed?
**Examples of patronizing language:**
- "This is a common pattern in Kubernetes deployments" (they know)
- "Helm charts support templating via {{ .Values }}" (they wrote the chart)
- "Why X, not Y" sections that dismiss alternatives before anyone suggested them
### 2. AI-isms to remove
- Em dashes used more than once per paragraph
- Every thought is a bullet point instead of a sentence
- Rigid structure that feels generated (Ask -> Why -> Context -> AC)
- Spec-writing voice: "When absent or false, existing behavior is preserved"
- Overuse of "ensures", "leverages", "facilitates", "streamlines"
- Unnecessary hedging: "It should be noted that..."
- Filler transitions: "Additionally", "Furthermore", "Moreover"
- Lists where prose would be more natural
### 3. Human voice check
- Does it sound like something you'd type in Slack, cleaned up slightly?
- Are there moments of humility? ("you'd know better than us", "if we're missing something")
- Is the tone collaborative rather than directive?
- Would you feel comfortable putting your name on this?
### 4. Kindness check
- Frame requests as requests, not demands
- Acknowledge the reader's expertise
- Offer context without over-explaining
- "Happy to chat more" > "Please advise"
## What to keep
- Technical detail and specifics (the reader needs these)
- Code snippets showing current state and desired state
- File references with line numbers
- Clear "done when" criteria (but keep them minimal)

27
plugins/compound-engineering/skills/john-voice/SKILL.md Normal file
View File

@@ -0,0 +1,27 @@
---
name: john-voice
description: "This skill should be used whenever writing content that should sound like John Lamb wrote it. It applies to all written output including Slack messages, emails, Jira tickets, technical docs, prose, blog posts, cover letters, and any other communication. This skill provides John's authentic writing voice, tone, and style patterns organized by venue and audience. Other skills should invoke this skill when producing written content on John's behalf. Triggers on any content generation, drafting, or editing task where the output represents John's voice."
allowed-tools: Read
---
# John's Writing Voice
This skill captures John Lamb's authentic writing voice for use across all written content. It is a reference skill designed to be called by other skills or used directly whenever producing text that should sound like John wrote it.
## How to Use This Skill
1. Determine the venue and audience for the content being produced
2. Load `references/core-voice.md` — this always applies regardless of context
3. Load the appropriate venue-specific tone guide from `references/`:
- **Prose, essays, blog posts** → `references/prose-essays.md`
- **Slack messages, quick emails, casual comms** → `references/casual-messages.md`
- **Technical docs, Jira tickets, PRs, code reviews** → `references/professional-technical.md`
- **Cover letters, LinkedIn, formal professional** → `references/formal-professional.md`
- **Personal reflection, journal, notes** → `references/personal-reflection.md`
4. For prose and essays, also load `references/signature-moves.md` — these are the techniques that make the writing move
5. Apply both the core voice and the venue-specific guide when drafting content
6. Before finishing, run `references/revision-checklist.md` — if any item flags, rewrite before delivering
## Key Principle
John prizes simplicity and clarity above all else. He writes to convey meaning, not to sound smart. If the output uses words John wouldn't say aloud to a friend, it's wrong. If it obscures meaning behind fancy language, it's wrong. If it sounds like a corporate press release or a ChatGPT default (NO emdashes!), it's catastrophically wrong.

69
plugins/compound-engineering/skills/john-voice/references/casual-messages.md Normal file
View File

@@ -0,0 +1,69 @@
# Casual Messages Tone Guide
Use this guide for Slack messages, quick emails, texts, Discord, and other informal communications.
## General Tone
John's casual writing is his natural voice with the polish stripped off. Lowercase is fine. Fragments are fine. He thinks out loud and lets the reader follow along.
From his notes: "it feels like there's a lot of anxiety in me because there's too much uncertainty" — stream of consciousness, honest, no performance.
## Sentence Patterns
- Short fragments: "turns out, not really."
- Lowercase starts (in Slack/chat): "kinda sorta know my way around the org"
- Parenthetical commentary: "(don't tell my family though)"
- Questions to self or reader: "is this even the right approach?"
- Trailing thoughts: "but I'm not totally sure about that yet"
## Vocabulary in Casual Mode
John's casual register drops even further toward spoken language:
- "kinda", "gonna", "wanna" (occasionally)
- "TBH", "FYI" (in work Slack)
- "the thing is..." as a thought starter
- "I think..." / "I wonder if..." for tentative ideas
- "honestly" / "to be honest" as a signal he's about to be direct
## Email Patterns
**Short emails (most of them):**
John gets to the point fast. He doesn't pad emails with pleasantries beyond a brief greeting. He tends toward 2-4 sentences for most emails.
Structure:
1. One line of context or greeting
2. The ask or the information
3. Maybe a follow-up detail
4. Sign-off
**Never do:**
- "I hope this email finds you well"
- "Per my last email"
- "Please don't hesitate to reach out"
- "Best regards" (too stiff — "thanks" or "cheers" or just his name)
## Slack Patterns
John's Slack messages are conversational and direct. He:
- Skips greetings in channels (just says the thing)
- Uses threads appropriately
- Drops casual asides and humor
- Asks questions directly without preamble
- Uses emoji reactions more than emoji in text
Example Slack style:
"hey, quick question — are we using the existing search API or building a new one for this? I was looking at the federated search setup and I think we might be able to reuse most of it"
Not:
"Hi team! I wanted to reach out regarding the search API implementation. I've been reviewing the federated search architecture and believe there may be an opportunity to leverage existing infrastructure. Thoughts?"
## Feedback and Opinions
When giving opinions in casual contexts, John is direct but not blunt. He leads with his honest take and explains why.
Pattern: "[honest assessment] + [reasoning]"
- "I think we're overthinking this. The simpler version would cover 90% of the cases."
- "that approach makes me a bit nervous because [reason]"
- "I like the direction but [specific concern]"
He doesn't soften feedback with excessive qualifiers or sandwich it between compliments.

154
plugins/compound-engineering/skills/john-voice/references/core-voice.md Normal file
View File

@@ -0,0 +1,154 @@
# John Lamb — Core Voice
These patterns apply to ALL writing regardless of venue or audience. They are the non-negotiable foundation of John's voice.
## Voice in One Line
Plainspoken but precise. Funny but never jokey. Direct but warm. Curious but not credulous. Committed but not preachy.
## Philosophy
John writes to be understood, not to impress. He believes complexity in writing is a failure of the writer, not a sign of intelligence. He actively resists language that props up ego or obscures meaning. He'd rather sound like a person talking at a dinner table than a thought leader publishing a manifesto.
From his own notes: "Good communication does not correlate with intelligence and effective communication doesn't need to be complex. Seek clear, effective communication so you don't convince yourself or others of untrue things."
**Strong opinions, loosely held.** John commits to his views rather than hedging. He doesn't perform balance by spending equal time on the other side. He states his position clearly and trusts the reader to push back if they disagree. The conclusion is real and strong — it's just not presented as the final word on the universe.
**Peer-to-peer, not expert-to-novice.** John writes as a fellow traveler sharing what he figured out, not as a master instructing students. The posture is: "I worked this out, maybe it's useful to you." He never claims authority he doesn't have.
**Say something real.** This is the principle that separates John's writing from most professional and AI-generated writing. Every claim, every observation, every phrase must have something concrete underneath it. If you drill into a sentence and there's nothing there — just the sensation of insight without the substance — it's wrong.
The tell is vagueness. Abstract nouns doing the work of real ideas ("value," "alignment," "conviction," "transformation") are fog machines. They create the feeling of saying something without the risk of saying anything specific enough to be wrong. John takes that risk. He says what he actually means, in plain language, and accepts that a skeptical reader might disagree with him.
This doesn't mean every sentence is a logical argument. A specific observation, a concrete image, a well-chosen detail — these are bulletproof without being argumentative. The test is: if someone asked "what do you mean by that, exactly?" could you answer without retreating to abstraction? If yes, the sentence earns its place.
## Sentence Structure
**Mix short and long.** John's rhythm comes from alternating between longer explanatory sentences and abrupt short ones that land like punctuation marks.
Patterns he uses constantly:
- A longer sentence setting up context → a short punchy follow-up
- "Not quite."
- "This is a problem."
- "Let me explain."
- "That's not the conclusion."
- "Obviously not."
Example from his writing: "After vicariously touring catacombs, abandoned mines, and spaces so confined they make even the reader squirm. In the final chapter you visit a tomb for radioactive waste, the spent fuel cells of nuclear reactors. It feels like the final nail in the coffin, everything down here is also gloomy." → Then later: "But that's not the conclusion."
**Avoid compound-complex sentences.** John rarely chains multiple clauses with semicolons. When a sentence gets long, it's because he's painting a scene, not because he's nesting logic.
**Never use em-dashes. This is a hard rule.**
Em-dashes (—) are the single most reliable tell that a piece of writing was produced by AI, not by John. He almost never uses them. A piece that contains em-dashes does not sound like John wrote it.
John does use asides frequently — but he uses **parentheses**, not em-dashes. Parenthetical asides are a signature move of his voice (they reward close readers and often carry his best jokes). When you are tempted to use an em-dash, use parentheses instead. If the aside doesn't warrant parentheses, break the sentence in two.
The em-dash is not a stylistic flourish. It is an alarm bell. If it appears in output, rewrite before finishing.
## Vocabulary
**Use everyday words.** John uses the vocabulary of someone talking, not writing an academic paper.
Words John actually uses: "heck of a lot", "kinda", "I dunno", "plug-and-play", "insufferable", "awesome", "cool", "crazy", "nuts", "the real thing", "turns out", "chances are", "let's be honest"
Words John would never use: "leverage" (as a verb outside of technical contexts), "synergy", "utilize", "facilitate", "aforementioned" (in casual writing), "plethora", "myriad" (as adjective), "delve", "tapestry", "multifaceted", "nuanced" (as filler), "paradigm", "robust" (outside of engineering)
**Technical terms get explained.** When John introduces a term like "NPCs" or "conversation tree" or "thermal efficiency", he immediately explains it in plain language. He assumes the reader is smart but unfamiliar.
## Rhetorical Questions
John leans heavily on rhetorical questions. They're his primary tool for advancing arguments and creating reader engagement.
Examples: "Does owning an EV keep you from embarking on long road trips?" / "What is a good tool but one that accomplishes its mission and makes us feel good while using it?" / "What makes a city beautiful?" / "Could I have done that if I had pulled straight into a parking spot?"
Use rhetorical questions to transition between ideas, not as filler.
## Analogies from the Mundane
John's signature move is taking something completely ordinary — parking lots, road trips, video games, cooking dinner — and extracting a surprising insight from it. He doesn't reach for grand metaphors. The analogy is always grounded in lived experience.
Example: He turns "backing into a parking spot" into a lesson about positioning and preparing your future self for success.
## Humor — The Defining Feature
This is the most important section. John's best writing is **kinetic, witty, and tongue-in-cheek**. When he's in full voice, the writing moves like water — each sentence pulls toward the next, the ideas spill out fully formed, and there's a joyful lightness to it. It doesn't take itself too seriously.
The humor is not a garnish. It is the texture of the voice itself. It shows up as:
- **Implied sarcasm** — the wit is in what's left unsaid or understated, never telegraphed
- **Deadpan absurdity** — stating something ridiculous as though it's obvious: "If, for instance, the eyes were placed in the back of their heads, they would be experts at driving in reverse"
- **Self-deprecating asides**: "I dunno if I'm any good as a cook but I'm still friends with all of my guests so the recipes must be doing the heavy lifting"
- **Parenthetical commentary that rewards attention**: "(dodged the extraterrestrial lifeforms)", "(I always tell guests to remove their shoes when they enter, otherwise, the sock-removing finale doesn't have the same effect)"
- **Whimsical understatement**: "I'm always wary of those adrenaline junkies who try to set land speed records in parking lots"
**Never use puns. Never use setup/punchline jokes.** The humor is woven into the motion of the prose, not bolted on. If a sentence could be lifted out and labeled "the joke," it's wrong. The wit should only land when the reader is already moving forward.
## Warmth as Deliberate Compensation
John is naturally direct and, by his own admission, somewhat prickly. He compensates deliberately in writing by adding warmth — not as performance, but as a counterbalance to his default edge. This means:
- Softening critical language consciously
- Approaching disagreement from a position of shared purpose, not opposition
- The tone should feel like someone who is honest with you because they're on your side, not because they want to win
This warmth is a choice, not a personality trait. It should be present but not saccharine. If the writing feels warm in the way a corporate "we value your feedback" email is warm, that's wrong. It should feel warm the way a direct friend is warm.
## The Compositional Voice
The single hardest thing to replicate about John's voice is **how his ideas connect**, not how his sentences are constructed. AI writing that sounds like John sentence-by-sentence but not paragraph-by-paragraph has failed.
What makes the connections work:
- Each sentence creates a small forward pull toward the next — the reader is always in mild anticipation
- Ideas build on each other rather than sitting side by side
- Transitions feel inevitable, not inserted
- The argument follows his curiosity, not a pre-planned structure
When writing in John's voice, do not assemble a collection of John-sounding sentences. Follow the thread of the thought. If you can't feel the momentum building as you write, the voice isn't there yet.
## Honesty and Disclaimers
John is transparent about his biases and limitations. He frequently declares them upfront.
Examples: "Let me disclose my bias upfront, I'm a car enthusiast." / "Full disclaimer, this recipe killed my Vitamix (until I resurrected it). It was certainly my fault." / "I'll be honest, it's totally unnecessary here."
## First Person, Active Voice
John writes in first person almost exclusively. He uses "I" freely and without apology. Passive voice is rare and only appears when he's describing historical events.
He addresses the reader directly: "You'd be forgiven for thinking...", "You can see if there are any other cars near the spot", "Don't overthink it!"
## Diagrams Over Walls of Text
John believes a good diagram communicates faster and more clearly than paragraphs of explanation. When a concept involves relationships between components, flows, or architecture, default to including a diagram. A three-box flowchart with labeled arrows will land in seconds where three paragraphs of prose might lose the reader.
When the `excalidraw-png-export` skill is available, use it to generate hand-drawn style diagrams and export them as PNG files. This applies to technical explanations, architecture overviews, process flows, and anywhere a visual would reduce the reader's cognitive load. If the output is going somewhere that supports images (docs, PRs, Slack threads, emails), a diagram should be the first instinct, not an afterthought.
## Structure
John's writing follows a consistent arc:
1. **Hook** — A concrete story, observation, or scenario (never an abstract thesis)
2. **Context** — Background the reader needs, delivered conversationally
3. **Core argument** — The insight, always grounded in the concrete example
4. **Evidence/exploration** — More examples, data, or personal experience (diagrams where visual clarity helps)
5. **Gentle landing** — A question, invitation, or understated conclusion (never a lecture)
He almost never ends with a declarative thesis statement. He prefers to leave the reader with a question or a quiet observation.
## What to Avoid — The Anti-John
The following patterns are the opposite of John's voice. If any of these appear in the output, rewrite immediately:
- **Corporate speak**: "In order to drive alignment across stakeholders..."
- **AI-default prose**: "In today's rapidly evolving landscape...", "Let's dive in!", "Here's the thing..."
- **Filler intensifiers**: "incredibly", "absolutely", "extremely" (unless used for genuine emphasis)
- **Throat-clearing**: "It's worth noting that...", "It goes without saying...", "Needless to say..."
- **Performative intelligence**: Using complex vocabulary where simple words work
- **Lecturing tone**: Telling the reader what to think rather than showing them and letting them arrive there
- **Emoji overuse**: John uses emoji sparingly and only in very casual contexts
- **Em-dashes**: Never. This is the #1 AI writing tell. Use parentheses for asides. Use a period to end the sentence. Never use —.
- **Exclamation points**: Rare. One per piece maximum in prose. More acceptable in Slack.
- **Buzzwords**: "game-changer", "cutting-edge", "innovative" (without substance), "holistic"
- **Vague claims masquerading as insight**: Sentences that sound like they mean something but dissolve under examination. "There's a real tension here between X and Y." "This gets at something fundamental about how we work." "The implications are significant." None of these say anything. Replace them with what the tension actually is, what the fundamental thing actually is, what the implications actually are.
- **Abstract nouns as load-bearing walls**: "value," "conviction," "alignment," "impact," "transformation" — when these words are doing the primary work of a sentence, the sentence is hollow. John uses them only when they follow a concrete explanation, never as a substitute for one.
- **Hedged non-claims**: "In some ways, this raises interesting questions about..." is not a sentence. It is a placeholder for a sentence. Write the sentence.

65
plugins/compound-engineering/skills/john-voice/references/formal-professional.md Normal file
View File

@@ -0,0 +1,65 @@
# Formal Professional Tone Guide
Use this guide for cover letters, LinkedIn posts, job descriptions, professional bios, formal proposals, and externally-facing professional content.
## General Tone
This is John's most polished register but it still sounds like him. The key difference from casual writing is more complete sentences, less slang, and more deliberate structure. He never becomes stiff or corporate. The warmth and directness remain.
## Cover Letters
John's cover letter voice is confident without being boastful. He leads with what he's done (concrete results) rather than listing qualities about himself.
**Structure he follows:**
1. Why this role/company interests him (specific, not generic)
2. What he's done that's relevant (with numbers and outcomes)
3. What he brings to the table
4. Brief, warm close
**Patterns from his actual writing:**
- Leads with concrete accomplishments: "As the tech lead, I built Indeed's first candidate quality screening automation product from 0 to 1"
- Quantifies impact: "increased downstream positive interview outcomes by 52%", "boosted interview completion rate by 72% in three months"
- Frames work in terms of people served: "hundreds of enterprise clients and hundreds of thousands of job seekers per year"
- Describes roles in plain terms: "Small teams took new product ideas and built an MVP seeking product-market fit"
**What to avoid:**
- "I am a highly motivated self-starter with a passion for..."
- "I believe my unique combination of skills makes me an ideal candidate..."
- Listing soft skills without evidence
- Generic enthusiasm: "I would be thrilled to join your team!"
**Better closings:** Direct and human, not gushing. Something like "I'd enjoy talking more about this" rather than "I would be honored to discuss this opportunity further at your earliest convenience."
## LinkedIn Posts
John's LinkedIn voice is more restrained than his essay voice but still personal. He uses first person, shares real experiences, and avoids the performative vulnerability that plagues the platform.
**Do:**
- Share genuine observations from work or career
- Use the same concrete-to-abstract pattern from his essays
- Keep it shorter than an essay (3-5 short paragraphs)
- End with a real question or observation, not engagement bait
**Don't:**
- Start with "I'm humbled to announce..."
- Use line breaks after every sentence for dramatic effect
- End with "Agree?" or "What do you think? Comment below!"
- Write in the LinkedIn-bro style of manufactured vulnerability
## Professional Bios
John describes himself in functional terms, not aspirational ones.
His style: "I'm a full stack engineer with over 8 years of experience, primarily in the innovation space. I've worked on bringing products from zero to one as well as scaling them once they've proven successful."
Not: "John is a visionary technology leader passionate about building the future of [industry]. With a proven track record of driving innovation..."
Keep bios in first person when possible. Third person only when the format demands it, and even then, keep it factual and plain.
## Elevator Pitch Style
John's elevator pitch is structured as: what he does → what he's accomplished → what he's looking for. No fluff.
Example from his notes: "I'm looking for another full stack engineer position with an opportunity to have influence over the product, preferably with a smaller company. I'm a leader and have demonstrated skills in a variety of areas so I'm looking for a position that will let me engage those skills."
Direct. No posturing. Honest about what he wants.

63
plugins/compound-engineering/skills/john-voice/references/personal-reflection.md Normal file
View File

@@ -0,0 +1,63 @@
# Personal Reflection Tone Guide
Use this guide for journal entries, personal notes, sermon discussion questions, spiritual reflection, internal brainstorming, and private writing not intended for external audiences.
## General Tone
This is John at his most raw and unguarded. Capitalization is optional. Grammar is loose. He thinks on paper through questions directed at himself. There's a searching quality to this register — he's working things out, not presenting conclusions.
## Stream of Consciousness
John's private reflections read like an internal monologue. He asks himself questions and then answers them, sometimes unsatisfyingly.
From his actual notes:
- "do I have a strong need to be great? does a correct understanding of my identity require it? no. it does not."
- "is the door to product manager open? yes. why do I not commit? because I fear failure."
- "what is restful to me?"
- "are sports restful or a distraction from what needs to be done?"
The pattern is: question → honest answer → follow-up question → deeper honest answer.
## Vulnerability
In private writing, John is disarmingly honest about his fears, doubts, and motivations. He doesn't perform vulnerability — he simply states what's true.
Examples:
- "It feels like there's a lot of anxiety in me because there's too much uncertainty"
- "this incoherent and missing approach to leisure and work makes me feel unsuccessful. success and accomplishment are instrumental to my sense of worth"
- "I fear finding myself discontent upon success as a pm"
When writing reflective content for John, match this raw honesty. Don't clean it up or make it sound wise. It should sound like someone thinking, not someone writing.
## Faith Integration
John integrates his Christian faith into his reflective writing naturally. It's not performative or preachy — it's part of how he processes life.
Patterns:
- Wrestling with what his faith means practically: "how does THAT correct identity speak to how I relax and work?"
- Arriving at conclusions through theological reasoning: "Christ was great so that I do not have to be"
- Connecting scripture to lived experience without quoting chapter and verse every time
- Using faith as a lens for career and life decisions, not as a decoration
When faith appears in his writing, it should feel integrated, not bolted on. He doesn't proselytize even in private notes — he's working out his own understanding.
## Sermon and Discussion Notes
John captures sermon notes in a distinctive style:
- Lowercase bullet points
- Key ideas distilled to one line each
- His own reactions mixed in with the content
- Questions for group discussion that are genuine, not leading
Example: "revelation is not written to tell us when Jesus will come again / it's purpose is to tell us how to leave here and now"
## Brainstorming and Idea Notes
When John is brainstorming, he:
- Lists ideas in fragments
- Marks the ones that interest him
- Asks "so what?" and "why does this matter?"
- Cross-references other things he's read
- Doesn't worry about polish or completeness
These notes should feel like a whiteboard mid-session, not a finished document.

90
plugins/compound-engineering/skills/john-voice/references/professional-technical.md Normal file
View File

@@ -0,0 +1,90 @@
# Professional-Technical Tone Guide
Use this guide for Jira tickets, technical documents, PR descriptions, code reviews, architecture docs, onboarding docs, and work-related technical writing.
## General Tone
John's professional-technical voice is his casual voice with more structure. He doesn't become a different person at work. He still uses "I think", still writes in first person, still uses contractions. The main shift is toward brevity and action-orientation.
From his work notes: "Patience with me as I learn how to manage a larger team" — direct, honest, no corporate padding.
**The soul test.** Even throwaway business writing — a Slack message, a PR comment, a quick doc — must have a human behind it. Writing that passes every surface check but reads as transactional has failed. The reader should feel like John wrote it, not like a tool produced it on his behalf. If it screams AI-written, it's wrong.
## Jira Tickets and Task Descriptions
**Be concrete and brief.** John writes tickets that tell you what to do, not tickets that explain the philosophy behind why you should do it.
Structure:
1. What needs to happen (1-2 sentences)
2. Context if needed (why this matters, what prompted it)
3. Acceptance criteria or key details as bullets
Example (in John's voice):
"The search API returns stale results when the index hasn't been refreshed. Add a cache invalidation step after writes. This is blocking recruiter Justin's use case."
Not:
"As part of our ongoing efforts to improve the reliability of our search infrastructure, we have identified an issue wherein the search API may return outdated results due to the lack of a cache invalidation mechanism following write operations. This ticket proposes the implementation of..."
## Technical Documentation
John explains technical concepts the same way he explains anything — start concrete, then zoom out.
Patterns:
- Explain what a system does before explaining how it works
- Use real examples ("when a recruiter searches for a candidate...")
- Name specific services, endpoints, and files rather than speaking abstractly
- Keep sentences short in technical docs — one idea per sentence
**Architecture docs:** John prefers bullet lists and short paragraphs over walls of text. He includes diagrams when they help and skips them when they don't.
**Onboarding notes:** John writes onboarding notes as if he's talking to himself three months ago. Practical, specific, no fluff.
From his 1:1 notes: "One on Ones are your time. They can be an hour long every week or 30m every other week. It's up to you." — direct, human, respects the reader's autonomy.
## PR Descriptions
Brief and functional. What changed, why, and any context a reviewer needs.
Structure:
1. One-line summary of the change
2. Why (if not obvious)
3. Notable decisions or tradeoffs
4. How to test (if relevant)
John doesn't pad PR descriptions with boilerplate sections that don't apply.
## Code Reviews
John gives code review feedback that is direct and specific. He explains the "why" when the suggestion isn't obvious.
**The underlying assumption is always collaborative.** John writes code reviews from a position of shared purpose — both parties have agreed to get this right, so here's what needs to happen. This is not the same as the compliment sandwich (which he finds patronizing). It's a posture, not a structure. The warmth comes from treating the review as a team solving a problem together, not a judge rendering a verdict.
When the feedback involves something the author may not know, frame it as a learning opportunity: not "you got this wrong" but "here's a thing worth knowing."
Pattern: "[what to change] because [why]"
- "This could be a constant — it's used in three places and the string is easy to typo"
- "I'd pull this into its own function. Right now it's hard to tell where the validation ends and the business logic starts"
He doesn't:
- Use "nit:" for everything (only actual nits)
- Write paragraph-length review comments for simple suggestions
- Hedge excessively: "I was just wondering if maybe we could possibly consider..."
- Lead with what's working before getting to the feedback (feels patronizing)
## Meeting Notes
John captures the decisions and action items, not a transcript. His meeting notes are bullet-pointed and terse.
Pattern:
- Key decisions (what was decided)
- Action items (who does what)
- Open questions (what's still unresolved)
- Context only when someone reading later would be lost without it
## Planning and Strategy Documents
When writing planning docs, John thinks out loud on paper. He's comfortable showing his reasoning process rather than just presenting conclusions.
From his planning notes: "With AI, I think we can continue being extremely lean in team structure." / "Do we need to hire? In some ways no. We already have existing resources working on Data and Integrations."
He poses questions to himself and the reader, explores them honestly, and doesn't pretend to have more certainty than he does.

98
plugins/compound-engineering/skills/john-voice/references/prose-essays.md Normal file
View File

@@ -0,0 +1,98 @@
# Prose & Essays Tone Guide
Use this guide for blog posts, essays, newsletters, long-form writing, and any polished creative prose.
## Opening
Always open with a concrete scene, story, or observation. Never open with an abstract thesis or a definition.
**John does this:**
- "Like the barbecue Texas is so well known for, it feels like I'm being slow-roasted whenever I step outside."
- "When I was a teenager, I attended take your kid to work day with a friend of my parents."
- "When I imagined life in my 20s, this is what I always imagined hanging out with friends would look like."
- "Imagine this. You're in a parking lot searching for a space."
- "A group of aerospace engineering professors are ushered onto a plane."
**John never does this:**
- "In today's world of electric vehicles, the question of range anxiety remains paramount."
- "The relationship between technology and nature has long been debated."
The opening should make the reader curious. It should feel like the beginning of a story someone tells at a bar, not the introduction of an academic paper.
## Building the Argument
John uses a "zoom out" pattern. He starts zoomed in on a specific moment or detail, then gradually pulls back to reveal the larger insight.
Example from the Navy Yard essay: Starts with a personal memory of visiting DC as a teenager → zooms out to the transformation of Navy Yard → zooms further to the Height of Buildings Act → arrives at the question of what makes cities desirable.
**Transition devices John uses:**
- Rhetorical questions: "Does it have to be this way?"
- Short declarative pivots: "Not quite." / "There is a simple solution." / "Consider this alternative."
- Direct address: "Let me explain."
- Callbacks to the opening story: returning to the concrete example after exploring the abstract
**Transition devices John avoids:**
- "Furthermore", "Moreover", "Additionally"
- "Having established X, we can now turn to Y"
- "This brings us to our next point"
## Paragraph Length
John varies paragraph length. Most paragraphs are 2-5 sentences. He occasionally drops a single-sentence paragraph for emphasis. He never writes wall-of-text paragraphs exceeding 8 sentences.
## Writing as Thinking
John writes to complete thoughts, not to present conclusions he already had. The essay is where the idea becomes fully formed — it arrives at a real, strong conclusion, but the journey to that conclusion follows his genuine curiosity rather than a pre-planned argument. The reader should feel like they're thinking alongside him, not being walked through a proof.
This means:
- The conclusion is earned by following the thread, not announced at the top
- The argument can shift slightly as it builds — that's not weakness, that's honest thinking
- The conclusion is strong and committed, not hedged into mush — but it's offered as where the thinking landed, not as the final word
## Tone Calibration
John's prose tone sits at about 60% conversational, 40% deliberate. He's more careful than a text message but less formal than a newspaper editorial. He writes like someone who revised their dinner party story a few times to make it land better.
He uses contractions freely: "it's", "don't", "can't", "I'm", "they're". Avoiding contractions would sound stiff and unlike him.
**The kinetic quality.** John's best prose moves. Each sentence creates a small pull toward the next. When it's working, the writing feels light and fast — tongue-in-cheek, a little playful, not labored. If the prose feels like it's trudging from one point to the next, it's not his voice. Aim for momentum.
## Humor in Prose
Humor appears as texture, never as the point. It's woven into observations and parentheticals.
Examples of his humor style in essays:
- "Running out of juice in Texas may mean Wile E Coyote is the closest help."
- "Sitting in the parking garage wasn't as much fun as sitting at the concert."
- "It's like the parking lot designers were only told they had to get the cars into the parking lot and were never told they would need to get them out of it."
- "It takes eight hours just to leave Texas watching ranches and wind turbines go by."
## Closing
John lands gently. His conclusions tend to:
- Ask a question: "Where else might we choose to do the hard work now so we're better positioned for the future?"
- Offer a quiet invitation: "Now go cook some excellent food and make some friends doing it because it's too good to keep to yourself."
- Circle back to the personal: "It's hoping we can find the cause of the toxic algae bloom in Lady Bird Lake, find a non-destructive solution, and feeling safe taking Bear to her favorite place again."
He never:
- Restates the thesis in summary form
- Uses "In conclusion" or "To sum up"
- Ends with a grand declaration or call to arms
## Audience
John writes for an adequately educated generalist — someone with common sense, a curious mind, and no specialized background required. The reference point is a show like Derek Thompson's Plain English: smart, accessible, treats the reader as a thinking adult.
The posture is peer-to-peer. John is a fellow traveler sharing what he figured out, not an expert teaching a course. "I worked this out and wrote it down. Maybe it's the next building block for someone else turning over the same ideas."
## Subject Matter
John gravitates toward essays that take a mundane observation and extract an unexpected insight. His favorite subjects: cars and driving, food and cooking, travel, technology's relationship with humanity, video games as learning tools, urban design, nature and environment. When writing on his behalf, lean into these interests and this pattern of mundane-to-meaningful.
## Quoting and References
John cites sources conversationally. He names books, authors, and people naturally rather than using footnotes or formal citations.
Example: "While reading Entangled Life, a book all about fungi, I recently learned about the 'wood wide web'."
Not: "According to Sheldrake (2020), fungal networks form a 'wood wide web' beneath forest floors."

19
plugins/compound-engineering/skills/john-voice/references/revision-checklist.md Normal file
View File

@@ -0,0 +1,19 @@
# Revision Checklist
Run before finishing any piece. Each "yes" requires a rewrite.
## Voice
- [ ] Does any sentence use an em-dash? → Use parentheses or split the sentence.
- [ ] Does any abstract noun carry a sentence? ("value," "conviction," "impact," "transformation") → Make it concrete or cut it.
- [ ] Does any claim dissolve when drilled into? → Add the logic or cut the claim.
- [ ] Does any hedge weaken without adding nuance? ("somewhat," "in some ways," "it's worth noting") → Cut it.
## Structure
- [ ] Does the opening start with an abstract thesis or definition? → Rewrite to open on a concrete scene.
- [ ] Does the conclusion restate or summarize? → Replace with a question, quiet observation, or callback.
- [ ] Do any paragraphs merely follow each other rather than cause each other? → Reorder or cut.
## Momentum
- [ ] Does any paragraph feel like it's trudging? → Rewrite until it moves.
- [ ] Are there runs of similarly-structured sentences? → Break the pattern.
- [ ] Does the last sentence of each paragraph land or pull forward? → Rewrite if it just stops.

57
plugins/compound-engineering/skills/john-voice/references/signature-moves.md Normal file
View File

@@ -0,0 +1,57 @@
# John's Signature Moves
## The "Not What You Think" Correction
Sets up a received wisdom, then reveals what's actually underneath. The inversion is the essay.
> "Many believe buildings in DC cannot be taller than the White House. The rule is actually based on the road the building adjoins."
> "The birth rate isn't falling because married women stopped having children. It's falling because fewer women are getting married in the first place."
> "The appliances didn't free time; they redefined our standards of what 'clean enough' meant."
---
## The Lateral Analogy
Builds through parallel examples from unrelated domains until a shared principle becomes undeniable. Two examples is a comparison. Three is a pattern.
> Crosscut saws → mechanical watches → mechanical keyboards → *therefore* manual cars will thrive as a niche.
> Vacuum cleaner → washing machine → dishwasher → *therefore* AI won't free your time either.
---
## The Parenthetical Aside
A secondary observation tucked in parentheses — a dry qualifier, a confession, or the best joke in the paragraph. It rewards close readers without slowing anyone else down.
> *(dodged the extraterrestrial lifeforms)*
> *(and will probably never go)*
> *(which are likely closer to 200 miles in reality)*
Use parentheses, never em-dashes. The parenthetical slips in; the em-dash announces itself.
---
## The Rhetorical Pivot
A question that advances the argument rather than decorating it. Often used as a structural bookend — asked at the start, answered by the end.
> "What makes a city beautiful?" — opens the essay and recurs mid-piece.
> "Does owning an EV keep you from embarking on long road trips?"
> "Why is this memory the one that's faded the least?"
---
## The Sensory Stack
When the reader needs to be *there*, enumerate specific sensory channels in sequence. Not impressionistic atmosphere — each detail is unique to the exact scene.
> "I hear the engine increase in its frothy fury, I feel the seat press back against me, I see the landscape start to blur slowly and then suddenly quickly, I stamp the clutch in, feel a sense of weightlessness..."
> "The greenness of the vegetation and the blueness of the sky. I remember how the flowering jasmine smells. The vibrations of the small, but mighty, engine chattering through the steering wheel."

45
plugins/compound-engineering/skills/proof-push/SKILL.md Normal file
View File

@@ -0,0 +1,45 @@
---
name: proof-push
description: This skill should be used when the user wants to push a markdown document to a running Proof server instance. It accepts a file path as an argument, posts the markdown content to the Proof API, and returns the document slug and URL. Triggers on "push to proof", "proof push", "open in proof", "send to proof", or any request to render markdown in Proof.
---
# Proof Push
Push a local markdown file to a running Proof server and open it in the browser.
## Usage
Accept a markdown file path as the argument. If no path is provided, ask for one.
### Execution
Run the bundled script to post the document:
```bash
bash scripts/proof_push.sh <file-path> [server-url]
```
- `file-path` — absolute or relative path to a `.md` file (required)
- `server-url` — Proof server URL, defaults to `http://localhost:4000`
The script:
1. Reads the file content
2. POSTs to `/share/markdown` as JSON with `{markdown, title}`
3. Returns the slug, base URL, and editor URL with access token
### Output
Report the returned slug and URLs to the user. The editor URL (with token) gives full edit access.
### Error Handling
If the script fails, check:
- Is the Proof server running? (`curl http://localhost:4000`)
- Does the file exist and contain non-empty markdown?
- Is `jq` installed? (required for JSON construction)
## Resources
### scripts/
- `proof_push.sh` — Shell script that posts markdown to Proof's `/share/markdown` endpoint and returns the document slug and URLs.

34
plugins/compound-engineering/skills/proof-push/scripts/proof_push.sh Executable file
View File

@@ -0,0 +1,34 @@
#!/usr/bin/env bash
# Push a markdown file to a running Proof server and return the document URL.
# Usage: proof_push.sh <path-to-markdown> [server-url]
set -euo pipefail
FILE="${1:?Usage: proof_push.sh <markdown-file> [server-url]}"
SERVER="${2:-http://localhost:4000}"
UI_URL="${3:-http://localhost:3000}"
if [[ ! -f "$FILE" ]]; then
echo "error: file not found: $FILE" >&2
exit 1
fi
TITLE=$(basename "$FILE" .md)
RESPONSE=$(curl -s -X POST "${SERVER}/share/markdown" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg md "$(cat "$FILE")" --arg title "$TITLE" '{markdown: $md, title: $title}')")
SLUG=$(echo "$RESPONSE" | jq -r '.slug // empty')
ERROR=$(echo "$RESPONSE" | jq -r '.error // empty')
if [[ -z "$SLUG" ]]; then
echo "error: failed to create document${ERROR:+: $ERROR}" >&2
echo "$RESPONSE" >&2
exit 1
fi
TOKEN_PATH=$(echo "$RESPONSE" | jq -r '.tokenPath // empty')
echo "slug: $SLUG"
echo "url: ${UI_URL}/d/${SLUG}"
[[ -n "$TOKEN_PATH" ]] && echo "editor-url: ${UI_URL}${TOKEN_PATH}"

369
plugins/compound-engineering/skills/python-package-writer/SKILL.md Normal file
View File

@@ -0,0 +1,369 @@
---
name: python-package-writer
description: This skill should be used when writing Python packages following production-ready patterns and philosophy. It applies when creating new Python packages, refactoring existing packages, designing package APIs, or when clean, minimal, well-tested Python library code is needed. Triggers on requests like "create a package", "write a Python library", "design a package API", or mentions of PyPI publishing.
---
# Python Package Writer
Write Python packages following battle-tested patterns from production-ready libraries. Emphasis on simplicity, minimal dependencies, comprehensive testing, and modern packaging standards (pyproject.toml, type hints, pytest).
## Core Philosophy
**Simplicity over cleverness.** Zero or minimal dependencies. Explicit code over magic. Framework integration without framework coupling. Every pattern serves production use cases.
## Package Structure (src layout)
The modern recommended layout with proper namespace isolation:
```
package-name/
├── pyproject.toml # All metadata and configuration
├── README.md
├── LICENSE
├── py.typed # PEP 561 marker for type hints
├── src/
│ └── package_name/ # Actual package code
│ ├── __init__.py # Entry point, exports, version
│ ├── core.py # Core functionality
│ ├── models.py # Data models (Pydantic/dataclasses)
│ ├── exceptions.py # Custom exceptions
│ └── py.typed # Type hint marker (also here)
└── tests/
├── conftest.py # Pytest fixtures
├── test_core.py
└── test_models.py
```
## Entry Point Structure
Every package follows this pattern in `src/package_name/__init__.py`:
```python
"""Package description - one line."""
# Public API exports
from package_name.core import Client, process_data
from package_name.models import Config, Result
from package_name.exceptions import PackageError, ValidationError
__version__ = "1.0.0"
__all__ = [
"Client",
"process_data",
"Config",
"Result",
"PackageError",
"ValidationError",
]
```
## pyproject.toml Configuration
Modern packaging with all metadata in one file:
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "package-name"
version = "1.0.0"
description = "Brief description of what the package does"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
authors = [
{ name = "Your Name", email = "you@example.com" }
]
classifiers = [
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Typing :: Typed",
]
keywords = ["keyword1", "keyword2"]
# Zero or minimal runtime dependencies
dependencies = []
[project.optional-dependencies]
dev = [
"pytest>=8.0",
"pytest-cov>=4.0",
"ruff>=0.4",
"mypy>=1.0",
]
# Optional integrations
fastapi = ["fastapi>=0.100", "pydantic>=2.0"]
[project.urls]
Homepage = "https://github.com/username/package-name"
Documentation = "https://package-name.readthedocs.io"
Repository = "https://github.com/username/package-name"
Changelog = "https://github.com/username/package-name/blob/main/CHANGELOG.md"
[tool.hatch.build.targets.wheel]
packages = ["src/package_name"]
[tool.ruff]
target-version = "py310"
line-length = 88
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_ignores = true
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q"
[tool.coverage.run]
source = ["src/package_name"]
branch = true
```
## Configuration Pattern
Use module-level configuration with dataclasses or simple attributes:
```python
# src/package_name/config.py
from dataclasses import dataclass, field
from os import environ
from typing import Any
@dataclass
class Config:
"""Package configuration with sensible defaults."""
timeout: int = 30
retries: int = 3
api_key: str | None = field(default=None)
debug: bool = False
def __post_init__(self) -> None:
# Environment variable fallbacks
if self.api_key is None:
self.api_key = environ.get("PACKAGE_API_KEY")
# Module-level singleton (optional)
_config: Config | None = None
def get_config() -> Config:
"""Get or create the global config instance."""
global _config
if _config is None:
_config = Config()
return _config
def configure(**kwargs: Any) -> Config:
"""Configure the package with custom settings."""
global _config
_config = Config(**kwargs)
return _config
```
## Error Handling
Simple hierarchy with informative messages:
```python
# src/package_name/exceptions.py
class PackageError(Exception):
"""Base exception for all package errors."""
pass
class ConfigError(PackageError):
"""Invalid configuration."""
pass
class ValidationError(PackageError):
"""Data validation failed."""
def __init__(self, message: str, field: str | None = None) -> None:
self.field = field
super().__init__(message)
class APIError(PackageError):
"""External API error."""
def __init__(self, message: str, status_code: int | None = None) -> None:
self.status_code = status_code
super().__init__(message)
# Validate early with ValueError
def process(data: bytes) -> str:
if not data:
raise ValueError("Data cannot be empty")
if len(data) > 1_000_000:
raise ValueError(f"Data too large: {len(data)} bytes (max 1MB)")
return data.decode("utf-8")
```
## Type Hints
Always use type hints with modern syntax (Python 3.10+):
```python
# Use built-in generics, not typing module
from collections.abc import Callable, Iterator, Mapping, Sequence
def process_items(
items: list[str],
transform: Callable[[str], str] | None = None,
*,
batch_size: int = 100,
) -> Iterator[str]:
"""Process items with optional transformation."""
for item in items:
if transform:
yield transform(item)
else:
yield item
# Use | for unions, not Union
def get_value(key: str) -> str | None:
return _cache.get(key)
# Use Self for return type annotations (Python 3.11+)
from typing import Self
class Client:
def configure(self, **kwargs: str) -> Self:
# Update configuration
return self
```
## Testing (pytest)
```python
# tests/conftest.py
import pytest
from package_name import Config, configure
@pytest.fixture
def config() -> Config:
"""Fresh config for each test."""
return configure(timeout=5, debug=True)
@pytest.fixture
def sample_data() -> bytes:
"""Sample input data."""
return b"test data content"
# tests/test_core.py
import pytest
from package_name import process_data, PackageError
class TestProcessData:
"""Tests for process_data function."""
def test_basic_functionality(self, sample_data: bytes) -> None:
result = process_data(sample_data)
assert result == "test data content"
def test_empty_input_raises_error(self) -> None:
with pytest.raises(ValueError, match="cannot be empty"):
process_data(b"")
def test_with_transform(self, sample_data: bytes) -> None:
result = process_data(sample_data, transform=str.upper)
assert result == "TEST DATA CONTENT"
class TestConfig:
"""Tests for configuration."""
def test_defaults(self) -> None:
config = Config()
assert config.timeout == 30
assert config.retries == 3
def test_env_fallback(self, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("PACKAGE_API_KEY", "test-key")
config = Config()
assert config.api_key == "test-key"
```
## FastAPI Integration
Optional FastAPI integration pattern:
```python
# src/package_name/fastapi.py
"""FastAPI integration - only import if FastAPI is installed."""
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from fastapi import FastAPI
from package_name.config import get_config
def init_app(app: "FastAPI") -> None:
"""Initialize package with FastAPI app."""
config = get_config()
@app.on_event("startup")
async def startup() -> None:
# Initialize connections, caches, etc.
pass
@app.on_event("shutdown")
async def shutdown() -> None:
# Cleanup resources
pass
# Usage in FastAPI app:
# from package_name.fastapi import init_app
# init_app(app)
```
## Anti-Patterns to Avoid
- `__getattr__` magic (use explicit imports)
- Global mutable state (use configuration objects)
- `*` imports in `__init__.py` (explicit `__all__`)
- Many runtime dependencies
- Committing `.venv/` or `__pycache__/`
- Not including `py.typed` marker
- Using `setup.py` (use `pyproject.toml`)
- Mixing src layout and flat layout
- `print()` for debugging (use logging)
- Bare `except:` clauses
## Reference Files
For deeper patterns, see:
- **[references/package-structure.md](./references/package-structure.md)** - Directory layouts, module organization
- **[references/pyproject-config.md](./references/pyproject-config.md)** - Complete pyproject.toml examples
- **[references/testing-patterns.md](./references/testing-patterns.md)** - pytest patterns, fixtures, CI setup
- **[references/type-hints.md](./references/type-hints.md)** - Modern typing patterns
- **[references/fastapi-integration.md](./references/fastapi-integration.md)** - FastAPI/Pydantic integration
- **[references/publishing.md](./references/publishing.md)** - PyPI publishing, CI/CD
- **[references/resources.md](./references/resources.md)** - Links to exemplary Python packages

120
plugins/compound-engineering/skills/ship-it/SKILL.md Normal file
View File

@@ -0,0 +1,120 @@
---
name: ship-it
description: This skill should be used when the user wants to ticket, branch, commit, and open a PR in one shot. It creates a Jira ticket from conversation context, assigns it, moves it to In Progress, creates a branch, commits changes, pushes, and opens a PR. Triggers on "ship it", "ticket and PR this", "put up a PR", "let's ship this", or any request to package completed work into a ticket + PR.
---
# Ship It
End-to-end workflow: Jira ticket + branch + commit + push + PR from conversation context. Run after a fix or feature is done and needs to be formally shipped.
## Constants
- **Jira cloudId**: `9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32`
- **Jira project**: `ZAS`
- **Issue type**: `Story`
- **Assignee accountId**: `712020:62c4d18e-a579-49c1-b228-72fbc63186de`
- **PR target branch**: `stg` (unless specified otherwise)
## Workflow
### Step 1: Gather Context
Analyze the conversation above to determine:
- **What was done** — the fix, feature, or change
- **Why** — the problem or motivation
- **Which files changed** — run `git diff` and `git status` to see the actual changes
Synthesize a ticket summary (under 80 chars, imperative mood) and a brief description. Do not ask the user to describe the work — extract it from conversation context.
### Step 2: Create Jira Ticket
Use `/john-voice` to draft the ticket content, then create via MCP:
```
mcp__atlassian__createJiraIssue
cloudId: 9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32
projectKey: ZAS
issueTypeName: Story
summary: <ticket title>
description: <ticket body>
assignee_account_id: 712020:62c4d18e-a579-49c1-b228-72fbc63186de
contentFormat: markdown
```
Extract the ticket key (e.g. `ZAS-123`) from the response.
### Step 3: Move to In Progress
Get transitions and find the "In Progress" transition ID:
```
mcp__atlassian__getTransitionsForJiraIssue
cloudId: 9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32
issueIdOrKey: <ticket key>
```
Then apply the transition:
```
mcp__atlassian__transitionJiraIssue
cloudId: 9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32
issueIdOrKey: <ticket key>
transition: { "id": "<transition_id>" }
```
### Step 4: Create Branch
Create and switch to a new branch named after the ticket:
```bash
git checkout -b <ticket-key>
```
Example: `git checkout -b ZAS-123`
### Step 5: Commit Changes
Stage and commit all relevant changes. Use the ticket key as a prefix in the commit message. Follow project git conventions (lowercase, no periods, casual).
```bash
git add <specific files>
git commit -m "<ticket-key> <short description>"
```
Example: `ZAS-123 fix candidate email field mapping`
Include the co-author trailer:
```
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
```
### Step 6: Push and Open PR
Push the branch:
```bash
git push -u origin <ticket-key>
```
Use `/john-voice` to write the PR title and body. Create the PR:
```bash
gh pr create --title "<PR title>" --base stg --body "<PR body>"
```
PR body format:
```markdown
## Summary
<2-3 bullets describing the change>
## Jira
[<ticket-key>](https://discoverorg.atlassian.net/browse/<ticket-key>)
## Test plan
<bulleted checklist>
```
### Step 7: Report
Output the ticket URL and PR URL to the user.

48
plugins/compound-engineering/skills/story-lens/SKILL.md Normal file
View File

@@ -0,0 +1,48 @@
---
name: story-lens
description: This skill should be used when evaluating whether a piece of prose constitutes a high-quality story. It applies George Saunders's craft framework — causality, escalation, efficiency, expectation, and character accumulation — as a structured diagnostic lens. Triggers on requests like "is this a good story?", "review this prose", "does this feel like a story or just an anecdote?", "critique this narrative", or any request to assess the craft quality of fiction or narrative nonfiction.
---
# Story Lens
A diagnostic skill for evaluating prose quality using George Saunders's storytelling framework. The framework operates on a single core insight: the difference between a story and an anecdote is causality plus irreversible change.
Load [saunders-framework.md](./references/saunders-framework.md) for the full framework, including all diagnostic questions and definitions.
## How to Apply the Skill
### 1. Read the Prose
Read the full piece before forming any judgments. Resist diagnosing on first pass.
### 2. Apply the Six Diagnostic Questions in Order
Each question builds on the previous.
**Beat Causality**
Map the beats. Does each beat cause the next? Or are they sequential — "and then... and then..."? Sequential beats = anecdote. Causal beats = story.
**Escalation**
Is the story moving up a staircase or running on a treadmill? Each step must be irrevocable. Once a character's condition has fundamentally changed, the story cannot re-enact that change or linger in elaboration. Look for sections that feel like they're holding still.
**The Story-Yet Test**
Stop at the end of each major section and ask: *if it ended here, would it be complete?* Something must have changed irreversibly. If nothing has changed, everything so far is setup — not story.
**Character Accumulation**
Track what the reader learns about the character, beat by beat. Is that knowledge growing? Does each beat confirm, complicate, or overturn prior understanding? Flat accumulation = underdeveloped character. Specificity accrues into care.
**The Three E's**
Check against the triad: Escalation (moving forward), Efficiency (nothing extraneous), Expectation (next beat is surprising but not absurd). Failure in any one of these is diagnosable.
**Moral/Technical Unity**
If something feels off emotionally or ethically — a character's choice that doesn't ring true, a resolution that feels unearned — look for the technical failure underneath. Saunders's claim: it is always there. Find the craft problem, and the moral problem dissolves.
### 3. Render a Verdict
After applying all six diagnostics, deliver a clear assessment:
- Is this a story, or still an anecdote?
- Which diagnostic reveals the primary weakness?
- What is the single most important structural fix?
Be direct. The framework produces precise, actionable diagnoses — not impressionistic feedback. Imprecise praise or vague encouragement is not useful here. The goal is to help the writer see exactly where the story is working and where it isn't.

75
plugins/compound-engineering/skills/story-lens/references/saunders-framework.md Normal file
View File

@@ -0,0 +1,75 @@
# The Saunders Storytelling Framework
A distillation of George Saunders's craft principles for evaluating whether prose constitutes a high-quality story.
---
## The Fundamental Unit: The Beat
Every moment in a story is a beat. Each beat must *cause* the next beat. Saunders calls causality "what melody is to a songwriter" — it's the invisible connective tissue the audience feels as the story's logic.
The test: are beats **causal** or merely **sequential**?
- Sequential (anecdote): "this happened, then this happened"
- Causal (story): "this happened, *therefore* this happened"
If beats are merely sequential, the work reads as anecdote, not story.
---
## What Transforms Anecdote into Story: Escalation
> "Always be escalating. That's all a story is, really: a continual system of escalation. A swath of prose earns its place in the story to the extent that it contributes to our sense that the story is still escalating."
Escalation isn't just raising stakes — it's **irrevocable change**. Once a story has moved forward through some fundamental change in a character's condition, you don't get to enact that change again, and you don't get to stay there elaborating on that state.
**The story is a staircase, not a treadmill.**
---
## The "Is This a Story Yet?" Diagnostic
Stop at any point and ask: *if it ended here, would it be complete?*
Early on, the answer is almost always no — because nothing has changed yet. The story only becomes a story at the moment something changes irreversibly.
**Precise test: change = story. No change = still just setup.**
---
## The "What Do We Know About This Character So Far?" Tool
Take inventory constantly. A reader's understanding of a character is always a running accumulation — and every beat should either **confirm**, **complicate**, or **overturn** that understanding.
The more we know about a person — their hopes, dreams, fears, and failures — the more compassionate we become toward them. This is how the empathy machine operates mechanically: **specificity accrues, and accrued specificity generates care.**
---
## The Three E's
Three words that capture the full framework:
1. **Escalation** — the story must continuously move forward through irrevocable change
2. **Efficiency** — ruthlessly exclude anything extraneous to the story's purposes
3. **Expectation** — what comes next must hit a Goldilocks level: not too obvious, not too absurd
---
## The Moral/Technical Unity
Any story that suffers from what seems like a **moral failing** will, with sufficient analytical attention, be found to be suffering from a **technical failing** — and if that failing is addressed, it will always become a better story.
This means: when a story feels wrong emotionally or ethically, look for the craft problem first. The fix is almost always structural.
---
## Summary: The Diagnostic Questions
Apply these in order to any piece of prose:
1. **Beat causality** — Does each beat cause the next, or are they merely sequential?
2. **Escalation** — Is the story continuously moving up the staircase, or running on a treadmill?
3. **Story-yet test** — If it ended here, would something have irreversibly changed?
4. **Character accumulation** — Is our understanding of the character growing richer with each beat?
5. **Three E's check** — Is it escalating, efficient, and pitched at the right level of expectation?
6. **Moral/technical unity** — If something feels off morally or emotionally, where is the technical failure?

153
plugins/compound-engineering/skills/sync-confluence/SKILL.md Normal file
View File

@@ -0,0 +1,153 @@
---
name: sync-confluence
description: This skill should be used when syncing local markdown documentation to Confluence Cloud pages. It handles first-time setup (creating mapping files and docs directories), pushing updates to existing pages, and creating new pages with interactive destination prompts. Triggers on "sync to confluence", "push docs to confluence", "update confluence pages", "create a confluence page", or any request to publish markdown content to Confluence.
allowed-tools: Read, Bash(find *), Bash(source *), Bash(uv run *)
---
# Sync Confluence
Sync local markdown files to Confluence Cloud pages via REST API. Handles the full lifecycle: first-time project setup, page creation, and bulk updates.
## Prerequisites
Two environment variables must be set (typically in `~/.zshrc`):
- `CONFLUENCE_EMAIL` — Atlassian account email
- `CONFLUENCE_API_TOKEN_WRITE` — Atlassian API token with write scope (falls back to `CONFLUENCE_API_TOKEN`)
Generate tokens at: https://id.atlassian.com/manage-profile/security/api-tokens
The script requires `uv` to be installed. Dependencies (`markdown`, `requests`, `truststore`) are declared inline via PEP 723 and resolved automatically by `uv run`.
## Workflow
### 1. Check for Mapping File
Before running the sync script, check whether a `.confluence-mapping.json` exists in the project:
```bash
find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -name ".confluence-mapping.json" -maxdepth 3 2>/dev/null
```
- **If found** — skip to step 3 (Sync).
- **If not found** — proceed to step 2 (First-Time Setup).
### 2. First-Time Setup
When no mapping file exists, gather configuration interactively via `AskUserQuestion`:
1. **Confluence base URL** — e.g., `https://myorg.atlassian.net/wiki`
2. **Space key** — short identifier in Confluence URLs (e.g., `ZR`, `ENG`)
3. **Parent page ID** — the page under which synced pages nest. Tell the user: "Open the parent page in Confluence — the page ID is the number in the URL."
4. **Parent page title** — prefix for generated page titles (e.g., `ATS Platform`)
5. **Docs directory** — where markdown files live relative to repo root (default: `docs/`)
Then create the docs directory and mapping file:
```python
import json
from pathlib import Path
config = {
"confluence": {
"cloudId": "<domain>.atlassian.net",
"spaceId": "",
"spaceKey": "<SPACE_KEY>",
"baseUrl": "<BASE_URL>"
},
"parentPage": {
"id": "<PARENT_PAGE_ID>",
"title": "<PARENT_TITLE>",
"url": "<BASE_URL>/spaces/<SPACE_KEY>/pages/<PARENT_PAGE_ID>"
},
"pages": {},
"unmapped": [],
"lastSynced": ""
}
docs_dir = Path("<REPO_ROOT>") / "<DOCS_DIR>"
docs_dir.mkdir(parents=True, exist_ok=True)
mapping_path = docs_dir / ".confluence-mapping.json"
mapping_path.write_text(json.dumps(config, indent=2) + "\n")
```
To discover `spaceId` (required for page creation), run:
```bash
source ~/.zshrc && curl -s -u "${CONFLUENCE_EMAIL}:${CONFLUENCE_API_TOKEN_WRITE}" \
-H "X-Atlassian-Token: no-check" \
"<BASE_URL>/rest/api/space/<SPACE_KEY>" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])"
```
Update the mapping file with the discovered spaceId before proceeding.
### 3. Sync — Running the Script
The sync script is at `${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py`.
**Always source shell profile before running** to load env vars:
```bash
source ~/.zshrc && uv run ${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py [options]
```
#### Common Operations
| Command | What it does |
|---------|-------------|
| _(no flags)_ | Sync all markdown files in docs dir |
| `--dry-run` | Preview changes without API calls |
| `--file docs/my-doc.md` | Sync a single file |
| `--update-only` | Only update existing pages, skip unmapped files |
| `--create-only` | Only create new pages, skip existing |
| `--mapping-file path/to/file` | Use a specific mapping file |
| `--docs-dir path/to/dir` | Override docs directory |
### 4. Creating a New Confluence Page
When the user wants to create a new page:
1. Ask for the page topic/title
2. Create the markdown file in the docs directory with a `# Title` heading and content
3. Run the sync script with `--file` pointing to the new file
4. The script detects the unmapped file, creates the page, and updates the mapping
**Title resolution order:** First `# H1` from the markdown → filename-derived title → raw filename. Titles are prefixed with the parent page title (e.g., `My Project: New Page`).
### 5. Mapping File Structure
```json
{
"confluence": {
"cloudId": "myorg.atlassian.net",
"spaceId": "1234567890",
"spaceKey": "ZR",
"baseUrl": "https://myorg.atlassian.net/wiki"
},
"parentPage": {
"id": "123456789",
"title": "My Project",
"url": "https://..."
},
"pages": {
"my-doc.md": {
"pageId": "987654321",
"title": "My Project: My Doc",
"url": "https://..."
}
},
"unmapped": [],
"lastSynced": "2026-03-03"
}
```
The script updates this file after each successful sync. Do not manually edit page entries unless correcting a known error.
## Technical Notes
- **Auth:** Confluence REST API v1 with Basic Auth + `X-Atlassian-Token: no-check`. Some Cloud instances block v2 or require this XSRF bypass.
- **Content format:** Markdown converted to Confluence storage format (XHTML) via Python `markdown` library with tables, fenced code, and TOC extensions.
- **SSL:** `truststore` delegates cert verification to the OS trust store, handling corporate SSL proxies (Zscaler, etc.).
- **Rate limiting:** Automatic retry with backoff on 429 and 5xx responses.
- **Sync timestamp:** `> **Last synced to Confluence**: YYYY-MM-DD` injected into the Confluence copy only. Local files are untouched.
- **Versioning:** Page versions auto-increment. The script GETs the current version before PUTting.

529
plugins/compound-engineering/skills/sync-confluence/scripts/sync_confluence.py Normal file
View File

@@ -0,0 +1,529 @@
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = ["markdown", "requests", "truststore"]
# ///
"""Sync markdown docs to Confluence Cloud.
Reads a .confluence-mapping.json file, syncs local markdown files
to Confluence pages via REST API v2, and updates the mapping file.
Run with: uv run scripts/sync_confluence.py [options]
"""
import argparse
import base64
import json
import os
import re
import subprocess
import sys
import time
from datetime import date, timezone, datetime
from pathlib import Path
from urllib.parse import quote
import truststore
truststore.inject_into_ssl()
import markdown
import requests
# ---------------------------------------------------------------------------
# Path discovery
# ---------------------------------------------------------------------------
def find_repo_root() -> Path | None:
"""Walk up from CWD to find a git repo root."""
try:
result = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
capture_output=True, text=True, check=True,
)
return Path(result.stdout.strip())
except (subprocess.CalledProcessError, FileNotFoundError):
return None
def find_mapping_file(start: Path) -> Path | None:
"""Search for .confluence-mapping.json walking up from *start*.
Checks <dir>/docs/.confluence-mapping.json and
<dir>/.confluence-mapping.json at each level.
"""
current = start.resolve()
while True:
for candidate in (
current / "docs" / ".confluence-mapping.json",
current / ".confluence-mapping.json",
):
if candidate.is_file():
return candidate
parent = current.parent
if parent == current:
break
current = parent
return None
# ---------------------------------------------------------------------------
# Mapping file helpers
# ---------------------------------------------------------------------------
def load_mapping(path: Path) -> dict:
"""Load and lightly validate the mapping file."""
data = json.loads(path.read_text(encoding="utf-8"))
for key in ("confluence", "parentPage"):
if key not in data:
raise ValueError(f"Mapping file missing required key: '{key}'")
data.setdefault("pages", {})
data.setdefault("unmapped", [])
return data
def save_mapping(path: Path, data: dict) -> None:
"""Write the mapping file with stable formatting."""
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
# ---------------------------------------------------------------------------
# Markdown → Confluence storage format
# ---------------------------------------------------------------------------
MD_EXTENSIONS = [
"markdown.extensions.tables",
"markdown.extensions.fenced_code",
"markdown.extensions.toc",
"markdown.extensions.md_in_html",
"markdown.extensions.sane_lists",
]
MD_EXTENSION_CONFIGS: dict = {
"markdown.extensions.toc": {"permalink": False},
}
def md_to_storage(md_content: str) -> str:
"""Convert markdown to Confluence storage-format XHTML."""
return markdown.markdown(
md_content,
extensions=MD_EXTENSIONS,
extension_configs=MD_EXTENSION_CONFIGS,
output_format="xhtml",
)
# ---------------------------------------------------------------------------
# Title helpers
# ---------------------------------------------------------------------------
def extract_h1(md_content: str) -> str | None:
"""Return the first ``# Heading`` from *md_content*, or None."""
for line in md_content.splitlines():
stripped = line.strip()
if stripped.startswith("# ") and not stripped.startswith("## "):
return stripped[2:].strip()
return None
def title_from_filename(filename: str) -> str:
"""Derive a human-readable title from a kebab-case filename."""
stem = filename.removesuffix(".md")
words = stem.split("-")
# Capitalise each word, then fix known acronyms/terms
title = " ".join(w.capitalize() for w in words)
acronyms = {
"Ats": "ATS", "Api": "API", "Ms": "MS", "Unie": "UNIE",
"Id": "ID", "Opa": "OPA", "Zi": "ZI", "Cql": "CQL",
"Jql": "JQL", "Sdk": "SDK", "Oauth": "OAuth", "Cdn": "CDN",
"Aws": "AWS", "Gcp": "GCP", "Grpc": "gRPC",
}
for wrong, right in acronyms.items():
title = re.sub(rf"\b{wrong}\b", right, title)
return title
def resolve_title(filename: str, md_content: str, parent_title: str | None) -> str:
"""Pick the best page title for a file.
Priority: H1 from markdown > filename-derived > raw filename.
If *parent_title* is set, prefix with ``<parent>: <title>``.
"""
title = extract_h1(md_content) or title_from_filename(filename)
if parent_title:
# Avoid double-prefixing if the title already starts with parent
if not title.startswith(parent_title):
title = f"{parent_title}: {title}"
return title
# ---------------------------------------------------------------------------
# Sync timestamp injection (Confluence copy only — local files untouched)
# ---------------------------------------------------------------------------
_SYNC_RE = re.compile(r"> \*\*Last synced to Confluence\*\*:.*")
def inject_sync_timestamp(md_content: str, sync_date: str) -> str:
"""Add or update the sync-timestamp callout in *md_content*."""
stamp = f"> **Last synced to Confluence**: {sync_date}"
if _SYNC_RE.search(md_content):
return _SYNC_RE.sub(stamp, md_content)
lines = md_content.split("\n")
insert_at = 0
# After YAML front-matter
if lines and lines[0].strip() == "---":
for i, line in enumerate(lines[1:], 1):
if line.strip() == "---":
insert_at = i + 1
break
# Or after first H1
elif lines and lines[0].startswith("# "):
insert_at = 1
lines.insert(insert_at, "")
lines.insert(insert_at + 1, stamp)
lines.insert(insert_at + 2, "")
return "\n".join(lines)
# ---------------------------------------------------------------------------
# Confluence REST API v1 client
# ---------------------------------------------------------------------------
class ConfluenceClient:
"""Thin wrapper around the Confluence Cloud REST API v1.
Uses Basic Auth (email + API token) with X-Atlassian-Token header,
which is required by some Confluence Cloud instances that block v2
or enforce XSRF protection.
"""
def __init__(self, base_url: str, email: str, api_token: str):
self.base_url = base_url.rstrip("/")
self.session = requests.Session()
cred = base64.b64encode(f"{email}:{api_token}".encode()).decode()
self.session.headers.update({
"Authorization": f"Basic {cred}",
"X-Atlassian-Token": "no-check",
"Content-Type": "application/json",
"Accept": "application/json",
})
# -- low-level helpers ---------------------------------------------------
def _request(self, method: str, path: str, **kwargs) -> requests.Response:
"""Make a request with basic retry on 429 / 5xx."""
url = f"{self.base_url}{path}"
for attempt in range(4):
resp = self.session.request(method, url, **kwargs)
if resp.status_code == 429:
wait = int(resp.headers.get("Retry-After", 5))
print(f" Rate-limited, waiting {wait}s …")
time.sleep(wait)
continue
if resp.status_code >= 500 and attempt < 3:
time.sleep(2 ** attempt)
continue
resp.raise_for_status()
return resp
resp.raise_for_status() # final attempt — let it raise
return resp # unreachable, keeps type-checkers happy
# -- page operations -----------------------------------------------------
def get_page(self, page_id: str) -> dict:
"""Fetch page metadata including current version number."""
return self._request(
"GET", f"/rest/api/content/{page_id}",
params={"expand": "version"},
).json()
def create_page(
self, *, space_key: str, parent_id: str, title: str, body: str,
) -> dict:
payload = {
"type": "page",
"title": title,
"space": {"key": space_key},
"ancestors": [{"id": parent_id}],
"body": {
"storage": {
"value": body,
"representation": "storage",
},
},
}
return self._request("POST", "/rest/api/content", json=payload).json()
def update_page(
self, *, page_id: str, title: str, body: str, version_msg: str = "",
) -> dict:
current = self.get_page(page_id)
next_ver = current["version"]["number"] + 1
payload = {
"type": "page",
"title": title,
"body": {
"storage": {
"value": body,
"representation": "storage",
},
},
"version": {"number": next_ver, "message": version_msg},
}
return self._request(
"PUT", f"/rest/api/content/{page_id}", json=payload,
).json()
# ---------------------------------------------------------------------------
# URL builder
# ---------------------------------------------------------------------------
def page_url(base_url: str, space_key: str, page_id: str, title: str) -> str:
"""Build a human-friendly Confluence page URL."""
safe = quote(title.replace(" ", "+"), safe="+")
return f"{base_url}/spaces/{space_key}/pages/{page_id}/{safe}"
# ---------------------------------------------------------------------------
# Core sync logic
# ---------------------------------------------------------------------------
def sync_file(
client: ConfluenceClient,
md_path: Path,
mapping: dict,
*,
dry_run: bool = False,
) -> dict | None:
"""Sync one markdown file. Returns page-info dict or None on failure."""
filename = md_path.name
cfg = mapping["confluence"]
parent = mapping["parentPage"]
pages = mapping["pages"]
existing = pages.get(filename)
today = date.today().isoformat()
md_content = md_path.read_text(encoding="utf-8")
md_for_confluence = inject_sync_timestamp(md_content, today)
storage_body = md_to_storage(md_for_confluence)
# Resolve title — keep existing title for already-mapped pages
if existing:
title = existing["title"]
else:
title = resolve_title(filename, md_content, parent.get("title"))
base = cfg.get("baseUrl", "")
space_key = cfg.get("spaceKey", "")
# -- update existing page ------------------------------------------------
if existing:
pid = existing["pageId"]
if dry_run:
print(f" [dry-run] update {filename} (page {pid})")
return existing
try:
client.update_page(
page_id=pid,
title=title,
body=storage_body,
version_msg=f"Synced from local docs {today}",
)
url = page_url(base, space_key, pid, title)
print(f" updated {filename}")
return {"pageId": pid, "title": title, "url": url}
except requests.HTTPError as exc:
_report_error("update", filename, exc)
return None
# -- create new page -----------------------------------------------------
if dry_run:
print(f" [dry-run] create {filename} → {title}")
return {"pageId": "DRY_RUN", "title": title, "url": ""}
try:
result = client.create_page(
space_key=cfg["spaceKey"],
parent_id=parent["id"],
title=title,
body=storage_body,
)
pid = result["id"]
url = page_url(base, space_key, pid, title)
print(f" created {filename} (page {pid})")
return {"pageId": pid, "title": title, "url": url}
except requests.HTTPError as exc:
_report_error("create", filename, exc)
return None
def _report_error(verb: str, filename: str, exc: requests.HTTPError) -> None:
print(f" FAILED {verb} {filename}: {exc}")
if exc.response is not None:
body = exc.response.text[:500]
print(f" {body}")
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
p = argparse.ArgumentParser(
description="Sync markdown docs to Confluence Cloud.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
environment variables
CONFLUENCE_EMAIL Atlassian account email
CONFLUENCE_API_TOKEN_WRITE Atlassian API token (write-scoped)
CONFLUENCE_API_TOKEN Fallback if _WRITE is not set
CONFLUENCE_BASE_URL Wiki base URL (overrides mapping file)
examples
%(prog)s # sync all docs
%(prog)s --dry-run # preview without changes
%(prog)s --file docs/my-doc.md # sync one file
%(prog)s --update-only # only update existing pages
""",
)
p.add_argument("--docs-dir", type=Path,
help="Docs directory (default: inferred from mapping file location)")
p.add_argument("--mapping-file", type=Path,
help="Path to .confluence-mapping.json (default: auto-detect)")
p.add_argument("--file", type=Path, dest="single_file",
help="Sync a single file instead of all docs")
p.add_argument("--dry-run", action="store_true",
help="Show what would happen without making API calls")
p.add_argument("--create-only", action="store_true",
help="Only create new pages (skip existing)")
p.add_argument("--update-only", action="store_true",
help="Only update existing pages (skip new)")
return p
def resolve_base_url(cfg: dict) -> str | None:
"""Derive the Confluence base URL from env or mapping config."""
from_env = os.environ.get("CONFLUENCE_BASE_URL")
if from_env:
return from_env.rstrip("/")
from_cfg = cfg.get("baseUrl")
if from_cfg:
return from_cfg.rstrip("/")
# cloudId might be a domain like "discoverorg.atlassian.net"
cloud_id = cfg.get("cloudId", "")
if "." in cloud_id:
return f"https://{cloud_id}/wiki"
return None
def main() -> None:
parser = build_parser()
args = parser.parse_args()
# -- discover paths ------------------------------------------------------
repo_root = find_repo_root() or Path.cwd()
if args.mapping_file:
mapping_path = args.mapping_file.resolve()
else:
mapping_path = find_mapping_file(repo_root)
if not mapping_path or not mapping_path.is_file():
print("ERROR: cannot find .confluence-mapping.json")
print(" Pass --mapping-file or run from within the project.")
sys.exit(1)
docs_dir = args.docs_dir.resolve() if args.docs_dir else mapping_path.parent
print(f"mapping: {mapping_path}")
print(f"docs dir: {docs_dir}")
# -- load config ---------------------------------------------------------
mapping = load_mapping(mapping_path)
cfg = mapping["confluence"]
email = os.environ.get("CONFLUENCE_EMAIL", "")
# Prefer write-scoped token, fall back to general token
token = (os.environ.get("CONFLUENCE_API_TOKEN_WRITE")
or os.environ.get("CONFLUENCE_API_TOKEN", ""))
base_url = resolve_base_url(cfg)
if not email or not token:
print("ERROR: CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN_WRITE must be set.")
print(" https://id.atlassian.com/manage-profile/security/api-tokens")
sys.exit(1)
if not base_url:
print("ERROR: cannot determine Confluence base URL.")
print(" Set CONFLUENCE_BASE_URL or add baseUrl to the mapping file.")
sys.exit(1)
# Ensure baseUrl is persisted so page_url() works
cfg.setdefault("baseUrl", base_url)
client = ConfluenceClient(base_url, email, token)
# -- collect files -------------------------------------------------------
if args.single_file:
target = args.single_file.resolve()
if not target.is_file():
print(f"ERROR: file not found: {target}")
sys.exit(1)
md_files = [target]
else:
md_files = sorted(
p for p in docs_dir.glob("*.md")
if not p.name.startswith(".")
)
if not md_files:
print("No markdown files found.")
sys.exit(0)
pages = mapping["pages"]
if args.create_only:
md_files = [f for f in md_files if f.name not in pages]
elif args.update_only:
md_files = [f for f in md_files if f.name in pages]
total = len(md_files)
mode = "dry-run" if args.dry_run else "live"
print(f"\n{total} file(s) to sync ({mode})\n")
# -- sync ----------------------------------------------------------------
created = updated = failed = 0
for i, md_path in enumerate(md_files, 1):
filename = md_path.name
is_new = filename not in pages
prefix = f"[{i}/{total}]"
result = sync_file(client, md_path, mapping, dry_run=args.dry_run)
if result:
if not args.dry_run:
pages[filename] = result
if is_new:
created += 1
else:
updated += 1
else:
failed += 1
# -- persist mapping -----------------------------------------------------
if not args.dry_run and (created or updated):
mapping["lastSynced"] = date.today().isoformat()
# Clean synced files out of the unmapped list
synced = {f.name for f in md_files}
mapping["unmapped"] = [u for u in mapping.get("unmapped", []) if u not in synced]
save_mapping(mapping_path, mapping)
print(f"\nmapping file updated")
# -- summary -------------------------------------------------------------
print(f"\ndone: {created} created · {updated} updated · {failed} failed")
if failed:
sys.exit(1)
if __name__ == "__main__":
main()

199
plugins/compound-engineering/skills/upstream-merge/SKILL.md Normal file
View File

@@ -0,0 +1,199 @@
---
name: upstream-merge
description: This skill should be used when incorporating upstream git changes into a local fork while preserving local intent. It provides a structured workflow for analyzing divergence, categorizing conflicts, creating triage todos for each conflict, reviewing decisions one-by-one with the user, and executing all resolutions. Triggers on "merge upstream", "incorporate upstream changes", "sync fork", or when local and remote branches have diverged significantly.
---
# Upstream Merge
Incorporate upstream changes into a local fork without losing local intent. Analyze divergence, categorize every changed file, triage conflicts interactively, then execute all decisions in a single structured pass.
## Prerequisites
Before starting, establish context:
1. **Identify the guiding principle** — ask the user what local intent must be preserved (e.g., "FastAPI pivot is non-negotiable", "custom branding must remain"). This principle governs every triage decision.
2. **Confirm remote** — verify `git remote -v` shows the correct upstream origin.
3. **Fetch latest** — `git fetch origin` to get current upstream state.
## Phase 1: Analyze Divergence
Gather the full picture before making any decisions.
**Run these commands:**
```bash
# Find common ancestor
git merge-base HEAD origin/main
# Count divergence
git rev-list --count HEAD ^origin/main # local-only commits
git rev-list --count origin/main ^HEAD # remote-only commits
# List all changed files on each side
git diff --name-only $(git merge-base HEAD origin/main) HEAD > /tmp/local-changes.txt
git diff --name-only $(git merge-base HEAD origin/main) origin/main > /tmp/remote-changes.txt
```
**Categorize every file into three buckets:**
| Bucket | Definition | Action |
|--------|-----------|--------|
| **Remote-only** | Changed upstream, untouched locally | Accept automatically |
| **Local-only** | Changed locally, untouched upstream | Keep as-is |
| **Both-changed** | Modified on both sides | Create triage todo |
```bash
# Generate buckets
comm -23 <(sort /tmp/remote-changes.txt) <(sort /tmp/local-changes.txt) > /tmp/remote-only.txt
comm -13 <(sort /tmp/remote-changes.txt) <(sort /tmp/local-changes.txt) > /tmp/local-only.txt
comm -12 <(sort /tmp/remote-changes.txt) <(sort /tmp/local-changes.txt) > /tmp/both-changed.txt
```
**Present summary to user:**
```
Divergence Analysis:
- Common ancestor: [commit hash]
- Local: X commits ahead | Remote: Y commits ahead
- Remote-only: N files (auto-accept)
- Local-only: N files (auto-keep)
- Both-changed: N files (need triage)
```
## Phase 2: Create Triage Todos
For each file in the "both-changed" bucket, create a triage todo using the template at [merge-triage-template.md](./assets/merge-triage-template.md).
**Process:**
1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1`
2. For each both-changed file:
- Read both versions (local and remote)
- Generate the diff: `git diff $(git merge-base HEAD origin/main)..origin/main -- <file>`
- Analyze what each side intended
- Write a recommendation based on the guiding principle
- Create todo: `todos/{id}-pending-p2-merge-{brief-name}.md`
**Naming convention for merge triage todos:**
```
{id}-pending-p2-merge-{component-name}.md
```
Examples:
- `001-pending-p2-merge-marketplace-json.md`
- `002-pending-p2-merge-kieran-python-reviewer.md`
- `003-pending-p2-merge-workflows-review.md`
**Use parallel agents** to create triage docs when there are many conflicts (batch 4-6 at a time).
**Announce when complete:**
```
Created N triage todos in todos/. Ready to review one-by-one.
```
## Phase 3: Triage (Review One-by-One)
Present each triage todo to the user for a decision. Follow the `/triage` command pattern.
**For each conflict, present:**
```
---
Conflict X/N: [filename]
Category: [agent/command/skill/config]
Conflict Type: [content/modify-delete/add-add]
Remote intent: [what upstream changed and why]
Local intent: [what local changed and why]
Recommendation: [Accept remote / Keep local / Merge both / Keep deleted]
Reasoning: [why, referencing the guiding principle]
---
How should we handle this?
1. Accept remote — take upstream version as-is
2. Keep local — preserve local version
3. Merge both — combine changes (specify how)
4. Keep deleted — file was deleted locally, keep it deleted
```
**Use AskUserQuestion tool** for each decision with appropriate options.
**Record decisions** by updating the triage todo:
- Fill the "Decision" section with the chosen resolution
- Add merge instructions if "merge both" was selected
- Update status: `pending` → `ready`
**Group related files** when presenting (e.g., present all 7 dspy-ruby files together, not separately).
**Track progress:** Show "X/N completed" with each presentation.
## Phase 4: Execute Decisions
After all triage decisions are made, execute them in a structured order.
### Step 1: Create Working Branch
```bash
git branch backup-local-changes # safety net
git checkout -b merge-upstream origin/main
```
### Step 2: Execute in Order
Process decisions in this sequence to avoid conflicts:
1. **Deletions first** — Remove files that should stay deleted
2. **Copy local-only files** — `git checkout backup-local-changes -- <file>` for local additions
3. **Merge files** — Apply "merge both" decisions (the most complex step)
4. **Update metadata** — Counts, versions, descriptions, changelogs
### Step 3: Verify
```bash
# Validate JSON/YAML files
cat <config-files> | python3 -m json.tool > /dev/null
# Verify component counts match descriptions
# (skill-specific: count agents, commands, skills, etc.)
# Check diff summary
git diff --stat HEAD
```
### Step 4: Commit and Merge to Main
```bash
git add <specific-files> # stage explicitly, not -A
git commit -m "Merge upstream vX.Y.Z with [guiding principle] (vX.Y.Z+1)"
git checkout main
git merge merge-upstream
```
**Ask before merging to main** — confirm the user wants to proceed.
## Decision Framework
When making recommendations, apply these heuristics:
| Signal | Recommendation |
|--------|---------------|
| Remote adds new content, no local equivalent | Accept remote |
| Remote updates content local deleted intentionally | Keep deleted |
| Remote has structural improvements (formatting, frontmatter) + local has content changes | Merge both: remote structure + local content |
| Both changed same content differently | Merge both: evaluate which serves the guiding principle |
| Remote renames what local deleted | Keep deleted |
| File is metadata (counts, versions, descriptions) | Defer to Phase 4 — recalculate from actual files |
## Important Rules
- **Never auto-resolve "both-changed" files** — always triage with user
- **Never code during triage** — triage is for decisions only, execution is Phase 4
- **Always create a backup branch** before making changes
- **Always stage files explicitly** — never `git add -A` or `git add .`
- **Group related files** — don't present 7 files from the same skill directory separately
- **Metadata is derived, not merged** — counts, versions, and descriptions should be recalculated from actual files after all other changes are applied
- **Preserve the guiding principle** — every recommendation should reference it

57
plugins/compound-engineering/skills/upstream-merge/assets/merge-triage-template.md Normal file
View File

@@ -0,0 +1,57 @@
---
status: pending
priority: p2
issue_id: "XXX"
tags: [upstream-merge]
dependencies: []
---
# Merge Conflict: [filename]
## File Info
| Field | Value |
|-------|-------|
| **File** | `path/to/file` |
| **Category** | agent / command / skill / config / other |
| **Conflict Type** | content / modify-delete / add-add |
## What Changed
### Remote Version
[What the upstream version added, changed, or intended]
### Local Version
[What the local version added, changed, or intended]
## Diff
<details>
<summary>Show diff</summary>
```diff
[Relevant diff content]
```
</details>
## Recommendation
**Suggested resolution:** Accept remote / Keep local / Merge both / Keep deleted
[Reasoning for the recommendation, considering the local fork's guiding principles]
## Decision
**Resolution:** *(filled during triage)*
**Details:** *(specific merge instructions if "merge both")*
## Acceptance Criteria
- [ ] Resolution applied correctly
- [ ] No content lost unintentionally
- [ ] Local intent preserved
- [ ] File validates (JSON/YAML if applicable)

189
plugins/compound-engineering/skills/weekly-shipped/SKILL.md Normal file
View File

@@ -0,0 +1,189 @@
---
name: weekly-shipped
description: Generate a weekly summary of all work shipped by the Talent team. Queries Jira ZAS board and GitHub PRs across talent-engine, talent-ats-platform, and agentic-ai-platform. Cross-references tickets and PRs, groups by theme, and writes a Slack-ready stakeholder summary to ~/projects/talent-engine/docs/. Run every Friday afternoon. Triggers on "weekly shipped", "weekly update", "friday update", "what shipped this week".
disable-model-invocation: true
allowed-tools: Bash(gh *), Bash(date *), Bash(jq *), Read, Write, mcp__atlassian__searchJiraIssuesUsingJql, mcp__atlassian__getJiraIssue
---
# Weekly Shipped Summary
Generate a stakeholder-ready summary of work shipped this week by the Talent team.
**Voice**: Before drafting the summary, load `/john-voice` — read [core-voice.md](../john-voice/references/core-voice.md) and [casual-messages.md](../john-voice/references/casual-messages.md). The tone is a 1:1 with your GM — you have real rapport, you're direct and honest, you say why things matter, but you're not slouching. Not a coffee chat, not a board deck.
## Constants
- **Jira cloudId**: `9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32`
- **Jira project**: `ZAS`
- **Jira board**: `https://discoverorg.atlassian.net/jira/software/c/projects/ZAS/boards/5615`
- **GitHub host**: `git.zoominfo.com`
- **Repos**:
- `dozi/talent-engine`
- `dozi/talent-ats-platform`
- `dozi/agentic-ai-platform` (talent PRs only)
- **Output dir**: `~/projects/talent-engine/docs/`
- **Ticket URL pattern**: `https://discoverorg.atlassian.net/browse/{KEY}`
- **PR URL pattern**: `https://git.zoominfo.com/{org}/{repo}/pull/{number}`
## Coverage Window
**Last Friday 1:00 PM CT → This Friday 12:59 PM CT**
The window is approximate at the day level for queries. The skill runs Friday afternoon, so "this week" means the 7-day period ending now.
## Workflow
### Step 1: Calculate Dates
Determine the date range for queries:
```bash
# Last Friday (YYYY-MM-DD) — macOS BSD date
LAST_FRIDAY=$(date -v-fri -v-1w "+%Y-%m-%d")
# This Friday (YYYY-MM-DD)
THIS_FRIDAY=$(date -v-fri "+%Y-%m-%d")
echo "Window: $LAST_FRIDAY to $THIS_FRIDAY"
```
Store `LAST_FRIDAY` and `THIS_FRIDAY` for use in all subsequent queries.
### Step 2: Gather Data
Run Jira and GitHub queries in parallel.
#### 2a. Jira — Tickets Completed This Week
Search for tickets resolved in the window:
```
mcp__atlassian__searchJiraIssuesUsingJql
cloudId: 9cbcbbfd-6b43-42ab-a91c-aaaafa8b7f32
jql: project = ZAS AND status = Done AND resolved >= "{LAST_FRIDAY}" AND resolved <= "{THIS_FRIDAY}" ORDER BY resolved DESC
limit: 50
```
For each ticket, capture: key, summary, assignee, status.
If the initial query returns few results, also try:
```
jql: project = ZAS AND status changed to "Done" after "{LAST_FRIDAY}" before "{THIS_FRIDAY}" ORDER BY updated DESC
```
#### 2b. GitHub — Merged PRs
Query all three repos for merged PRs. Run these three commands in parallel:
```bash
# talent-engine
GH_HOST=git.zoominfo.com gh pr list --repo dozi/talent-engine \
--state merged --search "merged:>={LAST_FRIDAY}" \
--json number,title,url,mergedAt,author,headRefName --limit 100
# talent-ats-platform
GH_HOST=git.zoominfo.com gh pr list --repo dozi/talent-ats-platform \
--state merged --search "merged:>={LAST_FRIDAY}" \
--json number,title,url,mergedAt,author,headRefName --limit 100
# agentic-ai-platform (fetch all, filter for talent next)
GH_HOST=git.zoominfo.com gh pr list --repo dozi/agentic-ai-platform \
--state merged --search "merged:>={LAST_FRIDAY}" \
--json number,title,url,mergedAt,author,headRefName --limit 100
```
**Filter agentic-ai-platform results**: Only keep PRs where:
- `title` contains "talent" or "[Talent]" (case-insensitive), OR
- `headRefName` starts with "talent-" or "talent/"
Discard the rest — they belong to other teams.
### Step 3: Cross-Reference
Build a unified picture of what shipped:
1. **Match PRs to Jira tickets** — Scan PR titles and branch names for ticket keys (ZAS-NNN pattern). Link matched pairs.
2. **Identify orphan PRs** — PRs with no Jira ticket. These represent real work that slipped through ticketing. Include them.
3. **Filter out empty tickets** — Jira tickets moved to Done with no corresponding PR and no evidence of work (no comments, no linked PRs). Exclude silently — these were likely backlog grooming moves, not shipped work.
4. **Verify merge times** — Confirm merged PRs fall within the actual window. GitHub search by date can be slightly off.
### Step 4: Group by Theme
Review all shipped items and cluster into 3-6 logical groups based on feature area. Examples of past groupings:
- **Outreach System** — email, templates, response tracking
- **Candidate Experience** — UI, cards, review flow
- **Search & Pipeline** — agentic search, batch generation, ranking
- **Dev Ops** — infrastructure, staging, deployments, CI
- **ATS Platform** — data model, architecture, platform decisions
- **Developer Tooling** — internal tools, automation
Adapt groups to whatever was actually shipped. Do not force-fit. If something doesn't fit a group, let it stand alone.
**Skip these unless the week is light on real content:**
- Dependency updates, version bumps
- Code cleanup, refactoring with no user-facing impact
- Test additions
- Linter/formatter config changes
- Minor bug fixes
### Step 5: Draft the Summary
**Title**: `Agentic Sourcing App Weekly Highlights {Mon} {Day}{ordinal}`
**Critical rules — read these before writing:**
1. **UNDERSTATE, never overstate.** Senior leaders read this. Getting caught overstating kills credibility. If the work is foundational, say "foundations." If it's on mock data, say "mock data." If it's not wired end-to-end, say so.
2. **Non-technical language.** The reader is a VP, not an engineer. "Database schema added" → "Tracking infrastructure set up." "Refactored query layer" → skip it or say "Search speed improvements."
3. **Qualify incomplete work honestly.** Qualifications aren't caveats — they're what makes the update credible. "Hasn't been tested end-to-end yet, but the pieces are connected" is stronger than pretending it's done. Always note gaps, blockers, and what's next.
4. **Say why, not just what.** Every bullet should connect what shipped to why it matters. Not "Nightly batch generation running in staging" — instead "Nightly batch generation is running in staging. The goal is recruiters waking up to fresh candidates every morning without doing anything." If you can't explain why a reader should care, reconsider including it.
5. **No laundry lists.** Each bullet should read like a short explanation, not a changelog entry. If a section has more than 3-4 bullets, you're listing features, not telling someone what happened. Merge related items. Bad: `"Contact actions MVP: compose email and copy phone directly from cards. Project metadata row in header. Outreach template MVP with search state polish."` Good: `"Cards are starting to feel like a real tool. Recruiters can send an email or grab a phone number without leaving the card, see previous roles, career trajectory, and AI scores inline."`
6. **Give credit.** Call out individuals with @first.last when they knocked something out of the park. Don't spray kudos everywhere — be selective and genuine.
7. **Be skimmable.** Each group gets a bold header + 2-4 bullet points max. Each bullet is 1-3 lines. The whole message should take 60 seconds to read.
8. **No corporate speak.** No "leveraging", "enhancing", "streamlining", "driving", "aligning", "meaningfully", "building block." Write like you're explaining what happened to someone you respect.
9. **Link tickets and PRs where they add value.** Inline link tickets where a reader might want to click through for detail: `[ZAS-123](https://discoverorg.atlassian.net/browse/ZAS-123)`. Link PRs when they represent significant standalone work. Don't link every single one — just where it helps.
10. **This is a first draft, not the final product.** Optimize for editability. Get the structure, facts, and links right. Keep the voice close. The human will sharpen it before sharing.
**Format:**
```
Agentic Sourcing App Weekly Highlights {date}
**{Group Name}** {optional — short color commentary or kudos}
- {Item} — {what shipped, why it matters, any qualifications}
- {Item} — {context}
**{Group Name}**
- {Item}
- {Item}
{Optional closing note — kudos, callout, or one-liner}
```
### Step 6: Write to File
Save the summary:
```
~/projects/talent-engine/docs/weekly-shipped-{YYYY-MM-DD}.md
```
Where the date is this Friday's date. The file is plain markdown optimized for copy-pasting into Slack.
### Step 7: Present and Confirm
Display the full summary to the user. Ask:
> Here's the weekly shipped summary. Anything to adjust, add, or cut before you share it?
Wait for confirmation before considering the skill complete.
## Troubleshooting
**gh auth issues**: If `GH_HOST=git.zoominfo.com gh` fails, check that `gh auth status --hostname git.zoominfo.com` shows an authenticated session.
**Jira returns no results**: Try broadening the JQL — drop the `resolved` filter and use `status = Done AND updated >= "{LAST_FRIDAY}"` instead. Some tickets may not have the resolution date set.
**Few PRs found**: Some repos may use squash merges or have PRs merged to non-default branches. Check if `--search "merged:>={LAST_FRIDAY}"` needs adjustment.