From e656bb7d7de32c52908854146889139262519ec6 Mon Sep 17 00:00:00 2001 From: Thomas Ricouard Date: Thu, 19 Mar 2026 08:52:23 +0100 Subject: [PATCH] Add more skills --- macos-menubar-tuist-app/SKILL.md | 99 +++++++++++++++++++ macos-menubar-tuist-app/agents/openai.yaml | 4 + orchestrate-batch-refactor/SKILL.md | 89 +++++++++++++++++ orchestrate-batch-refactor/agents/openai.yaml | 4 + .../references/agent-prompt-templates.md | 53 ++++++++++ .../references/work-packet-template.md | 31 ++++++ simplify-code/SKILL.md | 64 ++++++++++++ 7 files changed, 344 insertions(+) create mode 100644 macos-menubar-tuist-app/SKILL.md create mode 100644 macos-menubar-tuist-app/agents/openai.yaml create mode 100644 orchestrate-batch-refactor/SKILL.md create mode 100644 orchestrate-batch-refactor/agents/openai.yaml create mode 100644 orchestrate-batch-refactor/references/agent-prompt-templates.md create mode 100644 orchestrate-batch-refactor/references/work-packet-template.md create mode 100644 simplify-code/SKILL.md diff --git a/macos-menubar-tuist-app/SKILL.md b/macos-menubar-tuist-app/SKILL.md new file mode 100644 index 0000000..b6d14d6 --- /dev/null +++ b/macos-menubar-tuist-app/SKILL.md @@ -0,0 +1,99 @@ +--- +name: macos-menubar-tuist-app +description: Build, refactor, or review macOS menubar apps that use Tuist and SwiftUI. Use when creating or maintaining LSUIElement menubar utilities, defining Tuist targets/manifests, implementing model-client-store-view architecture, adding script-based launch flows, or validating reliable local build/run behavior without Xcode-first workflows. +--- + +# macos-menubar-tuist-app + +Build and maintain macOS menubar apps with a Tuist-first workflow and stable launch scripts. Preserve strict architecture boundaries so networking, state, and UI remain testable and predictable. + +## Core Rules + +- Keep the app menubar-only unless explicitly told otherwise. Use `LSUIElement = true` by default. +- Keep transport and decoding logic outside views. Do not call networking from SwiftUI view bodies. +- Keep state transitions in a store layer (`@Observable` or equivalent), not in row/view presentation code. +- Keep model decoding resilient to API drift: optional fields, safe fallbacks, and defensive parsing. +- Treat Tuist manifests as the source of truth. Do not rely on hand-edited generated Xcode artifacts. +- Prefer script-based launch for local iteration when `tuist run` is unreliable for macOS target/device resolution. + +## Expected File Shape + +Use this placement by default: + +- `Project.swift`: app target, settings, resources, `Info.plist` keys +- `Sources/*Model*.swift`: API/domain models and decoding +- `Sources/*Client*.swift`: requests, response mapping, transport concerns +- `Sources/*Store*.swift`: observable state, refresh policy, filtering, caching +- `Sources/*Menu*View*.swift`: menu composition and top-level UI state +- `Sources/*Row*View*.swift`: row rendering and lightweight interactions +- `run-menubar.sh`: canonical local restart/build/launch path +- `stop-menubar.sh`: explicit stop helper when needed + +## Workflow + +1. Confirm Tuist ownership +- Verify `Tuist.swift` and `Project.swift` (or workspace manifests) exist. +- Read existing run scripts before changing launch behavior. + +2. Probe backend behavior before coding assumptions +- Use `curl` to verify endpoint shape, auth requirements, and pagination behavior. +- If endpoint ignores `limit/page`, implement full-list handling with local trimming in the store. + +3. Implement layers from bottom to top +- Define/adjust models first. +- Add or update client request/decoding logic. +- Update store refresh, filtering, and cache policy. +- Wire views last. + +4. Keep app wiring minimal +- Keep app entry focused on scene/menu wiring and dependency injection. +- Avoid embedding business logic in `App` or menu scene declarations. + +5. Standardize launch ergonomics +- Ensure run script restarts an existing instance before relaunching. +- Ensure run script does not open Xcode as a side effect. +- Use `tuist generate --no-open` when generation is required. + +## Validation Matrix + +Run validations after edits: + +```bash +TUIST_SKIP_UPDATE_CHECK=1 tuist build --configuration Debug +``` + +If launch workflow changed: + +```bash +./run-menubar.sh +``` + +If shell scripts changed: + +```bash +bash -n run-menubar.sh +bash -n stop-menubar.sh +./run-menubar.sh +``` + +## Failure Patterns and Fix Direction + +- `tuist run` cannot resolve the macOS destination: +Use run/stop scripts as canonical local run path. + +- Menu UI is laggy or inconsistent after refresh: +Move derived state and filtering into the store; keep views render-only. + +- API payload changes break decode: +Relax model decoding with optional fields and defaults, then surface missing data safely in UI. + +- Feature asks for quick UI patch: +Trace root cause in model/client/store before changing row/menu presentation. + +## Completion Checklist + +- Preserve menubar-only behavior unless explicitly changed. +- Keep network and state logic out of SwiftUI view bodies. +- Keep Tuist manifests and run scripts aligned with actual build/run flow. +- Run the validation matrix for touched areas. +- Report concrete commands run and outcomes. diff --git a/macos-menubar-tuist-app/agents/openai.yaml b/macos-menubar-tuist-app/agents/openai.yaml new file mode 100644 index 0000000..a235c1b --- /dev/null +++ b/macos-menubar-tuist-app/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "macOS Menubar Tuist App" + short_description: "Tuist-first macOS menubar app build and maintenance" + default_prompt: "Use $macos-menubar-tuist-app to scaffold or refactor a menubar-only macOS app with Tuist, layered state architecture, and script-based run validation." diff --git a/orchestrate-batch-refactor/SKILL.md b/orchestrate-batch-refactor/SKILL.md new file mode 100644 index 0000000..91935ef --- /dev/null +++ b/orchestrate-batch-refactor/SKILL.md @@ -0,0 +1,89 @@ +--- +name: "orchestrate-batch-refactor" +description: "Plan and execute large refactor or rewrite efforts efficiently with parallel multi-agent analysis and implementation. Use when a user asks to refactor many files, split workstreams, analyze a target code area, and coordinate sub-agents with clear ownership and dependency-aware execution." +--- + +# Orchestrate Batch Refactor + +## Overview + +Use this skill to run high-throughput refactors safely. +Analyze scope in parallel, synthesize a single plan, then execute independent work packets with sub-agents. + +## Inputs + +- Repo path and target scope (paths, modules, or feature area) +- Goal type: refactor, rewrite, or hybrid +- Constraints: behavior parity, API stability, deadlines, test requirements + +## When to Use Parallelization + +- Use this skill for medium/large scope touching many files or subsystems. +- Skip multi-agent execution for tiny edits or highly coupled single-file work. + +## Core Workflow + +1. Define scope and success criteria. + - List target paths/modules and non-goals. + - State behavior constraints (for example: preserve external behavior). +2. Run parallel analysis first. + - Split target scope into analysis lanes. + - Spawn `explorer` sub-agents in parallel to analyze each lane. + - Ask each agent for: intent map, coupling risks, candidate work packets, required validations. +3. Build one dependency-aware plan. + - Merge explorer output into a single work graph. + - Create work packets with clear file ownership and validation commands. + - Sequence packets by dependency level; run only independent packets in parallel. +4. Execute with worker agents. + - Spawn one `worker` per independent packet. + - Assign explicit ownership (files/responsibility). + - Instruct every worker that they are not alone in the codebase and must ignore unrelated edits. +5. Integrate and verify. + - Review packet outputs, resolve overlaps, and run validation gates. + - Run targeted tests per packet, then broader suite for integrated scope. +6. Report and close. + - Summarize packet outcomes, key refactors, conflicts resolved, and residual risks. + +## Work Packet Rules + +- One owner per file per execution wave. +- No parallel edits on overlapping file sets. +- Keep packet goals narrow and measurable. +- Include explicit done criteria and required checks. +- Prefer behavior-preserving refactors unless user explicitly requests behavior change. + +## Planning Contract + +Every packet must include: + +1. Packet ID and objective. +2. Owned files. +3. Dependencies (none or packet IDs). +4. Risks and invariants to preserve. +5. Required checks. +6. Integration notes for main thread. + +Use [`references/work-packet-template.md`](references/work-packet-template.md) for the exact shape. + +## Agent Prompting Contract + +- Use the prompt templates in [`references/agent-prompt-templates.md`](references/agent-prompt-templates.md). +- Explorer prompts focus on analysis and decomposition. +- Worker prompts focus on implementation and validation with strict ownership boundaries. + +## Safety Guardrails + +- Do not start worker execution before plan synthesis is complete. +- Do not parallelize across unresolved dependencies. +- Do not claim completion if any required packet check fails. +- Stop and re-plan when packet boundaries cause repeated merge conflicts. + +## Validation Strategy + +Run in this order: + +1. Packet-level checks (fast and scoped). +2. Cross-packet integration checks. +3. Full project safety checks when scope is broad. + +Prefer fast feedback loops, but never skip required behavior checks. diff --git a/orchestrate-batch-refactor/agents/openai.yaml b/orchestrate-batch-refactor/agents/openai.yaml new file mode 100644 index 0000000..2e838c6 --- /dev/null +++ b/orchestrate-batch-refactor/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Batch Refactor Orchestrator" + short_description: "Plan and parallelize large refactors safely." + default_prompt: "Use $orchestrate-batch-refactor to analyze target scope, plan parallel workstreams, and execute multi-agent refactors safely." diff --git a/orchestrate-batch-refactor/references/agent-prompt-templates.md b/orchestrate-batch-refactor/references/agent-prompt-templates.md new file mode 100644 index 0000000..04ac091 --- /dev/null +++ b/orchestrate-batch-refactor/references/agent-prompt-templates.md @@ -0,0 +1,53 @@ +# Agent Prompt Templates + +Use these templates when spawning sub-agents. + +## Explorer Prompt Template + +``` +Analyze the target scope and return decomposition guidance only. + +Scope: +- Paths/modules: +- Goal: +- Constraints: + +Return: +1. Intent map (what each area currently does) +2. Coupling and dependency risks +3. Candidate work packets with non-overlapping ownership +4. Validation commands per packet +5. Recommended execution order +``` + +## Worker Prompt Template + +``` +You own this packet and are not alone in the codebase. +Ignore unrelated edits by others and do not touch files outside ownership. + +Packet: +- ID: +- Objective: +- Owned files: +- Dependencies already completed: +- Invariants to preserve: +- Required checks: + +Execution requirements: +1. Implement only the packet objective. +2. Preserve specified invariants and external behavior. +3. Run required checks and report exact results. +4. Summarize changed files and any integration notes. +``` + +## Main Thread Synthesis Prompt Template + +``` +Merge explorer outputs into a single dependency-aware plan. +Produce: +1. Packet table with ownership and dependencies +2. Parallel execution waves (no overlap per wave) +3. Validation matrix by packet and integration stage +4. Risk list with mitigation actions +``` diff --git a/orchestrate-batch-refactor/references/work-packet-template.md b/orchestrate-batch-refactor/references/work-packet-template.md new file mode 100644 index 0000000..751bf00 --- /dev/null +++ b/orchestrate-batch-refactor/references/work-packet-template.md @@ -0,0 +1,31 @@ +# Work Packet Template + +Use this template to define each packet before spawning workers. + +## Packet + +- `id`: +- `objective`: +- `mode`: `refactor` | `rewrite` | `hybrid` +- `owner_agent_type`: `worker` +- `owned_files`: +- `dependencies`: +- `invariants_to_preserve`: +- `out_of_scope`: +- `required_checks`: +- `integration_notes`: +- `done_criteria`: + +## Example + +- `id`: `P3` +- `objective`: "Extract duplicated parsing logic from thread reducers into shared helper" +- `mode`: `refactor` +- `owner_agent_type`: `worker` +- `owned_files`: `src/features/threads/hooks/threadReducer/*.ts` +- `dependencies`: `P1` +- `invariants_to_preserve`: "Thread ordering and hidden-thread filtering behavior" +- `out_of_scope`: "UI rendering components" +- `required_checks`: `npm run typecheck`, `npm run test -- src/features/threads/hooks` +- `integration_notes`: "Main thread verifies no overlapping helper names with existing util package" +- `done_criteria`: "No duplicated parsing block remains; all required checks pass" diff --git a/simplify-code/SKILL.md b/simplify-code/SKILL.md new file mode 100644 index 0000000..7d836a8 --- /dev/null +++ b/simplify-code/SKILL.md @@ -0,0 +1,64 @@ +--- +name: simplify-code +description: "Run a multi-agent review of changed files for reuse, quality, efficiency, and clarity issues followed by automated fixes. Use when the user asks to \"simplify code\", \"review changed code\", \"check for code reuse\", \"review code quality\", \"review efficiency\", \"simplify changes\", \"clean up code\", \"refactor changes\", or \"run simplify\"." +--- + +# Simplify Code + +Review all changed files for reuse, quality, and efficiency. Fix any issues found. + +## Step 1: Determine the Diff Command + +Determine the appropriate diff command (e.g. `git diff`, `git diff --cached`, `git diff HEAD`) based on the current git state. If the caller specifies which diff command to use, use that. Do NOT run the diff yourself — each review agent will run it independently to keep the diff out of the main agent's context. + +If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation. + +## Step 2: Launch Four Review Agents in Parallel + +Use the Agent tool to launch all four agents in a single message (`model: "opus"`, do not set `run_in_background`). Instruct each agent to run the diff command itself to obtain the diff. + +### Agent 1: Code Reuse Review + +For each change: + +1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones. +2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead. +3. **Flag any inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates. + +### Agent 2: Code Quality Review + +Review the same changes for hacky patterns: + +1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls +2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones +3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction +4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries +5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase +6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior + +### Agent 3: Efficiency Review + +Review the same changes for efficiency: + +1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns +2. **Missed concurrency**: independent operations run sequentially when they could run in parallel +3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths +4. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error +5. **Memory**: unbounded data structures, missing cleanup, event listener leaks +6. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one + +### Agent 4: Clarity and Standards Review + +Review the same changes for clarity, standards, and balance: + +1. **Project standards**: coding conventions from CLAUDE.md not followed — import sorting, naming conventions, component patterns, error handling patterns, module style +2. **Unnecessary complexity**: deep nesting, redundant abstractions, unclear variable or function names, comments that describe obvious code, nested ternary operators (prefer switch/if-else chains) +3. **Unclear code**: choose clarity over brevity — explicit code is better than overly compact code. Consolidate related logic, but not at the cost of readability +4. **Over-simplification**: overly clever solutions that are hard to understand, too many concerns combined into single functions or components, "fewer lines" prioritized over readability (dense one-liners, nested ternaries), helpful abstractions removed that were aiding code organization +5. **Dead weight**: unnecessary comments, redundant code, abstractions that add indirection without value + +## Step 3: Fix Issues + +Wait for all four agents to complete. Aggregate their findings, run the diff command to get the current diff, then apply each fix directly, skipping false positives. Only edit files — do not stage, build, or test. + +When done, briefly summarize what was fixed (or confirm the code was already clean).