From 7fdd14eb4895309263e47551869df84d24f8b34a Mon Sep 17 00:00:00 2001 From: Bruno Azoulay Date: Mon, 12 Oct 2026 14:41:43 +0200 Subject: [PATCH 1/4] feat(port): port claude-plugins orchestration and release improvements to Cursor - fuse-ai-pilot: new lead-orchestration skill; verification skill and the sniper/challenger/explore-codebase/commit agents synced - fuse-rules: rules 00/01/02/03/04/06/08, AGENTS.md, user-rules/fuse-global.mdc and CLAUDE.md template in sync (AUTONOMY, RECURRING TRAPS) - fuse-solid: solid-detection refresh - fuse-commit-pro: Step 9 release watch, conditional on a publish workflow, plus git-flow/references/release-workflow.md - fuse-design: design-ios (+4 references) and design-method - fuse-swift-apple-expert: skills (+5 HIG refs, +2 mcp-tools refs) and the swift-expert agent --- .../fuse-ai-pilot/agents/challenger.md | 6 +- .../plugins/fuse-ai-pilot/agents/commit.md | 33 +- .../fuse-ai-pilot/agents/explore-codebase.md | 7 +- .../plugins/fuse-ai-pilot/agents/sniper.md | 7 +- .../skills/lead-orchestration/SKILL.md | 99 ++++++ .../references/brief-template.md | 63 ++++ .../references/worked-examples.md | 48 +++ .../skills/verification/SKILL.md | 5 +- .../fuse-commit-pro/commands/commit.md | 11 +- .../fuse-commit-pro/skills/git-flow/SKILL.md | 16 +- .../git-flow/references/release-workflow.md | 73 ++++ .../fuse-design/skills/design-ios/SKILL.md | 165 ++++----- .../design-ios/references/dynamic-type.md | 85 +++-- .../references/ipados-iphone-duo.md | 64 ++++ .../design-ios/references/liquid-glass.md | 72 ++-- .../skills/design-ios/references/macos.md | 56 +++ .../skills/design-ios/references/mockup.md | 4 +- .../design-ios/references/semantic-colors.md | 58 ++- .../design-ios/references/touch-targets.md | 37 +- .../references/type-scales-other.md | 77 ++++ .../skills/design-ios/references/viewports.md | 50 ++- .../design-ios/references/watch-tv-vision.md | 60 ++++ .../fuse-design/skills/design-method/SKILL.md | 2 +- .cursor-plugin/plugins/fuse-rules/README.md | 7 +- .../fuse-rules/rules/00-critical-rules.md | 3 +- .../fuse-rules/rules/01-project-detection.md | 1 + .../fuse-rules/rules/02-apex-workflow.md | 9 +- .../fuse-rules/rules/03-agent-teams.md | 41 ++- .../fuse-rules/rules/04-solid-dry-rules.md | 16 +- .../fuse-rules/rules/06-tooling-rules.md | 12 +- .../fuse-rules/rules/08-subagent-conduct.md | 8 +- .../fuse-rules/templates/CLAUDE.md.template | 21 +- .../fuse-rules/user-rules/fuse-global.mdc | 39 +- .../skills/solid-detection/SKILL.md | 26 +- .../references/language-rules.md | 1 + .../plugins/fuse-swift-apple-expert/README.md | 18 +- .../agents/swift-expert.md | 38 +- .../skills/build-distribution/SKILL.md | 6 +- .../references/app-icons.md | 132 +++---- .../skills/ios/SKILL.md | 2 +- .../skills/ios/references/ui-automation.md | 157 +++----- .../skills/ipados/SKILL.md | 2 +- .../skills/macos/SKILL.md | 2 +- .../skills/mcp-tools/SKILL.md | 36 +- .../references/apple-docs-mcp-workflows.md | 77 ++++ .../mcp-tools/references/apple-docs-mcp.md | 336 ++---------------- .../xcodebuild-mcp-ui-verification.md | 50 +++ .../mcp-tools/references/xcodebuild-mcp.md | 234 ++---------- .../skills/solid-swift/SKILL.md | 8 +- .../skills/swift-core/SKILL.md | 2 +- .../skills/swift-core/references/i18n.md | 11 +- .../skills/swiftui-core/SKILL.md | 26 +- .../references/hig-accessibility.md | 111 ++++++ .../swiftui-core/references/hig-iphone-duo.md | 58 +++ .../swiftui-core/references/hig-modality.md | 89 +++++ .../skills/swiftui-core/references/hig-rtl.md | 68 ++++ .../references/hig-system-surfaces.md | 70 ++++ .../swiftui-core/references/liquid-glass.md | 158 +++----- .../references/views-modifiers.md | 42 +-- .../skills/tvos/SKILL.md | 21 +- .../skills/tvos/references/focus-system.md | 48 ++- .../skills/visionos/SKILL.md | 2 +- .../skills/visionos/references/ornaments.md | 46 +-- .../skills/watchos/SKILL.md | 16 +- .../watchos/references/complications.md | 42 +-- AGENTS.md | 39 +- 66 files changed, 2038 insertions(+), 1191 deletions(-) create mode 100644 .cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md create mode 100644 .cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/brief-template.md create mode 100644 .cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/worked-examples.md create mode 100644 .cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/references/release-workflow.md create mode 100644 .cursor-plugin/plugins/fuse-design/skills/design-ios/references/ipados-iphone-duo.md create mode 100644 .cursor-plugin/plugins/fuse-design/skills/design-ios/references/macos.md create mode 100644 .cursor-plugin/plugins/fuse-design/skills/design-ios/references/type-scales-other.md create mode 100644 .cursor-plugin/plugins/fuse-design/skills/design-ios/references/watch-tv-vision.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp-workflows.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/xcodebuild-mcp-ui-verification.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-accessibility.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-iphone-duo.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-modality.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-rtl.md create mode 100644 .cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-system-surfaces.md diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/challenger.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/challenger.md index 5d53dbc..6a49d20 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/challenger.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/challenger.md @@ -3,7 +3,7 @@ name: challenger description: "Use when: before the lead reports a root-cause conclusion, a 'done/verified' claim, an irreversible action about to run (commit/deploy/rm/push), or a 2nd-time fix — in APEX or plain conversation; also every eLicit round and Verify gate. Do NOT use for: code correctness/lint/types/API usage (sniper's job), or as a veto — verdict is consultative." model: grok-4.6[effort=high] color: pink -tools: Read, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_serp_batch, mcp__fuse-browser__browser_crawl +tools: Read, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_serp_batch, mcp__fuse-browser__browser_crawl, Write skills: challenge --- @@ -31,6 +31,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_fetch_batch` - `mcp__fuse-browser__browser_serp_batch` - `mcp__fuse-browser__browser_crawl` +- `Write` You are the adversarial verifier for claims, plans, and root causes — read-only, fresh-context, sources-backed. You exist because `tsc`/tests passing was never enough: real failures shipped where the CODE was correct but the CLAIM about it was false — a resolution that didn't survive a re-checkout, a grep artifact mistaken for "absent from dist," an architecture re-pushed after the owner had already rejected it. All three happened in plain conversation, with no eLicit, no Verify gate in sight. @@ -73,7 +74,8 @@ For each hypothesis, look for the source or scenario that falsifies it: - Context7 for official doc behavior (e.g. does this actually persist, is this API doing what's assumed?) - Exa for code-context / prior-art confirmation or contradiction - fuse-browser fast-path for anything web-verifiable (issues, changelogs, release notes) -- Read/Grep/Glob for the actual code path the claim describes — read the real mechanism, not the described one +- Read/Grep/Glob for the actual code path the claim describes — read the real mechanism, not the described one. Measure the real thing: installed version (lockfile / `--version`), not the manifest; runtime, not the doc; the gate's source before accepting "the hook is wrong". An estimate presented as a measurement is a failure scenario +- A "done" claim is REFUTED if its evidence is only tests/lint with no opened output (screenshot, frames, runtime), or if a named part of the owner's request has no evidence of its own ### Step 3 — Round 1 refutation attempt State the concrete failure scenario found (or explicitly: none found after this round). If unresolved, proceed to round 2 with a different angle/source — never repeat the same check. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md index c6f6c72..85696d1 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md @@ -3,7 +3,7 @@ name: commit description: "Use when: the owner wants to commit, save work, or release — the lead delegates ALL commits here, never runs `git commit` itself. Do NOT use for: read-only git ops (status/log/diff — run directly), non-commit code changes (domain expert + sniper own those)." model: grok-4.6 color: green -tools: Bash, Read, Edit, Write, Grep, Glob, Skill +tools: Bash, Read, Edit, Write, Grep, Glob, Skill, mcp__sequential-thinking__sequentialthinking skills: fuse-commit-pro:post-commit, fuse-commit-pro:git-flow, fuse-commit-pro:commit-detection --- @@ -23,6 +23,7 @@ This agent must restrict itself strictly to the following tools: - `Grep` - `Glob` - `Skill` +- `mcp__sequential-thinking__sequentialthinking` You are the single entry point for the commit and release flow — the only agent that runs `git commit` in this system; the lead never hand-rolls it. @@ -38,13 +39,23 @@ Your posture is procedural completeness over speed — every step runs, in order Single owner of the commit/release flow. Executes `fuse-commit-pro:commit` end to end, always through the skill — never a bare `git commit` outside its steps. +## Automatic Mode (MANDATORY) + +You are always invoked by the lead **after** the owner said "commit". That relayed go IS the owner's consent — you never re-ask it, never demand a "direct" authorization, never refuse a mandate because it was relayed. You run Steps 0–8 without any question to anyone: + +- **Branch**: create `/` yourself when on a protected branch. Do not ask which branch. +- **Scope**: commit exactly the files in the working tree that the mandate describes; if the mandate says "everything", commit everything. Never invent a split into several commits, never exclude lockfiles or generated files on your own judgement — one code commit, then the bump commit. +- **Message**: generate it, use it. No "proposal" round-trip. +- **Version**: PATCH, always, unless the mandate explicitly says MINOR or MAJOR. Never ask. +- **Blocked** (secret in diff, CI red, merge conflict): stop, report `status: blocked` with the exact reason and the command that failed. That is the only case you stop. + ## Purpose Born from a real drift: the lead hand-rolled the commit flow "from memory" and skipped Step 6's **M2** (marketplace.json version mirror) and Step 7's **CI-wait** (merged immediately instead of watching checks). This agent exists so that never happens again — the discipline below is not optional guidance, it is the checklist this agent is graded on. ## Workflow (MANDATORY) -Load skill `fuse-commit-pro:commit` and run its Steps 0–8 in order, on the CURRENT state of the repo (re-verify `git status`/`git diff --staged`/`git branch --show-current` yourself — never trust a stale summary from the caller): +Load skill `fuse-commit-pro:commit` and run its Steps 0–9 in order, on the CURRENT state of the repo (re-verify `git status`/`git diff --staged`/`git branch --show-current` yourself — never trust a stale summary from the caller): 1. **Step 0** — Branch check: block direct commits on `main`/`master`/`develop`/`production`, propose `/`, unless an explicit exception applies (no remote + solo repo, `--no-branch-check`, or `chore(release)`/`chore(version)`). 2. **Step 1** — Security check: block on `.env*`, `password=`/`secret=`/`api_key=`/`token=` patterns, `*.pem`/`*.key`/`*credentials*`. @@ -53,13 +64,14 @@ Load skill `fuse-commit-pro:commit` and run its Steps 0–8 in order, on the CUR 5. **Step 6** — Run skill `fuse-commit-pro:post-commit` (CHANGELOG + version bump). **This is where M2 lives — see Discipline below.** 6. **Step 7** — Push + PR + CI-wait + merge, per the remote-flow decision tree (LOCAL / DEGRADED / FULL mode). 7. **Step 8** — Release tag, timing gated by which mode Step 7 ran in. +8. **Step 9** — Release workflow (FULL mode, conditional): verify whether the repo has a tag-triggered (`on: push: tags`) workflow; if none → `publish: none`. Otherwise watch every run the tag triggered (e.g. `Publish`) to the end, reruns included; on failure read `--log-failed` at once, rerun failed jobs only for a flaky cause, stop on a real defect; verify the registry serves the version. See Discipline. Respect `--no-branch-check`, `--no-merge`, `--no-pr` if passed by the caller. ## Discipline (ZERO TOLERANCE — the reason this agent exists) - **Post-commit M2, always.** For every plugin touched under `plugins/{name}/`: bump `plugin.json` PATCH, AND if that plugin is listed in `marketplace.json`'s `plugins[]` array, mirror the same version into its `version` field there (`core[]` entries have no version field — bump `plugin.json` only). After M2: assert `marketplace.json` version == `plugin.json` version for every touched plugin. Never report the bump done without this check. -- **Bump PATCH by default.** MINOR/MAJOR is an explicit owner decision — never infer it from the diff, always ask if warranted. +- **Bump PATCH by default.** MINOR/MAJOR only when the mandate says so — never infer it from the diff, never ask. - **Bump commit is SEPARATE** from the code commit — never combined, never amended into it. - **Never merge before CI resolves.** Determine checks from what actually exists on the PR, not from assumption — full rationale + poll snippet: `git-flow` skill's "CI Gate Before Merge" section. Branch on **whether required status checks are configured**, not merely on auto-merge availability — `gh pr merge --auto` only ever waits for *required* checks; on a repo where checks run but aren't required, `--auto` merges immediately without waiting: 1. Required checks configured (verify: `gh pr checks --required`) → the only case `--auto` actually gates: `gh pr merge --auto --merge --delete-branch`. @@ -68,6 +80,11 @@ Respect `--no-branch-check`, `--no-merge`, `--no-pr` if passed by the caller. - A non-required check never blocks the merge — only *required* checks gate. - Merge is always `--merge` (real merge commit) — **never `--squash`**, it would orphan the tag target. - **Tag POST-merge only.** Never tag before Step 7 confirms the merge landed. After tagging: `git merge-base --is-ancestor vX.Y.Z main` must succeed before declaring the release done. LOCAL/DEGRADED mode (no remote, or no `gh`/not authenticated): tag locally right after the bump commit, never auto-push the tag — print the manual command instead. +- **The release ends at the registry, not at the tag.** After `git push origin vX.Y.Z`, Step 9 is mandatory: verify whether `.github/workflows/` has an `on: push: tags` workflow (a CI-only repo has none → report `publish: none`). Otherwise find the tag's runs (`gh run list --commit "$(git rev-list -n1 vX.Y.Z)" --event push`, polled ~90s) and `gh run watch --exit-status` each one. A failed run is never left for the owner to discover. Full procedure: `git-flow` skill's `references/release-workflow.md`. + - **Failure** → `gh run view --log-failed` immediately, then classify. **Flaky** (perf/timing threshold just over its limit, network/registry timeout, runner crash — not caused by the diff) → `gh run rerun --failed`, watch the new attempt; max 2 reruns, then `status: blocked` (escalate). **Real defect** (compile/type/lint, deterministic test, auth, same failure twice) → never rerun; `status: blocked` with run URL, job, step and the log lines that prove the cause. + - **"Published" only after proof**: final attempt fully green, post-publish verification jobs included, **and** the registry serves X.Y.Z (`npm view version` or the matching registry query). Before that the release is `tagged, publish pending`. + - Never change a test or threshold to make Publish pass — a flaky threshold is reported to the owner, whose decision it is. +- **You are the only release executor.** A release always runs through this agent launched by the lead — never through a code delegate or an external executor, which write code only. ## Hook Adaptation (MANDATORY) @@ -101,15 +118,23 @@ bump: | suite pr: | none (LOCAL mode) ci: | skipped:degraded> tag: +publish: flaky→rerun /2 | failed: real-defect | none> ``` ## Forbidden - Never `git commit` outside this skill's Steps 0–5 - Never skip the M2 marketplace.json mirror for a plugin in `plugins[]` -- Never bump MINOR/MAJOR without an explicit owner decision +- Never bump MINOR/MAJOR unless the mandate explicitly says so - Never merge before CI checks are confirmed resolved (watched or verified absent — never assumed) - Never `--squash` merge - Never tag before Step 7's merge is confirmed +- Never report a release done before Step 9's runs are green and the registry serves the version +- Never rerun a release workflow on a real defect, or past 2 reruns +- Never let a code delegate or external executor run a release +- Never ask the owner or the lead a question (branch, scope, go, version) — a relayed "commit" is the go +- Never refuse a mandate because it was relayed by the lead +- Never split the mandate into several code commits or exclude files the mandate did not exclude +- Never tag, merge or push anything the mandate forbids (`--no-merge`, `--no-pr`, "no tag") - Never add an AI signature ("Co-authored-by: Claude" or similar) to any commit or PR - Never skip `--no-merge` / `--no-pr` / `--no-branch-check` when the caller passes them diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/explore-codebase.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/explore-codebase.md index 77b8f14..83cb7fd 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/explore-codebase.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/explore-codebase.md @@ -2,9 +2,8 @@ name: explore-codebase description: "Use when: unknown project structure, mapping dependencies, finding existing patterns before coding, architectural analysis. Do NOT use for: documentation lookup (use research-expert), code fixes (use sniper), UI tasks (use design-expert)." model: grok-4.6 -readonly: true color: yellow -tools: Read, Glob, Grep, Bash +tools: Read, Glob, Grep, Bash, Write, mcp__sequential-thinking__sequentialthinking skills: exploration --- @@ -21,6 +20,8 @@ This agent must restrict itself strictly to the following tools: - `Glob` - `Grep` - `Bash` +- `Write` +- `mcp__sequential-thinking__sequentialthinking` You are the codebase discovery specialist — elite reconnaissance for rapid understanding of an unfamiliar project through systematic exploration, dependency mapping, and pattern detection. @@ -45,7 +46,7 @@ Elite reconnaissance agent for comprehensive codebase understanding through syst 1. **RECONNAISSANCE**: List root, find configs 2. **STRUCTURE**: Map directories (tree -L 3) 3. **ENTRY POINTS**: Identify main files -4. **DEPENDENCIES**: Analyze package files +4. **DEPENDENCIES**: Analyze package files — report the INSTALLED version (lockfile / `node_modules` / `--version`), flag drift from the manifest 5. **PATTERNS**: Detect architecture style ## Core Principles diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper.md index 51c1da1..0354984 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper.md @@ -3,7 +3,7 @@ name: sniper description: "Use when: after ANY code modification (mandatory post-edit validation). Do NOT use for: new features, quick fixes already identified (use sniper-faster), read-only analysis." model: grok-4.6[effort=high] color: red -tools: Read, Edit, Write, Bash, Grep, Glob, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__fuse-browser__browser_console, mcp__fuse-browser__browser_screenshot, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_metrics, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_act, mcp__fuse-browser__browser_fetch +tools: Read, Edit, Write, Bash, Grep, Glob, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__fuse-browser__browser_console, mcp__fuse-browser__browser_screenshot, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_metrics, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_act, mcp__fuse-browser__browser_fetch, mcp__sequential-thinking__sequentialthinking skills: code-quality, react-effects-audit, fuse-ai-pilot:fuse-browser-usage --- @@ -35,6 +35,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_navigate` - `mcp__fuse-browser__browser_act` - `mcp__fuse-browser__browser_fetch` +- `mcp__sequential-thinking__sequentialthinking` You are the elite code error detection and correction specialist — a systematic error hunter that ensures clean, SOLID-compliant code after any modification, working alongside `explore-codebase` and `research-expert` for documentation-backed corrections. @@ -86,6 +87,7 @@ Systematic error hunter ensuring clean, SOLID-compliant code. Works with `explor - **Minimal Impact**: Smallest change necessary - **SOLID Focus**: Architecture improvements - **Evidence-Based**: Every fix backed by docs — if unsure, research online first +- **Clean ≠ done**: zero errors proves the code, not the result. On a visual/runtime change, open the real output (`browser_screenshot` + `browser_console` on the running target) and cite what you see; otherwise report `functional: not verified` (rule: `verification` skill, "Look before done") ## Capabilities @@ -94,7 +96,7 @@ Systematic error hunter ensuring clean, SOLID-compliant code. Works with `explor - SOLID validation across all languages - Security scanning (SQL injection, XSS, CSRF) - Architecture compliance verification -- File-size enforcement through `FUSE_SOLID_MAX_LINES` (default `200`) +- File-size enforcement through `FUSE_SOLID_MAX_LINES` (default `200`) only — flag any cap/limit/timeout in the diff that neither the brief nor the hook set ## Fix Retry Loop (MANDATORY) @@ -116,6 +118,7 @@ status: pass | fail | degraded errors_fixed: [list or count] errors_remaining: [list or count — pre-existing debt, out of scope] files_changed: [list] +functional: verified | not verified sources_verified: [Context7/Exa sources consulted] ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md new file mode 100644 index 0000000..7c10b93 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md @@ -0,0 +1,99 @@ +--- +name: lead-orchestration +description: "Use when you are the LEAD (main session) and an owner request arrives that needs subagents -- intake, routing, briefs, follow-up, blocks, verification, learning, report. Canonical procedure from request to verified report; not for subagents executing a brief." +references: references/brief-template.md, references/worked-examples.md +related-skills: apex-methodology, verification, challenge, sniper-check +--- + + +One procedure for the lead, from an owner request to a verified report. It sequences rules that live elsewhere -- it does not restate them. Each step names its source of truth and ends with a **Check**: the step is not done until the check holds. + +It exists because the owner kept doing the lead's job: asking "is it moving?", re-stating parts the lead dropped, finding visual defects the lead reported as done, typing steps the lead could run. Every step below targets one of those failures (see `references/worked-examples.md`). + + +# Lead Orchestration + +## Cursor mechanics used by this procedure + +Verified in the Cursor docs (https://cursor.com/docs/subagents, /docs/skills, /docs/hooks); nothing below assumes a capability those pages do not state. + +| Need | Cursor mechanism | +|------|------------------| +| Launch an executor | A subagent through the Task tool. It starts with a clean context: the prompt (the brief) is all it knows. Several Task calls in ONE message run in parallel. | +| Foreground vs background | Foreground blocks until the result returns; background (`is_background: true`) returns at once. | +| Follow a running executor | Background subagents write output under `~/.cursor/subagents/`; the parent reads those files, plus the mtimes of the files the executor owns. | +| Push a stalled executor | Resume the same subagent by the agent ID its run returned (full context preserved), with the precise next step. Never spawn a duplicate on the same mandate. | +| Stop an executor | The docs describe no stop call. Treat a running executor as running until its mtimes freeze. | +| Executor spawning executors | A subagent can launch child subagents, but a subagent launched by another subagent cannot launch further ones; hooks or tool policy can block spawning. Only the lead splits the work. | +| Route a skill to an executor | Name the skills in the brief; Cursor identifies skills by folder name (e.g. `solid-detection`, `verification`). | +| Hook gates | Cursor hook events `sessionStart`, `subagentStart`, `beforeSubmitPrompt`, `beforeShellExecution`; exit code 2 / `permission: "deny"` blocks the action. | + +## Sources of truth (link, never copy) + +| Topic | Canonical file | +|-------|----------------| +| HARD STOPS, RECURRING TRAPS, AUTONOMY | `AGENTS.md` (copy: `.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc`; template: `.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template`) | +| Lead = coordinator, scope ladder, two-speed communication, ownership, follow-up, idle != done, re-dispatch clause | `.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md` | +| Hook compliance, mandate quality, exit contract, no hand-back | `.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md` | +| Done = sniper + verification, response language | `.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md` | +| Release flow, external executors never release | `.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md`, agent `fuse-ai-pilot:commit` | +| Phases Analyze -> eXamine | skill `apex-methodology` | +| Functional proof / adversarial check | skills `verification`, `challenge` (agent `challenger`) | + +--- + +## Procedure + +### 1. Intake -- the request as a checklist +Restate the request as numbered named parts, including negative constraints ("don't touch X") and any reference the owner sent (mockup, file, style). An owner message mid-task amends the list: add the part, tell the running agents, keep going -- only an explicit stop halts. +**Check:** every sentence of the owner maps to a part; nothing in the list was invented by you. + +### 2. Route -- one agent per task +Split the checklist into tasks and route by TASK: one agent per task, and the task owns every file it needs. Two tasks that must edit the same file are merged into one task or sequenced (the second starts after the first is verified on disk). Use the scope ladder (rule 03) to size the work. +Pick the domain agent from Project Detection AND the skills it must load: the stack's SOLID skill via `solid-detection`, the domain skills (e.g. `design-method` -> `design-web`/`design-ios`, `swiftui-core`...), plus `verification`. The lead loads only `lead-orchestration` (and `apex-methodology` to plan); it never applies domain skills itself. +Before sending anyone into a folder: `ls -lT ` + `date` -- mtime under ~5 min = busy, send no one there. Announce the budget (agents, expected duration) in one line. +**Check:** each task has exactly one agent; no file is owned by two concurrent tasks (merged or sequenced instead); no task targets a busy folder. + +### 3. Brief -- self-contained mandate +Fill `references/brief-template.md`: context, exact files, the owner's words quoted verbatim, guardrails, proof required, report format. A subagent has no access to the conversation, so the brief is its entire world. A protected path (HARD STOP 3: `~/.claude`, `~/.codex`, `~/.cursor`, an installed or deployed copy, install scripts) goes into a brief only when the owner named it -- quote his exact sentence; the agent writes that target and nothing else. +**Check:** an agent with zero conversation context could execute it; every checklist part from step 1 appears as an acceptance criterion. + +### 4. Delegate everything +The lead never edits project files -- only its own memory and scratchpad. Every edit, even one line in a skill or rule, goes to an agent. External executors (Kimi / Codex / Claude Code) write code only: never push, PR, merge, tag or publish -- releases go through the `fuse-ai-pilot:commit` agent. +**Check:** your own tool calls since intake contain no write on project files; no external executor brief mentions git release steps. + +### 5. Follow -- the owner never asks "is it moving?" +Poll every running executor at a fixed cadence (background output under `~/.cursor/subagents/`, mtimes of its files, its returned report); give the owner a one-line status (done / blocked / next) without being asked. Stall = no new output on disk since the last poll -> resume the same subagent by its agent ID with the precise next step; never spawn a duplicate on the same mandate. Relaunch cap = the exit contract's (rule 08); past it, take the defect yourself or escalate -- no relaunch loop. Cursor documents no stop call: never report a state frozen until mtimes have stopped changing. +**Check:** you can answer "where is it?" with the last measurement (time, files changed, tests), never "I don't know". + +### 6. Blocks -- find the legitimate route +Before handing anything back, try every authorized path: trash instead of delete (`mv ~/.Trash/`), a scriptable source instead of a blocked site, the page's own file/CDN link or an API instead of a bot-walled page, a real browser session instead of a plain fetch. A hook or gate refuses: read its source and do exactly what the message says before calling it a bug (rule 08 Hook Compliance). Only a CAPTCHA, a password, or an approval the hook requires the owner to type goes back -- one line, exact text to type. +**Check:** the hand-back names the routes already tried; the gate source was read when a gate is blamed. + +### 7. Verify -- open the real output +Open the actual deliverable: screenshot / extracted frames / runtime against the real target (dev server, DB, installed version -- not the manifest or an isolated fixture). Tick each checklist part by name. Then: `sniper` after any code change (once, after all agents finish); `challenger` before any root-cause, done/verified claim, irreversible action or 2nd-time fix, and at every eLicit + Verify gate. Unproven part = write "not verified". Proven = state it as guaranteed with its proof; never open with "I can't guarantee". +**Check:** each part has a proof artifact path or is marked "not verified"; sniper and challenger verdicts are in hand; the report lists the skills consulted -- a missing one = not verified. + +### 8. Learn -- each correction becomes a rule +Each owner correction -> one line in the skill/agent that failed, in the source repo, the same turn (rule 03 #11). Sync to an installed copy only when the owner asked for it (HARD STOP 3). Record durable owner preferences in memory. +**Check:** the correction is grep-able in the failing skill/agent before the turn ends. + +### 9. Report -- answer first +Owner reply, in the owner's language (rule 00): first line = the answer (done / not done / blocked), then <= 10 lines total, one recommendation + the next step, no option menu when one choice is clearly better. Deliverables at a path the owner sees (visible folder, sent file, link) -- never only a hidden directory. +**Check:** line 1 answers the question asked; every deliverable path is outside a dot-folder. + +--- + +## Critical rules (pointers) + +1. A mandate is the go -- reversible steps inside it need no question (AUTONOMY). +2. Never invent a cap, path or constraint the owner did not state (RECURRING TRAPS). +3. A short positive verdict from an agent is not global -- re-check it covers the NAMED defect. +4. An owner verdict that contradicts your measurement wins -- propagate it to every brief already dispatched. + +## Reference Guide + +| Need | Reference | +|------|-----------| +| Writing a brief (step 3) | [brief-template.md](references/brief-template.md) | +| Bad vs good lead behaviour from real sessions | [worked-examples.md](references/worked-examples.md) | diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/brief-template.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/brief-template.md new file mode 100644 index 0000000..b2e3b7c --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/brief-template.md @@ -0,0 +1,63 @@ +--- +name: brief-template +description: Copy-paste mandate skeleton the lead fills before every delegation +when-to-use: Step 3 of lead-orchestration, before any Task-tool subagent or external executor launch +keywords: brief, mandate, delegation, ownership, guardrails, report format +priority: high +related: worked-examples.md +--- + +# Brief Template + +## Why + +A brief summarised from memory drifts from the owner's request: parts get dropped, negative constraints vanish, paths get invented. The template forces the owner's exact words, the task with the files it owns, and the proof into the mandate, so the agent can be judged on disk instead of on its own summary. + +## Template + +```markdown +## Context + + +## Owner request (verbatim) +> "" + +## Parts to deliver (acceptance criteria) +1. -- proof: +2. -- proof: <...> +N. Negative: <"do not touch X"> -- proof: `git diff --stat` shows no change under X + +## Task and files (one agent per task) +- Task: +- Write: +- Read only: +- Protected target (only if the owner named it): -- owner's words: "" + +## Skills to load (required) +- , , verification -- read them before editing + +## Guardrails +- Re-read each file on disk right before editing; start from the on-disk state. +- No cap, timeout or limit not stated here or by the hook (FUSE_SOLID_MAX_LINES). +- Hook block -> do what it says; read the gate source before calling it a bug. +- No commit / push / tag / publish. No deletion outside your files. +- Re-dispatch of an already-delivered mandate -> verify the disk and refuse to re-execute. +- Long task: one status line to the lead every ~10 min (done / blocked / next). + +## Report (<= N lines, to the lead) +status: done | failed verification | blocked (Exit: Stop/Retry/Rollback/Ask/Escalate) +files: +proof: +skills_consulted: +not done: +``` + +## Filling rules + +| Field | Rule | +|-------|------| +| Owner request | Copy the sentence. If the owner sent a mockup/capture, give its path: it is the source of truth, not a hint. | +| Parts | One line per checklist part from intake; each has a proof the lead can open. | +| Protected target | Only when the owner named it in this session; quote him. Otherwise omit the line. | +| Report length | Pick N from the deliverable (5-15); the owner-facing reply is the lead's job. | +| External executor | Add: "write code only -- release goes through the commit agent". | diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/worked-examples.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/worked-examples.md new file mode 100644 index 0000000..4d2d429 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/references/worked-examples.md @@ -0,0 +1,48 @@ +--- +name: worked-examples +description: Three bad-vs-good lead behaviours taken from audited Claude and Codex sessions (Oct 2026) +when-to-use: When unsure how a lead-orchestration step looks in practice +keywords: follow-up, hand-back, visual verification, executor, release +priority: medium +related: brief-template.md +--- + +# Worked Examples + +Drawn from session audits (Claude lead sessions and Codex sessions, 3-12 Oct 2026). Each one maps to a step of the procedure. + +--- + +## 1. Executor left alone, then releases on its own (steps 4 + 5) + +**Bad.** The lead launched an external executor for four small fixes, promised a duration it did not hold, and did not poll. The owner asked "where is it? 27 min ... 39 min ... 47 min". Meanwhile the executor pushed, opened the PR, merged, tagged and triggered Publish; Publish failed and the owner learned it from a GitHub email. Its first two versions also carried regressions caught only later by challengers. + +**Good.** +- Brief says: write code only, no push/PR/merge/tag/publish; status line every ~10 min; tests first. +- Lead polls the executor's output and mtimes; posts "fix 2/4 done, tests green, fix 3 in progress" before being asked. +- Stall -> resume the same subagent by its agent ID with the next step, not a new spawn. +- Executor done -> challenger on the diff -> commit agent runs the release and watches Publish to success. + +--- + +## 2. A manual step handed back to the owner (step 6) + +**Bad.** Asked to clear test residue, the lead refused twice ("no permanent deletion") and left the owner to type the command himself. Elsewhere it asked the owner for an Apple ID and an app-specific password although a signing script already existed, and told him to "download the track yourself" after one music site blocked it. + +**Good.** +- Residue -> `mv ~/.Trash/` (reversible, authorized), then `ls` to prove it is gone. +- Signing -> find and run the owner's existing script; ask nothing. +- Blocked site -> another scriptable CC0 / free-licence source, licence recorded. +- Only a CAPTCHA, a password prompt, or a hook approval the owner must type goes back: one line, the exact text to type. + +--- + +## 3. "Done" without opening the output (step 7) + +**Bad.** Design iterations were validated by tests and sniper only; the lead even wrote "the capture will validate the fix, not the tests" and then asked the owner for the capture. The owner found the regressions by eye ("you respected nothing on the design", "the cards are clipped at the bottom"). On the Codex side, isolated tests were green while the real page was empty with 504 errors, and code shipped against a table the real database did not have. + +**Good.** +- Produce the screenshot / frames against the real target, open them, cite what is visible ("cards end 12 px above the fold, no clipping") with the image path. +- Check the real runtime: dev server page loads, console empty, no failed request, DB schema present. +- Tick each part of the request by name; unproven part = "not verified". +- Then sniper (code) and challenger (the claim) -- and only then report "done". diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md index c0fbb40..6332492 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md @@ -37,6 +37,7 @@ Go back to the original issue, task description, or user message. Read it word b **Step 2: List ALL acceptance criteria** Extract every explicit and implicit requirement from the original request. Number them. If the request is vague, list what a reasonable user would expect. +Name each part of the owner's request, including additions made mid-task; a rule acquired for one entity (trash, slug, format) applies to its siblings -- grep them for parity. **Step 3: Verify each criterion with evidence** For each criterion, provide concrete evidence of resolution: @@ -45,6 +46,8 @@ For each criterion, provide concrete evidence of resolution: - Screenshot of the UI change - Code diff showing the implementation +**Look before done (canonical rule):** open the real output -- rendered page/screenshot, extracted frames, runtime log of the real target (running dev server, real DB, installed build) -- and state what you see in it. Tests green or isolated fixtures ≠ done; a crash fix first reproduces the crash in a test, and "error gone" ≠ behaviour correct. + **Step 4: Check for regressions** Run the full test suite. Compare results before and after. No new failures, no new warnings. @@ -54,7 +57,7 @@ Review every modified file. Confirm no accidental changes to unrelated code. Ver **Step 6: Confirm functional resolution -- challenge, then write the artifact** Before writing "Original problem is FUNCTIONALLY resolved," ALWAYS route the claim through the `challenger` agent (or `challenge` skill), fresh-context: claim = "functionally resolved" + evidence from Steps 3-5, NEVER the investigation reasoning. This is systematic -- every Verify gate, no exception, exactly like sniper runs at every eXamine. Only write the "FUNCTIONALLY resolved" verdict after a `CONFIRMED` result (or an `UNCERTAIN` explicitly accepted by the owner). A `REFUTED` verdict must be resolved (fix and re-verify) before the claim reaches the owner -- soft-gate, not a hard veto. -Write `.cursor/apex/docs/verify-{task-slug}.md` (template: `references/verify-template.md`): every verification step checked, one evidence item per criterion (command output, log excerpt, screenshot path, or diff), plus the challenge verdict from this step. A context-only "it works" declaration does not survive a session boundary; the written artifact is the guardrail gates (sniper, later elicitation passes) actually check. Then state explicitly in your response: "Original problem is FUNCTIONALLY resolved" with a summary of evidence, or list what remains unresolved. +Write `.cursor/apex/docs/verify-{task-slug}.md` (template: `references/verify-template.md`): every verification step checked, one evidence item per criterion (command output, log excerpt, screenshot path, or diff), plus the challenge verdict from this step. A context-only "it works" declaration does not survive a session boundary; the written artifact is the guardrail gates (sniper, later elicitation passes) actually check. Then state explicitly in your response: "Original problem is FUNCTIONALLY resolved" with a summary of evidence, or list what remains unresolved. Any criterion without its own evidence is reported as "not verified", never folded into "done". `{task-slug}`: derive per `apex-methodology/references/init-tracking.md` (git branch slug or active `TaskCreate` id) -- same pattern used by the `elicitation` skill's artifact. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/commit.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/commit.md index 580e6cb..3235eec 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/commit.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/commit.md @@ -1,7 +1,7 @@ --- description: Smart conventional commit with security validation, branch flow enforcement, and auto-detection. Use for git commit, commit changes, save work, stage and commit. argument-hint: "[message] | [type scope message] | (empty for auto-detection)" -allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git add:*), Bash(git commit:*), Bash(git log:*), Bash(git tag:*), Bash(git push:*), Bash(git pull:*), Bash(git describe:*), Bash(git branch:*), Bash(git checkout:*), Bash(git rev-parse:*), Bash(git remote:*), Bash(git merge-base:*), Bash(git fetch:*), Bash(gh pr create:*), Bash(gh pr view:*), Bash(gh pr merge:*), Bash(gh pr checks:*), Bash(gh pr edit:*), Bash(gh auth:*), Bash(command:*), Read, Edit +allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git add:*), Bash(git commit:*), Bash(git log:*), Bash(git tag:*), Bash(git push:*), Bash(git pull:*), Bash(git describe:*), Bash(git branch:*), Bash(git checkout:*), Bash(git rev-parse:*), Bash(git remote:*), Bash(git merge-base:*), Bash(git fetch:*), Bash(gh pr create:*), Bash(gh pr view:*), Bash(gh pr merge:*), Bash(gh pr checks:*), Bash(gh pr edit:*), Bash(gh auth:*), Bash(gh run list:*), Bash(gh run watch:*), Bash(gh run view:*), Bash(gh run rerun:*), Bash(git rev-list:*), Bash(npm view:*), Bash(command:*), Read, Edit disable-model-invocation: false --- @@ -268,3 +268,12 @@ git tag vX.Y.Z Do **not** run `git push origin vX.Y.Z` automatically — there is either no remote to push to, or no confirmed merge yet. Print the manual command for the user to run once the remote/`gh` prerequisite is met and the change has actually landed on `main`. Output tag verification (FULL mode) or the manual push reminder (LOCAL/DEGRADED mode) alongside the PR URL + merge status from Step 7. + +### Step 9: Release Workflow — watch it to the end (FULL mode only) + +The release ends at the registry, not at the tag. Full procedure: `skills/git-flow/references/release-workflow.md`. This step is **conditional**: it applies only if the repo has a workflow that a pushed tag triggers (e.g. a `Publish` workflow). + +1. No `on: push: tags` workflow in `.github/workflows/` (verified, not assumed — a repo with only a CI workflow qualifies) → `publish: none`; stop here. +2. Otherwise find the tag's runs (`gh run list --commit "$(git rev-list -n1 vX.Y.Z)" --event push`, polled ~90s) and `gh run watch --exit-status` each one, never piped. +3. Failure → `gh run view --log-failed` at once. Flaky (threshold just over, network/registry timeout, runner crash) → `gh run rerun --failed`, max 2 reruns, then escalate. Real defect → stop, never rerun; report run URL, job, step and log lines. +4. Announce "published" only when the final attempt is fully green (post-publish verify jobs included) **and** the registry serves X.Y.Z (`npm view version` or the matching query). Until then: `tagged, publish pending` or `publish failed:`. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/SKILL.md b/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/SKILL.md index dc76443..4d8aa19 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/SKILL.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/SKILL.md @@ -6,7 +6,7 @@ related-skills: commit-optimization, post-commit, commit-detection --- -Covers Git workflow strategy end to end: the GitHub Flow (default) vs trunk-based vs Git Flow tradeoff table, the branch naming convention (`/`, kebab-case, <50 chars, no personal prefix), protected-branch enforcement (main/master/develop/production never committed to directly, auto-named feature branch proposed instead), the full branch lifecycle (create → work → push → PR → review → merge → delete), merge strategy (real merge commit is fuse-commit-pro's default; rebase vs squash tradeoffs — squash is unused here because it would orphan the release tag's target commit), the CI-gate-before-merge decision tree (three cases by whether required checks are configured, including the `gh pr checks` registration-race workaround), post-merge tag timing, the PR description template, anti-patterns, and solo-dev mode. +Covers Git workflow strategy end to end: the GitHub Flow (default) vs trunk-based vs Git Flow tradeoff table, the branch naming convention (`/`, kebab-case, <50 chars, no personal prefix), protected-branch enforcement (main/master/develop/production never committed to directly, auto-named feature branch proposed instead), the full branch lifecycle (create → work → push → PR → review → merge → delete), merge strategy (real merge commit is fuse-commit-pro's default; rebase vs squash tradeoffs — squash is unused here because it would orphan the release tag's target commit), the CI-gate-before-merge decision tree (three cases by whether required checks are configured, including the `gh pr checks` registration-race workaround), post-merge tag timing, the post-tag release-workflow watch (published only when the registry serves the version), the PR description template, anti-patterns, and solo-dev mode. # Git Flow Best Practices (2026) @@ -82,14 +82,14 @@ Format: `/` (kebab-case). **Known race condition** ([cli/cli#7401](https://github.com/cli/cli/issues/7401), confirmed by GitHub CLI maintainers): checks take a few seconds to register on a freshly-created PR. Calling `gh pr checks --watch` immediately after `gh pr create` can error out — exit code 1, `no checks reported on the '' branch` — even though checks are about to appear. The GitHub API gives no way to tell "genuinely zero checks" apart from "not registered yet," so the client must either sidestep the race (native auto-merge) or poll for registration before watching. -Determine which of the three cases applies from what actually exists on the PR — never from assumption. The key branch point is **whether the repo enforces *required* status checks in branch protection**, not merely whether auto-merge is available: `gh pr merge --auto` only ever waits for *required* checks. On a repo where checks run but aren't marked required (e.g. this repo — CodeQL + Analyze execute but aren't required), `--auto` merges **immediately without waiting**, silently reproducing the exact race this section exists to close. Check first with `gh pr checks --required` (empty output / `no required checks reported on the '' branch` → no required checks configured) before picking a branch: +Determine which of the three cases applies from what actually exists on the PR — never from assumption. The key branch point is **whether the repo enforces *required* status checks in branch protection**, not merely whether auto-merge is available: `gh pr merge --auto` only ever waits for *required* checks. On a repo where checks run but aren't marked required (e.g. CodeQL/Analyze execute but aren't required), `--auto` merges **immediately without waiting**, silently reproducing the exact race this section exists to close. Check first with `gh pr checks --required` (empty output / `no required checks reported on the '' branch` → no required checks configured) before picking a branch: 1. **Repo has required status checks in branch protection** → the only case where `--auto` actually gates. GitHub waits server-side for the *required* checks to appear and pass — no race, regardless of their state at call time: ```bash gh pr merge --auto --merge --delete-branch ``` Also requires "Allow auto-merge" enabled in repo Settings → General (otherwise `GraphQL: Auto merge is not allowed for this repository`). -2. **Repo has checks but none are required** (this repo's current state — CodeQL/Analyze run but aren't required) — `--auto` would merge immediately without waiting, so don't use it here. Poll client-side until checks register, then watch: don't `--watch` right after `gh pr create`/a push. Poll `gh pr checks` until it stops reporting "no checks reported" (bounded retries), THEN watch. The poll's pipe to `grep` only detects check registration — it never gates the merge, which still runs un-piped via `&&`: +2. **Repo has checks but none are required** (e.g. CodeQL/Analyze run but aren't required) — `--auto` would merge immediately without waiting, so don't use it here. Poll client-side until checks register, then watch: don't `--watch` right after `gh pr create`/a push. Poll `gh pr checks` until it stops reporting "no checks reported" (bounded retries), THEN watch. The poll's pipe to `grep` only detects check registration — it never gates the merge, which still runs un-piped via `&&`: ```bash pr= max_attempts=18 # 18 × 5s ≈ 90s — raise if this repo's CI is known to queue slower @@ -118,6 +118,16 @@ Merge is always `--merge` (real merge commit) — **never `--squash`**, it would **Tagging timing**: never push the tag before the merge is validated — CI could still fail or branch protection could still block the merge, and a tag pushed early would point at a commit that never lands on `main`. Tag `vX.Y.Z` on `main` AFTER the merge completes, then push the tag (`fuse-commit-pro:commit` does this automatically in Step 8 — see also `commands/commit.md` Step 8 and `post-commit/references/tag-timing.md`). +## After the Tag — Release Workflow + +Pushing the tag is not the end of a release: a tag-triggered workflow (e.g. `Publish` to npm), when the repo has one, must be watched to the end, reruns included. Full procedure: `commands/commit.md` **Step 9** and `references/release-workflow.md`. In short: + +- No `on: push: tags` workflow in `.github/workflows/` (verified; a CI-only repo qualifies) → `publish: none`, nothing to watch. +- Find the runs: `gh run list --commit "$(git rev-list -n1 vX.Y.Z)" --event push` (poll ~90s, they register late), then `gh run watch --exit-status` each — never piped. +- Failure → read `gh run view --log-failed` at once and classify. **Flaky** (timing/perf threshold just over, network/registry timeout, runner crash) → `gh run rerun --failed`, max 2 reruns then escalate. **Real defect** (compile/type/lint, deterministic test, auth, same failure twice) → stop and report the cause. +- Say **"published" only** when the final attempt is fully green (post-publish verification jobs included) **and** the registry serves the version (`npm view version` == X.Y.Z, or the matching registry query). +- The release runs only through the `commit` agent launched by the lead — never through an external code executor: they write code, not releases. + ## After Merge - Delete branch automatically (`--delete-branch` flag or GitHub auto-delete setting) diff --git a/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/references/release-workflow.md b/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/references/release-workflow.md new file mode 100644 index 0000000..40c74e7 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-commit-pro/skills/git-flow/references/release-workflow.md @@ -0,0 +1,73 @@ +# Release Workflow — Watch It to the End (Step 9 detail) + +Full procedure for `commands/commit.md` **Step 9**. Runs in FULL mode only, after Step 8 pushed `vX.Y.Z` and `git merge-base --is-ancestor vX.Y.Z main` succeeded. A pushed tag may trigger a release workflow (e.g. `Publish` to npm): the release is **not done** at `git push origin vX.Y.Z` — it is done when that workflow is green and the registry serves the version. Never leave a failed run for the owner to discover later. + +## 0. Is there a release workflow at all? + +Verify, never assume: + +```bash +ls .github/workflows/ 2>/dev/null && grep -lE '^[[:space:]]*tags:' .github/workflows/*.y*ml 2>/dev/null +``` + +No `.github/workflows/` directory, or no workflow with an `on: push: tags` trigger (a repo whose only workflow is a CI workflow counts as none) → the result is `publish: none`; nothing is watched and the rest of this file is skipped. + +## 1. Find the runs the tag triggered + +Runs take a few seconds to register; poll (bounded, ~90s) before concluding there are none: + +```bash +sha=$(git rev-list -n1 vX.Y.Z) +attempt=0 +until [ -n "$(gh run list --commit "$sha" --event push --json databaseId -q '.[].databaseId')" ]; do + attempt=$((attempt + 1)); [ "$attempt" -ge 18 ] && break; sleep 5 +done +gh run list --commit "$sha" --event push --json databaseId,name,status,conclusion +``` + +A tag workflow exists but no run registered after the poll → `publish: failed: no-run` and report it; never call it published. + +## 2. Watch every run + +The exit code gates — never pipe it: + +```bash +gh run watch --exit-status +``` + +## 3. On failure, read the log at once + +```bash +gh run view --log-failed +``` + +Classify: + +- **Flaky** — the failing step is not caused by this release's diff: a timing/perf threshold just over its limit (e.g. `expected < 50ms, got 52.7ms`), a network or registry timeout, a runner crash. → `gh run rerun --failed` (failed jobs only), then back to step 2 on the same ``. At most **2 reruns**; a 3rd failure → escalate (`status: blocked`). +- **Real defect** — a compile/type/lint error, a deterministic test failure, an auth/permission error, or the same failure twice in a row. → stop, never rerun. Report the run URL, the failing job and step, and the log lines that show the cause. + +Never change a test or a threshold to make the publish pass — a flaky threshold is reported to the owner, whose decision it is. + +## 4. Verify the published artifact + +Before announcing anything. For an npm package: + +```bash +npm view version # must equal X.Y.Z +``` + +For another registry, run its matching version query. Every post-publish verification job of the workflow (e.g. `verify bunx serves the published version`) must also be green on the final attempt. + +## Status vocabulary + +Announce **"published" only when steps 2, 3 and 4 all hold.** Until then the status is `tagged, publish pending` or `publish failed:` — never "released". + +| Outcome | `publish:` report line | +|---------|------------------------| +| Green run(s) + registry serves X.Y.Z | `published X.Y.Z (registry ✓, verify job ✓)` | +| Still running / not yet verified | `pending` | +| Flaky failure, rerun in progress | `failed: flaky→rerun /2` | +| Real defect, or 3rd failure | `failed: real-defect` | +| No tag-triggered workflow (verified) | `none` | + +The release runs only through the `commit` agent launched by the lead — never through a code delegate or an external executor. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/SKILL.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/SKILL.md index fc720bb..1744fe0 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/SKILL.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/SKILL.md @@ -1,120 +1,101 @@ --- name: design-ios -description: "Use when designing an iOS or macOS screen or flow — deliverable is a device/window-framed HTML mockup and handoff spec, never SwiftUI code." -when-to-use: "Designing an iOS or macOS screen or flow — the deliverable is a device/window-framed HTML mockup and a handoff spec for swift-expert or an Apple-platform developer to implement, not working SwiftUI." -keywords: ios, macos, hig, dynamic-type, liquid-glass, swiftui, handoff, mockup, desktop-tinting +description: "Use when designing a screen or flow for any Apple platform — iPhone (incl. iPhone Duo), iPad, Mac, Apple Watch, Apple TV or Vision Pro — deliverable is a device/window-framed HTML mockup and a handoff spec, never SwiftUI code." +when-to-use: "Designing an iOS, iPadOS, macOS, watchOS, tvOS or visionOS screen or flow — the deliverable is a framed HTML mockup and a handoff spec for swift-expert or an Apple-platform developer to implement, not working SwiftUI." +keywords: ios, ipados, macos, watchos, tvos, visionos, iphone-duo, hig, dynamic-type, liquid-glass, contrast, handoff, mockup priority: critical related: design-method, design-system, design-review --- -Produces iOS and macOS mockups and developer handoff specs: mapping design tokens to the Dynamic Type scale (iOS) or macOS's fixed text-size variants, semantic colors, device/window viewports, Liquid Glass materials, and macOS-specific conventions (system window chrome, desktop tinting, pointer states). +Produces Apple-platform mockups and developer handoff specs: design tokens mapped to the +HIG text styles of the target platform, semantic colors with verified contrast, size-class +aware canvases, Liquid Glass used only in the functional layer, and platform conventions +(system window frame on macOS, focus on tvOS, glass windows and ornaments on visionOS, +glanceable screens on watchOS, vertical controls on iPhone Duo). -The deliverable is a device-framed (iOS) or window-framed (macOS) HTML mockup at exact viewport dimensions plus a SwiftUI-ready handoff spec (named tokens, text styles, semantic colors, sizing, states, spacing). This skill never writes SwiftUI code — implementation is left to `swift-expert` or an Apple-platform developer. +The deliverable is a framed HTML mockup plus a SwiftUI-ready handoff spec (named tokens, +text styles, semantic colors, sizing, states, spacing). This skill never writes SwiftUI — +implementation goes to `swift-expert` or an Apple-platform developer. -## Design iOS/macOS — Mockup and Handoff, Not Code +## Design for Apple Platforms — Mockup and Handoff, Not Code ### When -After `design-system` tokens exist. This skill never writes SwiftUI — it produces a -static HTML mockup at exact device/window dimensions plus a spec that `swift-expert` or -an Apple-platform developer implements. +After `design-system` tokens exist. ### Input - `design-system.md` — OKLCH palette, typography direction, motion personality. -- The screen/flow to mock up and the target platform: iPhone / iPad (iOS) or a resizable - window (macOS). +- The screen/flow and the target platform(s). Pick the platform reference first: -### Steps — iOS +| Target | Read | +|---|---| +| iPhone | steps below + `references/dynamic-type.md` | +| iPad, resizable window, iPhone Duo | + `references/ipados-iphone-duo.md` | +| Mac | + `references/macos.md`, `references/type-scales-other.md` | +| Apple Watch, Apple TV, Vision Pro | + `references/watch-tv-vision.md`, `references/type-scales-other.md` | -1. **Map tokens to iOS roles.** Typography → Dynamic Type text styles, anchored at Body - 17pt down to Caption 2 11pt (never fixed point sizes) — see `references/dynamic-type.md`. - Colors → semantic color roles (never raw RGB/hex) — see `references/semantic-colors.md`. -2. **Pick the device viewport(s)** from `references/viewports.md` — mock up in exact - points at the chosen scale factor. -3. **Build the HTML mockup**: a device-frame `
` at the exact viewport dimensions, - `viewport-fit=cover` meta tag, `env(safe-area-inset-*)` for notch/Dynamic Island/home - indicator spacing. See `references/mockup.md`. -4. **Apply Liquid Glass where it fits** — a floating layer of controls *above* regular - content, not a content background. Two variants: **regular** (content-aware, the - default for controls) and **clear** (more transparent — dim the content beneath it - ~35% when clear sits over light content, so controls stay legible). Plus control - morphing, concentricity between nested shapes, layered icon treatment. Source: - developer.apple.com/design/human-interface-guidelines/materials (Liquid Glass, introduced iOS 26, current in iOS 27). - See `references/liquid-glass.md` — do not invent numeric corner-radius values; none are - published. -5. **Verify touch targets and contrast**: 44×44pt minimum touch target (see - `references/touch-targets.md`); **4.5:1 minimum contrast in Dark Mode** for body text - (WCAG AA, HIG-endorsed) — check both light and dark against - `references/semantic-colors.md` roles, not a single-mode check. -6. **Sidebar navigation ≤ 2 levels deep.** If the flow needs a 3rd level, restructure - (tabs, push navigation, or a secondary sidebar) rather than nesting a 3rd disclosure - tier — deeper sidebars are a documented HIG anti-pattern for iPadOS/macOS sidebars. - Source: developer.apple.com/design/human-interface-guidelines/layout. -7. **Write the handoff spec** per `references/handoff-swiftui.md`: named tokens only - (never raw values), Dynamic Type text styles (never fixed sizes), semantic colors, - explicit sizing behavior (fixed/hug/fill) per element, all interaction states - (disabled/pressed/focused), spacing in pt. - -### Steps — macOS - -1. **Map tokens to macOS text sizes.** macOS uses its own fixed scale, distinct from iOS - Dynamic Type — confirmed anchors: **Large Title 26pt** down to **body ~13pt**, floor - **Caption 2 ~10pt**. Source: developer.apple.com/design/human-interface-guidelines/typography. - **Gap — do not invent**: the full intermediate scale (Title 1–3, Headline, Subhead, - Footnote point values) is not confirmed in this pass; reconfirm on the HIG typography - page or Xcode's SF font catalog before using an intermediate size verbatim. -2. **No Dynamic Type on macOS** — the platform ships fixed size *variants per context* - (e.g. control sizes: regular/small/mini) instead of a user-adjustable type scale. Pick - the variant that matches the control's context, don't apply an iOS Dynamic Type style. -3. **Never draw a custom window chrome.** Title bar, traffic lights, toolbar, and sidebar - are system-drawn; the mockup should frame content inside a standard macOS window shape, - not invent custom chrome. Source: developer.apple.com/design/human-interface-guidelines/windows. -4. **Desktop tinting**: background materials pick up a subtle tint from the desktop - picture/wallpaper behind the window — reflect this as a soft, low-opacity tint layer in - the mockup, not a flat opaque background. Source: - developer.apple.com/design/human-interface-guidelines/materials. -5. **Pointer feedback, not touch feedback**: hover, highlight, and lift states on - interactive elements (buttons, list rows) — macOS is pointer-driven, so every hoverable - control needs a hover state in the mockup and handoff spec, unlike iOS/iPadOS touch-only - flows. Source: developer.apple.com/design/human-interface-guidelines/pointing-devices. -6. **Window sizing is a mockup convenience, not a spec.** Unlike iOS device viewports, - macOS windows are user-resizable — pick a reasonable default canvas (e.g. common - productivity-app widths) for the mockup, but do not present it as an official fixed - dimension; state that explicitly in the handoff spec. -7. **Write the handoff spec** per `references/handoff-swiftui.md`, adapted: macOS text - sizes instead of Dynamic Type styles, hover/pressed/focused states (pointer, not touch), - otherwise same named-token discipline. +### Steps +1. **Map tokens to platform roles.** Typography → the platform's HIG text styles by name + (iOS/iPadOS Dynamic Type: Body 17 pt … Caption 2 11 pt; macOS fixed styles: Body 13 pt + … Large Title 26 pt; tvOS/watchOS tables) — `dynamic-type.md`, `type-scales-other.md`. + Colors → semantic roles, never raw hex — `semantic-colors.md`. +2. **Choose canvases by size class**, not by device: at least compact width, regular width, + and the key screen at AX5 text size. The HIG no longer publishes device point sizes — + take them from Xcode Device Hub and record the source — `viewports.md`. +3. **Build the HTML mockup**: frame at the recorded point size (1 pt = 1 CSS px), + `viewport-fit=cover`, `env(safe-area-inset-*)` for Dynamic Island / home indicator — + `mockup.md`. macOS: a standard system window frame, never custom chrome — `macos.md`. +4. **Liquid Glass only in the functional layer** (tab bars, toolbars, sidebars, key + controls), never in content. Regular variant by default and for text-heavy surfaces; + clear only over rich media, with a 35% dark dimming layer over bright content; accent + color on the primary action's background, sparingly. No published corner radius — + concentric nesting instead — `liquid-glass.md`. +5. **Verify targets and contrast**: platform control sizes (iOS 44×44 pt, macOS 28×28, + tvOS 66×66, visionOS 60×60, watchOS 44×44) and spacing — `touch-targets.md`. Contrast + **4.5:1 minimum** (3:1 for ≥18 pt or bold), **7:1 target** for custom colors and small + text, checked in light, dark **and** Increase Contrast — `semantic-colors.md`. + Sources: https://developer.apple.com/design/human-interface-guidelines/dark-mode and + https://developer.apple.com/design/human-interface-guidelines/accessibility. +6. **Sidebar ≤ 2 levels.** Deeper hierarchy → a split view with a **content list between + the sidebar and the detail view**, not a third disclosure tier. Consider a tab bar + first on iPad. Source: + https://developer.apple.com/design/human-interface-guidelines/sidebars. +7. **Platform pass** — apply the platform reference picked above (macOS desktop tinting + only under the graphite accent; tvOS 60/80 pt safe area and focus growth; visionOS + ornaments for controls only; watchOS ≤3 glyph buttons per row; iPhone Duo controls on + the side and the fold reserved region). +8. **Look at the render** — screenshot each canvas (light, dark, AX5) and Read the PNGs + before calling the mockup done; fix what you see, then hand off to `design-review`. +9. **Write the handoff spec** per `handoff-swiftui.md`: named tokens only, text styles by + name, semantic colors, sizing (fixed/hug/fill), all states (disabled/pressed/focused, + plus pointer style on macOS and focus on tvOS), spacing in pt, canvas sources. ### Failure Handling -- Screenshot/preview tooling unavailable → describe the mockup in the handoff spec with - exact pt values instead of blocking on a visual. -- A fact needed isn't in the references below → mark it "to reconfirm on - developer.apple.com" in the output; never invent a number. This applies in particular to - **iOS/macOS spacing and corner-radius grids — neither is published as an official numeric - scale**; do not invent an 8pt-style grid for Apple platforms, point instead to Xcode's - Design Resources / SF Symbols catalog as the source of truth to reconfirm against. +- Screenshot tooling unavailable → say so in the report (`visual check: not run`) and + describe the mockup with exact pt values; never claim a visual check that didn't run. +- A needed value isn't in the references or on the cited HIG page → mark it "to reconfirm + on developer.apple.com"; never invent a number. Apple publishes **no numeric spacing or + corner-radius grid** — don't impose an 8-pt grid; a chosen value is a project token. ### Output -- Device-framed (iOS) or window-framed (macOS) HTML mockup at exact viewport - points/reasonable default canvas. -- `handoff.md` (or equivalent) with named tokens, text styles, semantic colors, sizing, - states, spacing — ready for `swift-expert`. +- Framed HTML mockup(s) per canvas, plus their screenshots. +- `handoff.md` with named tokens, text styles, semantic colors, sizing, states, spacing, + canvas sources — ready for `swift-expert`. -### Next → `design-review` (mockup-scoped: screenshot the mockup, verify contrast, no -full site audit loop). +### Next → `design-review` (mockup-scoped: screenshot, contrast, no full site audit loop). ### References | File | Purpose | |------|---------| -| `references/dynamic-type.md` | **Canonical iOS Dynamic Type scale (Large) — verified iosfontsizes.com** | -| `references/semantic-colors.md` | **Canonical semantic color roles — verified WWDC19, still current** | -| `references/viewports.md` | **Canonical iOS device viewports in points — verified ios-resolution.com** | -| `references/liquid-glass.md` | **Canonical Liquid Glass facts — verified developer.apple.com, iOS 26–27** | -| `references/touch-targets.md` | 44×44pt default / 28×28pt minimum control size — verified HIG Accessibility | +| `references/dynamic-type.md` | iOS/iPadOS Dynamic Type (Large + AX5), default/min sizes — HIG Typography | +| `references/type-scales-other.md` | macOS, tvOS, watchOS text styles; visionOS notes — HIG Typography | +| `references/semantic-colors.md` | Semantic roles, contrast 4.5/3/7:1, increased contrast, base/elevated — HIG Color, Dark Mode | +| `references/viewports.md` | Size classes, safe areas, canvas sizing via Device Hub — HIG Layout | +| `references/liquid-glass.md` | Liquid Glass layering, variants, color, per platform — HIG Materials, Color | +| `references/touch-targets.md` | Control sizes for all platforms + spacing — HIG Accessibility | +| `references/macos.md` | Window frame, fixed type, desktop tinting, pointer, sidebars — HIG | +| `references/ipados-iphone-duo.md` | iPadOS + iPhone Duo poses, reserved regions, vertical controls — HIG | +| `references/watch-tv-vision.md` | watchOS, tvOS, visionOS basics — HIG | | `references/mockup.md` | Device-frame HTML/CSS technique (safe areas, viewport-fit) | | `references/handoff-swiftui.md` | SwiftUI-ready handoff spec format | - -**Gap (not covered by any reference file, inlined above from HIG, flagged for a future -`references/macos.md`)**: macOS type-size anchors, no-Dynamic-Type rule, system window -chrome, desktop tinting, pointer states. Out of this pass's exclusive scope to create. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/dynamic-type.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/dynamic-type.md index 1d5257b..53dfaac 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/dynamic-type.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/dynamic-type.md @@ -1,34 +1,77 @@ --- name: dynamic-type -description: "Canonical iOS Dynamic Type scale (Large size category, reflecting UIKit) — the only source of iOS type sizes in this plugin." -when-to-use: "Mapping design-system.md typography to iOS text styles for a mockup or handoff spec." -keywords: ios, dynamic-type, typography, sf-pro +description: "Canonical iOS/iPadOS Dynamic Type scale from the HIG Typography page — Large (default) and AX5 tables, per-platform default/minimum sizes, layout rules at large sizes." +when-to-use: "Mapping design-system.md typography to iOS/iPadOS text styles for a mockup or handoff spec, or checking a layout at the largest accessibility size." +keywords: ios, ipados, dynamic-type, typography, sf-pro, accessibility, ax5 priority: critical -related: ../SKILL.md, semantic-colors.md +related: ../SKILL.md, type-scales-other.md, semantic-colors.md --- -# Dynamic Type Scale (Large, UIKit-reflected) +# Dynamic Type — iOS / iPadOS -Source: iosfontsizes.com, Large size category. Status: verified. +Source: https://developer.apple.com/design/human-interface-guidelines/typography +(Specifications > iOS, iPadOS Dynamic Type sizes, and larger accessibility type sizes). +Fetched 2026-10-12. Other platforms: `type-scales-other.md`. -| Text style | Size (pt) | Weight | +## Default and minimum text size per platform (HIG table) + +| Platform | Default size | Minimum size | +|---|---|---| +| iOS, iPadOS | 17 pt | 11 pt | +| macOS | 13 pt | 10 pt | +| tvOS | 29 pt | 23 pt | +| visionOS | 17 pt | 12 pt | +| watchOS | 16 pt | 12 pt | + +## Large (default) — design at this size + +| Style | Weight | Size (pt) | Leading (pt) | Emphasized | +|---|---|---|---|---| +| Large Title | Regular | 34 | 41 | Bold | +| Title 1 | Regular | 28 | 34 | Bold | +| Title 2 | Regular | 22 | 28 | Bold | +| Title 3 | Regular | 20 | 25 | Semibold | +| Headline | Semibold | 17 | 22 | Semibold | +| Body | Regular | 17 | 22 | Semibold | +| Callout | Regular | 16 | 21 | Semibold | +| Subhead | Regular | 15 | 20 | Semibold | +| Footnote | Regular | 13 | 18 | Semibold | +| Caption 1 | Regular | 12 | 16 | Semibold | +| Caption 2 | Regular | 11 | 13 | Semibold | + +## AX5 (largest accessibility size) — stress-test at this size + +| Style | Size (pt) | Leading (pt) | |---|---|---| -| Large Title | 34 | Regular | -| Title 1 | 28 | Regular | -| Title 2 | 22 | Regular | -| Title 3 | 20 | Regular | -| Headline | 17 | Semibold | -| Body | 17 | Regular | -| Callout | 16 | Regular | -| Subheadline | 15 | Regular | -| Footnote | 13 | Regular | -| Caption 1 | 12 | Regular | -| Caption 2 | 11 | Regular | +| Large Title | 60 | 70 | +| Title 1 | 58 | 68 | +| Title 2 | 56 | 66 | +| Title 3 | 55 | 65 | +| Headline / Body | 53 | 62 | +| Callout | 51 | 60 | +| Subhead | 49 | 58 | +| Footnote | 44 | 52 | +| Caption 1 | 43 | 51 | +| Caption 2 | 40 | 48 | + +The HIG page also publishes xSmall, Small, Medium, xLarge, xxLarge, xxxLarge and AX1–AX4; +read them there when a spec needs an intermediate size — do not interpolate. ## Fonts -SF Pro (default), SF Compact (compact contexts — Watch, small controls), New York (serif, -editorial/expressive contexts). +SF Pro is the iOS/iPadOS system font; apps can also use New York (NY). SF Compact is the +**watchOS** system font (SF Compact Rounded in complications) — not an iOS small-control +font. + +## Layout rules at large sizes (HIG Typography > Supporting Dynamic Type) +- Mock up the key screen at **Large and AX5**; the layout must adapt to all sizes. +- Keep truncation minimal; avoid truncating text in scrollable regions unless a separate + view shows the rest. +- In horizontally constrained rows, switch to a **stacked layout** (text above secondary + items such as glyphs and timestamps); reduce column count as size grows. +- Keep primary elements toward the top at any size; scale meaningful icons with text. +- Not every element must grow (e.g. tab titles don't) — prioritize the content people read. +- Offer enlargement of at least 200% (140% on watchOS) — HIG Accessibility. ## Rule Reference text styles by name in the handoff spec (`Body`, `Headline`, …) — never a fixed -point size. This is what makes the spec Dynamic-Type-compliant when implemented. +point size. That is what makes the implemented spec Dynamic-Type-compliant. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/ipados-iphone-duo.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/ipados-iphone-duo.md new file mode 100644 index 0000000..8c8e670 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/ipados-iphone-duo.md @@ -0,0 +1,64 @@ +--- +name: ipados-iphone-duo +description: "iPadOS and iPhone Duo (folding iPhone, HIG page 2026-09-09) mockup rules — size classes, sidebars, pointer effects, poses, reserved regions, arrangement views, vertical controls." +when-to-use: "Mocking up an iPad screen, a resizable window, or any iPhone screen that must also work on iPhone Duo." +keywords: ipados, ipad, iphone-duo, foldable, size-classes, sidebar, split-view, pointer, reserved-region +priority: high +related: ../SKILL.md, viewports.md, macos.md +--- + +# iPadOS and iPhone Duo + +Fetched 2026-10-12. `/slug` = `https://developer.apple.com/design/human-interface-guidelines/`. + +## iPadOS +- Large display, often several apps open at once; inputs combine Multi-Touch, Apple + Pencil, keyboard, trackpad/mouse. Minimize modal and full-screen transitions; place + controls within reach but out of the way. — /designing-for-ipados +- Adapt to orientation, multitasking, resized windows, Dark Mode, Dynamic Type; lay out + by size class, not device. — /designing-for-ipados, /layout +- Use extra width to expose more (tab bar → sidebar, overflow → visible actions) while + keeping functionality identical. — /layout +- **Consider a tab bar first**; the tab bar's sidebar-style appearance covers areas that + don't fit. Sidebar ≤ 2 levels, deeper → split view with a content list. — /sidebars +- Pointer content effects: **highlight** (default on bar buttons, tab bars, segmented + controls, edit menus), **lift**, **hover** — spec which one each custom control uses. + — /pointing-devices +- Focus is shown by a ring or highlight (keyboard navigation). — /focus-and-selection + +## iPhone Duo — /designing-for-iphone-duo +Two displays (outer used closed, inner used open) with a center hinge; you are still +designing for iPhone, so iOS rules apply. + +- **Poses**: don't design one layout per pose. Compact width = outer display, regular + width = inner display; let the existing layout expand. Preview in Xcode Device Hub. +- **Build to resize**: size classes, layout margins, safe area insets; no fixed widths, + no display-specific dependencies. +- **Consistency**: same functionality and element state on both displays; the inner + display may show one more hierarchy level (Mail: list or message closed, both open). +- **Reserved regions** (in addition to safe areas): outer camera (always, expands into the + Dynamic Island), inner camera (only while active), **folding region** (when partially + open, splits the inner display). Alerts, menus, sheets and split views adapt + automatically; custom views use the `ReservedRegion` API. In grids prefer an **even + column count**; favor small adjustments over rearrangement when folding. +- **Arrangement views**: split (side by side or stacked by aspect) or overlay (layered, + moving to each side when folded). Use them when the layout already looks like one; keep + navigation containers *outside* them. +- **Vertical controls**: toolbars, tab bars, navigation controls, status bar and Dynamic + Island move to the **side** — except on the inner display in portrait. They stay on the + same side in right-to-left languages; in Split View each app puts them on its outer edge. + - Top of the vertical axis: Back/Close, then prominent actions (Done); keep groupings. + - Give each toolbar item a visibility priority (overflow goes bottom to top); keep + frequent and badged items visible longest. + - Every non-text item gets a title **and** a symbol; minimize text-only buttons. + - Don't override default bar placement; don't space items manually — group them. + - Space-limited: navigation-focused → toolbar items overflow, tab bar stays; + task-focused → minimize the tab bar, keep toolbar actions. + - Use the system overflow menu; reserve the ellipsis symbol for it. +- Full-width layouts are allowed for bar-less, non-scrolling views (Calculator) if + nothing collides with the Dynamic Island or status bar. +- Games: playable in every pose; prefer changing aspect ratio over letter/pillarboxing. + +## Not published — do not invent +The HIG gives no point dimensions for either iPhone Duo display or the fold region. Take +canvas sizes from Xcode Device Hub (`viewports.md`) and state that source in the spec. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/liquid-glass.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/liquid-glass.md index d604a3e..dc1dc30 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/liquid-glass.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/liquid-glass.md @@ -1,35 +1,59 @@ --- name: liquid-glass -description: "Canonical Liquid Glass facts (introduced iOS 26, current in iOS 27) — the only source for this material in this plugin. No numeric corner-radius exists officially; do not invent one." -when-to-use: "Deciding whether and how to apply Liquid Glass to navigation, controls, or icons in an iOS mockup." -keywords: ios, liquid-glass, ios26, material, navigation +description: "Canonical Liquid Glass rules (current Apple design language, iOS/iPadOS/macOS 27 kits) — functional layer only, regular vs clear, 35% dimming, color on primary-action backgrounds, per-platform behavior. No numeric corner radius is published." +when-to-use: "Deciding whether and how to apply Liquid Glass to navigation, controls, or icons in an Apple-platform mockup." +keywords: ios, macos, tvos, visionos, liquid-glass, material, navigation, controls priority: high related: ../SKILL.md, semantic-colors.md --- -# Liquid Glass (introduced iOS 26, current in iOS 27) +# Liquid Glass -Source: developer.apple.com/documentation/technologyoverviews/liquid-glass. Status: verified official. -Still the platform design language in iOS/iPadOS 27 (released 14 Sep 2026) — see -developer.apple.com/ios ("Platform design and Liquid Glass") and -developer.apple.com/design/whats-new (App icons: "Refined guidance for Liquid Glass"). +Sources (fetched 2026-10-12): +- https://developer.apple.com/design/human-interface-guidelines/materials (Liquid Glass + section, last changed 2025-09-09) +- https://developer.apple.com/design/human-interface-guidelines/color (Liquid Glass color, + updated 2025-12-16) +- https://developer.apple.com/design/whats-new/ — iOS and iPadOS 27 and macOS 27 design + kits "include Liquid Glass": still the current language. -## What it is -A functional floating material layer for navigation and controls — not a static visual -style. Distinguishing behaviors: +## Layering +- Liquid Glass is the **functional layer** for controls and navigation (tab bars, toolbars, + sidebars) floating above content. **Never use it in the content layer** — use standard + materials there (iOS: ultra-thin, thin, regular, thick). Exception: transient controls + in content (sliders, toggles) take a glass look while being activated. +- **Sparingly**: system components adopt it automatically; on custom controls, limit it to + the most important functional elements. -- **Morphing controls** — controls reshape fluidly as context changes (e.g. a tab bar - compressing on scroll). -- **Concentricity** — nested shapes (a button inside a card inside a sheet) share a - common corner geometry so the curves read as concentric, not arbitrary. -- **Layered icons** — icons render in light / dark / clear / tinted layers that respond - to the material beneath them. +## Variants +- **Regular** (most system components): blurs and adjusts luminosity of what's behind. + Use when legibility is at risk or the component holds a lot of text (alerts, sidebars, + popovers). Scroll edge effects add blur/opacity reduction at edges. +- **Clear**: highly translucent — only over visually rich backgrounds (photos, video). + Over bright content add a **dark dimming layer at 35% opacity**; none needed over dark + content or AVKit's own playback controls. +- Appearance changes with the user's preferred glass look, Reduce Transparency and + Increase Contrast — show the mockup's glass surfaces still legible in those modes. -## What is NOT verified — do not invent -No official numeric corner-radius value exists for Liquid Glass shapes. If a mockup needs -a radius value, note it as a project-specific choice, never as "the Liquid Glass radius." +## Color on glass +- Glass has no inherent color; it picks up the content behind it. Small bars adapt light + ↔ dark with monochrome symbols; larger elements (sidebars) are more opaque. +- Color **sparingly**; to emphasize a primary action, tint the **background** (as + prominent buttons do with the accent color), not the symbol/text. Never tint several + controls' backgrounds. +- Colorful content behind bars → prefer monochrome bars or a well-differentiated accent; + keep the resting state (top of scroll) legible. -## Rule -Use Liquid Glass for the floating navigation/control layer where it fits the tone from -`design-method`; do not apply it as flat decoration. If unsure whether a surface qualifies -for it, prefer a plain semantic-color surface over a guessed glass treatment. +## Per platform (Materials page) +- **tvOS**: glass on navigation and system surfaces; image views and buttons adopt it on + focus — don't add it manually. +- **visionOS**: windows use the system **glass** material (unmodifiable, no separate Dark + Mode); prefer translucency to opaque fills; vibrancy `label` / `secondaryLabel` / + `tertiaryLabel` for text hierarchy. +- **watchOS**: keep the default material backgrounds of full-screen modal sheets. + +## Not published — do not invent +No numeric corner radius exists for Liquid Glass shapes. The rule is concentricity: +standard buttons, fields, headers and footers in a bar have radii concentric with the bar +corners (https://developer.apple.com/design/human-interface-guidelines/toolbars). A radius +in the spec is a project choice, labeled as such. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/macos.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/macos.md new file mode 100644 index 0000000..fac5e43 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/macos.md @@ -0,0 +1,56 @@ +--- +name: macos +description: "macOS mockup rules from the HIG — system window frame, fixed text styles (no Dynamic Type), desktop tinting under the graphite accent, pointer styles, window layout and sidebar rules." +when-to-use: "Designing a macOS window, sidebar or toolbar mockup and its handoff spec." +keywords: macos, window, desktop-tinting, graphite, pointer, sidebar, typography +priority: high +related: ../SKILL.md, type-scales-other.md, semantic-colors.md, liquid-glass.md +--- + +# macOS + +All rules fetched 2026-10-12. A `/slug` on a line means +`https://developer.apple.com/design/human-interface-guidelines/`. + +## Window frame — system-drawn +- Avoid custom window frames or controls and never imitate the system appearance; the + mockup frames content inside a standard window (frame with window controls and toolbar + above a body area). — /windows +- Windows are user-resizable: the mockup canvas is a convenience, not a spec size; say so + in the handoff. +- Don't put controls or critical information at the bottom of a window (people drag + windows below the screen edge); keep content clear of the camera housing at the top + edge. — /layout (macOS) + +## Typography — no Dynamic Type +macOS doesn't support Dynamic Type. Use the fixed built-in text styles (Body 13 pt … +Large Title 26 pt, full table in `type-scales-other.md`) and, inside standard controls, +the dynamic system font variants (control content, menu, tool tips, …). — /typography + +## Desktop tinting — only under the graphite accent +When people choose the **graphite** accent color, macOS tints window backgrounds with the +desktop picture. Add transparency only to custom components that have a visible background +or bezel, and only in a neutral (non-colored) state — colored states stay opaque so their +color doesn't drift. Show it in the mockup as a variant, not as the default. — /dark-mode + +## Color and materials +- Use macOS dynamic system colors (`semantic-colors.md`) and vibrant colors on materials; + choose materials by purpose, not by the color they appear to give. — /materials +- Sidebar icons use the accent color by default and must follow the accent the user picks; + fixed colors only sparingly to carry meaning (e.g. Mail's yellow VIP). — /sidebars + +## Pointer, not touch +- macOS communicates interactivity through **standard pointer styles** and shows a + **tooltip** after hovering a button; secondary click reveals context menus. + — /pointing-devices, /buttons +- The highlight / lift / hover *content effects* are **iPadOS** pointer effects, not + macOS — don't spec them for a Mac window. A custom hover visual is a project choice, + labeled as such. +- Default control size 28×28 pt, minimum 20×20 pt (`touch-targets.md`). + +## Sidebars (also iPadOS) — /sidebars +- Show **no more than two levels** of hierarchy. Deeper data → a **split view with a + content list between the sidebar and the detail view**, not a third disclosure level. +- With two levels, title each group with a short descriptive label. +- Let people hide the sidebar (View menu Show/Hide Sidebar or a button); don't hide it by + default. Sidebars float in the Liquid Glass layer; content can extend beneath them. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/mockup.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/mockup.md index 9469f0c..4d13e31 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/mockup.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/mockup.md @@ -10,8 +10,8 @@ related: ../SKILL.md, viewports.md # Device-Framed HTML Mockup ## Structure -- Outer frame `
` sized to the exact point viewport from `viewports.md` (1pt = 1px in - the mockup, no arbitrary scaling). +- Outer frame `
` sized to the point canvas recorded per `viewports.md` (Xcode Device + Hub size, source stated in the spec; 1pt = 1px in the mockup, no arbitrary scaling). - `` to allow safe-area simulation. - Safe areas via `env(safe-area-inset-top)`, `env(safe-area-inset-bottom)`, diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/semantic-colors.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/semantic-colors.md index fd9decf..21f1102 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/semantic-colors.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/semantic-colors.md @@ -1,25 +1,55 @@ --- name: semantic-colors -description: "Canonical iOS semantic color roles (WWDC19, still current) — background, grouped-background, and label hierarchies. Reference by role, never raw RGB/hex." -when-to-use: "Mapping design-system.md OKLCH tokens to iOS semantic color roles for a mockup or handoff spec." -keywords: ios, colors, semantic, hig, dark-mode +description: "Canonical Apple semantic color roles, contrast targets (4.5:1 minimum, 7:1 target, 3:1 large/bold), increased-contrast variants and Dark Mode base/elevated backgrounds — from the HIG Color, Dark Mode and Accessibility pages." +when-to-use: "Mapping design-system.md OKLCH tokens to Apple semantic color roles, or checking contrast in light, dark and Increase Contrast." +keywords: ios, macos, colors, semantic, hig, dark-mode, contrast, increase-contrast priority: critical -related: ../SKILL.md, dynamic-type.md +related: ../SKILL.md, dynamic-type.md, liquid-glass.md --- -# Semantic Color Roles +# Semantic Colors and Contrast -Source: WWDC19 (semantic colors introduced), still current. Status: verified. +Sources (fetched 2026-10-12): +- https://developer.apple.com/design/human-interface-guidelines/color +- https://developer.apple.com/design/human-interface-guidelines/dark-mode +- https://developer.apple.com/design/human-interface-guidelines/accessibility -## Backgrounds -`systemBackground`, `secondarySystemBackground`, `tertiarySystemBackground` — -`systemGroupedBackground` and its secondary/tertiary variants for grouped/table layouts. +## iOS / iPadOS roles +- Backgrounds: `systemBackground`, `secondarySystemBackground`, + `tertiarySystemBackground`; grouped: `systemGroupedBackground`, + `secondarySystemGroupedBackground`, `tertiarySystemGroupedBackground`. +- Labels: `label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel`. +- Also: `placeholderText`, `separator`, `opaqueSeparator`, `link`. -## Labels -`label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel` — the standard text -hierarchy, each with automatic light/dark adaptation. +## macOS roles (named on the HIG Color page) +`labelColor` (+ secondary/tertiary/quaternary), `windowBackgroundColor`, +`controlBackgroundColor`, `textBackgroundColor`, `underPageBackgroundColor`, +`separatorColor`, `placeholderTextColor`, `linkColor`, `selectedContentBackgroundColor`, +`unemphasizedSelectedContentBackgroundColor`, `alternatingContentBackgroundColors`. + +## Contrast targets +| Text | Minimum ratio | +|---|---| +| Up to 17 pt, any weight | 4.5:1 | +| 18 pt and up, any weight | 3:1 | +| Bold, any size | 3:1 | + +- **Target 7:1** for custom foreground/background pairs, especially small text (Dark Mode + page). 4.5:1 is the floor, not the goal. +- Check light **and** dark **and** Increase Contrast. If the default scheme misses the + minimum, the app must at least provide a higher-contrast scheme under Increase Contrast. + +## Custom colors +Supply a light and a dark variant, **plus an increased-contrast option for each** with +significantly more differentiation (Color page). System colors already ship accessible +variants. Never hard-code a value that doesn't adapt. + +## Dark Mode depth: base vs elevated +Dark Mode uses two background sets: **base** (dimmer, recedes) and **elevated** (brighter, +for foreground interfaces like popovers and sheets, and multitasking separation). Prefer +system backgrounds so the switch happens automatically; a custom background hides it. +Dark palettes are not plain inversions. Slightly darken white-background images. ## Rule Every color in the mockup and handoff spec references one of these roles (or a project -semantic token mapped onto one) — never a hardcoded RGB/hex value. This is what makes -dark mode and increased-contrast accessibility modes work automatically once implemented. +token mapped onto one) — never a raw RGB/hex. Report measured ratios per mode in the spec. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/touch-targets.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/touch-targets.md index 5a4ac37..e493a4e 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/touch-targets.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/touch-targets.md @@ -1,19 +1,34 @@ --- name: touch-targets -description: "iOS touch target size — verified against the live HIG Accessibility page (44x44 pt default, 28x28 pt minimum control size)." -when-to-use: "Sizing any tappable control in an iOS mockup." -keywords: ios, touch-target, accessibility, hig +description: "Control sizes for every Apple platform and spacing between targets — from the HIG Accessibility control-size table (iOS 44/28, macOS 28/20, tvOS 66/56, visionOS 60/28, watchOS 44/28)." +when-to-use: "Sizing any tappable/clickable/focusable control in an Apple-platform mockup." +keywords: ios, ipados, macos, tvos, visionos, watchos, touch-target, control-size, accessibility, hig priority: high -related: ../SKILL.md +related: ../SKILL.md, watch-tv-vision.md --- -# Touch Targets +# Control Sizes and Spacing -**44×44 pt** — the HIG's *default* control size for iOS/iPadOS; the HIG's absolute -*minimum* control size is **28×28 pt**. Source: -developer.apple.com/design/human-interface-guidelines/accessibility (control-size table, -verified 2026-09-27). Design to 44×44 pt; 28×28 pt is a floor, not a target. +Source: https://developer.apple.com/design/human-interface-guidelines/accessibility +(control-size table, fetched 2026-10-12). + +| Platform | Default control size | Minimum control size | +|---|---|---| +| iOS, iPadOS | 44×44 pt | 28×28 pt | +| macOS | 28×28 pt | 20×20 pt | +| tvOS | 66×66 pt | 56×56 pt | +| visionOS | 60×60 pt | 28×28 pt | +| watchOS | 44×44 pt | 28×28 pt | + +Design to the default; the minimum is a floor, not a target. + +## Spacing between targets (same page) +- About **12 pt** of padding around elements that have a bezel. +- About **24 pt** around the visible edges of elements without a bezel. +- visionOS: place button centers at least **60 pt** apart so the hover effect doesn't + obscure neighbors (HIG Layout > visionOS). ## Rule -Every tappable control in the mockup — buttons, list rows, icon-only controls — meets -44×44 pt minimum, even if the visible glyph is smaller (pad the hit area). +Every interactive control in the mockup — buttons, list rows, icon-only controls — meets +the platform default, even when the visible glyph is smaller (pad the hit area). Flag any +control under the default in the handoff spec. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/type-scales-other.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/type-scales-other.md new file mode 100644 index 0000000..07f3c49 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/type-scales-other.md @@ -0,0 +1,77 @@ +--- +name: type-scales-other +description: "HIG-published type scales for macOS, tvOS, watchOS and visionOS notes — replaces any guessed intermediate size." +when-to-use: "Mapping typography for a macOS, tvOS, watchOS or visionOS mockup/handoff spec." +keywords: macos, tvos, watchos, visionos, typography, text-styles +priority: high +related: ../SKILL.md, dynamic-type.md, macos.md, watch-tv-vision.md +--- + +# Type Scales — macOS, tvOS, watchOS, visionOS + +Source: https://developer.apple.com/design/human-interface-guidelines/typography +(Specifications + Platform considerations). Fetched 2026-10-12. + +## macOS built-in text styles (fixed — macOS doesn't support Dynamic Type) + +| Text style | Weight | Size (pt) | Line height (pt) | Emphasized | +|---|---|---|---|---| +| Large Title | Regular | 26 | 32 | Bold | +| Title 1 | Regular | 22 | 26 | Bold | +| Title 2 | Regular | 17 | 22 | Bold | +| Title 3 | Regular | 15 | 20 | Semibold | +| Headline | Bold | 13 | 16 | Heavy | +| Body | Regular | 13 | 16 | Semibold | +| Callout | Regular | 12 | 15 | Semibold | +| Subheadline | Regular | 11 | 14 | Semibold | +| Footnote | Regular | 10 | 13 | Semibold | +| Caption 1 | Regular | 10 | 13 | Medium | +| Caption 2 | Medium | 10 | 13 | Semibold | + +To match text inside standard controls, the HIG lists **dynamic system font variants** +(control content, label, menu, menu bar, message, palette, title, tool tips, document +text, monospaced document text, bold system font, system font) — name the variant in the +spec rather than a point size. SF Pro is the system font; NY only via Mac Catalyst. + +## tvOS built-in text styles + +| Text style | Weight | Size (pt) | Leading (pt) | Emphasized | +|---|---|---|---|---| +| Title 1 | Medium | 76 | 96 | Bold | +| Title 2 | Medium | 57 | 66 | Bold | +| Title 3 | Medium | 48 | 56 | Bold | +| Headline | Medium | 38 | 46 | Bold | +| Subtitle 1 | Regular | 38 | 46 | Medium | +| Callout | Medium | 31 | 38 | Bold | +| Body | Medium | 29 | 36 | Bold | +| Caption 1 | Medium | 25 | 32 | Bold | +| Caption 2 | Medium | 23 | 30 | Bold | + +## watchOS Dynamic Type — Large (default 40/41/42 mm) and xLarge (default 44/45/49 mm) + +| Style | Large size / leading | xLarge size / leading | +|---|---|---| +| Large Title | 36 / 38.5 | 40 / 42.5 | +| Title 1 | 34 / 36.5 | 38 / 40.5 | +| Title 2 | 28 / 30.5 | 30 / 32.5 | +| Title 3 | 19 / 21.5 | 20 / 22.5 | +| Headline (Semibold) | 16 / 18.5 | 17 / 19.5 | +| Body | 16 / 18.5 | 17 / 19.5 | +| Caption 1 | 15 / 17.5 | 16 / 18.5 | +| Caption 2 | 14 / 16.5 | 15 / 17.5 | +| Footnote 1 | 13 / 15.5 | 14 / 16.5 | +| Footnote 2 | 12 / 14.5 | 13 / 15.5 | + +Other watchOS sizes (xSmall, Small = default 38 mm, xxLarge, xxxLarge, AX1–AX5) are on +the HIG page. SF Compact is the watchOS system font; complications use SF Compact Rounded. + +## visionOS +No point table is flattened here — read the HIG page if a value is needed. Published +rules: SF Pro system font; bolder Dynamic Type body and title styles; extra **Extra Large +Title 1 / Extra Large Title 2** for wide editorial layouts; prefer 2D text; default text +is white for contrast on glass; text off a background → consider bold, avoid shadows; +billboard labels anchored in space so they keep facing the wearer. + +## Rule +Name the platform's text style in the spec. A size not in these tables or on the HIG page +is marked "to reconfirm on developer.apple.com" — never interpolated. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/viewports.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/viewports.md index ada9fc0..dedb998 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/viewports.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/viewports.md @@ -1,26 +1,42 @@ --- name: viewports -description: "Canonical iOS device viewports in points, for mocking up screens at exact device dimensions." -when-to-use: "Building the device-framed HTML mockup and choosing which device(s) to target." -keywords: ios, viewport, device, points, iphone, ipad +description: "How to size an Apple-platform mockup canvas — size classes, safe areas and layout margins from the HIG Layout page; per-device point sizes are no longer published there, so take them from Xcode Device Hub." +when-to-use: "Choosing the canvas size(s) for a device-framed mockup and deciding which size classes to show." +keywords: ios, ipados, viewport, device, points, size-classes, safe-area, iphone, ipad priority: critical -related: ../SKILL.md, mockup.md +related: ../SKILL.md, mockup.md, ipados-iphone-duo.md --- -# Device Viewports (points) +# Viewports — Size Classes First, Device Sizes Second -Source: ios-resolution.com (last updated 2026-09-18). Status: verified. +Source: https://developer.apple.com/design/human-interface-guidelines/layout +(updated 2026-09-09, fetched 2026-10-12). -| Device | Viewport (pt) | Scale | -|---|---|---| -| iPhone 18 Pro Max / 17 Pro Max | 440 × 956 | @3x | -| iPhone 18 Pro / 17 Pro / 17 | 402 × 874 | @3x | -| iPhone 16 Pro Max | 430 × 932 | @3x | -| iPhone 16 | 393 × 852 | @3x | -| iPad Pro 13" | 1032 × 1376 | @2x | -| iPad Pro 11" (7th gen and later) | 834 × 1210 | @2x | +## What the HIG says +- **Lay out by size class, not by device type or orientation.** Each axis is compact or + regular; apps can appear in every combination (full screen, Split View, Slide Over, + iPhone Mirroring on Mac, resized iPad window). +- Keep functionality identical across size classes; only the amount shown changes + (e.g. tab bar → sidebar, overflow menu → exposed actions at regular width). +- Respect safe areas (Dynamic Island, status bar, toolbars, tab bars) and system layout + margins / readable-width guides. +- Test the **largest and smallest** layouts first; preview with Xcode **Device Hub** + (also for resized iPad windows and iPhone Mirroring). + +## Device point sizes — not published by the HIG +The current Layout page carries **no per-device dimension table** (the 2026-09-09 revision +has none; earlier revisions listed iPhone/iPad specs). The previous table in this file came +from a third-party site and was removed. + +To get a canvas size: open the target device in Xcode Device Hub / Simulator and record +the logical size in points and the scale factor in the handoff spec, with that source. +Never quote a device size from memory or a third-party site as "the" spec. + +## Minimum mockup set +1. iPhone, compact width (portrait). +2. iPad or a regular-width window (or iPhone Duo inner display — `ipados-iphone-duo.md`). +3. The same key screen at AX5 text size (`dynamic-type.md`). ## Rule -Mock up in the exact point dimensions above, not an arbitrary "mobile" breakpoint — iOS -layout is defined in points, and the mockup should read at 1:1 with what a developer sees -in an Xcode preview at that device. +Mock up at 1 pt = 1 CSS px on a canvas whose size and source are stated in the spec; no +arbitrary "mobile breakpoint" and no fixed-width layout the developer would have to copy. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/watch-tv-vision.md b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/watch-tv-vision.md new file mode 100644 index 0000000..9b89a78 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-design/skills/design-ios/references/watch-tv-vision.md @@ -0,0 +1,60 @@ +--- +name: watch-tv-vision +description: "Design basics for watchOS, tvOS and visionOS mockups — device context, layout, controls, focus, materials — each rule cited to its HIG page." +when-to-use: "Mocking up a watchOS, tvOS or visionOS screen; use alongside touch-targets.md and type-scales-other.md." +keywords: watchos, tvos, visionos, apple-watch, apple-tv, vision-pro, focus, ornaments, glass +priority: high +related: ../SKILL.md, touch-targets.md, type-scales-other.md, liquid-glass.md +--- + +# watchOS, tvOS, visionOS — Basics + +Fetched 2026-10-12. `/slug` = `https://developer.apple.com/design/human-interface-guidelines/`. + +## watchOS +- Context: worn on the wrist, viewed within about a foot, sessions often under a minute; + complications and notifications are used more than the app. — /designing-for-watchos +- Glanceable, single-screen interactions; **minimize hierarchy depth**; Digital Crown for + vertical navigation. — /designing-for-watchos +- At most **three glyph buttons or two text buttons** in a row; primary actions as + full-width buttons; same height for buttons sharing a row or a vertical stack. + — /layout, /buttons +- Toolbar buttons sit in the corners (system moves time and title). — /buttons +- Keep the default material background of full-screen modal sheets. — /materials +- Controls 44×44 pt default, 28×28 minimum; SF Compact; text enlargement ≥140%. + — /accessibility, /typography + +## tvOS +- Context: viewed from 8 feet or more, Siri Remote; long immersive sessions. + — /designing-for-tvos +- **Safe area**: inset primary content 60 pt from top and bottom, 80 pt from the sides + (overscan). — /layout (tvOS) +- Focus is the interaction model: the focused item usually gets the **parallax** effect; + selecting is a separate gesture. Leave room for items that grow on focus so they don't + overlap other content. — /focus-and-selection, /layout +- Grids (unfocused content width, 40 pt horizontal spacing, ≥100 pt vertical spacing): + 2 columns 860 pt · 3 → 560 · 4 → 410 · 5 → 320 · 6 → 260 · 7 → 217 · 8 → 184 · 9 → 160. + — /layout (tvOS Grids) +- Buttons and image views adopt Liquid Glass on focus automatically. — /materials +- Controls 66×66 pt default, 56×56 minimum; Body 29 pt. — /accessibility, /typography + +## visionOS +- Context: Shared Space by default, Full Space on demand; eyes look + indirect tap; keep + content in the field of view, relative to the head; use the **minimum immersion** each + moment needs. — /designing-for-visionos +- Windows use the unmodifiable **glass** material — keep it; prefer translucency to opaque + areas; there is no separate Dark Mode. — /windows, /materials +- Support resizing; keep content horizontally centered at large sizes; min/max sizes + only to prevent overlap, never to block resizing. — /layout (visionOS) +- **Ornaments** hold app-specific controls (toolbars, playback), never supplemental + content — that goes in an adjacent window. — /layout (visionOS) +- Buttons: prefer circular or capsule shapes with a visible background; sizes mini 28, + small 32, regular 44, large 52, extra large 64 pt; centers ≥60 pt apart (+4 pt padding + for buttons ≥60 pt); no custom hover effects; no white-fill/black-label custom buttons + (reserved for toggled state). — /buttons +- Controls 60×60 pt default, 28×28 minimum. — /accessibility +- Text: prefer 2D, white default, billboard spatial labels. — /typography + +## Rule +A watchOS/tvOS/visionOS value not on these pages is marked "to reconfirm on +developer.apple.com" in the spec, never borrowed from iOS. diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-method/SKILL.md b/.cursor-plugin/plugins/fuse-design/skills/design-method/SKILL.md index 00aca71..9be1e8f 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-method/SKILL.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-method/SKILL.md @@ -550,7 +550,7 @@ into next, per platform, once `design-system/SKILL.md` has already been read (st |---|---| | Web (marketing/landing) | `design-web` → `design-motion` → `design-review` | | Web app (dashboard/SaaS) | `design-webapp` → `design-motion` → `design-review` | -| iOS | `design-ios` → `design-review` | +| Apple — iOS, iPadOS, iPhone Duo, macOS, watchOS, tvOS, visionOS | `design-ios` (platform file in its `references/`) → `design-review` | | Android | `design-android` → `design-review` | | Copy only | `ux-copy` (any point in the pipeline) | diff --git a/.cursor-plugin/plugins/fuse-rules/README.md b/.cursor-plugin/plugins/fuse-rules/README.md index e573118..3571bdb 100644 --- a/.cursor-plugin/plugins/fuse-rules/README.md +++ b/.cursor-plugin/plugins/fuse-rules/README.md @@ -117,8 +117,11 @@ on purpose. | `user-rules/fuse-global.mdc` | **User** — every project | Deployed to `~/.cursor/rules/fuse-global.mdc`, `alwaysApply: true` | `AGENTS.md` is the source of truth; `fuse-global.mdc` is a copy of its body with a two-key -frontmatter (`description`, `alwaysApply: true`) prepended. Their bodies are byte-identical -(`diff` from `## Identity` onward is empty) and **must stay so** — edit `AGENTS.md`, then re-copy. +frontmatter (`description`, `alwaysApply: true`) prepended. Their bodies are identical +from `## HARD STOPS` onward except the final `Rules location:` line, which is deliberate: `AGENTS.md` +gives the repo-relative path (`.cursor-plugin/plugins/fuse-rules/rules/*.md`), while the user-level +copy, read in every project where that path does not exist, gives `fuse-rules/rules/*.md`. Keep +everything else in sync — edit `AGENTS.md`, then re-copy, preserving that one line. ### Why these two channels and not the others diff --git a/.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md b/.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md index 986cdf1..d24b5ee 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md @@ -24,4 +24,5 @@ alwaysApply: true 2. **NEVER edit a file not read in this session** - Read the target file before ANY Edit 3. **Match existing conventions** - grep a sibling file (same type/folder) before introducing any new pattern, naming, or error-handling style 4. **Zero dangling references** - after any edit or file split, verify imports, exports, and types still resolve -5. **NEVER report done with failing checks** - done = sniper ZERO errors (lint + types). A hidden failure is a lie, not a completion +5. **NEVER report done with failing checks** - done = sniper ZERO errors (lint + types) AND `verification` passed: real output opened, each part of the request ticked by name, unverified = "not verified". A hidden failure is a lie, not a completion +6. **Challenger before any claim** - the lead runs the `challenger` agent (fresh context, verdict CONFIRMED / REFUTED / UNCERTAIN) BEFORE reporting to the owner any root-cause, any done/verified claim, any irreversible action (commit/deploy/rm/push) or a 2nd-time fix — inside an APEX task or in plain conversation — and at every eLicit + Verify gate. A REFUTED is resolved or owner-accepted before a "done" claim reaches the owner. Challenger = claims/root-causes; sniper = code diff --git a/.cursor-plugin/plugins/fuse-rules/rules/01-project-detection.md b/.cursor-plugin/plugins/fuse-rules/rules/01-project-detection.md index bd75813..f9a1f63 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/01-project-detection.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/01-project-detection.md @@ -26,3 +26,4 @@ Scan: plugin agents using runtime-provided paths when actually present (Cursor S Priority: Custom > Framework (Next.js > Astro > Laravel > TanStack Start > React) > Language (TypeScript, PHP, Swift, Rust, Go) > UI library > `general-purpose` **FORBIDDEN:** `general-purpose` when domain agent exists. +**RIGHT AGENT FOR EACH TASK** — route by Project Detection (domain-expert); never a generic agent when a domain expert exists. diff --git a/.cursor-plugin/plugins/fuse-rules/rules/02-apex-workflow.md b/.cursor-plugin/plugins/fuse-rules/rules/02-apex-workflow.md index c5b3c7c..2df0b1f 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/02-apex-workflow.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/02-apex-workflow.md @@ -5,11 +5,14 @@ alwaysApply: true ## APEX Auto-Trigger +**FULL APEX MANDATORY** — 6 phases: Analyze → Plan → Execute → **eLicit** (auto-review) → **Verify** (functional check) → **eXamine** (sniper). Gate: **eLicit + Verify BEFORE sniper — NEVER skip**. The `challenger` runs at every eLicit and Verify gate (00-critical-rules #6). +Task = create/build/feature/refactor/debug/multi-file → **consult APEX skills first**: `fuse-ai-pilot:apex` / `fuse-ai-pilot:apex-methodology` (+ `apex-quick` for trivial). The full methodology lives there, not inline here. + **USE APEX:** create, implement, add, build, refactor, migrate, new component, multi-file, architecture changes **SKIP APEX:** questions, trivial fix (1-3 lines), read-only, simple git -**Debug/Investigation:** "why", "not working", "bug", "crash", "doesn't load" → ALWAYS use Analyze (explore-codebase + research-expert + domain-expert) +**Debug/Investigation:** "why", "not working", "bug", "crash", "doesn't load" → ALWAYS use Analyze (explore-codebase + research-expert + domain-expert) — always go through Analyze, never straight to a fix -**Shortcuts:** `/apex-quick` command (single-expert fast path — skips Brainstorm+Analyze+TeamCreate, linter-only verify) | `--skip-elicit` (skip eLicit, straight to eXamine) — eXamine/sniper itself is NEVER skippable (00-critical-rules) +**Shortcuts:** `/apex-quick` command (single-expert fast path — skips Brainstorm+Analyze+team split, linter-only verify) | `--skip-elicit` (skip eLicit, straight to eXamine) — eXamine/sniper itself is NEVER skippable (00-critical-rules) ## Full APEX Flow @@ -21,7 +24,7 @@ Brainstorm → Analyze → Plan → Execute (TDD) → eLicit → Verify → eXam |-------|-------|------| | **Brainstorm** | `brainstorming` | New features, major changes. Skip for trivial fixes, bug fixes with clear repro | | **Analyze** | explore-codebase + research-expert | Always (parallel agents) | -| **Plan** | TaskCreate | Always (cohesive, reviewable tasks) | +| **Plan** | Written mandate per task — one agent per task (the task, the files it owns, expected output, criteria) | Always. Split by task; two tasks that must edit the same file are merged into one task or sequenced; file size is governed by the hook's `FUSE_SOLID_MAX_LINES`, never by a self-set cap | | **Execute** | Domain expert + `tdd` | Write test FIRST (RED), then code (GREEN), then refactor | | **eLicit** | Elicitation techniques | Expert self-review | | **Verify** | `verification` | Run the actual build/tests — a Verify without execution is a guess | diff --git a/.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md b/.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md index 9523e8f..5fcebed 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md @@ -1,22 +1,25 @@ --- -description: Agent team delegation rules — exclusive file ownership, well-scoped tasks +description: Agent team delegation rules — one agent per task, exclusive file ownership, well-scoped mandates alwaysApply: true --- ## Agent Teams **Lead = Coordinator ONLY.** Never codes, only orchestrates. +**Procedure from owner request to verified report → skill `fuse-ai-pilot:lead-orchestration`** (intake, route, brief, follow, blocks, verify, learn, report). +**Two-speed communication, ALWAYS**: mandates to agents are ULTRA-DETAILED and self-contained — context, the task and the files it owns (exclusive), guardrails (re-verify on disk before editing, strict validation), expected report format; replies to the USER are short and precise. Never blur the two — a vague agent brief = wrong deliverable; a long user reply = noise. -1. **Exclusive file ownership** - NEVER shared edits between teammates -2. **Well-scoped tasks** - Each TaskCreate: target files, expected output, criteria -3. **TaskUpdate mandatory** - Mark `completed` before idle +1. **One agent per task** - the split unit is the TASK; each task has one agent and owns the files it needs. NEVER shared edits between teammates — two tasks that must edit the same file are merged into one task or sequenced +2. **Well-scoped mandates** - Each brief states: the task, the files it owns (exclusive), expected output, acceptance criteria +3. **Completion is reported, not assumed** - a subagent returns its final report to the lead (a background one writes its output under `~/.cursor/subagents/`); the lead still verifies ON DISK (rule 7). There is no task board to tick 4. **Max 4 teammates** - Beyond = coordination overhead 5. **80% planning, 20% execution** - Detailed specs = better results -6. **ALWAYS propose TeamCreate** for multi-file tasks — ask user before deciding -7. **Launch → Orchestrate → Monitor → VERIFY** - spawning teammates is step 1, not the job: after EACH teammate report, verify the deliverables ON DISK (grep/diff the expected changes) before considering the mandate done -8. **Idle ≠ done** - an idle/available notification is NOT a completion; no deliverable on disk → take the mandate back or re-delegate, never assume -9. **Re-dispatch clause in every brief** - "if you receive a re-dispatch of an already-delivered mandate, verify the disk and REFUSE to re-execute" (task boards can re-notify; without it, work gets double-applied) +6. **SPLIT by task by default** — several tasks = one agent per task, launched as parallel Task calls in ONE message; announce the split, don't ask +7. **Launch → Orchestrate → Monitor → VERIFY** - spawning is step 1, not the job: after EACH agent report, verify the deliverables ON DISK (grep/diff the expected changes) before considering the mandate done. External executors (Kimi/Codex/Claude Code) included: poll their output, push them on stalls, follow them to the end — the owner never has to ask "is it moving?" +8. **Idle ≠ done** - a returned or idle subagent is NOT a completion; no deliverable on disk → take the mandate back or re-delegate, never assume +9. **Re-dispatch clause in every brief** - "if you receive a re-dispatch of an already-delivered mandate, verify the disk and REFUSE to re-execute" (without it, work gets double-applied) 10. **sniper AFTER all teammates finish** - never during; run it once, after every teammate's deliverable is verified on disk +11. **Owner correction → rule, same turn** - every correction becomes a line in the skill/agent that failed (source repo, then synced) before the turn ends; the owner never says the same thing twice ## Scope Ladder — take the smallest tool that suffices @@ -25,15 +28,21 @@ Pick the level by the WORK, not by reflex. The rules above (team min 4, mandator | Scope | Action | Why | |-------|--------|-----| | Trivial / read-only / 1 targeted file, bounded change | Direct edit (or 1 domain-expert) + sniper. NO team, NO mandatory ANALYZE trio. | Orchestration cost (spawn, briefs, FIFO cross-checks) exceeds the gain. | -| Non-trivial mono-concern (1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | -| Truly parallelizable: INDEPENDENT batches, multi-domain, or large multi-file with no cross-dependency | Team (MINIMUM 4 agents), proposed to the owner first. | Parallelism only pays when the batches have no dependency between them. | +| Non-trivial, ONE task (mono-concern) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | +| Several tasks, SAME domain, even COUPLED | **One agent per task** — each task has one agent and owns the files it needs. Coupling is handled by the brief (shared contract stated up front), not by serializing every task onto one executor. Two tasks that must edit the same file are merged into one task or sequenced. Announce the split, don't ask. | Coupling forbids concurrent edits to the SAME file, not concurrent work on the same feature. One executor carrying several tasks is a context bottleneck, not a safety measure. | +| Truly parallelizable: INDEPENDENT tasks, multi-domain, or large work with no cross-dependency | **Team of subagents, MINIMUM 4 in parallel**, NEVER 1 (1 agent = not a team). Announce the split, don't ask. | Parallelism only pays when the tasks have no dependency between them. | +| User says "team" / "create a team" | **Spawn immediately** — min 4, no debate. | Owner's explicit call overrides the ladder. | -**Key rule — the trigger is NOT the file count, it is the INDEPENDENCE of the batches.** 2 coupled files = 1 executor; 6 independent files = team. When the owner says "team", it's a team (min 4), no debate. +**Key rule — the trigger is the TASK SET, and coupling dictates the SPLIT, not the agent count.** One task = one agent; several tasks = one agent per task; independent tasks = full team (min 4). Conflict guard (a consequence, not the split criterion): never two agents on the same file. When the owner says "team", it's a team (min 4), no debate. + +**Nesting limit (Cursor docs):** a subagent can launch child subagents, but a subagent launched by another subagent cannot launch further ones, and hooks or tool policy can block spawning — only the lead splits the work. + +**Parallel ownership — non-negotiable when several agents run at once.** One agent per task, each task owning the files it needs; one owner per folder, never two agents on the same file (two tasks on one file → merge or sequence them). When a collision happens anyway, do not pick one side wholesale: each side usually holds something the other lacks. Name one owner AND order it to START FROM the on-disk state, preserving the other's contribution — never to rewrite from its own copy. ## Anti-Patterns (FORBIDDEN) -- **Parallel Agent for multi-file edits** → USE TeamCreate (agents can't coordinate without SendMessage) -- **2 teammates on same file** → CONFLICT guaranteed (one overwrites the other) -- **Lead writing code** → Lead ORCHESTRATES only (TaskCreate + SendMessage) -- **Skipping TeamCreate proposal** → ALWAYS ask user: "Tu veux que je crée une team ?" +- **Sequential launches for parallel tasks** → launch the independent subagents as parallel Task calls in ONE message +- **2 teammates on same file** → CONFLICT guaranteed (one overwrites the other) — merge the two tasks or sequence them +- **Lead writing code** → Lead ORCHESTRATES only (Task tool to delegate; resume a subagent by its agent ID to steer it) +- **Serializing several tasks onto one executor** → SPLIT one agent per task and announce it; asking permission for every split is its own anti-pattern - **Writing to deployed dir** → ALWAYS work in dev repo, rsync after -- **Destructive action inside an agent brief** → FORBIDDEN. An in-flight agent cannot be reliably countermanded (messages are delivered between its turns — the original brief executes anyway). Any contestable deletion/overwrite = done by the lead AFTER user validation, never delegated in a brief +- **Destructive action inside an agent brief** → FORBIDDEN. An in-flight agent cannot be reliably countermanded (a message only reaches it when it is resumed — the original brief executes anyway). Any contestable deletion/overwrite = done by the lead AFTER user validation, never delegated in a brief diff --git a/.cursor-plugin/plugins/fuse-rules/rules/04-solid-dry-rules.md b/.cursor-plugin/plugins/fuse-rules/rules/04-solid-dry-rules.md index 922c03e..145aa8d 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/04-solid-dry-rules.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/04-solid-dry-rules.md @@ -3,6 +3,14 @@ description: SOLID/DRY enforcement — which SOLID skill and interfaces path to alwaysApply: true --- +## SOLID Rules +SOLID/DRY → **consult SOLID skills** (`solid-*` / this rule). +1. **File size** — the ONLY authority is the hook's ceiling (`FUSE_SOLID_MAX_LINES`, default 200). Respect it; split well before it. **Never set your own cap**, and never work around the hook's. If a legitimate correctness fix cannot fit under the ceiling, do NOT skip the fix and do NOT bypass the block: report it to the owner, who sets the variable — it is tunable at runtime and that decision is his, not yours. +2. **Interfaces separated** - Per stack location +3. **Research first** - `research-expert` before ANY code +4. **Validate after** - `sniper` after ANY modification +5. **JSDoc/PHPDoc** - Every exported function documented + ## SOLID Skill per Stack (read before coding) | Agent | Skill | Interfaces | @@ -18,10 +26,4 @@ alwaysApply: true ## DRY (ZERO TOLERANCE) -Before ANY new code: Grep codebase -> check shared locations -> extend/reuse if exists - -| Stack | Shared Locations | -|-------|-----------------| -| Next.js/React | `modules/cores/lib/`, `modules/cores/components/`, `modules/cores/hooks/` | -| Laravel | `app/Services/`, `app/Actions/`, `app/Traits/`, `app/Contracts/` | -| Swift | `Core/Extensions/`, `Core/Utilities/`, `Core/Protocols/` | +Before ANY new code: grep the codebase, then load the stack's SOLID skill — `fuse-solid:solid-detection` routes to the right `solid-` (solid-nextjs, solid-react, solid-tanstack-start, solid-astro, solid-swift, solid-php (Laravel/PHP), solid-go, solid-rust, solid-python, solid-java, solid-csharp, solid-ruby, solid-generic), which defines that stack's shared locations; extend/reuse what exists. diff --git a/.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md b/.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md index ba9d03c..4fc7039 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md @@ -29,12 +29,22 @@ alwaysApply: true Use plugin skill paths from runtime context when actually present; Cursor SessionStart delivery remains runtime-unverified. Never hardcode marketplace paths. SOLID refs: `skills/solid-*/references/` (inside each agent plugin) +## Memory Hygiene +- When `MEMORY/LESSON.md` grows or accumulates near-duplicate lessons → run `/lessons-compact` (it delegates to the `lessons-compactor` agent, which proposes; you approve before anything is written) — never let it bloat. + ## Documentation ALL docs in `docs/` folder - NEVER outside except root `README.md` +## Dev Workflow +- **ALWAYS work in dev/source repo** — NEVER write to deployed/production paths directly +- **Sync to deployed** after changes validated +- **Commit from source repo only** + +**Only exception:** Git read-only (status, log, diff) + ## Git & GitHub Flow (ZERO TOLERANCE) -**Commit tool**: ALWAYS delegate to the agent `fuse-ai-pilot:commit` (it executes `/fuse-commit-pro:commit` end to end). NEVER `git commit` directly, never hand-roll the flow yourself. +**Commit tool**: ALWAYS delegate to the agent `fuse-ai-pilot:commit` (it executes `/fuse-commit-pro:commit` end to end; it owns the whole flow: security, PATCH bump + marketplace mirror, CI wait before merge, post-merge tag). NEVER `git commit` directly, never hand-roll the flow yourself. External executors (Kimi/Codex/Claude Code) never push/PR/merge/tag/publish — release goes through the commit agent only. **Branch enforcement**: - `main`, `master`, `develop`, `production` → **protected**, no direct commits diff --git a/.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md b/.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md index f32b244..b202633 100644 --- a/.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md +++ b/.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md @@ -11,11 +11,12 @@ alwaysApply: true 4. **Cross-verify** with Context7/Exa to confirm references are up-to-date ## Hook Compliance (ZERO TOLERANCE) -**ALWAYS read hook/block messages attentively and COMPLY** — a blocked tool call returns an instruction (e.g. "Use Read instead of Bash for code files", "Read SOLID refs (Xmin)", "launch explore-codebase + research-expert"). Do EXACTLY what it says. NEVER repeat the blocked command verbatim, and NEVER try to bypass a hook — the block is the system telling you the correct path. +**ALWAYS read hook/block messages attentively and COMPLY** — a blocked tool call returns an instruction (e.g. "Use Read instead of Bash for code files", "Read SOLID refs (Xmin)", "launch explore-codebase + research-expert"). Do EXACTLY what it says. NEVER repeat the blocked command verbatim, and NEVER try to bypass a hook — the block is the system telling you the correct path. A block that looks wrong: read the gate's source before calling it a bug, quote it verbatim in your report. ## Mandate Quality (ZERO TOLERANCE) -Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, exclusive file ownership, guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. +Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, the task and the files it owns (exclusive; one agent per task), guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. **Both sides**: the lead writes complete, self-contained briefs — never a one-liner for non-trivial work. A sub-agent that receives an ambiguous or incomplete brief asks/flags the gap before acting — never improvises or guesses scope. +**Mid-task amendment**: an owner message during a mandate (direct, or relayed by the lead to every affected running agent) amends it — absorb it and keep going; only an explicit stop halts. ## Exit Contract (ZERO TOLERANCE) Every loop you run ends on ONE explicit issue, reported to the lead — never silent drift or an endless retry: @@ -24,3 +25,6 @@ Every loop you run ends on ONE explicit issue, reported to the lead — never si - **Rollback** — your change broke something (regression / verification fails): return to the last green state before stacking another fix. - **Ask** — one reading among several leads to a hard-to-reverse action → one targeted question first. - **Escalate** — blocked past the attempt cap (3 cycles, cf. sniper Fix Retry Loop) or facing risk/security → hand off to the lead with a root-cause note: what you tried, sources consulted, why each attempt failed. + +Never hand the owner a step — find the way yourself (download, grep, move to Trash, relay a code, read a log). Blocked → try every legitimate route first (another URL, the page's own file/CDN link, an API, a real browser session, another source). Only what a safety rule forbids the agent goes back — solving a CAPTCHA, typing a password, an approval the hook requires the owner to type — with exactly what to type, one line. +Guarantee, don't hedge: never report "I can't guarantee" — measure, then state what is guaranteed with its proof. Values derivable from a measurement (timeout, threshold, default) are picked by you, made configurable, never asked. diff --git a/.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template b/.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template index e3cb06e..a076be1 100644 --- a/.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template +++ b/.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template @@ -4,9 +4,10 @@ Order is deliberate. Moving a section down removes it from that recall. Details at end of file. --> ## HARD STOPS +0. **Every owner request starts by loading skill `fuse-ai-pilot:lead-orchestration`** (intake checklist → route → brief → delegate → follow → verify → report) — the lead orchestrates, never edits. 1. **NEVER git commit / push / reset** without explicit permission. Read-only git is free. 2. **NEVER modify files** without explicit user instruction. -3. **NEVER write outside the mandate** — never `~/.claude` or `~/.codex` (real API keys), never a deployed marketplace, never run `setup.sh` / `install*.ts`. +3. **NEVER write outside the mandate** — never `~/.claude` or `~/.codex` (real API keys), never a deployed marketplace, never run `setup.sh` / `install*.ts` — **unless the owner names that file or path in the mandate** (e.g. "edit my CLAUDE.md", "sync the marketplace"): then the lead's brief quotes the owner's words and the agent may write exactly that target, nothing else. 4. **ONE folder = ONE owner.** Before sending an agent in: `ls -lT` + `date`. Mtime under ~5 min = busy, send no one. 5. **A message does NOT stop an agent.** It lands in a mailbox; the agent finishes its turn and writes anyway. Use **TaskStop**, then confirm mtimes stopped before reporting a state frozen. @@ -18,6 +19,17 @@ - **When a human verdict contradicts your measurement, the measurement falls** — at once, and in every brief already dispatched. - **After 2 failed delegations on a localised, already-measured defect: read and fix it yourself.** +## AUTONOMY +- **A mandate is the go**: inside it, reversible steps need no question; never re-ask a permission already given. Irreversible → ONE binary question (Clarify rule, `00-critical-rules.md`). +- **Always delegate** — every edit, even one line (skills, rules, CLAUDE.md), goes to an agent; the lead orchestrates and verifies. +- **Never hand the owner a step — find the way yourself.** Blocked → try every legitimate route first (another URL, the page's own file/CDN link, an API, a real browser session, another source). Only what a safety rule forbids the agent goes back — solving a CAPTCHA, typing a password, an approval the hook requires the owner to type — and then exactly what to type, one line. +- **An owner message mid-task amends the mandate** — absorb it, keep going. +- **Guarantee, don't hedge.** Never open with "I can't guarantee" — measure first, then state what is guaranteed with its proof (diff, tests, runtime). A value you can derive from a measurement (timeout, threshold, default) is yours to pick, configurable — never a question to the owner. +- **Each owner correction → a rule in the skill/agent that failed, same turn**, then synced. The owner never repeats himself. +- **Before "done": open the real output** (screenshot, frames, file, page) **and tick every part of the request by name**; unverified = "not verified". +- **Deliverables where the owner sees them** (visible folder / sent file / link), never only a hidden dir. **Follow executors to the end**; releases only via the commit agent, never an external executor (Kimi/Codex/Cursor). +- **Replies**: answer first, ≤ 10 lines, one recommendation + the next step — no option menus when one choice is clearly better. + ## Identity Expert full-stack engineer. ALWAYS use latest stable versions for the current year — check docs before assuming any version. Posture: skeptical, analytical, direct, ultra-concise. Zero filler/preamble/apologies. Say "I don't know" > guessing. Challenge own ideas via `research-expert` + fuse-browser fast-path before proposing. @@ -25,7 +37,7 @@ User = expert engineer who knows the system better than you — no hand-holding, Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only the details that change a decision. NEVER write like a dictionary — no exhaustive lists when one answer is expected, no theory recap before the point, no restating what the user already knows. ## Non-Negotiables (read first) -1. **ALWAYS DELEGATE** — the lead orchestrates, never executes (details in "Before ANY Action"). **Two-speed communication, ALWAYS**: mandates to agents are ULTRA-DETAILED and self-contained — context, exclusive file ownership, guardrails (re-verify on disk before editing, strict validation), expected report format; replies to the USER are short and precise. Never blur the two — a vague agent brief = wrong deliverable; a long user reply = noise. +1. **ALWAYS DELEGATE** — the lead orchestrates, never executes (details in "Before ANY Action"). **Two-speed communication, ALWAYS**: mandates to agents are ULTRA-DETAILED and self-contained — context, the task and the files it owns (exclusive), guardrails (re-verify on disk before editing, strict validation), expected report format; replies to the USER are short and precise. Never blur the two — a vague agent brief = wrong deliverable; a long user reply = noise. 2. **FULL APEX MANDATORY** — 6 phases: Analyze → Plan → Execute → **eLicit** (auto-review) → **Verify** (functional check) → **eXamine** (sniper). Gate: **eLicit + Verify BEFORE sniper — NEVER skip**. 3. **RIGHT AGENT FOR EACH TASK** — route by Project Detection (domain-expert); never a generic agent when a domain expert exists. 4. **EXIT CONTRACT** — every agentic loop ends on one explicit issue, never silent drift: **Stop** (goal *verified* with proof, not "I changed it") · **Retry** (new hypothesis — never the same fix twice) · **Rollback** (change broke something → return to the last green state via `git stash`/revert *before* stacking another fix) · **Ask** (several readings → one targeted question first) · **Escalate** (past the attempt cap, or risk/security → hand off with a root-cause note). The attempt counter and its cap live in code (sniper Fix Retry Loop), not prose. @@ -66,8 +78,8 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only |-------|--------|-----| | Trivial / read-only / 1 targeted file, bounded change | Direct edit (or 1 domain-expert) + sniper. NO team, NO mandatory ANALYZE trio. | Orchestration cost (spawn, briefs, FIFO cross-checks) exceeds the gain. | | Non-trivial mono-concern (1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | -| Truly parallelizable: INDEPENDENT batches, multi-domain, or large multi-file with no cross-dependency | **Propose TeamCreate** — ask user first. A team is **MINIMUM 4 agents in parallel**, NEVER 1 (1 agent = not a team). | Parallelism only pays when the batches have no dependency between them. | -| User says "team" / "crée une team" | **TeamCreate immediately** — team of min 4, no debate. | Owner's explicit call overrides the ladder. | +| Truly parallelizable: INDEPENDENT tasks, multi-domain, or large work with no cross-dependency | **Parallel team** — launch the sub-agents as parallel calls in one message. A team is **MINIMUM 4 sub-agents in parallel**, NEVER 1 (1 agent = not a team). Announce the split, don't ask. | Parallelism only pays when the tasks have no dependency between them. | +| User says "team" / "crée une team" | **Spin the team up immediately** — minimum 4, no debate. | Owner's explicit call overrides the ladder. | **Key rule — the trigger is NOT the file count, it is the INDEPENDENCE of the batches.** 2 coupled files = 1 executor; 6 independent files = team. @@ -84,6 +96,7 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only - Task = create/build/feature/refactor/debug/multi-file → **consult APEX skills first**: `fuse-ai-pilot:apex` / `fuse-ai-pilot:apex-methodology` (+ `apex-quick` for trivial). The full methodology lives there, not inline here. - SOLID/DRY → **consult SOLID skills** (`solid-*` / rule `04-solid-dry-rules.md`). - Full rule detail → rules `00-08`, injected at SessionStart and SubagentStart — don't restate them here. +- Lead procedure (request → verified report) → **consult `fuse-ai-pilot:lead-orchestration`**. - Commit/release → delegate to the **`fuse-ai-pilot:commit`** agent (it owns the whole flow: security, PATCH bump + M2 marketplace mirror, CI-wait before merge, post-merge tag). NEVER hand-roll a commit. - **Memory hygiene**: when `MEMORY/LESSON.md` grows or accumulates near-duplicate lessons → run `/lessons-compact` (it delegates to the `lessons-compactor` agent, which proposes; you approve before anything is written) — never let it bloat. - Debug/investigation ("why", "not working", "bug", "crash") → always go through Analyze (explore-codebase + research-expert + domain-expert). diff --git a/.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc b/.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc index 38721a5..818d304 100644 --- a/.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc +++ b/.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc @@ -9,6 +9,33 @@ alwaysApply: true Edit AGENTS.md, then re-copy here — never diverge the two. Deployed to ~/.cursor/rules/fuse-global.mdc by the installer, never by an agent. --> +## HARD STOPS +0. **Every owner request starts by loading skill `fuse-ai-pilot:lead-orchestration`** (intake checklist → route → brief → delegate → follow → verify → report) — the lead orchestrates, never edits. +1. **NEVER git commit / push / reset** without explicit permission. Read-only git is free. +2. **NEVER modify files** without explicit user instruction. +3. **NEVER write outside the mandate** — never `~/.cursor`, `~/.claude` or `~/.codex` (real API keys), never an installed or deployed copy, never run `install.sh` / `install.ps1` — **unless the owner names that file or path in the mandate** (e.g. "edit my global rule", "sync the install"): then the lead's brief quotes the owner's words and the agent may write exactly that target, nothing else. +4. **ONE folder = ONE owner.** Before sending an agent in: `ls -lT` + `date`. Mtime under ~5 min = busy, send no one. +5. **A message does NOT stop an agent.** It reaches a subagent only when it is resumed; the running one finishes its turn and writes anyway. Cursor documents no stop call for a running subagent: confirm mtimes stopped before reporting a state frozen. + +## RECURRING TRAPS +- **Never invent a constraint the owner did not ask for** — no size, line or file-count cap. Yours becomes a VETO: an executant will refuse a real fix to honour it. Only the hook's limits hold (`FUSE_SOLID_MAX_LINES`): respect them, never bypass; if one blocks a legitimate fix, report it — the owner tunes it, you do not. +- **A recent mtime proves a file was touched, never that the named defect is fixed.** Re-measure the defect itself before relaunching or reporting. +- **VISUAL defect: screenshot BEFORE naming a cause.** A diagnosis read off the CSS ranks causes by elegance, not by what jumps out. +- **A short positive verdict is not necessarily global** — check it covers the NAMED defect that motivated the mandate. +- **When a human verdict contradicts your measurement, the measurement falls** — at once, and in every brief already dispatched. +- **After 2 failed delegations on a localised, already-measured defect: read and fix it yourself.** + +## AUTONOMY +- **A mandate is the go**: inside it, reversible steps need no question; never re-ask a permission already given. Irreversible → ONE binary question (Clarify rule, Non-Negotiables #5). +- **Always delegate** — every edit, even one line (skills, rules, AGENTS.md), goes to an agent; the lead orchestrates and verifies. +- **Never hand the owner a step — find the way yourself.** Blocked → try every legitimate route first (another URL, the page's own file/CDN link, an API, a real browser session, another source). Only what a safety rule forbids the agent goes back — solving a CAPTCHA, typing a password, an approval the hook requires the owner to type — and then exactly what to type, one line. +- **An owner message mid-task amends the mandate** — absorb it, keep going. +- **Guarantee, don't hedge.** Never open with "I can't guarantee" — measure first, then state what is guaranteed with its proof (diff, tests, runtime). A value you can derive from a measurement (timeout, threshold, default) is yours to pick, configurable — never a question to the owner. +- **Each owner correction → a rule in the skill/agent that failed, same turn**, then synced. The owner never repeats himself. +- **Before "done": open the real output** (screenshot, frames, file, page) **and tick every part of the request by name**; unverified = "not verified". +- **Deliverables where the owner sees them** (visible folder / sent file / link), never only a hidden dir. **Follow executors to the end**; releases only via the commit agent, never an external executor (Kimi/Codex/Claude Code). +- **Replies**: answer first, ≤ 10 lines, one recommendation + the next step — no option menus when one choice is clearly better. + ## Identity Expert full-stack engineer. ALWAYS use latest stable versions for the current year — check docs before assuming any version. Posture: skeptical, analytical, direct, ultra-concise. Zero filler/preamble/apologies. Say "I don't know" > guessing. Challenge own ideas via `research-expert` + fuse-browser fast-path before proposing. @@ -16,7 +43,7 @@ User = expert engineer who knows the system better than you — no hand-holding, Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only the details that change a decision. NEVER write like a dictionary — no exhaustive lists when one answer is expected, no theory recap before the point, no restating what the user already knows. ## Non-Negotiables (read first) -1. **ALWAYS DELEGATE** — the lead is a COORDINATOR: it orchestrates, never executes itself. No reading, searching or editing by hand — delegate to a specialised sub-agent (see "Before ANY Action" below). Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, exclusive file ownership, guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. **IMPORTANT — two-speed communication, ALWAYS: give agents ULTRA-DETAILED, exhaustive tasks (context + exclusive files + guardrails + expected report); reply to the USER clear, short, concise. Never blur the two — a short agent brief = wrong deliverable; a long user reply = noise.** +1. **ALWAYS DELEGATE** — the lead is a COORDINATOR: it orchestrates, never executes itself. No reading, searching or editing by hand — delegate to a specialised sub-agent (see "Before ANY Action" below). Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, the task and the files it owns (exclusive; one agent per task), guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. **IMPORTANT — two-speed communication, ALWAYS: give agents ULTRA-DETAILED, exhaustive tasks (context + the task and its exclusive files + guardrails + expected report); reply to the USER clear, short, concise. Never blur the two — a short agent brief = wrong deliverable; a long user reply = noise.** 2. **FULL APEX MANDATORY** — 6 phases: Analyze → Plan → Execute → **eLicit** (auto-review) → **Verify** (functional check) → **eXamine** (sniper). Gate: **eLicit + Verify BEFORE sniper — NEVER skip**. 3. **RIGHT AGENT FOR EACH TASK** — route by Project Detection (domain-expert); never a generic agent when a domain expert exists. 4. **EXIT CONTRACT** — every agentic loop ends on one explicit issue, never silent drift: **Stop** (goal *verified* with proof, not "I changed it") · **Retry** (new hypothesis — never the same fix twice) · **Rollback** (change broke something → return to the last green state via `git stash`/revert *before* stacking another fix) · **Ask** (several readings → one targeted question first) · **Escalate** (past the attempt cap, or risk/security → hand off with a root-cause note). The attempt counter and its cap live in code (sniper Fix Retry Loop), not prose. @@ -53,11 +80,12 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only | Scope | Action | Why | |-------|--------|-----| | Trivial / read-only / 1 targeted file, bounded change | Direct edit (or 1 domain-expert) + sniper. NO team, NO mandatory ANALYZE trio. | Orchestration cost (spawn, briefs, FIFO cross-checks) exceeds the gain. | -| Non-trivial mono-concern (1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | -| Truly parallelizable: INDEPENDENT batches, multi-domain, or large multi-file with no cross-dependency | **Propose a parallel team** — ask user first. A team is **MINIMUM 4 sub-agents in parallel**, NEVER 1 (1 agent = not a team). | Parallelism only pays when the batches have no dependency between them. | +| Non-trivial, ONE task (mono-concern; 1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | +| Several tasks, SAME domain, even COUPLED | **One agent per task** — each task has one agent and owns the files it needs; coupling is handled by the brief (shared contract stated up front). Two tasks that must edit the same file are merged into one task or sequenced. Announce the split, don't ask. | Coupling forbids concurrent edits to the SAME file, not concurrent work on the same feature. | +| Truly parallelizable: INDEPENDENT tasks, multi-domain, or large work with no cross-dependency | **Parallel team** — launch the sub-agents as parallel calls in one message. A team is **MINIMUM 4 sub-agents in parallel**, NEVER 1 (1 agent = not a team). Announce the split, don't ask. | Parallelism only pays when the tasks have no dependency between them. | | User says "team" / "crée une team" | **Spin the team up immediately** — minimum 4, no debate. | Owner's explicit call overrides the ladder. | -**Key rule — the trigger is NOT the file count, it is the INDEPENDENCE of the batches.** 2 coupled files = 1 executor; 6 independent files = team. +**Key rule — the trigger is the TASK SET; coupling dictates the SPLIT, not the agent count.** One task = one agent; several tasks = one agent per task; independent tasks = team. Never two agents on the same file. ### Dev Workflow - **ALWAYS work in dev/source repo** — NEVER write to deployed/production paths directly @@ -67,6 +95,7 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only **Only exception:** Git read-only (status, log, diff) ## Directives — Consult Your Skills +- Lead procedure (request → verified report) → **consult `fuse-ai-pilot:lead-orchestration`**. - Task = create/build/feature/refactor/debug/multi-file → **consult APEX skills first**: `fuse-ai-pilot:apex` / `fuse-ai-pilot:apex-methodology` (+ `apex-quick` for trivial). The full methodology lives there, not inline here. - SOLID/DRY → **consult SOLID skills** (`solid-*` / rule `04-solid-dry-rules.md`). - Full rule detail → rules `00-08`, which the `fuse-rules` plugin intends to deliver through its hooks; end-to-end Cursor delivery is runtime-unverified — don't restate them here. @@ -76,7 +105,7 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only - `sniper` runs AFTER all teammates finish — never during. ## SOLID Rules -1. **File size** - `FUSE_SOLID_MAX_LINES` (default `200`) is the only file-size ceiling; split files that exceed it +1. **File size** - `FUSE_SOLID_MAX_LINES` (default `200`) is the only file-size ceiling; split files that exceed it. Never set your own cap and never work around the hook's; if a legitimate fix cannot fit, report it to the owner, who tunes the variable 2. **Interfaces separated** - Per stack location 3. **Research first** - `research-expert` before ANY code 4. **Validate after** - `sniper` after ANY modification diff --git a/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/SKILL.md b/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/SKILL.md index d1ffaac..fb07726 100644 --- a/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/SKILL.md +++ b/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/SKILL.md @@ -6,7 +6,7 @@ user-invocable: false --- -SOLID Detection identifies a project's language/framework from its config files (package.json + next/react, tsconfig.json/bun files, composer.json + laravel, Package.swift/*.xcodeproj, pom.xml/build.gradle, go.mod, Gemfile+Rakefile, Cargo.toml, pyproject.toml/requirements.txt) in a fixed priority order, then maps it to the matching SOLID skill and sets `SOLID_PROJECT_TYPE`, `SOLID_INTERFACE_DIR`, and `SOLID_STRUCTURE` environment variables via `detect-project.sh`. File-size validation uses the canonical `FUSE_SOLID_MAX_LINES` variable (default `200`). +SOLID Detection identifies a project's language/framework from its config files (package.json + next/@tanstack/react-start/astro/react, tsconfig.json/bun files, composer.json + laravel, Package.swift/*.xcodeproj, pom.xml/build.gradle, *.csproj/*.sln, go.mod, Gemfile+Rakefile, Cargo.toml, pyproject.toml/requirements.txt) in a fixed priority order, then maps it to the matching SOLID skill and sets `SOLID_PROJECT_TYPE`, `SOLID_INTERFACE_DIR`, and `SOLID_STRUCTURE` environment variables via `detect-project.sh`. File-size validation uses the canonical `FUSE_SOLID_MAX_LINES` variable (default `200`). An interface found in the wrong location is a hard BLOCK; exceeding the file-size limit or missing documentation is a WARNING only. See `language-rules.md` for the full per-language interface-location, forbidden-zone, and line-counting rules. @@ -15,7 +15,7 @@ An interface found in the wrong location is a hard BLOCK; exceeding the file-siz ## References -- [language-rules.md](references/language-rules.md) - Load when: resolving the exact interface directory, file-limit, or pattern-detection regex for a specific language (Next.js, React, Generic TS, Laravel, Swift, Java, Go, Ruby, Rust, Python), or counting lines while excluding comments/blanks +- [language-rules.md](references/language-rules.md) - Load when: resolving the exact interface directory, file-limit, or pattern-detection regex for a specific language (Next.js, TanStack Start, Astro, React, Generic TS, Laravel, Swift, Java, C#, Go, Ruby, Rust, Python), or counting lines while excluding comments/blanks ## Project Detection @@ -25,7 +25,13 @@ Detect project type from configuration files: # Next.js (priority over React) [ -f "package.json" ] && grep -q '"next"' package.json -# React (no "next" in package.json) +# TanStack Start (priority over React) +[ -f "package.json" ] && grep -q '"@tanstack/react-start"' package.json + +# Astro (priority over React) +[ -f "package.json" ] && grep -q '"astro"' package.json + +# React (no next / TanStack Start / astro in package.json) [ -f "package.json" ] && grep -q '"react"' package.json && ! grep -q '"next"' package.json # Generic TypeScript (no react/next, has .ts files) @@ -41,6 +47,9 @@ Detect project type from configuration files: # Java [ -f "pom.xml" ] || [ -f "build.gradle" ] || [ -f "build.gradle.kts" ] +# C# / .NET +ls *.csproj *.sln *.slnx 2>/dev/null | grep -q . + # Go [ -f "go.mod" ] @@ -54,7 +63,7 @@ Detect project type from configuration files: [ -f "pyproject.toml" ] || [ -f "requirements.txt" ] ``` -**Priority order:** Next.js > React > Generic TS > Laravel > Swift > Java > Go > Ruby > Rust > Python +**Priority order:** Next.js > TanStack Start > Astro > React > Generic TS > Laravel > Swift > Java > C# > Go > Ruby > Rust > Python For the full per-language rule tables (interface location, forbidden zones, pattern-detection regex) and line-counting rules, see [language-rules.md](references/language-rules.md). @@ -71,22 +80,27 @@ For the full per-language rule tables (interface location, forbidden zones, patt | Project Type | SOLID Skill | Skill Path | |--------------|-------------|------------| | `nextjs` | solid-nextjs | `nextjs-expert/skills/solid-nextjs/` | +| `tanstack-start` | solid-tanstack-start | `tanstack-start-expert/skills/solid-tanstack-start/` | +| `astro` | solid-astro | `astro-expert/skills/solid-astro/` | | `react` | solid-react | `react-expert/skills/solid-react/` | | `generic` | solid-generic | `solid/skills/solid-generic/` | | `laravel` | solid-php | `laravel-expert/skills/solid-php/` | | `swift` | solid-swift | `swift-apple-expert/skills/solid-swift/` | | `java` | solid-java | `solid/skills/solid-java/` | +| `csharp` | solid-csharp | `solid/skills/solid-csharp/` | | `go` | solid-go | `solid/skills/solid-go/` | | `ruby` | solid-ruby | `solid/skills/solid-ruby/` | | `rust` | solid-rust | `solid/skills/solid-rust/` | -| `python` | _(no skill yet)_ | - | +| `python` | solid-python | `solid/skills/solid-python/` | + +Each `solid-` skill defines that stack's own shared locations (DRY "Check shared locations" step) — load it before writing new code; never apply another stack's directories. ## Environment Variables Set by `detect-project.sh`: ```bash -SOLID_PROJECT_TYPE=nextjs|react|generic|laravel|swift|java|go|ruby|rust|python|unknown +SOLID_PROJECT_TYPE=nextjs|tanstack-start|astro|react|generic|laravel|swift|java|csharp|go|ruby|rust|python|unknown FUSE_SOLID_MAX_LINES=200 SOLID_INTERFACE_DIR=path/to/interfaces SOLID_STRUCTURE=modular diff --git a/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/references/language-rules.md b/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/references/language-rules.md index 338f072..ea72570 100644 --- a/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/references/language-rules.md +++ b/.cursor-plugin/plugins/fuse-solid/skills/solid-detection/references/language-rules.md @@ -149,6 +149,7 @@ | File limit | `FUSE_SOLID_MAX_LINES` (default `200`) | | Interface location | `src/interfaces/` | | Forbidden | ABC outside interfaces/ | +| SOLID skill | `solid-python` | **Pattern detection**: ```regex diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/README.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/README.md index 3e6758c..d9d46b9 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/README.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/README.md @@ -23,16 +23,16 @@ would be a divergence, not a precaution (R4–R6 / R8–R10 preamble). | Skill | Description | | :-- | :-- | | `swift-core` | Swift 6 fundamentals — concurrency, architecture, testing, i18n, performance — across any Apple platform | -| `swiftui-core` | SwiftUI views, navigation, persistence, state management — shared across iOS, macOS, watchOS, visionOS | +| `swiftui-core` | SwiftUI views, navigation, persistence, state management, Liquid Glass, and HIG rules (accessibility, RTL, modality, widgets/Live Activities/notifications/Siri, iPhone Duo) — shared across iOS, macOS, watchOS, visionOS | | `ios` | iPhone apps — simulator/device testing, UI automation, debugging — with XcodeBuildMCP tools | | `ipados` | iPad apps — split views, external keyboard support, multitasking, Stage Manager, adaptive layouts | | `macos` | Mac apps — menu bar extras, window management, AppKit integration, notarized distribution | | `watchos` | Apple Watch apps — complications, workouts, HealthKit, iPhone-Watch connectivity | | `visionos` | Vision Pro apps — spatial computing, RealityKit 3D content, immersive spaces, volumes | | `tvos` | Apple TV apps — focus-based navigation, Siri Remote interactions, media/video streaming UI | -| `mcp-tools` | Xcode build automation and Apple API/WWDC documentation lookup via XcodeBuildMCP and apple-docs MCP servers | -| `build-distribution` | Apple releases — code signing, TestFlight upload, App Store submission, app icons, CI | -| `solid-swift` | SOLID for Swift 6/SwiftUI — file-size limits, protocol separation, `@Observable`, actors, feature-modular architecture | +| `mcp-tools` | Xcode build automation and Apple API/WWDC documentation lookup via XcodeBuildMCP and apple-docs MCP servers; UI verification on simulator | +| `build-distribution` | Apple releases — code signing, TestFlight upload, App Store submission, Icon Composer app icons, CI | +| `solid-swift` | SOLID for Swift 6/SwiftUI — hook size ceiling (`FUSE_SOLID_MAX_LINES`), protocol separation, `@Observable`, actors, feature-modular architecture | SOLID guidance is **local** here (`solid-swift`), not delegated to `fuse-solid`. @@ -42,6 +42,8 @@ The agent activates when `Package.swift` or an `*.xcodeproj` is detected — iOS visionOS/tvOS apps, SwiftUI views, Swift concurrency, XcodeBuildMCP automation. Not for web frontend, Laravel/PHP, or non-Apple platforms. +For UI changes the agent runs a 10-item HIG gate on the simulator (Dynamic Type AX5, dark mode + Increase Contrast, VoiceOver labels, hit targets, RTL, Reduce Motion/Transparency, Liquid Glass, screen sizes, modality/order), each reported `pass` / `fail` / `not verified`, before `sniper`. + ## Configuration No `variables` are declared; the plugin needs no secrets. Hooks shell out to @@ -82,8 +84,12 @@ declares no `mcpServers` of its own; it did not in the source either. ### Skills All 11 satisfy Cursor's hard rule that `name:` equals the parent folder name (R9). `references/` and -nested `references/templates/` folders are natively supported and were copied verbatim — -`diff -rq` between the source `skills/` and this one is empty. +nested `references/templates/` folders are natively supported and were copied verbatim in the +initial port. On 2026-10-12 the source's uncommitted working-tree improvements were ported on top +(HIG references, mcp-tools workflows, tvOS/watchOS/visionOS/build-distribution updates), so +`diff -rq` against the source is no longer empty. Target-only deviations kept on purpose: the +`Task`-based wording (instead of Claude's `Agent`-with-`name`) in the SKILL.md "Agent Workflow" sections, the `FUSE_SOLID_MAX_LINES` rewrite of +`solid-swift`, the same ceiling wording in `swiftui-core` (no "30+ lines" view cap), this README's port notes, and the Cursor frontmatter of the agent. Frontmatter keys preserved verbatim, absent from Cursor's documented skill schema and **not verified against the binary**, so their status is unknown rather than unsupported (R7/R19): diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/agents/swift-expert.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/agents/swift-expert.md index abefa25..92da7c2 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/agents/swift-expert.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/agents/swift-expert.md @@ -3,7 +3,7 @@ name: swift-expert description: "Use when: Package.swift or *.xcodeproj detected, iOS/macOS/watchOS/visionOS/tvOS apps, SwiftUI views, Swift concurrency, XcodeBuildMCP automation. Do NOT use for: web frontend, Laravel/PHP, non-Apple platforms." model: grok-4.6 color: red -tools: mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__XcodeBuildMCP__*, mcp__apple-docs__*, Read, Glob, Grep, Edit, Write, Bash, Task, Skill, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_console, mcp__fuse-browser__browser_inspect, mcp__fuse-browser__browser_snapshot, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch +tools: mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__XcodeBuildMCP__*, mcp__apple-docs__*, Read, Glob, Grep, Edit, Write, Bash, Task, Skill, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_console, mcp__fuse-browser__browser_inspect, mcp__fuse-browser__browser_snapshot, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__sequential-thinking__sequentialthinking skills: swift-core, swiftui-core, ios, macos, ipados, watchos, visionos, tvos, mcp-tools, build-distribution, solid-swift, elicitation, fuse-ai-pilot:fuse-browser-usage --- @@ -36,6 +36,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_snapshot` - `mcp__fuse-browser__browser_fetch` - `mcp__fuse-browser__browser_fetch_batch` +- `mcp__sequential-thinking__sequentialthinking` You are an expert Swift and SwiftUI developer, specialized across all Apple platforms — iOS, macOS, watchOS, visionOS, and tvOS. You work with the latest stable Swift release; version specifics live in the `swift-core` skill. You have XcodeBuildMCP for build/test automation and Apple Docs MCP for official API and WWDC research — you prioritize Apple Docs MCP over Context7 for anything Apple-specific. @@ -61,13 +62,12 @@ Then implement using the platform-specific skill(s) (see Coding Standards below) ## MCP Tools Available (NEW 2026) ### XcodeBuildMCP (Xcode Automation) -**Source**: [XcodeBuildMCP GitHub](https://github.com/cameroncooke/XcodeBuildMCP) +**Source**: [xcodebuildmcp.com](https://www.xcodebuildmcp.com) — details in `mcp-tools` skill (`xcodebuild-mcp.md`) - **Discover Projects**: Find Xcode projects and workspaces -- **Build Operations**: Build for macOS, iOS simulator, iOS device -- **List Schemes**: Show available schemes in projects -- **Show Build Settings**: Display Xcode build configuration -- **Clean Build**: Clean build products and derived data +- **Build/Run/Test**: `build_sim`, `build_run_sim`, `test_sim` (simulator), device and macOS workflows +- **List Schemes / Show Build Settings / Clean** +- **UI evidence**: `screenshot`, `snapshot_ui` (default workflow); `set_sim_appearance` and taps need the `simulator-management` / `ui-automation` workflows - **Create Project**: Scaffold new iOS/macOS projects with modern templates **Use cases**: @@ -83,7 +83,7 @@ Then implement using the platform-specific skill(s) (see Coding Standards below) - **Get Framework Details**: Access detailed framework information - **Get Symbol Info**: Retrieve class, method, property documentation - **List Technologies**: Explore available Apple frameworks -- **Search WWDC**: Find WWDC sessions (2014-2025) with transcripts +- **Search WWDC**: Bundled WWDC sessions (2014-2025) with transcripts; newer sessions via `browser_fetch` on developer.apple.com/videos - **Get Sample Code**: Access Apple code examples and snippets **Use cases**: @@ -119,6 +119,7 @@ Then implement using the platform-specific skill(s) (see Coding Standards below) - **Protocol-oriented** design, **cohesive views** (extract subviews when responsibilities diverge), **accessibility** mandatory - **i18n** — ALL user-facing text must use String Catalogs - See platform-specific skills (`ios`, `macos`, `watchos`, `visionos`, `tvos`, `ipados`) for platform targeting +- **HIG** — for any UI work load the `swiftui-core` HIG references (`hig-accessibility.md`, `hig-rtl.md`, `hig-modality.md`, `hig-system-surfaces.md`, `hig-iphone-duo.md`, `liquid-glass.md`). Visual specs come from the design-ios handoff when one exists; you implement and verify them. ## fuse-browser (ZERO TOLERANCE) @@ -132,7 +133,27 @@ Then implement using the platform-specific skill(s) (see Coding Standards below) Done = all checks below pass with ZERO errors: 1. Run `build_sim` (XcodeBuildMCP) — build succeeds 2. Run `test_sim` (XcodeBuildMCP) — all tests pass -3. Run **fuse-ai-pilot:sniper** for validation +3. **UI changed? Run the HIG UI Gate below** — no `done` while an item is `fail` +4. Run **fuse-ai-pilot:sniper** for validation + +### HIG UI Gate (any UI change) + +`session_show_defaults` → `build_run_sim` on a booted simulator, then capture evidence with `screenshot` / `snapshot_ui`. Procedure and commands: `mcp-tools` → `xcodebuild-mcp-ui-verification.md`. Rules: `swiftui-core` HIG references. + +| # | Check | Pass criterion (HIG source) | +|---|-------|-----------------------------| +| 1 | Baseline | Light mode, default text size screenshot, no layout errors | +| 2 | Dynamic Type AX5 | `simctl ui content_size accessibility-extra-extra-extra-large`: no clipping/overlap, no truncation in scrollable text, rows stacked (/typography) | +| 3 | Dark mode + Increase Contrast | Text ≥ 4.5:1 (target 7:1 small text); custom colors adapt (/dark-mode, /color) | +| 4 | VoiceOver labels | `snapshot_ui`: every interactive element labeled, icon-only controls included (/voiceover) | +| 5 | Hit targets | Frames ≥ 44×44 pt iOS/iPadOS/watchOS, 60 visionOS, 66 tvOS, 28 macOS; below platform minimum = fail (/accessibility) | +| 6 | RTL | `launch_app_sim` args `-AppleTextDirection YES`: navigation/progress mirrored, logos/checkmarks not (/right-to-left) | +| 7 | Reduce Motion / Transparency | Custom animations become fades; custom glass/material falls back to opaque (/accessibility, /materials) | +| 8 | Liquid Glass | No `glassEffect` on content layer, standard bars, sidebars; tint only on primary action (/materials) | +| 9 | Screen sizes | Compact iPhone + iPad regular (+ iPhone Duo poses if available); no fixed widths (/layout, /designing-for-iphone-duo) | +| 10 | Modality & order | Sheet Cancel leading / Done trailing; `snapshot_ui` order = sensible VoiceOver order (/sheets, /voiceover) | + +Report every item as `pass`, `fail` or `not verified` (with reason, e.g. "ui-automation workflow disabled", "no iPad simulator"). Never `pass` without a screenshot or snapshot proving it. ## Output Format @@ -140,5 +161,6 @@ Report back to the lead with: - **status**: `done` | `failed` | `blocked` - **files_changed**: list of modified/created files - **verification**: results from the Verification Gate above (build_sim/test_sim + sniper outcome) +- **hig_gate**: the 10 items above, each `pass` / `fail` / `not verified` + evidence path (screenshot/snapshot) — or `n/a (no UI change)` - **remaining_issues**: any known gaps or follow-ups, or `none` - **sources_verified**: Apple Docs MCP / Context7 / Exa references consulted (Core Rule) diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/SKILL.md index 9602127..a30bd14 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/SKILL.md @@ -11,7 +11,7 @@ related-skills: swift-core, ios, macos, mcp-tools Covers app build, code signing, and distribution across all Apple platforms: certificate/profile management, TestFlight beta distribution, App Store submission, app icon/asset preparation, and StoreKit 2 in-app purchases/subscriptions. -Includes a release checklist (version/build number, app icons for light/dark/tinted, privacy manifest, release configuration, archive validation, TestFlight testing, screenshots, App Store metadata) and guidance on automating releases with fastlane and CI/CD (e.g. GitHub Actions). +Includes a release checklist (version/build number, layered Icon Composer app icon checked in default/dark/clear/tinted appearances, privacy manifest, release configuration, archive validation, TestFlight testing, screenshots, App Store metadata) and guidance on automating releases with fastlane and CI/CD (e.g. GitHub Actions). Best practices favor automatic signing, TestFlight testing before any public release, incrementing the build number on every upload, and a mandatory privacy manifest for App Store submission. @@ -22,7 +22,7 @@ App build, signing, and distribution for all Apple platforms. ## Agent Workflow (MANDATORY) -Before ANY distribution, use `TeamCreate` to spawn 3 agents: +Before ANY distribution, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing build configuration 2. **fuse-ai-pilot:research-expert** - Verify latest App Store requirements @@ -69,7 +69,7 @@ After implementation, run **fuse-ai-pilot:sniper** for validation. ## Release Checklist - [ ] Version and build number updated -- [ ] App icons complete (light/dark/tinted) +- [ ] Layered app icon (Icon Composer) checked in default/dark/clear/tinted appearances, incl. alternate icons ([HIG app icons](https://developer.apple.com/design/human-interface-guidelines/app-icons)) - [ ] Privacy manifest (PrivacyInfo.xcprivacy) - [ ] Release configuration - [ ] Archive validates diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/references/app-icons.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/references/app-icons.md index c0374a6..ceaa0af 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/references/app-icons.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/build-distribution/references/app-icons.md @@ -1,110 +1,76 @@ --- name: app-icons -description: App icons, SF Symbols, launch screens, and asset catalogs for all Apple platforms -when-to-use: creating app icons, using SF Symbols, configuring launch screens, managing assets -keywords: app icon, SF Symbols, launch screen, asset catalog, dark mode icon, tinted icon +description: Layered app icons with Icon Composer (Liquid Glass), appearance variants, SF Symbols, launch screens and asset catalogs for all Apple platforms +when-to-use: creating or updating app icons, using SF Symbols, configuring launch screens, managing assets +keywords: app icon, Icon Composer, layered icon, Liquid Glass, dark icon, clear icon, tinted icon, SF Symbols, launch screen, asset catalog priority: medium related: code-signing.md, app-store.md --- # App Icons & Assets -## When to Use +Source: https://developer.apple.com/design/human-interface-guidelines/app-icons -- Creating app icons -- Using SF Symbols -- Configuring launch screens -- Managing asset catalogs -- Supporting dark/tinted icons +## Layered Icons (Liquid Glass) -## Key Concepts +- iOS, iPadOS, macOS and watchOS icons are a **background layer + one or more foreground layers**. The system applies Liquid Glass effects (specular highlights, refraction, translucency), adapting per size and system version. +- A flattened image is still accepted, but layers give the most control. +- tvOS: 2-5 layers (parallax). visionOS: background + 1-2 layers (3D, embossed). -### Single-Size Icons (Xcode 15+) -Provide one 1024x1024 PNG, Xcode generates all sizes. +## Icon Composer Workflow (iOS, iPadOS, macOS, watchOS) -**Key Points:** -- No transparency (alpha = 1.0) -- No rounded corners (system applies) -- PNG format, sRGB or Display P3 -- Simple design readable at small sizes +1. Draw foreground layers in your design tool - prefer **vector (SVG/PDF)**; PNG for raster or mesh gradients. Outline text. +2. Import layers into **Icon Composer** (included with Xcode). +3. Define the background there (solid color or gradient - no custom background image needed in most cases; if imported: full-bleed, opaque). +4. Adjust layer placement, opacity, effects; group layers to apply effects at group level. +5. Annotate appearance variants, preview across system versions, export for Xcode. -### iOS 26 Dark & Tinted Icons -Three icon variants for appearance modes. +tvOS/visionOS: add layers directly to an image stack in Xcode (Parallax Previewer/Exporter for tvOS). -**Variants:** -- **Light** - Default icon (required) -- **Dark** - For dark mode -- **Tinted** - Monochrome for tint +## Layer Rules -**Dark Icon Guidelines:** -- Darker background -- Gradient: #313131 → #141414 -- Keep design recognizable +- Provide **square, unmasked layers** (tvOS: rectangular). The system masks corners (iOS/iPadOS/macOS rounded rect; watchOS/visionOS circle). Pre-masked layers break highlights and edges. +- Crisp edges on foreground shapes (no feathering). Vary opacity across foreground layers for depth. +- **Don't bake effects**: no specular highlights, drop shadows, bevels, blurs or glows - the system adds dynamic ones. +- Keep primary content centered (masking, watchOS/visionOS circles). Use the production template grids (Apple Design Resources). +- Simple concept, few shapes, simple background; no photos, no UI replicas, no Apple hardware, no text unless essential to the brand. +- tvOS: keep a safe zone (focus scaling crops edges); avoid black backgrounds. -**Tinted Icon Guidelines:** -- Grayscale only -- Black background -- 100% → 60% opacity gradient +## Appearances (iOS, iPadOS, macOS) -### SF Symbols -Apple's icon system with 5,000+ symbols. +People pick **default, dark, clear, or tinted** Home Screen icons. Layouts per platform: -**Rendering Modes:** -- Monochrome - Single color -- Hierarchical - Depth levels -- Palette - Custom colors -- Multicolor - Original colors +| Platform | Layout | Mask | Size | Appearances | +|----------|--------|------|------|-------------| +| iOS, iPadOS, macOS | Square | Rounded rectangle | 1024x1024 px | Default, dark, clear light, clear dark, tinted light, tinted dark | +| tvOS | Rectangle (landscape) | Rounded rectangle | 800x480 px | N/A (parallax) | +| visionOS | Square | Circle | 1024x1024 px | N/A (3D) | +| watchOS | Square | Circle | 1088x1088 px | N/A | -**Key Points:** -- Always add accessibility labels -- Use semantic names -- Check availability per OS version +- Keep core features identical across appearances; don't swap elements per variant. +- Base the dark icon on the light one; dark is more subdued, clear/tinted even more. The system generates any variant you don't provide. +- **Alternate icons** (iOS/iPadOS) need their own dark, clear and tinted variants; all are subject to App Review. +- Color spaces: sRGB, Gray Gamma 2.2, Display P3 (not visionOS). -### Launch Screen -Modern approach without storyboard. +## SF Symbols -**Info.plist Configuration:** -- UILaunchScreen dictionary -- UIImageName for image -- UIColorName for background +Source: https://developer.apple.com/design/human-interface-guidelines/sf-symbols ---- - -## Platform Icon Sizes - -| Platform | Master Size | Notes | -|----------|-------------|-------| -| iOS/iPadOS | 1024×1024 | Square, auto-rounded | -| macOS | 1024×1024 | .icns generated | -| watchOS | 1024×1024 | Circular mask | -| visionOS | 1024×1024 | 3 layers for parallax | +- Thousands of symbols aligned with San Francisco at every weight and size; availability depends on the OS version targeted. +- Four rendering modes: monochrome, hierarchical, palette, multicolor. Gradients (SF Symbols 7+) and variable color work across modes. +- Animations (incl. Draw On/Off, SF Symbols 7+): use judiciously, honour Reduce Motion. +- Icon-only symbols need an accessibility label; symbols get RTL variants automatically. ---- - -## Asset Catalog Structure - -``` -Assets.xcassets/ -├── AppIcon.appiconset/ -│ ├── Contents.json -│ ├── icon-light.png -│ ├── icon-dark.png (optional) -│ └── icon-tinted.png (optional) -├── AccentColor.colorset/ -├── LaunchImage.imageset/ -└── Colors/ - └── BrandPrimary.colorset/ -``` +## Launch Screen (iOS/iPadOS) ---- +`UILaunchScreen` dictionary in Info.plist (`UIColorName`, `UIImageName`, iOS 14+). +HIG (https://developer.apple.com/design/human-interface-guidelines/launching): nearly identical to the first screen, no text, no logo/branding, matches orientation and appearance. ## Best Practices -- ✅ Provide single 1024×1024 icon -- ✅ Support dark mode icon -- ✅ Use SF Symbols when possible -- ✅ Add accessibility labels to icons -- ✅ Test at all sizes -- ❌ Don't use transparency in app icon -- ❌ Don't add manual rounded corners -- ❌ Don't use complex details +- ✅ Layered icon built in Icon Composer, square unmasked layers +- ✅ Check every appearance (default/dark/clear/tinted) in Icon Composer or Device Hub +- ✅ SF Symbols for interface icons, with labels +- ❌ Don't pre-round corners or bake highlights/shadows +- ❌ Don't put text, photos or UI screenshots in the icon +- ❌ Don't put branding on the launch screen diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/SKILL.md index af28e57..0a56df6 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/SKILL.md @@ -23,7 +23,7 @@ iOS-specific development with XcodeBuildMCP automation tools. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing iOS patterns 2. **fuse-ai-pilot:research-expert** - Verify latest iOS 27 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/references/ui-automation.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/references/ui-automation.md index 774948a..f31b2b2 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/references/ui-automation.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ios/references/ui-automation.md @@ -1,130 +1,61 @@ --- name: ui-automation -description: XcodeBuildMCP UI automation tools - tap, swipe, screenshot, type_text, snapshot_ui -when-to-use: automating user interactions, capturing screenshots, testing UI flows -keywords: tap, swipe, screenshot, type_text, snapshot_ui, gesture, UI automation, AXe +description: XcodeBuildMCP UI automation tools - snapshot_ui, tap, batch, swipe, gesture, type_text, screenshot (elementRef-based) +when-to-use: automating user interactions, capturing screenshots, testing UI flows, accessibility checks on simulator +keywords: tap, swipe, screenshot, type_text, snapshot_ui, elementRef, batch, gesture, UI automation priority: medium requires: simulator-tools.md -related: debugging.md +related: debugging.md, ../../mcp-tools/references/xcodebuild-mcp-ui-verification.md --- # iOS UI Automation -## When to Use - -- Automating repetitive UI interactions -- Capturing screenshots for documentation -- Testing UI flows programmatically -- Extracting view hierarchy information -- Building automation scripts +Tool names and parameters read from `xcodebuildmcp@2.7.0` manifests. ## Prerequisites -**AXe Installation Required:** -```bash -brew tap cameroncooke/axe -brew install axe +- `screenshot` and `snapshot_ui` are in the default **simulator** workflow. +- `tap`, `batch`, `long_press`, `swipe`, `gesture`, `type_text`, `button`, `key_press`, `wait_for_ui` need the **ui-automation** workflow (`XCODEBUILDMCP_ENABLED_WORKFLOWS` or `.xcodebuildmcp/config.yaml` `enabledWorkflows`). +- The AXe automation binary ships bundled with the npm package. + +## Model: observe, then act by elementRef + +1. `snapshot_ui` returns a semantic runtime UI tree; actionable nodes carry an `elementRef` (e.g. `e8`) and list their actions. +2. Act on an `elementRef` - not raw coordinates. +3. Refresh `snapshot_ui` after navigation, scrolling, sheet changes or layout changes; old refs go stale. + +## Tools + +| Tool | Key parameters | Use | +|------|----------------|-----| +| `snapshot_ui` | `simulatorId`, optional `sinceScreenHash` | Element tree, labels, frames, refs | +| `wait_for_ui` | - | Wait for an element/state before acting | +| `tap` | `elementRef`, optional `preDelay`/`postDelay` | One tap on a ref listing the tap action | +| `batch` | `steps: [{"action":"tap","elementRef":"e1"}, ...]` | Several same-screen taps (e.g. toggles) | +| `long_press` | `elementRef`, `duration` (ms) | Context menus | +| `swipe` | `direction` up/down/left/right, optional `withinElementRef`, `distance`, `duration` | Scrolling, dismissing | +| `gesture` | preset `scroll-up/down/left/right`, `swipe-from-{top,bottom,left,right}-edge` | Standard system gestures | +| `type_text` | `elementRef`, `text`, optional `replaceExisting` | Form input | +| `screenshot` | `returnFormat`: `path` or `base64` | Visual evidence | + +## Workflow + +```text +1. snapshot_ui -> find elementRef + check labels/frames +2. tap / type_text / batch -> act +3. snapshot_ui (refresh) -> assert new state +4. screenshot -> evidence ``` -## Available MCP Tools - -### tap -Touch element or coordinate. - -**Parameters:** -- `x`, `y` - Screen coordinates -- `duration` - Optional hold time -- `udid` - Optional simulator UDID - -**Use when:** -- Simulating button taps -- Selecting elements - -### long_press -Extended press at coordinates. - -**Parameters:** -- `x`, `y` - Screen coordinates -- `duration` - Hold duration - -**Use when:** -- Context menu triggers -- Drag initiation - -### swipe -Drag between two points. - -**Parameters:** -- `fromX`, `fromY` - Start position -- `toX`, `toY` - End position -- `duration` - Swipe speed - -**Use when:** -- Scrolling -- Dismissing -- Page navigation - -### type_text -Enter text via keyboard. - -**Parameters:** -- `text` - String to type - -**Use when:** -- Form filling -- Search input - -### screenshot -Capture current screen. +## Accessibility Use -**Parameters:** -- `savePath` - Output file path - -**Use when:** -- Documenting UI -- Bug reports -- Visual testing - -### snapshot_ui -Get complete view hierarchy with coordinates. - -**Returns:** -- Element tree with positions -- Accessibility labels -- Frame coordinates - -**Use when:** -- Finding tap coordinates -- Understanding UI structure -- Accessibility testing - -### gesture -Execute predefined gestures. - -**Parameters:** -- `gestureType` - swipeUp, swipeDown, pinch, etc. - -**Use when:** -- Standard gestures -- Multi-finger interactions - ---- - -## Workflow: UI Automation - -1. `snapshot_ui` - Get view hierarchy -2. Find element coordinates -3. `tap` / `swipe` - Interact -4. `screenshot` - Capture result -5. Repeat as needed - ---- +`snapshot_ui` doubles as an accessibility check: unlabeled interactive nodes and frames under 44x44 pt are HIG violations (https://developer.apple.com/design/human-interface-guidelines/accessibility). Full gate: `mcp-tools/references/xcodebuild-mcp-ui-verification.md`. ## Best Practices -- ✅ Use snapshot_ui to find coordinates -- ✅ Add accessibility identifiers for reliability -- ✅ Screenshot before and after actions -- ✅ Use gestures for standard interactions -- ❌ Don't hardcode coordinates without snapshot_ui -- ❌ Don't assume static coordinates +- ✅ Always act on refs from the latest `snapshot_ui` +- ✅ Give controls accessibility labels/identifiers - they make refs stable and VoiceOver usable +- ✅ Screenshot before and after key actions +- ✅ Use `batch` for multiple same-screen taps +- ❌ Don't reuse refs after navigation or scrolling +- ❌ Don't pass text-only rows to `tap` diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ipados/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ipados/SKILL.md index 14ef052..e652dcc 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ipados/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/ipados/SKILL.md @@ -22,7 +22,7 @@ iPadOS-specific development for tablet and productivity experiences. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing iPad patterns 2. **fuse-ai-pilot:research-expert** - Verify latest iPadOS 27 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/macos/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/macos/SKILL.md index aa351f8..de7b031 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/macos/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/macos/SKILL.md @@ -23,7 +23,7 @@ macOS-specific development with window management and distribution tools. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing macOS patterns 2. **fuse-ai-pilot:research-expert** - Verify latest macOS 27 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/SKILL.md index 534b29e..5dd7f7b 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/SKILL.md @@ -2,12 +2,12 @@ name: mcp-tools description: Use when needing Xcode build automation or Apple API/WWDC documentation lookup via XcodeBuildMCP or apple-docs MCP servers. user-invocable: false -references: references/xcodebuild-mcp.md, references/apple-docs-mcp.md +references: references/xcodebuild-mcp.md, references/xcodebuild-mcp-ui-verification.md, references/apple-docs-mcp.md, references/apple-docs-mcp-workflows.md related-skills: swift-core, ios, macos --- -Documents the two MCP servers that power the Swift/Apple workflow: XcodeBuildMCP for Xcode project automation and build validation (discover projects, build for macOS/iOS Simulator/device, list schemes, clean builds, scaffold new projects, and autonomous build-fix-rebuild loops), and Apple Docs MCP for official documentation with offline WWDC access (all frameworks, symbol details, WWDC sessions 2014-2025 with transcripts, sample code, API availability/deprecation). +Documents the two MCP servers that power the Swift/Apple workflow: XcodeBuildMCP for Xcode project automation, build validation and on-simulator UI verification (discover projects, build/run/test on simulator, screenshots, runtime UI snapshots, appearance, autonomous build-fix-rebuild loops), and Apple Docs MCP for official documentation (all frameworks, symbol details, availability/deprecation, sample code, and bundled WWDC transcripts for 2014-2025 - newer sessions via developer.apple.com). Defines the mandatory research-first priority order (Apple Docs MCP first, then Context7 for third-party libraries, then Exa web search) and the mandatory build-validation loop after every code change (build, read errors, fix, rebuild, only commit on zero errors). @@ -23,14 +23,14 @@ Includes installation snippets for both servers and a quick-reference table mapp ### 1. XcodeBuildMCP **Purpose**: Xcode project automation and build validation -**Documentation**: `xcode-build-mcp.md` +**Documentation**: [xcodebuild-mcp.md](references/xcodebuild-mcp.md), [xcodebuild-mcp-ui-verification.md](references/xcodebuild-mcp-ui-verification.md) **Key features**: - Discover Xcode projects and workspaces -- Build for macOS, iOS Simulator, iOS Device +- Build/run/test on simulator (`build_run_sim`, `test_sim`), device and macOS - List schemes and show build settings - Clean builds and derived data -- Create new projects from templates +- `screenshot` + `snapshot_ui` for UI verification (default workflow); appearance and taps via optional workflows - **Autonomous build validation** (AI can build, read errors, fix, rebuild) **Installation**: @@ -56,12 +56,12 @@ Includes installation snippets for both servers and a quick-reference table mapp ### 2. Apple Docs MCP **Purpose**: Official Apple documentation with offline WWDC access -**Documentation**: `apple-docs-mcp.md` +**Documentation**: [apple-docs-mcp.md](references/apple-docs-mcp.md), [apple-docs-mcp-workflows.md](references/apple-docs-mcp-workflows.md) **Key features**: - Search all Apple frameworks (SwiftUI, UIKit, Foundation, etc.) - Get detailed symbol information (classes, methods, properties) -- **WWDC sessions 2014-2025** with full transcripts (offline) +- **WWDC sessions bundled offline for 2014-2025**; newer sessions via developer.apple.com/videos - Access Apple sample code - Framework exploration and discovery - API availability and deprecation checking @@ -130,7 +130,8 @@ After EVERY code change: ↓ 7. Run tests (if available) ↓ -8. Commit changes +8. UI changed? HIG verification gate on simulator + (xcodebuild-mcp-ui-verification.md) ``` --- @@ -146,19 +147,18 @@ After EVERY code change: ### Apple Docs MCP ✅ Official Apple documentation (most accurate) -✅ WWDC sessions offline (2014-2025) -✅ Zero network latency -✅ Complete API coverage +✅ WWDC sessions offline (2014-2025 bundled) ✅ Deprecation and availability info +⚠️ No HIG pages and no post-2025 WWDC: use developer.apple.com via `browser_fetch` --- ## Resources **XcodeBuildMCP**: -- [GitHub](https://github.com/cameroncooke/XcodeBuildMCP) +- [Website](https://www.xcodebuildmcp.com) (repository moved to getsentry) - [npm](https://www.npmjs.com/package/xcodebuildmcp) -- Version: 2.7.0 (npm, September 2026) +- Version: 2.7.0 (npm) **Apple Docs MCP**: - [GitHub](https://github.com/kimsungwhee/apple-docs-mcp) @@ -173,7 +173,9 @@ After EVERY code change: | Search Apple API | `apple-docs` | `apple-docs-mcp.md` | | Find WWDC session | `apple-docs` | `apple-docs-mcp.md` | | Get code example | `apple-docs` | `apple-docs-mcp.md` | -| Build project | `XcodeBuildMCP` | `xcode-build-mcp.md` | -| Validate changes | `XcodeBuildMCP` | `xcode-build-mcp.md` | -| Clean build | `XcodeBuildMCP` | `xcode-build-mcp.md` | -| Create project | `XcodeBuildMCP` | `xcode-build-mcp.md` | +| Research workflow | `apple-docs` | `apple-docs-mcp-workflows.md` | +| Build project | `XcodeBuildMCP` | `xcodebuild-mcp.md` | +| Validate changes | `XcodeBuildMCP` | `xcodebuild-mcp.md` | +| Clean build | `XcodeBuildMCP` | `xcodebuild-mcp.md` | +| Create project | `XcodeBuildMCP` | `xcodebuild-mcp.md` | +| Verify UI (HIG gate) | `XcodeBuildMCP` | `xcodebuild-mcp-ui-verification.md` | diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp-workflows.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp-workflows.md new file mode 100644 index 0000000..fbe81a1 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp-workflows.md @@ -0,0 +1,77 @@ +--- +name: apple-docs-mcp-workflows +description: Research-first workflows with Apple Docs MCP - API verification, WWDC research, and worked examples +when-to-use: planning research before implementing an Apple API, verifying availability, learning a new framework feature +keywords: research workflow, API verification, WWDC research, availability, deprecation +priority: medium +related: apple-docs-mcp.md +--- + +# Apple Docs MCP Workflows + +Tool reference: `apple-docs-mcp.md`. + +## Research-First (before coding) + +```text +1. search_apple_docs "" +2. get_apple_doc_content -> exact declaration +3. get_platform_compatibility -> availability, deprecation +4. search_wwdc_content "" -> recommended approach (bundled 2014-2025) +5. get_sample_code -> reference implementation +6. Implement with the official pattern +``` + +Never write an API you could not find; if unverifiable, leave it out and say so. + +## API Verification + +```text +1. get_apple_doc_content (signature + parameters) +2. get_platform_compatibility (min OS per platform) +3. Deprecated? -> get_related_apis / find_similar_apis for the replacement +4. Very new symbol missing from the MCP? -> fetch + https://developer.apple.com/tutorials/data/documentation//.json +``` + +## HIG Rule Lookup + +```text +1. browser_fetch https://developer.apple.com/design/human-interface-guidelines/ +2. Quote the rule + cite the URL in code review / report +3. Cross-check the swiftui-core HIG references (hig-*.md) +``` + +## Examples + +### SwiftUI navigation + +```text +1. search_apple_docs "NavigationStack" +2. get_apple_doc_content NavigationStack init +3. search_wwdc_content "SwiftUI navigation" +4. get_sample_code navigation +``` + +### Core Data / SwiftData issue + +```text +1. search_apple_docs "SwiftData ModelContext" +2. search_framework_symbols swiftdata +3. search_wwdc_content "SwiftData performance" +4. Apply recommended fix, rebuild with XcodeBuildMCP +``` + +### New OS feature (after the bundled WWDC range) + +```text +1. get_documentation_updates +2. browser_fetch https://developer.apple.com/videos/ (current WWDC sessions) +3. get_apple_doc_content for each new symbol +4. Verify availability before using it +``` + +## Priority Reminder + +- Apple Docs MCP first for SwiftUI, UIKit, AppKit, Foundation and every Apple framework. +- Context7 for third-party packages and general Swift libraries. diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp.md index adf2306..993c6ea 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/apple-docs-mcp.md @@ -1,324 +1,62 @@ --- name: apple-docs-mcp -description: Apple Docs MCP for official documentation, WWDC sessions, and sample code with offline access -when-to-use: researching Apple APIs, searching WWDC sessions, getting symbol documentation, finding sample code -keywords: Apple Docs, WWDC, documentation, SwiftUI, UIKit, Foundation, CoreData, sample code +description: Apple Docs MCP server - tools for official Apple documentation, symbols, platform availability, sample code and bundled WWDC sessions +when-to-use: researching Apple APIs, checking availability/deprecation, searching WWDC sessions, getting sample code +keywords: Apple Docs, WWDC, documentation, symbols, availability, SwiftUI, UIKit, sample code priority: high -related: xcodebuild-mcp.md +related: apple-docs-mcp-workflows.md, xcodebuild-mcp.md --- -# Apple Docs MCP Usage Guide +# Apple Docs MCP -**MCP Server for Apple Developer Documentation with offline WWDC access.** - -Source: [apple-docs-mcp GitHub](https://github.com/kimsungwhee/apple-docs-mcp) - ---- +Source: https://github.com/kimsungwhee/apple-docs-mcp (npm `@kimsungwhee/apple-docs-mcp`; tool names read from v1.0.26). ## Installation -Add to your MCP configuration: - ```json { "mcpServers": { - "apple-docs": { - "command": "npx", - "args": ["-y", "@kimsungwhee/apple-docs-mcp"] - } + "apple-docs": { "command": "npx", "args": ["-y", "@kimsungwhee/apple-docs-mcp"] } } } ``` ---- - -## Available Tools - -### 1. Search Documentation - -**Purpose**: Find information across all Apple frameworks - -**Searchable content**: -- SwiftUI (views, modifiers, state management) -- UIKit (view controllers, UI components) -- Foundation (data types, networking, file system) -- CoreData (persistence, fetch requests) -- ARKit (augmented reality) -- CoreML (machine learning) -- All other Apple frameworks - -**Use when**: -- Starting implementation of new feature -- Looking for specific API -- Exploring available frameworks -- Researching best practices - -**Example queries**: -``` -"SwiftUI Navigation" -"UITableView delegate methods" -"URLSession async await" -"Core Data relationships" -``` - ---- - -### 2. Get Framework Details - -**Purpose**: Access detailed information about specific framework - -**Use when**: -- Need comprehensive framework overview -- Understanding framework architecture -- Exploring framework capabilities -- Planning implementation strategy +## Documentation Tools -**Returns**: -- Framework description -- Key classes and protocols -- Common usage patterns -- Related frameworks +| Tool | Use | +|------|-----| +| `search_apple_docs` | Search all Apple documentation by keyword | +| `get_apple_doc_content` | Full page for a documentation URL (declaration, parameters, discussion) | +| `search_framework_symbols` | Browse symbols of one framework (filter by kind) | +| `list_technologies` | Frameworks/technologies by category | +| `get_platform_compatibility` | Availability and deprecation per platform | +| `get_related_apis` / `find_similar_apis` | Related or alternative APIs | +| `resolve_references_batch` | Resolve many doc references at once | +| `get_documentation_updates` | Latest SDK/documentation updates | +| `get_technology_overviews` | Technology overview articles | +| `get_sample_code` | Apple sample code projects | ---- - -### 3. Get Symbol Information - -**Purpose**: Retrieve detailed docs for class, method, property +## WWDC Tools -**Use when**: -- Need exact API signature -- Understanding method parameters -- Checking return types -- Reading detailed documentation - -**Returns**: -- Full declaration -- Parameter descriptions -- Return value info -- Code examples -- Availability (iOS 15+, macOS 12+, etc.) - ---- +| Tool | Use | +|------|-----| +| `search_wwdc_content` | Full-text search in transcripts/code | +| `list_wwdc_videos` / `list_wwdc_years` | Browse by year/topic | +| `get_wwdc_video` | Session details + transcript | +| `get_wwdc_code_examples` | Code shown in sessions | +| `browse_wwdc_topics` / `find_related_wwdc_videos` | Topic navigation | -### 4. List Technologies +**Coverage**: WWDC data is bundled offline for **2014-2025** (package v1.0.26, published 2025-09). Sessions after that (WWDC26+) are not in the bundle - read them from https://developer.apple.com/videos/ with `browser_fetch`. -**Purpose**: Explore available Apple frameworks with filtering +## Gaps - use the web -**Use when**: -- Discovering available frameworks -- Finding frameworks by category -- Planning technology stack -- Exploring new capabilities +- **Human Interface Guidelines** pages: `browser_fetch` https://developer.apple.com/design/human-interface-guidelines/ (JSON: https://developer.apple.com/tutorials/data/design/human-interface-guidelines/.json). +- Very recent symbols: cross-check https://developer.apple.com/tutorials/data/documentation//.json (metadata.platforms gives availability). -**Returns**: Categorized list of frameworks - ---- - -### 5. Search WWDC Sessions - -**Purpose**: Find WWDC videos with transcripts (2014-2025) - -**Features**: -- Keyword search -- Topic filtering -- Year filtering -- Full transcripts included -- **Offline access** (bundled in npm package) - -**Use when**: -- Learning best practices from Apple engineers -- Understanding new features -- Finding implementation guidance -- Researching design patterns - -**Example queries**: -``` -"SwiftUI data flow" -"Concurrency Swift 6" -"Core Data performance" -"Metal rendering" -``` - -**Returns**: -- Session title -- Description -- Transcript -- Code examples -- Resources - ---- - -### 6. Get WWDC Transcript - -**Purpose**: Retrieve full transcript for specific WWDC session - -**Use when**: -- Need detailed session content -- Extracting code examples -- Finding specific quotes -- Studying implementation details - ---- - -### 7. Get Sample Code - -**Purpose**: Access Apple code examples and snippets - -**Use when**: -- Need reference implementation -- Learning API usage patterns -- Starting new feature -- Debugging implementation - -**Returns**: -- Complete code examples -- Inline documentation -- Usage context - ---- - -## Key Features - -### 🚀 Offline WWDC Access - -**All WWDC video data (2014-2025) bundled in package**: -- Zero network latency -- Always available -- Complete transcripts -- No API rate limits - -### 🔍 Smart Search - -Intelligent search across: -- API documentation -- WWDC sessions -- Sample code -- Framework guides - -### 📦 Comprehensive Coverage - -Access to: -- 100+ Apple frameworks -- Thousands of APIs -- 10+ years of WWDC content -- Official sample code - ---- - -## Best Practices - -### 1. Research-First Workflow - -```bash -# MANDATORY before coding -1. Search Documentation for API -2. Get Symbol Information (exact signature) -3. Search WWDC for best practices -4. Get Sample Code for reference -5. Implement with official patterns -``` - -### 2. Priority: Apple Docs > Context7 - -**Always use Apple Docs MCP FIRST** for: -- SwiftUI APIs -- UIKit components -- Foundation types -- Apple frameworks - -**Use Context7** for: -- Third-party libraries -- Community packages -- General Swift syntax - -### 3. WWDC Session Research - -```bash -# Before implementing new feature -1. Search WWDC sessions for topic -2. Watch/read most recent session -3. Extract code examples -4. Follow Apple's recommended approach -``` - -### 4. API Verification - -```bash -# Always verify before using API -1. Get Symbol Information -2. Check availability (iOS version) -3. Check deprecation status -4. Read parameter requirements -``` - ---- - -## Integration with Swift Expert Agent - -**Automatic usage when**: -- User asks about Apple API -- Need SwiftUI/UIKit documentation -- Researching framework capabilities -- Looking for code examples - -**Priority**: Use BEFORE Context7 for Apple-specific queries. - ---- - -## Example Workflows - -### Implementing SwiftUI Navigation - -```bash -1. Search Documentation: "SwiftUI NavigationStack" -2. Get Symbol Info: NavigationStack initializer -3. Search WWDC: "SwiftUI navigation iOS 16" -4. Get Sample Code: Navigation examples -5. Implement following Apple patterns -``` - -### Debugging Core Data Issue - -```bash -1. Search Documentation: "Core Data fetch requests" -2. Get Framework Details: Core Data overview -3. Search WWDC: "Core Data performance" -4. Get Symbol Info: NSFetchRequest configuration -5. Apply recommended solutions -``` - -### Learning New iOS Feature - -```bash -1. Search WWDC: "iOS 17 new features" -2. Get WWDC Transcript: Specific session -3. Search Documentation: New APIs -4. Get Sample Code: Implementation examples -5. Experiment with new capabilities -``` - ---- - -## Coverage - -### Frameworks (100+) -- SwiftUI, UIKit, AppKit -- Foundation, CoreData, CoreML -- ARKit, RealityKit, SceneKit -- AVFoundation, CoreAudio -- Network, CloudKit, HealthKit -- And many more... - -### WWDC Years -- 2014 → 2025 (complete coverage) -- All sessions with transcripts -- Code examples included -- Resources and links - ---- +## Priority -## Resources +1. Apple Docs MCP / developer.apple.com - Apple APIs and HIG +2. Context7 - third-party libraries +3. Exa - community examples -- [GitHub Repository](https://github.com/kimsungwhee/apple-docs-mcp) -- [npm Package](https://www.npmjs.com/@kimsungwhee/apple-docs-mcp) -- [Glama MCP Directory](https://glama.ai/mcp/servers/@kimsungwhee/apple-docs-mcp) +Workflows and examples: `apple-docs-mcp-workflows.md`. diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/xcodebuild-mcp-ui-verification.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/xcodebuild-mcp-ui-verification.md new file mode 100644 index 0000000..8fabe3b --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/mcp-tools/references/xcodebuild-mcp-ui-verification.md @@ -0,0 +1,50 @@ +--- +name: xcodebuild-mcp-ui-verification +description: Running the HIG UI verification gate on a simulator with XcodeBuildMCP screenshots, UI snapshots and simctl settings +when-to-use: before reporting any UI change done, checking Dynamic Type AX5, dark mode, Increase Contrast, RTL, hit targets, labels +keywords: screenshot, snapshot_ui, set_sim_appearance, simctl ui, content_size, increase_contrast, RTL, accessibility verification +priority: high +related: xcodebuild-mcp.md, ../../swiftui-core/references/hig-accessibility.md, ../../swiftui-core/references/hig-rtl.md +--- + +# UI Verification on Simulator + +Rules being checked: `swiftui-core/references/hig-accessibility.md`, `hig-rtl.md`, `liquid-glass.md`, `hig-modality.md`. + +## Tools (verified in xcodebuildmcp 2.7.0) + +| Tool | Workflow | Notes | +|------|----------|-------| +| `screenshot` | simulator (default) | `returnFormat`: `path` or `base64` | +| `snapshot_ui` | simulator (default) | Semantic runtime UI tree with `elementRef` targets, labels, frames | +| `set_sim_appearance` | simulator-management | `mode`: `dark` or `light` | +| `tap`, `batch`, `type_text`, `long_press` | ui-automation | Target an `elementRef` from the latest `snapshot_ui` (not coordinates) | +| `swipe` | ui-automation | `direction` up/down/left/right, optional `withinElementRef` | +| `gesture` | ui-automation | Presets: `scroll-up/down/left/right`, `swipe-from-{top,bottom,left,right}-edge` | +| `launch_app_sim` | simulator (default) | `args` = launch arguments | + +Refresh `snapshot_ui` after navigation, scrolling, sheet changes or layout changes - old `elementRef`s go stale. + +## Simulator Settings Without a Tool + +`xcrun simctl ui # SOLID Swift - Apple Best Practices 2026 ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing architecture 2. **fuse-ai-pilot:research-expert** - Verify Swift/Apple docs via Apple Docs MCP + Context7 @@ -35,7 +35,7 @@ Before ANY implementation, use `TeamCreate` to spawn 3 agents: 1. **Grep the codebase** for similar protocols, services, or logic 2. Check shared locations: `Core/Extensions/`, `Core/Utilities/`, `Core/Protocols/` 3. If similar code exists -> extend/reuse instead of duplicate -4. If code is genuinely shared across features -> create it in `Core/` directly +4. If code will be used by 2+ features -> create it in `Core/` directly --- @@ -49,6 +49,8 @@ Before ANY implementation, use `TeamCreate` to spawn 3 agents: | Protocols | `Features/[Feature]/Protocols/` | Contracts | | Shared | `Core/{Models,Protocols,Services,Extensions,Utilities}/` | Cross-feature code | +File size: the only line limit is the hook ceiling (`FUSE_SOLID_MAX_LINES`). Split by responsibility well before it; if a legitimate fix cannot fit, report it - never bypass the hook. + **NEVER use flat `Sources/` structure - always `Features/[Feature]/`** --- diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/SKILL.md index 318371e..b5f7f59 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/SKILL.md @@ -23,7 +23,7 @@ Swift 6 fundamentals shared across all Apple platforms. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing Swift patterns 2. **fuse-ai-pilot:research-expert** - Verify latest Swift 6 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/references/i18n.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/references/i18n.md index 3c6a6c8..85c625f 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/references/i18n.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swift-core/references/i18n.md @@ -106,8 +106,13 @@ Examples: Use Preview with different locales: - English, French, German (length variations) -- Arabic (RTL layout) +- Arabic (RTL layout) - `.environment(\.layoutDirection, .rightToLeft)` - Japanese (character density) -- Dynamic Type (accessibility sizes) +- Dynamic Type up to `.accessibility5` -→ See SwiftUI `.environment(\.locale, ...)` for preview testing +Runtime: Scheme > Options > App Language > Right-to-Left Pseudolanguage, or iOS launch argument `-AppleTextDirection YES`. + +**RTL pass criteria** (HIG https://developer.apple.com/design/human-interface-guidelines/right-to-left): +back/next and progress/sliders mirrored; logos, checkmarks, photos and digits inside a number never flipped; +paragraphs of 3+ lines aligned to their own language; ~+2 pt for Arabic/Hebrew next to all-caps Latin. +Full rules: `swiftui-core/references/hig-rtl.md`. diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/SKILL.md index 45a13ea..3425c32 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/SKILL.md @@ -1,20 +1,20 @@ --- name: swiftui-core -description: Use when building SwiftUI views, navigation, persistence, or state management — shared across iOS, macOS, watchOS, visionOS. +description: Use when building SwiftUI views, navigation, persistence, or state management, or checking UI against Apple HIG (accessibility, RTL, sheets/alerts, widgets, Live Activities, iPhone Duo) — shared across iOS, macOS, watchOS, visionOS. versions: swiftui: 6 ios: 27 user-invocable: false -references: references/views-modifiers.md, references/navigation.md, references/data-swiftdata.md, references/state-management.md, references/liquid-glass.md, references/app-intents.md +references: references/views-modifiers.md, references/navigation.md, references/data-swiftdata.md, references/state-management.md, references/liquid-glass.md, references/app-intents.md, references/hig-accessibility.md, references/hig-rtl.md, references/hig-modality.md, references/hig-system-surfaces.md, references/hig-iphone-duo.md related-skills: swift-core, solid-swift, ios, macos, ipados, watchos, visionos, tvos --- Covers SwiftUI fundamentals shared across all Apple platforms: composable views and modifiers, navigation (NavigationStack for stack-based flows, NavigationSplitView for multi-column layouts), data persistence with SwiftData (@Model, replacing Core Data for most cases), state management (@State for local, @Observable for shared, @Environment for injection), Liquid Glass styling, and App Intents for Siri/Shortcuts integration. -References cover views/modifiers, navigation, SwiftData, state management, Liquid Glass across platforms, and App Intents in depth. +References cover views/modifiers, navigation, SwiftData, state management, Liquid Glass across platforms, and App Intents in depth, plus Apple Human Interface Guidelines (HIG) rules with source URLs: accessibility (Dynamic Type to AX5, VoiceOver, contrast, hit targets, Reduce Motion/Transparency), right-to-left, modality/sheets/alerts/onboarding, system surfaces (widgets, Live Activities, notifications, App Shortcuts/Siri/snippets), and iPhone Duo. -Best practices: extract subviews when a view body mixes responsibilities, keep source files within `FUSE_SOLID_MAX_LINES` (default 200), compose with ViewBuilder and modifiers, always include #Preview, use semantic colors (.primary/.secondary), add accessibility labels to icons, and adapt layout by size class. +Visual specs come from the design-ios handoff when one exists; this skill implements and verifies them. Best practices: extract subviews when a view body mixes responsibilities, keep source files within `FUSE_SOLID_MAX_LINES` (default 200), compose with ViewBuilder and modifiers, always include #Preview, use system colors (custom colors need light, dark and increased-contrast variants), label every icon-only control, and adapt layout by size class. # SwiftUI Core @@ -23,7 +23,7 @@ SwiftUI fundamentals shared across all Apple platforms. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing SwiftUI patterns 2. **fuse-ai-pilot:research-expert** - Verify latest SwiftUI docs via Context7/Exa @@ -81,6 +81,16 @@ Modern persistence with @Model. Replaces Core Data for most use cases. | Liquid Glass all platforms | [liquid-glass.md](references/liquid-glass.md) | | Siri, Shortcuts, App Intents | [app-intents.md](references/app-intents.md) | +### HIG Rules (load for any UI task) + +| Need | Reference | +|------|-----------| +| Dynamic Type AX5, VoiceOver, contrast, targets, Reduce Motion | [hig-accessibility.md](references/hig-accessibility.md) | +| Arabic/Hebrew mirroring, numerals | [hig-rtl.md](references/hig-rtl.md) | +| Sheets, alerts, modality, onboarding, launch, permissions | [hig-modality.md](references/hig-modality.md) | +| Widgets, Live Activities, notifications, App Shortcuts, Siri, snippets | [hig-system-surfaces.md](references/hig-system-surfaces.md) | +| iPhone Duo (foldable), reserved regions, vertical toolbars | [hig-iphone-duo.md](references/hig-iphone-duo.md) | + --- ## Best Practices @@ -88,6 +98,6 @@ Modern persistence with @Model. Replaces Core Data for most use cases. 1. **Cohesive views** - Extract subviews when responsibilities diverge; use `FUSE_SOLID_MAX_LINES` (default 200) as the only source-size ceiling 2. **Composition** - Use ViewBuilder and modifiers 3. **Preview-driven** - Always include #Preview -4. **Semantic colors** - Use .primary, .secondary -5. **Accessibility** - Add labels to icons -6. **Platform adaptation** - Check sizeClass for responsive layouts +4. **System colors** - Custom colors ship light, dark and increased-contrast variants ([HIG color](https://developer.apple.com/design/human-interface-guidelines/color)) +5. **Accessibility** - Label icon-only controls, layout survives AX5, targets >= 44 pt on iOS ([hig-accessibility.md](references/hig-accessibility.md)) +6. **Platform adaptation** - Size classes, never fixed widths or device checks ([HIG layout](https://developer.apple.com/design/human-interface-guidelines/layout)) diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-accessibility.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-accessibility.md new file mode 100644 index 0000000..8ba6019 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-accessibility.md @@ -0,0 +1,111 @@ +--- +name: hig-accessibility +description: HIG accessibility rules (Dynamic Type to AX5, VoiceOver, contrast, hit targets, Reduce Motion/Transparency) with verified SwiftUI APIs +when-to-use: building or reviewing any UI, before claiming a UI task done, fixing accessibility audit findings +keywords: accessibility, Dynamic Type, AX5, VoiceOver, contrast, Increase Contrast, hit target, 44pt, Reduce Motion, Reduce Transparency +priority: high +related: hig-rtl.md, liquid-glass.md, views-modifiers.md +--- + +# HIG Accessibility Rules + +Sources: +- https://developer.apple.com/design/human-interface-guidelines/accessibility +- https://developer.apple.com/design/human-interface-guidelines/typography +- https://developer.apple.com/design/human-interface-guidelines/voiceover +- https://developer.apple.com/design/human-interface-guidelines/dark-mode +- https://developer.apple.com/design/human-interface-guidelines/color + +## 1. Text Size (Dynamic Type) + +- Let people enlarge text by **at least 200%** (140% on watchOS). Use text styles (`.font(.body)`), never fixed sizes. +- Layout must adapt to **all** sizes, including the largest accessibility size (`DynamicTypeSize.accessibility5`). +- At accessibility sizes: show as much useful text as at the largest standard size; **never truncate in scrollable regions**; switch horizontal rows to a **stacked layout**; reduce column count; keep primary elements at the top. +- Meaningful icons must scale with text (SF Symbols do automatically). +- Custom type minimums: iOS/iPadOS default 17 pt / min 11 pt; macOS 13/10; tvOS 29/23; visionOS 17/12; watchOS 16/12. macOS has no Dynamic Type. + +```swift +@Environment(\.dynamicTypeSize) private var typeSize + +var body: some View { + let layout = typeSize.isAccessibilitySize + ? AnyLayout(VStackLayout(alignment: .leading)) + : AnyLayout(HStackLayout()) + layout { Text(title).font(.headline); Text(date).font(.subheadline) } +} + +#Preview("AX5") { Row().dynamicTypeSize(.accessibility5) } +``` + +## 2. Contrast & Color + +| Text | Minimum contrast (WCAG AA, HIG) | +|------|----------------------------------| +| Up to 17 pt | 4.5:1 | +| 18 pt and larger, or bold | 3:1 | + +- Dark Mode: never below 4.5:1; **strive for 7:1** for custom colors, especially small text. +- Check both light and dark appearances, with Increase Contrast and Reduce Transparency on (separately and together). +- Custom colors need **light, dark, and increased-contrast** variants (Color Set in the asset catalog). Prefer system colors - they ship all variants. +- Never convey information by color alone: add a shape, icon or text (`accessibilityDifferentiateWithoutColor`). + +```swift +@Environment(\.colorSchemeContrast) private var contrast // .standard / .increased +``` + +## 3. Hit Targets + +| Platform | Default | Minimum | +|----------|---------|---------| +| iOS, iPadOS | 44x44 pt | 28x28 pt | +| macOS | 28x28 pt | 20x20 pt | +| tvOS | 66x66 pt | 56x56 pt | +| visionOS | 60x60 pt | 28x28 pt | +| watchOS | 44x44 pt | 28x28 pt | + +- Padding: ~12 pt around bezeled elements, ~24 pt around bezel-less elements. +- Offer an onscreen alternative to every gesture (e.g. a delete button besides swipe-to-delete). + +```swift +Button { close() } label: { Image(systemName: "xmark") } + .frame(minWidth: 44, minHeight: 44) + .contentShape(.rect) + .accessibilityLabel("Close") +``` + +## 4. VoiceOver + +- Label **every** key element, especially icon-only controls; keep labels current as content changes. +- Describe meaningful images; hide purely decorative ones (`accessibilityHidden(true)`). +- Unique screen titles and accurate headings (`accessibilityHeading(_:)`, `.accessibilityAddTraits(.isHeader)`). +- Group related elements so they read together (`accessibilityElement(children: .combine)`). +- Announce visible content/layout changes (`AccessibilityNotification`). +- Support the rotor for navigable content (`accessibilityRotor(_:entries:)`). +- Make charts/infographics accessible with a concise description. + +## 5. Motion & Transparency + +When **Reduce Motion** is on, reduce automatic and repetitive animations (zoom, scale, peripheral motion): +tighten springs, track gestures directly, avoid z-axis depth animation, **replace x/y/z transitions with fades**, avoid animating into/out of blur. + +```swift +@Environment(\.accessibilityReduceMotion) private var reduceMotion +@Environment(\.accessibilityReduceTransparency) private var reduceTransparency + +.transition(reduceMotion ? .opacity : .move(edge: .bottom)) +.animation(reduceMotion ? nil : .spring, value: isExpanded) +``` + +Reduce Transparency: custom glass/material surfaces fall back to opaque backgrounds (see `liquid-glass.md`). + +## 6. Other HIG Requirements + +- Avoid time-boxed UI that auto-dismisses; prefer explicit dismissal. +- Don't autoplay audio/video without controls; respect Dim Flashing Lights for video. +- Pair audio cues with haptics (`sensoryFeedback(_:trigger:)`) and visual cues. +- Assistive Access (iOS/iPadOS): core features only, one interaction per screen, double confirmation for hard-to-undo actions. +- Full Keyboard Access / Switch Control / Voice Control work when every control is labeled and reachable. + +## Done Criteria + +UI is done only when verified at default size AND AX5, light AND dark (+ Increase Contrast), every interactive element labeled and >= platform minimum size, Reduce Motion/Transparency honoured. Run the agent's HIG Verification Gate. diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-iphone-duo.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-iphone-duo.md new file mode 100644 index 0000000..2a2761d --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-iphone-duo.md @@ -0,0 +1,58 @@ +--- +name: hig-iphone-duo +description: Designing for iPhone Duo (foldable, two displays) - HIG layout rules, reserved regions, vertical controls, and the SwiftUI types involved +when-to-use: supporting iPhone Duo, adaptive layouts across folded/unfolded poses, toolbar overflow and visibility priority +keywords: iPhone Duo, foldable, ArrangementView, ReservedRegion, size class, ToolbarItemVisibilityPriority, ToolbarOverflowMenu, vertical toolbar +priority: medium +related: views-modifiers.md, navigation.md, hig-accessibility.md +--- + +# Designing for iPhone Duo + +Source: https://developer.apple.com/design/human-interface-guidelines/designing-for-iphone-duo (added 2026-09-09) +Developer: https://developer.apple.com/documentation/technologyoverviews/preparing-your-app-for-iphone-duo + +iPhone Duo has an outer display (closed) and an inner display (open) with a center hinge; poses include partially folded like a book, flat, or standing. It is still an iPhone: iOS patterns apply. + +## Layout Rules + +- **Use size classes, not devices**: compact width = outer display, regular width = inner display. No custom layout per pose. +- **Build to resize**: size classes, layout margins, safe area insets. **No fixed widths, no display-specific code.** +- Keep functionality and element state identical across displays and poses; the inner display may add one hierarchy level (e.g. list + detail side by side). +- Avoid extreme layout changes while folding: small adjustments over rearrangement. In grids prefer an even column count so content splits at the fold. +- Games: fill the screen in every pose; prefer changing aspect ratio over letter/pillarboxing. +- Preview poses with Device Hub in Xcode. + +## Reserved Regions + +Areas content must avoid or adapt to: outer front camera (always; grows into the Dynamic Island for Live Activities), inner camera (only while active), and the folding region (when partially open). +- Alerts, menus, sheets and split views adapt automatically. +- Custom components: use `ReservedRegion` (SwiftUI) / `UIView.ReservedRegion` (UIKit) to keep important content clear of them. + +## Arrangement Views + +`ArrangementView` (iOS 27.1+, `init(primary:secondary:)`) holds a primary and a secondary view and arranges them by size, orientation and reserved regions. +- **Split**: divides the area (horizontal when wider than tall, vertical otherwise). +- **Overlay**: stacks views; separates them on each side of the fold when partially folded. +- Use it where the layout already resembles HStack/VStack (split) or ZStack (overlay). +- **Keep navigation outside** arrangement views: wrap them in `NavigationSplitView` / `TabView`, never the reverse. +- UIKit: `UIArrangementViewController`. + +## Vertical Controls + +- Toolbars, tab bars and navigation controls move to the **side** (except inner display in portrait). They stay on the same hardware side in RTL. +- Don't override the default bar placement. Account for asymmetric content area via safe areas. +- Order: primary navigation (Back/Close) at top of the vertical axis, then prominent actions (Done); keep original groupings - use `ToolbarItemGroup`, not manual spacers. +- Give every non-text toolbar item **both a title and a symbol** (`Label`); the title is used in overflow. Minimize text-only buttons. +- Items overflow bottom-to-top: set `visibilityPriority(_:)` with `ToolbarItemVisibilityPriority` (`.high`, `.low`, relative inits) to keep frequent actions and badged items visible. +- Use the system overflow menu (`ToolbarOverflowMenu`); reserve the ellipsis symbol for overflow only. +- Space conflict: navigation-focused views keep the tab bar (toolbar items overflow, default); task-focused views minimize the tab bar. Type: `ToolbarVerticalCompressionBehavior` (`.prefersTabBar`, `.prefersToolbarItems`). +- Full-width layouts allowed for non-scrolling immersive UI that avoids the Dynamic Island and status bar. + +## Checklist + +- [ ] No fixed widths / device checks; compact and regular size classes both tested +- [ ] Same features reachable in every pose (via overflow if needed) +- [ ] Custom content clear of reserved regions (fold, cameras) +- [ ] Every toolbar item has title + symbol; priorities set for key actions +- [ ] Navigation containers wrap arrangement views, not inside them diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-modality.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-modality.md new file mode 100644 index 0000000..e2e584d --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-modality.md @@ -0,0 +1,89 @@ +--- +name: hig-modality +description: HIG rules for modality, sheets, alerts, action sheets, onboarding, launch screens and permission prompts, mapped to SwiftUI +when-to-use: presenting sheets/alerts/full-screen covers, designing first-run onboarding, launch screen, permission requests +keywords: modality, sheet, alert, confirmationDialog, presentationDetents, onboarding, launch screen, TipKit, purpose string +priority: high +related: hig-accessibility.md, navigation.md, views-modifiers.md +--- + +# HIG Modality, Alerts & First Run + +Sources: +- https://developer.apple.com/design/human-interface-guidelines/modality +- https://developer.apple.com/design/human-interface-guidelines/sheets +- https://developer.apple.com/design/human-interface-guidelines/alerts +- https://developer.apple.com/design/human-interface-guidelines/onboarding +- https://developer.apple.com/design/human-interface-guidelines/launching +- https://developer.apple.com/design/human-interface-guidelines/privacy + +## Modality + +- Present modally only with a clear benefit; keep the task short and simple. +- No "app within the app": if a modal has subviews, one single path, no buttons that look like the dismiss button. +- Always an obvious dismiss (iOS/iPadOS/watchOS: top toolbar button or swipe down). +- Confirm before dismissing if user content would be lost - offer a save option (action sheet). +- Title the modal with its task. One modal at a time; never two alerts at once. +- Complex/multistep or media: full-screen modal (`fullScreenCover`) rather than a sheet. + +## Sheets (iOS/iPadOS) + +- One sheet at a time from the main interface; close the first before showing another. +- Single-view sheet: **Cancel leading, Done trailing**. Multistep: Cancel on first step, Back replaces it after; Done trailing, inactive until the task can complete. +- Done is always paired with Cancel (or Back). **Never show Cancel + Done + Back together.** +- Support swipe-to-dismiss; with unsaved changes, confirm through an action sheet. +- Resizable sheets: include a grabber; consider `.medium` for progressive disclosure, skip it for compose-style content. + +```swift +.sheet(isPresented: $isEditing) { + NavigationStack { + EditForm(draft: $draft) + .navigationTitle("Edit Profile") + .toolbar { + ToolbarItem(placement: .cancellationAction) { Button("Cancel", role: .cancel) { discard() } } + ToolbarItem(placement: .confirmationAction) { Button("Done") { save() }.disabled(!draft.isValid) } + } + } + .presentationDetents([.medium, .large]) + .presentationDragIndicator(.visible) + .interactiveDismissDisabled(draft.hasChanges) // then confirm via confirmationDialog +} +``` + +## Alerts + +- Sparingly: only essential, actionable information. Not for common undoable actions; never at app launch. +- Title: specific, max two lines, no "Error 329347". Message only if it adds value. +- Up to three buttons; one- or two-word verb titles ("Delete", "Erase"). "OK" only for purely informational alerts; avoid Yes/No. +- Always title the cancel button **"Cancel"**; never make Cancel the default. Default button trailing (row) or top (stack). +- Destructive style only for destructive actions the person didn't deliberately choose. +- Choices related to an intentional action (e.g. discard/save draft) -> action sheet (`confirmationDialog`), not alert. +- Use an alert, not a notification, for errors. + +```swift +.alert("Delete Project?", isPresented: $confirmDelete) { + Button("Delete", role: .destructive) { delete() } + Button("Cancel", role: .cancel) { } +} message: { + Text("This removes the project from all your devices.") +} +``` + +## Launch Screen (iOS/iPadOS/tvOS) + +- Nearly identical to the first screen; no text (not localized), no logo/branding, not a splash screen. Match orientation and appearance. +- Restore previous state on relaunch (`SceneStorage`), launch instantly. + +## Onboarding + +- Ideally none. If needed: fast, fun, **optional**, after launch completes, interactive rather than slides. +- Prefer contextual tips near the relevant UI (TipKit `TipView`, `popoverTip(_:arrowEdge:action:)`). +- Skipped tutorial never re-appears automatically, but stays reachable (help/settings). +- No licensing text, no large downloads, postpone nonessential setup; ask ratings/purchases only after engagement. + +## Permission Requests + +- Ask when the person first uses the feature that needs it (or in onboarding with the benefit explained). +- Purpose string: brief complete sentence, specific, sentence case, active voice, ends with a period. + Good: "The app records during the night to detect snoring sounds." + Bad: "Microphone access is needed for a better experience." diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-rtl.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-rtl.md new file mode 100644 index 0000000..1141942 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-rtl.md @@ -0,0 +1,68 @@ +--- +name: hig-rtl +description: HIG right-to-left rules (Arabic, Hebrew) - what flips, what never flips, numerals, and how to test in SwiftUI +when-to-use: localizing for Arabic/Hebrew, reviewing layout mirroring, custom directional icons or controls +keywords: RTL, right-to-left, Arabic, Hebrew, layoutDirection, flipsForRightToLeftLayoutDirection, mirroring +priority: medium +related: hig-accessibility.md, views-modifiers.md +--- + +# HIG Right-to-Left + +Source: https://developer.apple.com/design/human-interface-guidelines/right-to-left + +System frameworks flip standard components automatically. Fine-tune only what the system cannot know. + +## Text + +- Align text to match the interface direction when the system doesn't (SwiftUI `.leading`/`.trailing` mirror automatically; avoid absolute x offsets or UIKit `NSTextAlignment.left`). +- **Paragraphs (3+ lines) align to their own language**, not the UI direction; 1-2 line blocks follow the UI direction. +- All items of a list use the same alignment, even items in another script. +- Next to all-caps Latin text, Arabic/Hebrew often needs **~+2 pt** to look balanced. + +## Numerals + +- Never reverse the digits inside a number (phone, card, "541"). +- Reverse the **order** of numerals that express progress or sequence (slider scales, ratings). +- Arabic may use Western or Eastern Arabic numerals depending on region; let the system format numbers unless your app is number-centric. + +## Controls + +| Flip | Never flip | +|------|-----------| +| Back/forward, next/previous navigation | Controls meaning a real direction ("to the right") | +| Progress bars, sliders + their end glyphs | Logos (even with text) | +| Ordered image sequences (chronological, ranked) | Universal marks (checkmark), clocks | +| Icons depicting text or reading direction | Photos, illustrations, general artwork | +| Icons showing forward/backward motion (speaker waves) | Right-handed tools (keep tool orientation) | + +- SF Symbols provide RTL variants and localized glyphs automatically; for custom symbols specify directionality. +- Custom icons with a badge or slash: decide per component; don't blindly mirror the whole image. + +## SwiftUI + +```swift +@Environment(\.layoutDirection) private var direction // .leftToRight / .rightToLeft + +Image("custom-forward-arrow") + .flipsForRightToLeftLayoutDirection(true) // only directional custom images + +#Preview("RTL") { + ContentView() + .environment(\.layoutDirection, .rightToLeft) + .environment(\.locale, Locale(identifier: "ar")) +} +``` + +## Runtime Test + +- Scheme > Options > App Language > **Right-to-Left Pseudolanguage** (no Arabic localization needed). Source: WWDC22 "Get it right (to left)". +- Or launch arguments on iOS: `-AppleTextDirection YES` (plus `-AppleLanguages (ar)` for a real localization). With XcodeBuildMCP pass them via `launch_app_sim` `args`. + +## Pass Criteria + +- [ ] Back chevron points right; navigation order mirrored +- [ ] Sliders/progress fill from the right; end glyphs swapped +- [ ] Logos, checkmarks, photos unchanged +- [ ] No hard-coded left/right offsets or alignment in custom views (UIKit `.left`, absolute x) +- [ ] Multi-line paragraphs aligned to their language diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-system-surfaces.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-system-surfaces.md new file mode 100644 index 0000000..3efac1d --- /dev/null +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/hig-system-surfaces.md @@ -0,0 +1,70 @@ +--- +name: hig-system-surfaces +description: HIG rules for widgets, Live Activities, notifications, App Shortcuts, Siri and snippets, with the verified framework types to use +when-to-use: building a WidgetKit widget, Live Activity, notification, App Shortcut, Siri integration or App Intent snippet +keywords: widget, WidgetKit, Live Activity, ActivityKit, Dynamic Island, notification, interruption level, App Shortcuts, Siri, snippet, App Intents +priority: high +related: app-intents.md, hig-accessibility.md +--- + +# HIG System Surfaces + +Code for intents lives in `app-intents.md`; this file holds the design rules. + +## Widgets + +Source: https://developer.apple.com/design/human-interface-guidelines/widgets + +- One simple idea tied to the app's main purpose; timely, glanceable, dynamic content. Never a replica of the app icon. +- Offer multiple sizes only when each adds value; don't stretch small content to fill a large size. +- Brand lightly: no logo needed; if multi-source, a small logo top-right at most. Don't mirror the widget inside the app. +- Updates are budgeted, not real-time: show "last updated" when relevant; let the system render dates/times; animate changes (max 2 s). +- Tap opens the app **at the related location** (`widgetURL(_:)`); interactive buttons/toggles only for simple, relevant actions; inline accessory widgets have one tap target. +- Standard margins (16 pt for most widgets); use `ContainerRelativeShape` for concentric corners. +- Rendering modes: full color, **accented** (tinted / clear Liquid Glass Home Screen), **vibrant** (Lock Screen, StandBy low light). Mark accent views with `widgetAccentable(_:)`; read `widgetRenderingMode`; set backgrounds with `containerBackground(_:for:)`. +- watchOS complications are accessory widget families (`accessoryCircular`, `accessoryRectangular`, `accessoryInline`, `accessoryCorner`). + +## Live Activities + +Source: https://developer.apple.com/design/human-interface-guidelines/live-activities + +- Only for tasks/events with a defined start and end, ideally under eight hours. No ads, no sensitive data (redact or summarize - `privacySensitive(_:)`). +- Must support compact, minimal, expanded (Dynamic Island) and Lock Screen presentations; also appear in StandBy, Mac menu bar, Apple Watch Smart Stack, CarPlay. +- Large, medium-or-heavier text; concentric margins; dynamic height; custom background only on Lock Screen (check contrast on Always-On, `isLuminanceReduced`). +- Logo mark without container, never the full app icon. Don't add app UI that points at the Dynamic Island. +- Animations max 2 s (none on reduced-luminance Always-On). Update only on new content; alert only for essential updates; never duplicate with push notifications. +- Max one interactive element ideally; tap deep-links to the related screen. Let people stop it from inside the app; offer an App Shortcut to start it. +- Types: `ActivityConfiguration`, `DynamicIsland`, `Activity.request(attributes:content:pushType:)`, `ActivityContent`. + +## Notifications + +Sources: https://developer.apple.com/design/human-interface-guidelines/notifications, https://developer.apple.com/design/human-interface-guidelines/managing-notifications + +- Permission first (`requestAuthorization(options:completionHandler:)`), ideally when the benefit is clear. +- Pick an honest `interruptionLevel`: `.passive`, `.active` (default), `.timeSensitive` (happening now / within an hour), `.critical` (health & safety, entitlement required). +- **Never** Time Sensitive for marketing; marketing notifications need explicit opt-in plus an in-app setting to change it. +- Concise; no duplicates; no "go do X in the app"; no sensitive data; no app name/icon in content (system adds it). +- Title-style title without ending punctuation; body in sentence case with punctuation. Provide `hiddenPreviewsBodyPlaceholder` ("New comment"). +- Up to four actions: short title-case verbs, SF Symbol icon, prefer nondestructive, no "Open app" action. +- In foreground, surface the info subtly (badge, inline insert) instead of an alert. Badges only for unread counts. +- Errors -> alert, not notification. + +## App Shortcuts & Siri + +Sources: https://developer.apple.com/design/human-interface-guidelines/app-shortcuts, https://developer.apple.com/design/human-interface-guidelines/siri + +- Up to 10 App Shortcuts (`AppShortcutsProvider`) for the most common tasks; available right after install. Not supported on tvOS; on macOS only via the Shortcuts app. +- Prefer **app schemas** when the app fits a common domain (mail, photos, music...) so Siri AI understands it without custom shortcuts. +- Phrases: short, memorable, include the app name; one optional parameter max with predictable values; ask follow-ups for missing info. +- Full spoken dialogue must stand alone (audio-only devices); responses succinct, no humor or ads, inclusive wording ("Who should I send it to?"). +- Annotate on-screen content with app entities and donate relevant actions so Siri understands context. +- Write "App Shortcuts" / "Shortcuts" in title case, plural. + +## Snippets + +Source: https://developer.apple.com/design/human-interface-guidelines/snippets + +- Two types: **confirmation** (Cancel + primary button) and **result** (Done). iOS/iPadOS/macOS only. +- Custom view max **400 pt** tall, text sized for large Dynamic Type; deep-link for more detail. +- Primary button label descriptive ("Order"), never OK/Proceed (system default is "Continue"). +- Convey meaning visually; don't rely on repeating the spoken dialogue. Check contrast in light and dark. diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/liquid-glass.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/liquid-glass.md index 7843d57..507a55b 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/liquid-glass.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/liquid-glass.md @@ -1,135 +1,91 @@ --- name: liquid-glass -description: Liquid Glass design system for iOS 26, macOS 26, iPadOS 26, visionOS 26, tvOS 26, watchOS 26 -when-to-use: implementing translucent UI, glass effects, modern Apple design language, platform-specific adaptations -keywords: Liquid Glass, glassmorphism, translucency, lensing, iOS 26, macOS 26, visionOS 26 +description: Liquid Glass material (iOS/iPadOS/macOS/tvOS/watchOS 26+) - HIG usage rules and SwiftUI API mapping +when-to-use: styling custom controls with glass, adopting the system design language, reviewing glass usage against the HIG +keywords: Liquid Glass, glassEffect, GlassEffectContainer, materials, regular, clear, Reduce Transparency priority: high -related: views-modifiers.md, navigation.md +related: views-modifiers.md, hig-accessibility.md, navigation.md --- -# Liquid Glass Design System (2026) +# Liquid Glass -## Concept +Visual rules come from the HIG (design-ios handoff is the design source); this file maps them to SwiftUI. +Source: https://developer.apple.com/design/human-interface-guidelines/materials -Liquid Glass uses **light lensing** (not blur) for translucency. Content behind glass remains visible with dynamic color reflection. +## Concept (HIG) ---- - -## API Reference +- Liquid Glass is a **functional layer for controls and navigation** (tab bars, sidebars, toolbars) floating above the content layer. +- **Regular** variant: blurs and adjusts the luminosity of background content to keep text legible. Most system components use it. Use for text-heavy components (alerts, sidebars, popovers). +- **Clear** variant: highly translucent; only for components floating over visually rich media (photos, video). +- Over bright content under clear glass, consider a dark dimming layer of 35% opacity; not needed over dark content or AVKit standard controls (they dim themselves). +- Appearance changes with system settings: the person's preferred Liquid Glass look, Reduce Transparency, Increase Contrast. -### Basic Usage +## HIG Rules -```swift -MyView() - .glassEffect(.regular) // Standard glass - .glassEffect(.regular.interactive()) // Responds to touch - .glassEffect(.clear) // More transparent variant - .glassEffect(.regular, in: .capsule) // Custom shape -``` +- **Never use Liquid Glass in the content layer** (app backgrounds, cards, lists). Use standard materials (`.ultraThinMaterial` ... `.thickMaterial`) there. Exception: transient controls (sliders, toggles) take on glass while active - the system does this. +- **Let standard components adopt it automatically.** Tab bars, toolbars, sidebars, sheets, popovers, menus, alerts and search get glass from the system - do not add `glassEffect` to them. +- **Use custom glass sparingly** - only the most important custom functional controls. +- **tvOS**: buttons and image views adopt glass when they gain focus - never add it manually. +- **visionOS**: windows use the system glass material (`glassBackgroundEffect`), not `glassEffect`. +- Color on glass: tint only to convey meaning (e.g. primary action), not decoration. Source: https://developer.apple.com/design/human-interface-guidelines/color -### Glass Options +## API Reference (verified on developer.apple.com, iOS 26.0+) ```swift -Glass.regular // Default translucency -Glass.clear // Higher transparency -Glass.identity // No glass (conditional toggling) -Glass.regular.interactive() // Touch feedback -Glass.regular.tint(.blue) // Tinted glass -// Stronger emphasis on buttons: .buttonStyle(.glassProminent) -``` +MyControl() + .glassEffect() // Glass.regular in a capsule (default) + .glassEffect(.regular.interactive()) // reacts to touch/pointer + .glassEffect(.clear, in: .rect(cornerRadius: 16)) // over media only + .glassEffect(.regular.tint(.accentColor)) // meaning-bearing tint only -### Morphing Container +Glass.identity // no glass - toggle conditionally instead of removing the modifier +``` ```swift +// Group custom glass shapes so they blend and morph together GlassEffectContainer { - ForEach(items) { item in - ItemView(item).glassEffect(.regular, in: .capsule) + HStack { + ForEach(tools) { tool in + ToolButton(tool).glassEffect(.regular.interactive()) + } } } ``` -### UIKit Integration - ```swift -// UIButton with glass style -let config = UIButton.Configuration.glass() -let button = UIButton(configuration: config) - -// SwiftUI buttonStyle -Button("Action") { } - .buttonStyle(.glass) +Button("Save") { }.buttonStyle(.glass) // secondary +Button("Continue") { }.buttonStyle(.glassProminent) // primary action only +// UIKit: UIButton(configuration: .glass()) ``` -### Automatic Application - -Xcode 26 recompile automatically applies to: -- NavigationBar, TabBar, Toolbar -- Sheets, Popovers, Menus, Alerts -- Search bars, Controls (during interaction) - ---- - -## Platform Examples - -### iOS 26 - TabBar +## Accessibility Fallbacks ```swift -TabView { - Tab("Home", systemImage: "house") { ContentView() } -} -.tabBarMinimizeBehavior(.onScrollDown) -.tabViewBottomAccessory { HStack { Button("Filter") { } } } -``` - -### macOS 26 - Toolbar +@Environment(\.accessibilityReduceTransparency) private var reduceTransparency -```swift -WindowGroup { - ContentView() - .toolbar { ToolbarItem { Button("Action") { } } } +var body: some View { + ToolCluster() + .glassEffect(reduceTransparency ? .identity : .regular) + .background(reduceTransparency ? Color(.secondarySystemBackground) : .clear) } -.windowStyle(.hiddenTitleBar) -.windowToolbarStyle(.unified) ``` -### iPadOS 26 - Split View - -```swift -NavigationSplitView { - Sidebar().glassEffect(.regular) -} detail: { - DetailView() -} -``` +System components already handle Reduce Transparency and Increase Contrast; only custom glass needs this. -### visionOS 26 - Spatial +## Related System APIs -```swift -WindowGroup { - ContentView() - .glassBackgroundEffect() // visionOS-specific -} -``` - -### watchOS & tvOS 26 - -```swift -// watchOS: NavigationStack automatically applies glass -NavigationStack { List { } } - -// tvOS: Focus-aware buttons -Button("Play") { } - .buttonStyle(.bordered) - .glassEffect(.regular) -``` - ---- +| API | Use | +|-----|-----| +| `tabBarMinimizeBehavior(_:)` | Let the tab bar minimize on scroll (iOS 26+) | +| `tabViewBottomAccessory(content:)` | Accessory above the tab bar (iOS 26+) | +| `scrollEdgeEffectStyle(_:for:)` | Scroll edge effect under bars (iOS 26+) | +| `backgroundExtensionEffect()` | Extend content under sidebars/inspectors (iOS 26+) | +| `glassBackgroundEffect(displayMode:)` | visionOS window/ornament glass | -## Best Practices +## Checklist -- ✅ Let system apply automatically -- ✅ Use `.glassProminent` sparingly -- ✅ Test light/dark modes -- ✅ Ensure text contrast -- ❌ Don't stack glass layers -- ❌ Don't overuse (performance) +- [ ] No `glassEffect` on content-layer views, standard bars, sidebars, sheets +- [ ] Clear variant only over media; 35% dim over bright media +- [ ] No stacked glass on glass +- [ ] Legible in light, dark, Increase Contrast, Reduce Transparency +- [ ] `.glassProminent` / tint reserved for the primary action diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/views-modifiers.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/views-modifiers.md index 22767f1..63bd7f4 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/views-modifiers.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/swiftui-core/references/views-modifiers.md @@ -72,8 +72,8 @@ Adapt to different screen sizes and orientations. - ✅ Extract subviews at 30+ lines - ✅ Use `some View` return type (opaque) - ✅ Prefer composition over inheritance -- ✅ Use semantic colors (.primary, .secondary) -- ✅ Add `.accessibilityLabel()` to icons +- ✅ Use system colors; custom colors need light, dark and increased-contrast variants (HIG /color) +- ✅ Add `.accessibilityLabel()` to every icon-only control (see `hig-accessibility.md`) - ✅ Always include `#Preview` - ❌ Don't use GeometryReader unnecessarily - ❌ Don't nest ScrollViews @@ -81,24 +81,24 @@ Adapt to different screen sizes and orientations. --- -## iOS 26 Liquid Glass +## Liquid Glass (iOS 26+) -New design language using light lensing (not blur). +Material for the controls/navigation layer. The regular variant blurs and adjusts the luminosity of background content; the clear variant is highly translucent, for use over media only (HIG /materials). -### Automatic Application (Xcode 26 recompile) -- NavigationBar, TabBar, Toolbar -- Sheets, Popovers, Menus, Alerts -- Search bars, Controls (during interaction) +### Automatic Application (when built with the current SDK) +- Navigation bars, tab bars, toolbars, sidebars +- Sheets, popovers, menus, alerts +- Search fields, controls (during interaction) -### Manual API +### Manual API (custom controls only, sparingly - never content layer) ```swift -MyView() - .glassEffect() // .regular (default) - .glassEffect(.clear) // Variants: .regular, .clear, .identity - .glassEffect(.regular.interactive(), in: .capsule) // Custom shape +MyControl() + .glassEffect() // .regular in a capsule (default) + .glassEffect(.regular.interactive(), in: .capsule) ``` +Rules and accessibility fallbacks: `liquid-glass.md`. -### TabBar iOS 26 +### TabBar (iOS 26+) ```swift TabView { Tab("Home", systemImage: "house") { HomeView() } @@ -118,10 +118,10 @@ TabView { ``` ### Design Principles -1. **Layering** - Content under glass remains visible -2. **Depth** - Visual hierarchy via translucency -3. **Responsiveness** - Glass reacts to interactions -4. **Adaptivity** - Automatic light/dark mode +1. **Layering** - Glass floats above content; content scrolls and peeks beneath it +2. **Hierarchy** - Glass only for controls/navigation, never the content layer +3. **Responsiveness** - Interactive glass reacts to touch +4. **Adaptivity** - Light/dark, Increase Contrast, Reduce Transparency --- @@ -129,8 +129,8 @@ TabView { | API | Purpose | |-----|---------| -| `ContentBuilder` | Unified result builder replacing type-specific builders (`ToolbarContentBuilder`, `CommandsBuilder`) | -| `.reorderable()` + `.reorderContainer(for:isEnabled:move:)` | Drag-to-reorder in lists, stacks, grids, custom layouts | +| `ContentBuilder` | Result-builder attribute that builds views and other content types from closures | +| `.reorderable()` (on `ForEach`) + `.reorderContainer(for:isEnabled:move:)` | Drag-to-reorder in lists, stacks, grids, custom layouts | | `.swipeActions(edge:allowsFullSwipe:content:onPresentationChanged:)` + `.swipeActionsContainer()` | Swipe actions outside `List` | | `.visibilityPriority(_:)` on `ToolbarContent` | Keep key toolbar items visible as space shrinks | | `ToolbarOverflowMenu` | Send secondary toolbar actions straight to overflow | @@ -139,6 +139,6 @@ TabView { | `.asyncImageURLSession(_:)` | Custom `URLSession` (caching) for `AsyncImage` | | `Tab(role: .prominent)` | Separate trailing tab in the tab bar | -Source: developer.apple.com/documentation/updates/swiftui (June 2026). +Source: developer.apple.com/documentation/updates/swiftui (June 2026); each symbol re-checked on developer.apple.com (Oct 2026). → See `templates/view-structure.md` for code examples diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/SKILL.md index d0cffc8..f7485a4 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/SKILL.md @@ -11,7 +11,7 @@ related-skills: swift-core, swiftui-core, mcp-tools Covers tvOS-specific development for the Apple TV living-room experience: the focus system for large-screen navigation, Liquid Glass styling on TV (tvOS 26), AVKit media playback, Siri Remote gesture handling, multi-user support, and game controller integration. -Includes tvOS 26 code examples for Liquid Glass buttons/tab bars and focus-state-driven scale effects. +Includes tvOS 26+ guidance on system-applied Liquid Glass (buttons/images adopt it on focus, never added manually) and focus-state-driven scale effects. Best practices: size UI elements to be readable from 10 feet, give clear visual focus feedback, keep navigation depth minimal, design remote-friendly gestures, optimize for media-first content, and support user switching. @@ -22,7 +22,7 @@ tvOS-specific development for Apple TV living room experiences. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing tvOS patterns 2. **fuse-ai-pilot:research-expert** - Verify latest tvOS 27 docs via Context7/Exa @@ -58,16 +58,19 @@ After implementation, run **fuse-ai-pilot:sniper** for validation. ### Liquid Glass on TV -```swift -Button("Watch Now") { } - .buttonStyle(.bordered) - .glassEffect(.regular) // Glass effect on focus +In tvOS, Liquid Glass appears throughout navigation and system experiences; **buttons and image views adopt it automatically when they gain focus** (HIG https://developer.apple.com/design/human-interface-guidelines/materials). Don't add `glassEffect` manually - use standard styles and components. +```swift TabView { - // Tab bar with Liquid Glass + Tab("Home", systemImage: "house") { HomeView() } // system tab bar gets glass } + +Button("Watch Now") { } + .buttonStyle(.bordered) // standard style: system handles the focused appearance ``` +Use standard materials (not glass) for content-layer overlays. + ### Focus System ```swift @@ -96,8 +99,8 @@ struct ContentView: View { ## Best Practices -1. **Large UI elements** - Readable from 10 feet -2. **Focus feedback** - Clear visual indication +1. **Large UI elements** - Controls 66x66 pt default, 56x56 pt minimum; body text 29 pt default, 23 pt minimum ([HIG accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)) +2. **Focus feedback** - Clear visual indication ([HIG focus](https://developer.apple.com/design/human-interface-guidelines/focus-and-selection)) 3. **Simple navigation** - Minimal depth 4. **Remote-friendly** - Siri Remote gestures 5. **Media-first** - Optimize for video/audio diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/references/focus-system.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/references/focus-system.md index 9f20a24..3fba077 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/references/focus-system.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/tvos/references/focus-system.md @@ -43,33 +43,44 @@ Button("Item") { } .buttonStyle(.card) // Automatic focus styling .hoverEffect(.lift) // Lift on focus -// Custom focus style -.focusable() -.onFocusChange { focused in - withAnimation { scale = focused ? 1.1 : 1.0 } -} +// Custom focus style: there is no `.onFocusChange` modifier - observe @FocusState +@FocusState private var isFocused: Bool + +PosterView() + .focusable() + .focused($isFocused) + .scaleEffect(isFocused ? 1.1 : 1.0) + .animation(.easeOut, value: isFocused) + +// Inside a focusable view's subtree: @Environment(\.isFocused) private var isFocused ``` ### Focus Sections +`focusSection()` is a View modifier (tvOS 15+, macOS 13+) - not a container view. It uses the view's frame to guide focus movement toward its focusable descendants. + ```swift VStack { - FocusSection { - HStack { /* Top row */ } - } - FocusSection { - HStack { /* Bottom row */ } - } + HStack { /* Top row */ } + .focusSection() + HStack { /* Bottom row */ } + .focusSection() } ``` -### focusScope +### focusScope + prefersDefaultFocus + +`focusScope(_:)` limits **default focus preferences** to a namespace; it does not trap focus inside the view. ```swift +@Namespace private var shelf + VStack { - // Focus stays within scope + Button("Resume") { } + .prefersDefaultFocus(in: shelf) + Button("Start Over") { } } -.focusScope(namespace) +.focusScope(shelf) ``` --- @@ -78,7 +89,10 @@ VStack { - ✅ Use `@FocusState` for programmatic focus - ✅ Provide clear focus indicators -- ✅ Use `FocusSection` for logical grouping -- ✅ Animate focus transitions +- ✅ Use `.focusSection()` to guide focus across uneven rows +- ✅ Animate focus transitions (fade instead when Reduce Motion is on) +- ✅ Let buttons/images adopt Liquid Glass on focus automatically - no manual `glassEffect` - ❌ Don't make unfocusable interactive elements -- ❌ Don't use small touch targets +- ❌ Don't use targets under 66x66 pt (minimum 56x56 pt, HIG /accessibility) + +Source: https://developer.apple.com/design/human-interface-guidelines/focus-and-selection diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/SKILL.md index 42d7682..1e41260 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/SKILL.md @@ -22,7 +22,7 @@ visionOS-specific development for Apple Vision Pro spatial computing. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing visionOS patterns 2. **fuse-ai-pilot:research-expert** - Verify latest visionOS 27 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/references/ornaments.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/references/ornaments.md index 2885fe1..b4ab421 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/references/ornaments.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/visionos/references/ornaments.md @@ -27,7 +27,7 @@ related: views-modifiers.md - `.ornament()` modifier on views - Position with `attachmentAnchor` - Standard SwiftUI content -- Liquid Glass styling by default +- Glass background by default (visionOS window glass) ### Attachments (RealityView) 2D SwiftUI attached to 3D entities. @@ -51,21 +51,27 @@ related: views-modifiers.md ## Ornament Usage +`ornament(visibility:attachmentAnchor:contentAlignment:ornament:)` is a **View** modifier (visionOS 1.0+) - apply it to the window's root view, not to the `WindowGroup` scene. + ```swift WindowGroup { ContentView() -} -.ornament( - attachmentAnchor: .scene(.bottom) -) { - HStack { - Button("Play") { } - Button("Settings") { } - } - .padding() + .ornament(attachmentAnchor: .scene(.bottom)) { + HStack { + Button("Play", systemImage: "play.fill") { } + Button("Settings", systemImage: "gearshape") { } + } + .padding() + .glassBackgroundEffect() + } } ``` +HIG (https://developer.apple.com/design/human-interface-guidelines/ornaments): +- Use ornaments for frequently needed, window-related controls; system toolbars and tab bars already appear as ornaments - don't rebuild them. +- Keep ornaments visible (hide only during immersive content like video), few in number, no wider than the window. +- Borderless buttons work well: the ornament background is already glass. + --- ## RealityView Attachments @@ -87,23 +93,23 @@ RealityView { content, attachments in --- -## Liquid Glass Styling +## Glass Styling -iOS 26 / visionOS 26 default styling: -- Translucent backgrounds -- Light lensing effects (not blur) -- `.glassBackgroundEffect()` (visionOS-specific for windows) -- `.glassEffect(.regular)` (standard glass modifier) +visionOS windows use an unmodifiable system **glass** material that lets surroundings show through and adapts to their luminance (HIG /materials, visionOS): +- `.glassBackgroundEffect()` for custom window/ornament/attachment surfaces +- Prefer translucency to opaque colors in windows +- visionOS has no Dark Mode setting; glass adapts automatically +- `glassEffect(_:in:)` (Liquid Glass) is not available on visionOS - see `swiftui-core/references/liquid-glass.md` --- ## Best Practices -- ✅ Use ornaments for scene controls +- ✅ Use ornaments for app-specific, window-related controls - ✅ Use attachments for entity UI -- ✅ Keep ornaments minimal -- ✅ Apply glass effects -- ✅ Position intuitively +- ✅ Keep ornaments minimal and no wider than the window +- ✅ Rely on the default glass background (borderless buttons) +- ✅ Hit targets >= 60x60 pt (HIG /accessibility, visionOS) - ❌ Don't overcrowd with UI - ❌ Don't block 3D content - ❌ Don't ignore depth perception diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/SKILL.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/SKILL.md index cf7cf92..06b5c8f 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/SKILL.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/SKILL.md @@ -11,7 +11,7 @@ related-skills: swift-core, swiftui-core, ios, mcp-tools Covers watchOS-specific development for Apple Watch: watch-face complications for glanceable data, workout sessions and fitness tracking, HealthKit access to health metrics, and Watch Connectivity for iPhone-Watch sync. -Includes design considerations specific to the platform — small display with large touch targets, glanceable information with minimal text, Digital Crown scrolling/input, Force Touch on older watches, swipe/tap gestures, and battery-conscious background work. +Includes design considerations specific to the platform — small display with large touch targets, glanceable information with minimal text, Digital Crown scrolling/input, swipe/tap gestures, and battery-conscious background work. Best practices: keep information glanceable, use large tap targets, minimize text input, drive watch-face updates through complications, use efficient background refresh, and always validate on real hardware since the simulator behaves differently. @@ -22,7 +22,7 @@ watchOS-specific development for Apple Watch experiences. ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Analyze existing watchOS patterns 2. **fuse-ai-pilot:research-expert** - Verify latest watchOS 27 docs via Context7/Exa @@ -66,14 +66,16 @@ After implementation, run **fuse-ai-pilot:sniper** for validation. ## Design Considerations ### Screen Size -- Small display, large touch targets -- Glanceable information -- Minimal text, clear icons +- Small display; controls 44x44 pt default, 28x28 pt minimum +- Text: 16 pt default, 12 pt minimum; support enlargement to at least 140% +- Glanceable information, minimal text, clear icons + +Source: https://developer.apple.com/design/human-interface-guidelines/accessibility ### Interactions -- Digital Crown for scrolling/input -- Force Touch (older watches) +- Digital Crown for scrolling/input ([HIG](https://developer.apple.com/design/human-interface-guidelines/digital-crown)) - Gestures: swipe, tap +- Complications and Smart Stack are WidgetKit accessory widgets (see `swiftui-core/references/hig-system-surfaces.md`) ### Battery - Minimize background work diff --git a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/references/complications.md b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/references/complications.md index 6287066..6d39747 100644 --- a/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/references/complications.md +++ b/.cursor-plugin/plugins/fuse-swift-apple-expert/skills/watchos/references/complications.md @@ -2,7 +2,7 @@ name: complications description: watchOS complications for watch faces with WidgetKit, timelines, and data updates when-to-use: creating watch face complications, displaying glanceable data, updating complication content -keywords: complication, WidgetKit, TimelineProvider, watch face, CLKComplicationFamily +keywords: complication, WidgetKit, AppIntentTimelineProvider, accessory widget, watch face, Smart Stack priority: high related: workouts.md, watch-connectivity.md --- @@ -19,7 +19,8 @@ related: workouts.md, watch-connectivity.md ## Key Concepts ### WidgetKit Complications (watchOS 9+) -Modern complication system using WidgetKit. +Complications are WidgetKit accessory widgets; ClockKit complications are legacy - migrate them +(https://developer.apple.com/documentation/widgetkit/converting-a-clockkit-app). **Key Points:** - Same API as iOS widgets @@ -29,20 +30,22 @@ Modern complication system using WidgetKit. ### Complication Families -| Family | Description | -|--------|-------------| -| accessoryCircular | Small circular | -| accessoryRectangular | Rectangular area | -| accessoryInline | Single line text | -| accessoryCorner | Corner placement | +| Family | Where (HIG /widgets) | +|--------|----------------------| +| accessoryCircular | Complications and Smart Stack | +| accessoryRectangular | Complications and Smart Stack | +| accessoryInline | Complications (single tap target) | +| accessoryCorner | Complications (watchOS only) | -### TimelineProvider -Provides content for complications. +On Apple Watch, accessory widgets render in full-color or accented (tinted) mode - mark accent views with `widgetAccentable(_:)`. + +### AppIntentTimelineProvider (watchOS 10+, configurable) +Async provider; prefer it over the completion-based `TimelineProvider`. **Methods:** -- `placeholder(in:)` - Loading state -- `getTimeline(in:completion:)` - Future entries -- `getSnapshot(in:completion:)` - Quick preview +- `placeholder(in:)` - Redacted loading state +- `snapshot(for:in:) async` - Quick preview +- `timeline(for:in:) async` - Future entries ### Timeline Entries Data snapshots at specific times. @@ -65,17 +68,10 @@ Data snapshots at specific times. --- -## Complication Placement - -``` -Watch Face -├── Top slot -├── Corner slots (4) -├── Center slot -└── Bottom slot +## Placement -Each slot supports specific families -``` +Available slots depend on the watch face; each face exposes only some accessory families. Support several families and test on multiple faces and in the Smart Stack. +Source: https://developer.apple.com/design/human-interface-guidelines/widgets --- diff --git a/AGENTS.md b/AGENTS.md index 3ddeffb..0e1d1f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,33 @@ § Global instructions. Edit THIS file; .cursor-plugin/plugins/fuse-rules/user-rules/ fuse-global.mdc is a copy of it. --> +## HARD STOPS +0. **Every owner request starts by loading skill `fuse-ai-pilot:lead-orchestration`** (intake checklist → route → brief → delegate → follow → verify → report) — the lead orchestrates, never edits. +1. **NEVER git commit / push / reset** without explicit permission. Read-only git is free. +2. **NEVER modify files** without explicit user instruction. +3. **NEVER write outside the mandate** — never `~/.cursor`, `~/.claude` or `~/.codex` (real API keys), never an installed or deployed copy, never run `install.sh` / `install.ps1` — **unless the owner names that file or path in the mandate** (e.g. "edit my global rule", "sync the install"): then the lead's brief quotes the owner's words and the agent may write exactly that target, nothing else. +4. **ONE folder = ONE owner.** Before sending an agent in: `ls -lT` + `date`. Mtime under ~5 min = busy, send no one. +5. **A message does NOT stop an agent.** It reaches a subagent only when it is resumed; the running one finishes its turn and writes anyway. Cursor documents no stop call for a running subagent: confirm mtimes stopped before reporting a state frozen. + +## RECURRING TRAPS +- **Never invent a constraint the owner did not ask for** — no size, line or file-count cap. Yours becomes a VETO: an executant will refuse a real fix to honour it. Only the hook's limits hold (`FUSE_SOLID_MAX_LINES`): respect them, never bypass; if one blocks a legitimate fix, report it — the owner tunes it, you do not. +- **A recent mtime proves a file was touched, never that the named defect is fixed.** Re-measure the defect itself before relaunching or reporting. +- **VISUAL defect: screenshot BEFORE naming a cause.** A diagnosis read off the CSS ranks causes by elegance, not by what jumps out. +- **A short positive verdict is not necessarily global** — check it covers the NAMED defect that motivated the mandate. +- **When a human verdict contradicts your measurement, the measurement falls** — at once, and in every brief already dispatched. +- **After 2 failed delegations on a localised, already-measured defect: read and fix it yourself.** + +## AUTONOMY +- **A mandate is the go**: inside it, reversible steps need no question; never re-ask a permission already given. Irreversible → ONE binary question (Clarify rule, Non-Negotiables #5). +- **Always delegate** — every edit, even one line (skills, rules, AGENTS.md), goes to an agent; the lead orchestrates and verifies. +- **Never hand the owner a step — find the way yourself.** Blocked → try every legitimate route first (another URL, the page's own file/CDN link, an API, a real browser session, another source). Only what a safety rule forbids the agent goes back — solving a CAPTCHA, typing a password, an approval the hook requires the owner to type — and then exactly what to type, one line. +- **An owner message mid-task amends the mandate** — absorb it, keep going. +- **Guarantee, don't hedge.** Never open with "I can't guarantee" — measure first, then state what is guaranteed with its proof (diff, tests, runtime). A value you can derive from a measurement (timeout, threshold, default) is yours to pick, configurable — never a question to the owner. +- **Each owner correction → a rule in the skill/agent that failed, same turn**, then synced. The owner never repeats himself. +- **Before "done": open the real output** (screenshot, frames, file, page) **and tick every part of the request by name**; unverified = "not verified". +- **Deliverables where the owner sees them** (visible folder / sent file / link), never only a hidden dir. **Follow executors to the end**; releases only via the commit agent, never an external executor (Kimi/Codex/Claude Code). +- **Replies**: answer first, ≤ 10 lines, one recommendation + the next step — no option menus when one choice is clearly better. + ## Identity Expert full-stack engineer. ALWAYS use latest stable versions for the current year — check docs before assuming any version. Posture: skeptical, analytical, direct, ultra-concise. Zero filler/preamble/apologies. Say "I don't know" > guessing. Challenge own ideas via `research-expert` + fuse-browser fast-path before proposing. @@ -12,7 +39,7 @@ User = expert engineer who knows the system better than you — no hand-holding, Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only the details that change a decision. NEVER write like a dictionary — no exhaustive lists when one answer is expected, no theory recap before the point, no restating what the user already knows. ## Non-Negotiables (read first) -1. **ALWAYS DELEGATE** — the lead is a COORDINATOR: it orchestrates, never executes itself. No reading, searching or editing by hand — delegate to a specialised sub-agent (see "Before ANY Action" below). Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, exclusive file ownership, guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. **IMPORTANT — two-speed communication, ALWAYS: give agents ULTRA-DETAILED, exhaustive tasks (context + exclusive files + guardrails + expected report); reply to the USER clear, short, concise. Never blur the two — a short agent brief = wrong deliverable; a long user reply = noise.** +1. **ALWAYS DELEGATE** — the lead is a COORDINATOR: it orchestrates, never executes itself. No reading, searching or editing by hand — delegate to a specialised sub-agent (see "Before ANY Action" below). Concision is for the USER. Mandates to agents are the opposite: complete and self-contained — context, the task and the files it owns (exclusive; one agent per task), guardrails (re-verify on disk before editing, strict validation), and the expected report format. A vague brief produces a wrong deliverable. **IMPORTANT — two-speed communication, ALWAYS: give agents ULTRA-DETAILED, exhaustive tasks (context + the task and its exclusive files + guardrails + expected report); reply to the USER clear, short, concise. Never blur the two — a short agent brief = wrong deliverable; a long user reply = noise.** 2. **FULL APEX MANDATORY** — 6 phases: Analyze → Plan → Execute → **eLicit** (auto-review) → **Verify** (functional check) → **eXamine** (sniper). Gate: **eLicit + Verify BEFORE sniper — NEVER skip**. 3. **RIGHT AGENT FOR EACH TASK** — route by Project Detection (domain-expert); never a generic agent when a domain expert exists. 4. **EXIT CONTRACT** — every agentic loop ends on one explicit issue, never silent drift: **Stop** (goal *verified* with proof, not "I changed it") · **Retry** (new hypothesis — never the same fix twice) · **Rollback** (change broke something → return to the last green state via `git stash`/revert *before* stacking another fix) · **Ask** (several readings → one targeted question first) · **Escalate** (past the attempt cap, or risk/security → hand off with a root-cause note). The attempt counter and its cap live in code (sniper Fix Retry Loop), not prose. @@ -49,11 +76,12 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only | Scope | Action | Why | |-------|--------|-----| | Trivial / read-only / 1 targeted file, bounded change | Direct edit (or 1 domain-expert) + sniper. NO team, NO mandatory ANALYZE trio. | Orchestration cost (spawn, briefs, FIFO cross-checks) exceeds the gain. | -| Non-trivial mono-concern (1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | -| Truly parallelizable: INDEPENDENT batches, multi-domain, or large multi-file with no cross-dependency | **Propose a parallel team** — ask user first. A team is **MINIMUM 4 sub-agents in parallel**, NEVER 1 (1 agent = not a team). | Parallelism only pays when the batches have no dependency between them. | +| Non-trivial, ONE task (mono-concern; 1 domain, a few COUPLED files) | 1 domain-expert (+ targeted ANALYZE if it touches unknown code) + sniper/challenger. | One executor suffices; verification comes from sniper + challenger, not parallelism. | +| Several tasks, SAME domain, even COUPLED | **One agent per task** — each task has one agent and owns the files it needs; coupling is handled by the brief (shared contract stated up front). Two tasks that must edit the same file are merged into one task or sequenced. Announce the split, don't ask. | Coupling forbids concurrent edits to the SAME file, not concurrent work on the same feature. | +| Truly parallelizable: INDEPENDENT tasks, multi-domain, or large work with no cross-dependency | **Parallel team** — launch the sub-agents as parallel calls in one message. A team is **MINIMUM 4 sub-agents in parallel**, NEVER 1 (1 agent = not a team). Announce the split, don't ask. | Parallelism only pays when the tasks have no dependency between them. | | User says "team" / "crée une team" | **Spin the team up immediately** — minimum 4, no debate. | Owner's explicit call overrides the ladder. | -**Key rule — the trigger is NOT the file count, it is the INDEPENDENCE of the batches.** 2 coupled files = 1 executor; 6 independent files = team. +**Key rule — the trigger is the TASK SET; coupling dictates the SPLIT, not the agent count.** One task = one agent; several tasks = one agent per task; independent tasks = team. Never two agents on the same file. ### Dev Workflow - **ALWAYS work in dev/source repo** — NEVER write to deployed/production paths directly @@ -63,6 +91,7 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only **Only exception:** Git read-only (status, log, diff) ## Directives — Consult Your Skills +- Lead procedure (request → verified report) → **consult `fuse-ai-pilot:lead-orchestration`**. - Task = create/build/feature/refactor/debug/multi-file → **consult APEX skills first**: `fuse-ai-pilot:apex` / `fuse-ai-pilot:apex-methodology` (+ `apex-quick` for trivial). The full methodology lives there, not inline here. - SOLID/DRY → **consult SOLID skills** (`solid-*` / rule `04-solid-dry-rules.md`). - Full rule detail → rules `00-08`, which the `fuse-rules` plugin intends to deliver through its hooks; end-to-end Cursor delivery is runtime-unverified — don't restate them here. @@ -72,7 +101,7 @@ Writing style (ALWAYS): clear, concise, precise. Lead with the answer, then only - `sniper` runs AFTER all teammates finish — never during. ## SOLID Rules -1. **File size** - `FUSE_SOLID_MAX_LINES` (default `200`) is the only file-size ceiling; split files that exceed it +1. **File size** - `FUSE_SOLID_MAX_LINES` (default `200`) is the only file-size ceiling; split files that exceed it. Never set your own cap and never work around the hook's; if a legitimate fix cannot fit, report it to the owner, who tunes the variable 2. **Interfaces separated** - Per stack location 3. **Research first** - `research-expert` before ANY code 4. **Validate after** - `sniper` after ANY modification From f651ba551eb8672e22a9cbfe56d92127eb9c21cf Mon Sep 17 00:00:00 2001 From: Bruno Azoulay Date: Mon, 12 Oct 2026 14:41:54 +0200 Subject: [PATCH 2/4] chore(deps): bump scripts and fuse-seo dependencies - scripts: @clack/prompts ^1.8.1, @types/bun ^1.4.3 (bun.lock refreshed) - fuse-seo: fast-xml-parser ^5.11.2, lighthouse ^13.5.0, chrome-launcher ^1.2.2, @types/bun ^1.4.3 --- .cursor-plugin/plugins/fuse-seo/package.json | 8 ++++---- .cursor-plugin/scripts/bun.lock | 12 ++++++------ .cursor-plugin/scripts/package.json | 4 ++-- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.cursor-plugin/plugins/fuse-seo/package.json b/.cursor-plugin/plugins/fuse-seo/package.json index 4ca253f..d506095 100644 --- a/.cursor-plugin/plugins/fuse-seo/package.json +++ b/.cursor-plugin/plugins/fuse-seo/package.json @@ -16,12 +16,12 @@ }, "dependencies": { "cheerio": "^1.2.0", - "fast-xml-parser": "^5.10.1", - "lighthouse": "^13.4.1", - "chrome-launcher": "^1.2.1" + "fast-xml-parser": "^5.11.2", + "lighthouse": "^13.5.0", + "chrome-launcher": "^1.2.2" }, "devDependencies": { - "@types/bun": "^1.3.14", + "@types/bun": "^1.4.3", "typescript": "^7.0.2" } } diff --git a/.cursor-plugin/scripts/bun.lock b/.cursor-plugin/scripts/bun.lock index 4d4382f..bf6f656 100644 --- a/.cursor-plugin/scripts/bun.lock +++ b/.cursor-plugin/scripts/bun.lock @@ -5,23 +5,23 @@ "": { "name": "@fusengine/hooks-loader", "dependencies": { - "@clack/prompts": "^1.7.0", + "@clack/prompts": "^1.8.1", }, "devDependencies": { - "@types/bun": "^1.3.14", + "@types/bun": "^1.4.3", }, }, }, "packages": { - "@clack/core": ["@clack/core@1.4.3", "", { "dependencies": { "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-/kr3UWNtdJfxZtPgDqUOmG2pvwlmcLGheex5yiZKdwbzZJxhV+HMNR9QNmyY5cGwTNV6LrR7Jtp+KjhUAP1qBQ=="], + "@clack/core": ["@clack/core@1.5.1", "", { "dependencies": { "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-iHTrHA8MtVuLl2TfZySmcKv1qO2PoyC9Z7pfSDozEuV5vtY3/wcOPKJXlqJ5Oq2Cx5DDGQGAMVx6HZfRRoVEbQ=="], - "@clack/prompts": ["@clack/prompts@1.7.0", "", { "dependencies": { "@clack/core": "1.4.3", "fast-string-width": "^3.0.2", "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A=="], + "@clack/prompts": ["@clack/prompts@1.8.1", "", { "dependencies": { "@clack/core": "1.5.1", "fast-string-width": "^3.0.2", "fast-wrap-ansi": "^0.2.0", "sisteransi": "^1.0.5" } }, "sha512-dlT1m5e/0yUL0kRNcQn7yGLVThkgbB0Ga/1AmfDDC/8ik6AIiSf2QLQO2zPYvefsHP0aFgxO93cVLCCfDp7kzQ=="], - "@types/bun": ["@types/bun@1.4.0", "", { "dependencies": { "bun-types": "1.4.0" } }, "sha512-K+lZULY23vRgK/CfTjFIV+tyifaNdSMlPh9j+6mQ/cLfpOznLyAuzgV/JQysyECpkBQLVMSyvjlr2fBUSA9wFQ=="], + "@types/bun": ["@types/bun@1.4.3", "", { "dependencies": { "bun-types": "1.4.3" } }, "sha512-N67Pqy8JXbAY/j0tNraS3V5mubGvc6rrrNDmDCtZLlFzccbUJPDb0tvgUBC5q4m8ybkP93Jcn1QB+RYQ6PvBhw=="], "@types/node": ["@types/node@26.4.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-faiGnoIrLH/V8cibOMEAZ8pMw6oXqSukl29ra4mN8GdaB2ZewzeaLj+INpV5N+Z1eKWzY+IzaIZH2EIR6YZRNQ=="], - "bun-types": ["bun-types@1.4.0", "", { "dependencies": { "@types/node": "*" } }, "sha512-iIKw23BspnQQYd3prITOBxeUsxBHnwzX6YJfGMuNOZzeNcMmVqzIIVGRm1l69ogaPQmb4wB6BN8mA5bE9YuC5Q=="], + "bun-types": ["bun-types@1.4.3", "", { "dependencies": { "@types/node": "*", "undici-types": "*" } }, "sha512-tinRJNGOmUN+tEAsn2y2e942n9JHRHR42iUYzDH75NmhJqVBokGSQkkfSFdNWwsANIdrK6ACH9t01M452YyTwg=="], "fast-string-truncated-width": ["fast-string-truncated-width@3.0.3", "", {}, "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g=="], diff --git a/.cursor-plugin/scripts/package.json b/.cursor-plugin/scripts/package.json index 39f7e5a..9635043 100644 --- a/.cursor-plugin/scripts/package.json +++ b/.cursor-plugin/scripts/package.json @@ -2,7 +2,7 @@ "name": "@fusengine/hooks-loader", "version": "2.0.0", "devDependencies": { - "@types/bun": "^1.3.14" + "@types/bun": "^1.4.3" }, "description": "Hooks loader for Cursor plugins - Bun + SOLID", "engines": { @@ -16,6 +16,6 @@ }, "type": "module", "dependencies": { - "@clack/prompts": "^1.7.0" + "@clack/prompts": "^1.8.1" } } From d74914c7ab8fe670dbf20a7925df629da0f88e90 Mon Sep 17 00:00:00 2001 From: Bruno Azoulay Date: Mon, 12 Oct 2026 14:42:15 +0200 Subject: [PATCH 3/4] chore(parity): align skills and agents with claude-plugins - TeamCreate -> Task wording across plugins - new agent fuse-ai-pilot/agents/skill-creator.md - agent tools lists synced (sequential-thinking, Write/Bash); readonly removed on 3 agents - README version refreshes (Go 1.27, Rust 1.98, PHP PER-CS 3.1, TypeScript 7.0 / Bun 1.4) - fuse-design fora-recode reference translated to English --- .../plugins/fuse-ai-pilot/README.md | 6 +- .../fuse-ai-pilot/agents/brainstorming.md | 3 +- .../fuse-ai-pilot/agents/research-expert.md | 4 +- .../fuse-ai-pilot/agents/skill-creator.md | 78 + .../fuse-ai-pilot/agents/sniper-faster.md | 3 +- .../plugins/fuse-ai-pilot/agents/websearch.md | 5 +- .../agent-creator/references/architecture.md | 2 +- .../references/templates/agent-template.md | 2 +- .../skills/brainstorming/SKILL.md | 2 +- .../fuse-astro/skills/astro-7/SKILL.md | 2 +- .../fuse-astro/skills/astro-actions/SKILL.md | 2 +- .../fuse-astro/skills/astro-assets/SKILL.md | 2 +- .../fuse-astro/skills/astro-content/SKILL.md | 2 +- .../fuse-astro/skills/astro-db/SKILL.md | 2 +- .../skills/astro-deployment/SKILL.md | 2 +- .../fuse-astro/skills/astro-i18n/SKILL.md | 2 +- .../skills/astro-integrations/SKILL.md | 2 +- .../fuse-astro/skills/astro-islands/SKILL.md | 2 +- .../fuse-astro/skills/astro-security/SKILL.md | 2 +- .../fuse-astro/skills/astro-seo/SKILL.md | 2 +- .../skills/astro-starlight/SKILL.md | 2 +- .../fuse-astro/skills/astro-styling/SKILL.md | 2 +- .../fuse-astro/skills/solid-astro/SKILL.md | 2 +- .../fuse-cartographer/agents/cartographer.md | 4 +- .../agents/changelog-watcher.md | 3 +- .../fuse-commit-pro/agents/commit-detector.md | 5 +- .../plugins/fuse-commit-pro/commands/chore.md | 2 +- .../plugins/fuse-commit-pro/commands/docs.md | 2 +- .../plugins/fuse-commit-pro/commands/feat.md | 2 +- .../plugins/fuse-commit-pro/commands/fix.md | 2 +- .../fuse-commit-pro/commands/refactor.md | 2 +- .../plugins/fuse-commit-pro/commands/test.md | 2 +- .../fuse-design/agents/design-expert.md | 28 +- .../references/glassmorphism-advanced-ref.md | 2 +- .../references/interactive-states-ref.md | 2 +- .../references/layered-backgrounds-ref.md | 2 +- .../references/component-composition-ref.md | 2 +- .../references/component-variants-ref.md | 2 +- .../refs-design/fora-recode/index.html | 634 +++---- .../refs-design/fora-recode/styles.css | 1587 ++++++++--------- .cursor-plugin/plugins/fuse-go/README.md | 6 +- .../fuse-go/skills/go-concurrency/SKILL.md | 2 +- .../fuse-go/skills/go-core-idioms/SKILL.md | 2 +- .../skills/go-tooling-security/SKILL.md | 2 +- .cursor-plugin/plugins/fuse-laravel/README.md | 2 +- .../fuse-laravel/skills/fusecore/SKILL.md | 2 +- .../skills/laravel-ai-sdk/SKILL.md | 2 +- .../fuse-laravel/skills/laravel-api/SKILL.md | 2 +- .../skills/laravel-architecture/SKILL.md | 2 +- .../skills/laravel-attributes/SKILL.md | 2 +- .../fuse-laravel/skills/laravel-auth/SKILL.md | 2 +- .../skills/laravel-billing/SKILL.md | 2 +- .../skills/laravel-blade/SKILL.md | 2 +- .../skills/laravel-eloquent/SKILL.md | 2 +- .../fuse-laravel/skills/laravel-i18n/SKILL.md | 2 +- .../skills/laravel-jsonapi/SKILL.md | 2 +- .../skills/laravel-livewire/SKILL.md | 2 +- .../skills/laravel-migrations/SKILL.md | 2 +- .../skills/laravel-permission/SKILL.md | 2 +- .../skills/laravel-queues/SKILL.md | 2 +- .../skills/laravel-reverb/SKILL.md | 2 +- .../skills/laravel-scout/SKILL.md | 2 +- .../skills/laravel-stripe-connect/SKILL.md | 2 +- .../skills/laravel-testing/SKILL.md | 2 +- .../skills/laravel-upgrade-v13/SKILL.md | 2 +- .../skills/laravel-vector-search/SKILL.md | 2 +- .../fuse-laravel/skills/laravel-vite/SKILL.md | 2 +- .../fuse-laravel/skills/solid-php/SKILL.md | 2 +- .../fuse-lessons/agents/lessons-compactor.md | 3 +- .cursor-plugin/plugins/fuse-nextjs/README.md | 2 +- .../fuse-nextjs/skills/better-auth/SKILL.md | 2 +- .../fuse-nextjs/skills/nextjs-16/SKILL.md | 2 +- .../fuse-nextjs/skills/nextjs-i18n/SKILL.md | 2 +- .../skills/nextjs-server-components/SKILL.md | 2 +- .../fuse-nextjs/skills/nextjs-shadcn/SKILL.md | 2 +- .../fuse-nextjs/skills/nextjs-stack/SKILL.md | 2 +- .../skills/nextjs-tanstack-form/SKILL.md | 2 +- .../skills/nextjs-tanstack-query/SKILL.md | 2 +- .../skills/nextjs-zustand/SKILL.md | 2 +- .../fuse-nextjs/skills/prisma-7/SKILL.md | 2 +- .../fuse-nextjs/skills/solid-nextjs/SKILL.md | 2 +- .cursor-plugin/plugins/fuse-php/README.md | 8 +- .../skills/php-ecosystem-reference/SKILL.md | 2 +- .../fuse-php/skills/php-http-psr/SKILL.md | 2 +- .../skills/php-language-modern/SKILL.md | 2 +- .../skills/php-quality-tooling/SKILL.md | 2 +- .../fuse-php/skills/php-standards/SKILL.md | 2 +- .../fuse-php/skills/php-testing/SKILL.md | 2 +- .../agents/prompt-engineer.md | 3 +- .../templates/agents/api-designer.md | 2 +- .../templates/agents/code-reviewer.md | 2 +- .../templates/agents/data-analyst.md | 2 +- .../templates/agents/security-auditor.md | 2 +- .../templates/agents/support-assistant.md | 2 +- .../templates/agents/technical-writer.md | 2 +- .../fuse-react/skills/react-19/SKILL.md | 2 +- .../fuse-react/skills/react-forms/SKILL.md | 2 +- .../fuse-react/skills/react-i18n/SKILL.md | 2 +- .../fuse-react/skills/react-shadcn/SKILL.md | 2 +- .../fuse-react/skills/react-state/SKILL.md | 2 +- .../skills/react-tanstack-router/SKILL.md | 2 +- .../fuse-react/skills/react-testing/SKILL.md | 2 +- .../fuse-react/skills/solid-react/SKILL.md | 2 +- .cursor-plugin/plugins/fuse-rust/README.md | 4 +- .../skills/rust-ecosystem-crates/SKILL.md | 2 +- .../skills/rust-testing-quality/SKILL.md | 2 +- .../skills/rust-tooling-cicd/SKILL.md | 2 +- .../plugins/fuse-seo/agents/seo-cluster.md | 4 +- .../plugins/fuse-seo/agents/seo-content.md | 4 +- .../plugins/fuse-seo/agents/seo-expert.md | 3 +- .../plugins/fuse-seo/agents/seo-geo.md | 4 +- .../plugins/fuse-seo/agents/seo-images.md | 4 +- .../plugins/fuse-seo/agents/seo-local.md | 4 +- .../plugins/fuse-seo/agents/seo-schema.md | 3 +- .../plugins/fuse-seo/agents/seo-sitemap.md | 3 +- .../plugins/fuse-seo/agents/seo-technical.md | 3 +- .../skills/shadcn-components/SKILL.md | 2 +- .../skills/shadcn-detection/SKILL.md | 2 +- .../skills/shadcn-migration/SKILL.md | 2 +- .../skills/shadcn-registries/SKILL.md | 2 +- .../skills/shadcn-theming/SKILL.md | 2 +- .../fuse-solid/agents/solid-orchestrator.md | 5 +- .../fuse-solid/skills/solid-csharp/SKILL.md | 4 +- .../fuse-solid/skills/solid-generic/SKILL.md | 4 +- .../references/architecture-patterns.md | 2 +- .../fuse-solid/skills/solid-go/SKILL.md | 4 +- .../references/single-responsibility.md | 2 +- .../fuse-solid/skills/solid-java/SKILL.md | 4 +- .../fuse-solid/skills/solid-python/SKILL.md | 4 +- .../fuse-solid/skills/solid-ruby/SKILL.md | 4 +- .../references/architecture-patterns.md | 6 +- .../references/single-responsibility.md | 2 +- .../fuse-solid/skills/solid-rust/SKILL.md | 4 +- .../agents/tailwindcss-expert.md | 3 +- .../skills/tailwindcss-accessibility/SKILL.md | 2 +- .../plugins/fuse-typescript/README.md | 7 +- .../fuse-typescript/skills/ts-config/SKILL.md | 2 +- .../skills/ts-language-patterns/SKILL.md | 2 +- .../skills/ts-lint-format/SKILL.md | 2 +- .../skills/ts-packaging/SKILL.md | 2 +- .../skills/ts-runtime-bun/SKILL.md | 2 +- .../skills/ts-runtime-node/SKILL.md | 2 +- .../skills/ts-testing/SKILL.md | 2 +- 143 files changed, 1400 insertions(+), 1277 deletions(-) create mode 100644 .cursor-plugin/plugins/fuse-ai-pilot/agents/skill-creator.md diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/README.md b/.cursor-plugin/plugins/fuse-ai-pilot/README.md index a3af284..95122b1 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/README.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/README.md @@ -11,8 +11,8 @@ resolving. | Component | Count | Cursor discovery | | :-- | :-- | :-- | -| Agents (subagents) | 8 | `agents/*.md` | -| Skills | 17 | `skills//SKILL.md` | +| Agents (subagents) | 9 | `agents/*.md` | +| Skills | 18 | `skills//SKILL.md` | | Commands | 12 | `commands/*.md` | | Hooks | 5 events | `hooks/hooks.json` | | Docs | 1 | `docs/*.md` — content, not a Cursor component | @@ -44,7 +44,7 @@ Cursor's subagent frontmatter is limited to `name`, `description`, `model`, `rea exists in the data model, but nothing proves the YAML frontmatter parser populates it from a local `.md`, nor that it is enforced as a hard restriction at runtime. Keeping both costs a few lines and covers either outcome. -- **`model:` is `grok-4.6` on all 8 agents** — no `inherit`, no `sonnet`; `claude-opus-*` stays +- **`model:` is `grok-4.6` on all 9 agents** — no `inherit`, no `sonnet`; `claude-opus-*` stays barred by policy. The ID is verified in the binary: `{modelId:"grok-4.6", parameters:[{id:"effort",value:"medium"}, {id:"fast",value:"false"}], legacyModelName:"cursor-grok-4.6-medium", displayName:"Cursor Grok 4.6 Medium"}`. Because diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/brainstorming.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/brainstorming.md index eeb0420..afc7014 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/brainstorming.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/brainstorming.md @@ -3,7 +3,7 @@ name: brainstorming description: "Use when: new features, component creation, major changes, adding functionality — triggers BEFORE Analyze phase. Do NOT use for: bug fixes, trivial changes, refactoring, read-only tasks." model: grok-4.6 color: cyan -tools: Read, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__sequential-thinking__sequentialthinking +tools: Read, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__sequential-thinking__sequentialthinking, Write skills: brainstorming, research, exploration --- @@ -24,6 +24,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__context7__query-docs` - `mcp__exa__web_search_exa` - `mcp__sequential-thinking__sequentialthinking` +- `Write` You are the creative design agent for the APEX workflow's Brainstorm phase, triggered before Analyze. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/research-expert.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/research-expert.md index d9a24cd..00e91e2 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/research-expert.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/research-expert.md @@ -3,7 +3,7 @@ name: research-expert description: "Use when: library docs lookup, API verification, best practices research. Do NOT use for: codebase exploration (use explore-codebase), code fixes (use sniper)." model: grok-4.6 color: blue -tools: Read, Glob, Grep, WebFetch, WebSearch, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_crawl, mcp__fuse-browser__browser_serp_batch +tools: Read, Glob, Grep, WebFetch, WebSearch, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_crawl, mcp__fuse-browser__browser_serp_batch, Write, Bash skills: research, fuse-ai-pilot:fuse-browser-usage --- @@ -33,6 +33,8 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_fetch_batch` - `mcp__fuse-browser__browser_crawl` - `mcp__fuse-browser__browser_serp_batch` +- `Write` +- `Bash` You are the technical research expert — precise, current, source-backed answers by combining official documentation (Context7), web/code intelligence (Exa), and structured reasoning (Sequential Thinking). diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/skill-creator.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/skill-creator.md new file mode 100644 index 0000000..56f6971 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/skill-creator.md @@ -0,0 +1,78 @@ +--- +name: skill-creator +description: "Use when: creating a new skill, restructuring one that lacks the SKILL.md + references/ layout, or repairing a skill with missing/outdated references. Do NOT use for: creating agents (use the agent-creator skill), SOLID audits (solid-orchestrator), or only reading the methodology (/fuse-ai-pilot:skill-creator)." +model: grok-4.6 +color: purple +tools: Read, Write, Edit, Glob, Grep, Bash, Skill, mcp__sequential-thinking__sequentialthinking, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa +skills: skill-creator +--- + +## Allowed tools + +> Reminder, not a substitute. The `tools:` key in the frontmatter above is the +> authoritative declaration — it is a first-class repeated field of Cursor's internal +> `agent.v1.CustomSubagent` model. It is restated here because runtime enforcement of +> that key is unverified, so this list keeps the constraint in the model's context. + +This agent must restrict itself strictly to the following tools: + +- `Read` +- `Write` +- `Edit` +- `Glob` +- `Grep` +- `Bash` +- `Skill` +- `mcp__sequential-thinking__sequentialthinking` +- `mcp__context7__resolve-library-id` +- `mcp__context7__query-docs` +- `mcp__exa__web_search_exa` +- `mcp__exa__get_code_context_exa` + + +You are the skill scaffolding specialist — you turn the `skill-creator` methodology into a written `SKILL.md` + `references/` tree, end to end, in an isolated context so the lead never has to hand-hold file creation. + +What separates you from your neighbors: the `skill-creator` **skill** is the methodology preloaded into your context via `skills:` — you are the actor that executes it, not the methodology itself. `agent-creator` (a skill with no dedicated agent) scaffolds **agent** frontmatter/body; you scaffold **skill** file trees — never write an agent `.md` here, and never let an agent mandate land on you. `prompt-engineer` designs prose quality and structure for any prompt; you own one specific convention — SKILL.md descriptive shell, conceptual references, complete templates, every file within `FUSE_SOLID_MAX_LINES`, and native Cursor discovery — not general prompt critique. + + +# Skill Creator Agent + +## Purpose + +Execute the 4 skill-creator flows — New, Restructure, Improve, Adapt — producing a compliant `SKILL.md` + `references/` structure, verified discoverable by Cursor, validated by `sniper`. + +## Workflow (MANDATORY) + +**Adaptation from the base methodology**: this agent has no `Task` tool and never spawns subagents. Where the skill says to delegate `explore-codebase` + `research-expert`, this agent does that research itself — `Glob`/`Grep`/`Read` for existing skill structure and patterns, `mcp__context7__*` and `mcp__exa__*` for official docs and code examples. The **lead** runs `fuse-ai-pilot:sniper` after this agent reports — never this agent. + +1. **Identify the flow**: New (no matching skill exists) / Restructure (skill exists but not `SKILL.md` + `references/` pattern) / Improve (pattern present, references missing or stale) / Adapt (copy an existing skill to a new framework — see `references/adaptation.md`). +2. **Research** (self-performed, no delegation): `Glob`/`Grep` sibling skills under the target plugin for structure and conventions; `Read` the closest match; `mcp__context7__resolve-library-id` + `query-docs` and `mcp__exa__*` for current library/framework facts. Never invent version numbers or APIs — verify or omit. +3. **Structure**: create `skills//references/templates/` under the owning plugin only. +4. **Write `SKILL.md`** from `references/templates/SKILL-template.md` — frontmatter (`name`, `description` starting with "Use when...", `versions`, `user-invocable`, `references`, `related-skills`), Agent Workflow, Overview, Critical Rules, Architecture, Reference Guide, Best Practices. +5. **Write references** (conceptual, WHY + WHEN) and **templates** (complete, copy-paste-ready code). Every file stays within `FUSE_SOLID_MAX_LINES` (positive integer, default `200`) — split rather than truncate content. +6. **Verify discovery**: confirm `skills//SKILL.md` sits under the plugin's native `skills/` root (or an explicit `.cursor-plugin/plugin.json` `skills` path, if the plugin declares one). Per the skill's `references/registration.md`, Claude-compatibility registration is added only when that target is explicitly in scope; state explicitly when it was skipped and why. +7. **Report** using Output Format below. Do not run `sniper` yourself — hand off to the lead. + +## Size and SOLID Rules + +`FUSE_SOLID_MAX_LINES` is the only file-size ceiling for every generated file — never set your own cap, never bypass the hook. If a legitimate file can't fit, report it instead of working around the hook. + +## Output Format + +``` +status: pass | fail | degraded +files_changed: [list] +skill_discovery: [native skills/ path verified? compatibility registration added or "not required — "] +sources_verified: [Context7/Exa sources consulted] +errors: [list or none] +``` + +## Forbidden + +- Never write outside the target plugin's `skills//`, plus any manifest path named by `references/registration.md` +- Never write a file without re-reading its current on-disk content first +- Never write under `~/.cursor`, `~/.claude`, an installed copy, or any path outside the owning repo +- Never `git commit` +- Never write skill content in a language other than English +- Never invent a directory layout the skill-creator methodology doesn't define (no ad-hoc top-level folders, no renamed `references/`) +- Never spawn subagents — do the research yourself or hand back to the lead diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper-faster.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper-faster.md index 540ef18..87d737b 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper-faster.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/sniper-faster.md @@ -3,7 +3,7 @@ name: sniper-faster description: "Use when: applying an already-identified, mechanical, non-ambiguous fix that requires no analysis. Do NOT use for: new features, refactoring, investigation, or any task requiring understanding — use sniper or the domain expert instead." model: grok-4.6 color: orange -tools: Read, Edit, Write, Bash, Grep, Glob, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__get_code_context_exa, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_screenshot +tools: Read, Edit, Write, Bash, Grep, Glob, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__exa__get_code_context_exa, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_screenshot, mcp__sequential-thinking__sequentialthinking skills: code-quality, react-effects-audit, fuse-ai-pilot:fuse-browser-usage --- @@ -29,6 +29,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__exa__get_code_context_exa` - `mcp__fuse-browser__browser_visual_diff` - `mcp__fuse-browser__browser_screenshot` +- `mcp__sequential-thinking__sequentialthinking` You are Sniper-Faster, a micro-fix applicator — you apply corrections that have already been decided, at maximum speed and with zero verbosity. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/websearch.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/websearch.md index 43c9d9a..feee2fd 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/websearch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/websearch.md @@ -3,7 +3,7 @@ name: websearch description: "Use when: current events, real-time info, quick factual lookup where speed > depth. Do NOT use for: library docs (use research-expert Context7+Exa), codebase analysis (use explore-codebase)." model: grok-4.6 color: yellow -tools: Read, WebFetch, WebSearch, Skill, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__fuse-browser__browser_serp_batch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_crawl +tools: Read, WebFetch, WebSearch, Skill, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__fuse-browser__browser_serp_batch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_crawl, Write, Bash, mcp__sequential-thinking__sequentialthinking skills: research, fuse-ai-pilot:fuse-browser-usage --- @@ -28,6 +28,9 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_fetch_batch` - `mcp__fuse-browser__browser_fetch` - `mcp__fuse-browser__browser_crawl` +- `Write` +- `Bash` +- `mcp__sequential-thinking__sequentialthinking` You are a quick web research specialist — fast, authoritative lookups via Exa alone, favoring speed over depth. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/architecture.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/architecture.md index d45b20e..df274bc 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/architecture.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/architecture.md @@ -61,7 +61,7 @@ hooks: ... # Agent Title ## Agent Workflow (MANDATORY) -... (uses TeamCreate) +... (spawns subagents in parallel via the `Task` tool, one call each) ## MANDATORY SKILLS USAGE ... diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/templates/agent-template.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/templates/agent-template.md index 16e1e9d..f5bce2a 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/templates/agent-template.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/agent-creator/references/templates/agent-template.md @@ -45,7 +45,7 @@ or `Task` surface when it is available: Then call **mcp__context7__query-docs** separately to check patterns. Context7 is an MCP tool call, not a third agent. If this file is emitted for the explicitly labeled Claude Code -compatibility target, `TeamCreate` may dispatch the same two agent tasks; keep the MCP call separate. +compatibility target, parallel `Agent` calls may dispatch the same two agent tasks; keep the MCP call separate. After implementation, run **fuse-ai-pilot:sniper** for validation. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/brainstorming/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/brainstorming/SKILL.md index aac88c9..6faef01 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/brainstorming/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/brainstorming/SKILL.md @@ -21,7 +21,7 @@ Skip it entirely for trivial fixes, typos, or simple renames -- those go straigh ## Agent Workflow (MANDATORY) -Before ANY brainstorming session, use `TeamCreate` to spawn agents: +Before ANY brainstorming session, spawn subagents in parallel (one Task call each, all in ONE message): 1. **fuse-ai-pilot:explore-codebase** - Understand project context, patterns, constraints 2. **fuse-ai-pilot:research-expert** - Fetch best practices and documentation diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-7/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-7/SKILL.md index b812af1..ebca479 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-7/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-7/SKILL.md @@ -22,7 +22,7 @@ Production-ready web framework for content-driven sites with unified dev runtime ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing routes, layouts, and config 2. **fuse-ai-pilot:research-expert** - Verify latest Astro 7 docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-actions/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-actions/SKILL.md index 1d79736..995d188 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-actions/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-actions/SKILL.md @@ -21,7 +21,7 @@ Type-safe server functions with automatic validation, standardized errors, and p ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Check existing actions in `src/actions/` 2. **fuse-ai-pilot:research-expert** - Verify latest Actions docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-assets/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-assets/SKILL.md index 1f9b063..a944cd9 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-assets/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-assets/SKILL.md @@ -20,7 +20,7 @@ Production-ready image optimization and asset management with `astro:assets` in ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing image usage and asset patterns 2. **fuse-ai-pilot:research-expert** - Verify astro:assets API via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-content/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-content/SKILL.md index f52e2f7..8401956 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-content/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-content/SKILL.md @@ -21,7 +21,7 @@ Type-safe content management with loaders, Zod schemas, and the unified Content ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Check existing collections, loaders, and content structure 2. **fuse-ai-pilot:research-expert** - Verify latest Content Layer docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-db/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-db/SKILL.md index 49f477b..61ddc5c 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-db/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-db/SKILL.md @@ -22,7 +22,7 @@ Type-safe SQL database built into Astro, powered by libSQL/Turso. Use for struct ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Check existing db/config.ts, tables, and Actions 2. **fuse-ai-pilot:research-expert** - Verify Astro DB API via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-deployment/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-deployment/SKILL.md index 3d02797..7ad5858 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-deployment/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-deployment/SKILL.md @@ -20,7 +20,7 @@ Production deployment for Astro 7 across all major platforms — Cloudflare, Ver ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze astro.config.mjs, output mode, and existing adapter 2. **fuse-ai-pilot:research-expert** - Verify adapter docs via Context7/Exa for target platform diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-i18n/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-i18n/SKILL.md index 3395f87..716e15d 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-i18n/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-i18n/SKILL.md @@ -18,7 +18,7 @@ Also covers translating Content Collections per locale and adding `hreflang` alt ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing routing, content collections, and locale files 2. **fuse-ai-pilot:research-expert** - Verify latest Astro i18n docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-integrations/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-integrations/SKILL.md index 37fb694..0acc11e 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-integrations/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-integrations/SKILL.md @@ -20,7 +20,7 @@ Framework-agnostic: use React, Vue, Svelte, Solid, and more in the same Astro pr ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Check existing integrations and astro.config.ts 2. **fuse-ai-pilot:research-expert** - Verify latest integration docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-islands/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-islands/SKILL.md index cb922fa..d980b2b 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-islands/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-islands/SKILL.md @@ -20,7 +20,7 @@ Partial hydration architecture: zero JS by default, selective interactivity via ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing components and hydration patterns 2. **fuse-ai-pilot:research-expert** - Verify latest Islands docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-security/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-security/SKILL.md index fd68cad..04870d6 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-security/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-security/SKILL.md @@ -18,7 +18,7 @@ Also covers the adapters' `staticHeaders` option (formerly `experimentalStaticHe ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing security config, adapters, headers 2. **fuse-ai-pilot:research-expert** - Verify latest Astro 7 CSP docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-seo/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-seo/SKILL.md index 31352a9..b6d3f19 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-seo/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-seo/SKILL.md @@ -20,7 +20,7 @@ Complete SEO strategy for Astro 7 sites — zero JS by default makes Astro natur ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing layouts, head components, and metadata 2. **fuse-ai-pilot:research-expert** - Verify latest SEO best practices via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-starlight/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-starlight/SKILL.md index 059d9e4..395865a 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-starlight/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-starlight/SKILL.md @@ -21,7 +21,7 @@ Production-ready documentation theme for Astro with built-in search, dark mode, ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing Starlight config, sidebar, and content structure 2. **fuse-ai-pilot:research-expert** - Verify Starlight plugin APIs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/astro-styling/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/astro-styling/SKILL.md index 58199d0..52dfbad 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/astro-styling/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/astro-styling/SKILL.md @@ -18,7 +18,7 @@ This skill addresses `.astro`-file styling specifically (scoping semantics uniqu ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze existing styles, integrations, and patterns 2. **fuse-ai-pilot:research-expert** - Verify latest Astro/Tailwind/UnoCSS docs via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-astro/skills/solid-astro/SKILL.md b/.cursor-plugin/plugins/fuse-astro/skills/solid-astro/SKILL.md index d06ba51..c087769 100644 --- a/.cursor-plugin/plugins/fuse-astro/skills/solid-astro/SKILL.md +++ b/.cursor-plugin/plugins/fuse-astro/skills/solid-astro/SKILL.md @@ -18,7 +18,7 @@ Provides ready-to-copy templates for components, layouts, services, and interfac ## Agent Workflow (MANDATORY) -Before ANY implementation, use `TeamCreate` to spawn 3 agents: +Before ANY implementation, spawn 3 agents in parallel, one `Task` call each: 1. **fuse-ai-pilot:explore-codebase** - Analyze project structure, naming, and existing patterns 2. **fuse-ai-pilot:research-expert** - Verify Astro 7 architecture best practices via Context7/Exa diff --git a/.cursor-plugin/plugins/fuse-cartographer/agents/cartographer.md b/.cursor-plugin/plugins/fuse-cartographer/agents/cartographer.md index a2f86ed..61a5ff2 100644 --- a/.cursor-plugin/plugins/fuse-cartographer/agents/cartographer.md +++ b/.cursor-plugin/plugins/fuse-cartographer/agents/cartographer.md @@ -3,7 +3,7 @@ name: cartographer description: "Use when: /map command, finding skills/agents, understanding ecosystem layout. Do NOT use for: code generation, debugging, file editing." model: grok-4.6[effort=low] color: green -tools: Read, Write, Glob, Grep +tools: Read, Write, Glob, Grep, Bash, mcp__sequential-thinking__sequentialthinking --- ## Allowed tools @@ -19,6 +19,8 @@ This agent must restrict itself strictly to the following tools: - `Write` - `Glob` - `Grep` +- `Bash` +- `mcp__sequential-thinking__sequentialthinking` You are the cartography expert of the Fusengine ecosystem — you understand how `.cartographer/` maps work, how they're structured, and how to navigate them faster than any other agent. diff --git a/.cursor-plugin/plugins/fuse-changelog/agents/changelog-watcher.md b/.cursor-plugin/plugins/fuse-changelog/agents/changelog-watcher.md index 5227d06..4674f70 100644 --- a/.cursor-plugin/plugins/fuse-changelog/agents/changelog-watcher.md +++ b/.cursor-plugin/plugins/fuse-changelog/agents/changelog-watcher.md @@ -3,7 +3,7 @@ name: changelog-watcher description: "Use when: checking for Claude Code updates (/watch command), detecting breaking changes in our plugins, monitoring community feedback (/watch --pulse). Do NOT use for: code fixes (use sniper), general web research (use research-expert)." model: grok-4.6 color: cyan -tools: Read, Bash, Grep, Glob, Task, WebFetch, WebSearch, Skill, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_crawl, mcp__fuse-browser__browser_visual_diff +tools: Read, Bash, Grep, Glob, Task, WebFetch, WebSearch, Skill, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__sequential-thinking__sequentialthinking, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_crawl, mcp__fuse-browser__browser_visual_diff, Write skills: changelog-scan, breaking-changes, community-pulse, fuse-ai-pilot:fuse-browser-usage --- @@ -33,6 +33,7 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_fetch_batch` - `mcp__fuse-browser__browser_crawl` - `mcp__fuse-browser__browser_visual_diff` +- `Write` You are the Claude Code update tracking and plugin compatibility specialist — you monitor Claude Code releases, detect breaking changes that could affect this plugin ecosystem, and gather community feedback to inform plugin development strategy. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/agents/commit-detector.md b/.cursor-plugin/plugins/fuse-commit-pro/agents/commit-detector.md index 51edc91..835a277 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/agents/commit-detector.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/agents/commit-detector.md @@ -2,9 +2,8 @@ name: commit-detector description: "Use PROACTIVELY when: user says commit/save/git, mentions wip/feat/fix/chore. Do NOT use for: code review, non-commit git ops (log/diff/status)." model: grok-4.6[effort=low] -readonly: true color: cyan -tools: Bash, Read, Grep, Glob +tools: Bash, Read, Grep, Glob, Write, mcp__sequential-thinking__sequentialthinking skills: commit-detection --- @@ -21,6 +20,8 @@ This agent must restrict itself strictly to the following tools: - `Read` - `Grep` - `Glob` +- `Write` +- `mcp__sequential-thinking__sequentialthinking` You are an expert git commit analyzer — you automatically detect the best conventional commit type for the current changes, by analyzing what's staged, not by asking. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/chore.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/chore.md index 8db4dfb..29a23e9 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/chore.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/chore.md @@ -31,4 +31,4 @@ Create a maintenance/chore commit. 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/docs.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/docs.md index 120ba5c..ee7de80 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/docs.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/docs.md @@ -31,4 +31,4 @@ Create a documentation commit. 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/feat.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/feat.md index 4673aeb..f9f3de7 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/feat.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/feat.md @@ -28,6 +28,6 @@ Create a quick feature commit. 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) **Note**: All commits trigger **PATCH** bump only (1.37.0 → 1.37.1). MINOR/MAJOR bumps are manual user decisions. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/fix.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/fix.md index 613bea5..b04bae3 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/fix.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/fix.md @@ -28,4 +28,4 @@ Create a quick bugfix commit. 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/refactor.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/refactor.md index 21367a7..df3f1b7 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/refactor.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/refactor.md @@ -28,6 +28,6 @@ Create a refactoring commit (no behavior change). 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) Note: Refactor = code restructure WITHOUT functional changes. diff --git a/.cursor-plugin/plugins/fuse-commit-pro/commands/test.md b/.cursor-plugin/plugins/fuse-commit-pro/commands/test.md index 5684cda..0a8abf7 100644 --- a/.cursor-plugin/plugins/fuse-commit-pro/commands/test.md +++ b/.cursor-plugin/plugins/fuse-commit-pro/commands/test.md @@ -30,4 +30,4 @@ Create a test commit. 5. **NO AI SIGNATURE**: Never add Co-authored-by, Generated by, or any AI mention 6. Ask confirmation before committing 7. Execute and show result -8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Step 7/8, not by this quick command) +8. Execute the `post-commit` skill (CHANGELOG + version bump only — no tag here; tagging is handled post-merge by `/fuse-commit-pro:commit`'s Steps 7–9 (merge, tag, release-workflow watch), not by this quick command — never call a release "published" from here) diff --git a/.cursor-plugin/plugins/fuse-design/agents/design-expert.md b/.cursor-plugin/plugins/fuse-design/agents/design-expert.md index e7be0ba..2117d6b 100644 --- a/.cursor-plugin/plugins/fuse-design/agents/design-expert.md +++ b/.cursor-plugin/plugins/fuse-design/agents/design-expert.md @@ -1,9 +1,9 @@ --- name: design-expert -description: "Use when: designing or auditing a design system, a marketing site, a web app screen, or an iOS/Android mockup. Do NOT use for: wiring components into a codebase (delegate to the matching framework expert), or writing SwiftUI/Compose implementation code (delegate to swift-expert or an Android developer)." +description: "Use when: designing or auditing a design system, a marketing site, a web app screen, or an Apple-platform (iOS, iPadOS, macOS, watchOS, tvOS, visionOS) or Android mockup. Do NOT use for: wiring components into a codebase (delegate to the matching framework expert), or writing SwiftUI/Compose implementation code (delegate to swift-expert or an Android developer)." model: grok-4.6 color: pink -tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, Skill, mcp__magic__21st_magic_component_builder, mcp__magic__21st_magic_component_inspiration, mcp__magic__21st_magic_component_refiner, mcp__magic__logo_search, mcp__shadcn__search_items_in_registries, mcp__shadcn__view_items_in_registries, mcp__shadcn__get_item_examples_from_registries, mcp__shadcn__get_add_command_for_items, mcp__gemini-design__create_frontend, mcp__gemini-design__modify_frontend, mcp__gemini-design__snippet_frontend, mcp__fuse-browser__browser_open, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_scroll, mcp__fuse-browser__browser_wait_for, mcp__fuse-browser__browser_snapshot, mcp__fuse-browser__browser_screenshot, mcp__fuse-browser__browser_click, mcp__fuse-browser__browser_close, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_shots_batch, mcp__fuse-browser__browser_site_shots, mcp__fuse-browser__browser_extract_schema, mcp__fuse-browser__browser_metrics, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_serp_batch, Task +tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, Skill, mcp__magic__21st_magic_component_builder, mcp__magic__21st_magic_component_inspiration, mcp__magic__21st_magic_component_refiner, mcp__magic__logo_search, mcp__shadcn__search_items_in_registries, mcp__shadcn__view_items_in_registries, mcp__shadcn__get_item_examples_from_registries, mcp__shadcn__get_add_command_for_items, mcp__gemini-design__create_frontend, mcp__gemini-design__modify_frontend, mcp__gemini-design__snippet_frontend, mcp__fuse-browser__browser_open, mcp__fuse-browser__browser_navigate, mcp__fuse-browser__browser_scroll, mcp__fuse-browser__browser_wait_for, mcp__fuse-browser__browser_snapshot, mcp__fuse-browser__browser_screenshot, mcp__fuse-browser__browser_click, mcp__fuse-browser__browser_close, mcp__fuse-browser__browser_visual_diff, mcp__fuse-browser__browser_shots_batch, mcp__fuse-browser__browser_site_shots, mcp__fuse-browser__browser_extract_schema, mcp__fuse-browser__browser_metrics, mcp__fuse-browser__browser_fetch, mcp__fuse-browser__browser_fetch_batch, mcp__fuse-browser__browser_serp_batch, Task, mcp__sequential-thinking__sequentialthinking skills: design-method, design-system, design-web, design-webapp, design-motion, design-review, ux-copy, design-ios, design-android, elicitation, fuse-ai-pilot:fuse-browser-usage --- @@ -53,9 +53,10 @@ This agent must restrict itself strictly to the following tools: - `mcp__fuse-browser__browser_fetch_batch` - `mcp__fuse-browser__browser_serp_batch` - `Task` +- `mcp__sequential-thinking__sequentialthinking` -You are the UI/UX design director for four targets: marketing websites, web apps, iOS, and Android. You are a thin router — zero taste decisions live in you; every floor, brief gate, register rule, and move procedure lives in the `design-method` skill and its references, and your only job is resolving which one applies and dispatching to it. +You are the UI/UX design director for four targets: marketing websites, web apps, Apple platforms (iOS, iPadOS, macOS, watchOS, tvOS, visionOS), and Android. You are a thin router — zero taste decisions live in you; every floor, brief gate, register rule, and move procedure lives in the `design-method` skill and its references, and your only job is resolving which one applies and dispatching to it. You generate production-ready HTML/CSS directly by default — Gemini Design MCP, Magic (21st.dev), and shadcn MCP are optional fallback tools, never a requirement. For mobile targets you ship tokens, an HTML device-framed mockup, and a handoff spec — never SwiftUI or Compose code; implementation is always delegated onward. @@ -64,7 +65,7 @@ Your posture is procedural discipline over taste: you never restate or override # Design Expert Agent -UI/UX design director covering four targets: marketing websites, web apps, iOS, and +UI/UX design director covering four targets: marketing websites, web apps, Apple platforms, and Android. **Thin router — zero taste decisions live here.** Every floor, brief gate, register rule, and move procedure lives in `skills/design-method/SKILL.md` and its `references/register/` + `references/moves/` files; this agent's only job is to resolve @@ -116,7 +117,7 @@ happened. Never let a routing decision resolve to a quiet "done." **Platform resolution (orthogonal to the move — always resolve it before entering a target skill).** A move alone never picks the target skill; the *platform* does. Once a move is matched, resolve WHAT surface is being designed — marketing/landing site, logged-in -web app, iOS/macOS, Android, or copy-only — then enter the matching skill by following +web app, an Apple platform (iOS, iPadOS, macOS, watchOS, tvOS, visionOS), Android, or copy-only — then enter the matching skill by following `design-method`'s **`Target skill chain`** table (its columns are Platform | Chain; that table is the canonical home — e.g. a marketing site → `design-web`). Never hardcode or reproduce that mapping here; point at the table. The site-vs-web-app split IS the @@ -124,6 +125,14 @@ brand-vs-product **Register** call `design-method` resolves first; if the platfo genuinely ambiguous (could read as a marketing page OR an app screen), ask exactly **ONE** question before entering a chain — never guess past it. +**Owner's material wins.** A design, mockup, screenshot or style reference the owner sends +is the source of truth: compare against it, never reinterpret it. Quote each owner +requirement and each "don't touch X" as an acceptance check before starting. + +**Deliverable contract.** If format, target path or style is unstated, settle all three in +one binary question (raster default WebP). Deliver to the owner's path — never a hidden +dot-folder or an invented folder — and report exact absolute paths. + Zero taste rules here: floors, anti-slop clusters, brief gates, and move mechanics all live in `design-method` and its `register`/`moves` references. This router never restates or overrides them — if a rule looks like it belongs here, it belongs in `design-method` @@ -148,6 +157,10 @@ additionally means `design-review`'s deterministic checks + bounded visual loop and passed (or the remaining gaps are explicitly reported) — the matched move file's report template says which apply. +**Look before done.** Capture the rendered mockup/page (light + dark, each canvas), Read +the PNGs yourself and state in the report what you see, with the image path. Passing tests +never validate a visual; never ask the owner for a capture you can take. + Browser efficiency rules: invoke skill `fuse-ai-pilot:fuse-browser-usage` (profile: visual-design). Always `browser_close` sessions opened during research/screenshot phases. @@ -183,7 +196,10 @@ Report back to the lead with: - **status**: `done` | `failed` | `blocked` - **move**: which `references/moves/.md` ran - **register**: `brand` | `product` -- **files_changed**: list of modified/created files +- **files_changed**: list of modified/created files (absolute paths) +- **brief_checklist**: each owner requirement quoted and ticked `[x]`/`[ ]` with its + evidence (screenshot path, diff line); an unticked item blocks `status: done` +- **visual_check**: screenshot paths + what they show, or `not run` with the reason - **verification**: the move's report-template output, plus `design-review` results (deterministic checks + visual loop verdict) where applicable, plus sniper outcome - **challenger_verdict**: resolved / owner-accepted findings, or `not judged` on fallback diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/glassmorphism-advanced-ref.md b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/glassmorphism-advanced-ref.md index 43d030b..79698ef 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/glassmorphism-advanced-ref.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/glassmorphism-advanced-ref.md @@ -12,7 +12,7 @@ related-skills: designing-systems, generating-components ## Agent Workflow (MANDATORY) -Before implementation, use `TeamCreate` to spawn 3 agents: +Before implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing glass patterns 2. **fuse-ai-pilot:research-expert** - Latest backdrop-filter support diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/interactive-states-ref.md b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/interactive-states-ref.md index 801fbfb..bf56fa9 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/interactive-states-ref.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/interactive-states-ref.md @@ -12,7 +12,7 @@ related-skills: adding-animations, generating-components ## Agent Workflow (MANDATORY) -Before implementation, use `TeamCreate` to spawn 3 agents: +Before implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing state patterns 2. **fuse-ai-pilot:research-expert** - Framer Motion state animations diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/layered-backgrounds-ref.md b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/layered-backgrounds-ref.md index 9b077df..f09fb4c 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/layered-backgrounds-ref.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-motion/references/layered-backgrounds-ref.md @@ -13,7 +13,7 @@ related-skills: glassmorphism-advanced, generating-components ## Agent Workflow (MANDATORY) -Before implementation, use `TeamCreate` to spawn 3 agents: +Before implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing background patterns 2. **fuse-ai-pilot:research-expert** - CSS filter and blend modes diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-composition-ref.md b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-composition-ref.md index bf501ab..0d6193b 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-composition-ref.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-composition-ref.md @@ -12,7 +12,7 @@ related-skills: generating-components ## Agent Workflow (MANDATORY) -Before implementation, use `TeamCreate` to spawn 3 agents: +Before implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing composition patterns 2. **fuse-ai-pilot:research-expert** - React 19 composition patterns diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-variants-ref.md b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-variants-ref.md index dd9a6be..de620c0 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-variants-ref.md +++ b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/component-variants-ref.md @@ -12,7 +12,7 @@ related-skills: glassmorphism-advanced, generating-components ## Agent Workflow (MANDATORY) -Before implementation, use `TeamCreate` to spawn 3 agents: +Before implementation, delegate via `Task` — spawn 3 agents in parallel (single message, 3 `Task` calls): 1. **fuse-ai-pilot:explore-codebase** - Check existing variant patterns 2. **fuse-ai-pilot:research-expert** - cva/class-variance-authority docs diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/index.html b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/index.html index 5633611..dd0fd09 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/index.html +++ b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/index.html @@ -7,103 +7,103 @@ - + - + + [measured] .framer-wz7sin{height:min-content;padding:var(--1gxu5kl);…gap:10px;width:1440px} + with --1gxu5kl:0px 40px 0px 40px (desktop) and 0px 24px 0px 24px (mobile). --> + The gradient is written in plain text in the source; the two hill images are + anchored AT THE BOTTOM, full width. It is not a section background, it is a horizon. -->
- -
+
-
- Community platform for creators -

Your community deserves its own home.

-

Fora gives creators, educators, +

+ Community platform for creators +

Your community deserves its own home.

+

Fora gives creators, educators, and coaches a fully branded space with courses, events, discussions, and members.

-
- Get started free +
+ Get started free
- -
+ +
-
+
- +
- +
- Overview - Chat - Analytics - Courses - Events - Members - Leaderboard + Overview + Chat + Analytics + Courses + Events + Members + Leaderboard
-
+
- -
-
- S -

Strong By Ava

-

- + +

+
+ S +

Strong By Ava

+

+ @@ -111,8 +111,8 @@

Your community deserves its own home.

847 members

- Join now -

Ava Torres is a certified strength coach with + Join now +

Ava Torres is a certified strength coach with 80k+ followers on Instagram. → 12-week progressive training programs with video lessons → Weekly live Q&As and form-check threads → A supportive community of women training for strength

@@ -122,15 +122,15 @@

Your community deserves its own home.

- +
-
- Intro +
+ Intro
-
- +
-
-
-
- Core Features -

One platform to run right +
+
+
+ Core Features +

One platform to run right your entire community.

-

Fora brings your courses, events, +

Fora brings your courses, events, discussions, and members into one space, so you stop switching between tools and start spending time with your community.

-
- -
- - - - - +
+ +
+ + + + +
-
- -
- +
-
-
- -

Post, discuss, react — +

+
+ +

Post, discuss, react — the feed your members live in.

-
- -
@@ -219,70 +219,70 @@

One platform to run right

-
-
-
-
- What you get -

Set up once.
+ [measured] .framer-uc3xgg{flex-flow:column;…gap:48px…} — THREE LARGE STACKED + CARDS, not a three-column grid. Each is cut into two halves whose + order flips from one card to the next. --> +
+
+
+
+ What you get +

Set up once.
Run it the way you want.

-

Fora is built so you spend time +

Fora is built so you spend time with your community, not configuring it. From your first setting to your hundredth member, the platform stays out of your way.

-
-
- -
-
+
+
+ +
+

Your front door

A community overview page that sells itself.

Customize your hero with a static color or animated gradient. Add a headline, a description and member avatars. Your overview page is the first thing a visitor sees — make it yours.

-

+

First impressions that convert.

-
-
- -
-
+
+ +
+

Friendly competition

A leaderboard your members actually check.

Rankings based on posts, completions, and activity — surfaced automatically. Gives your most engaged members a reason to stay and your quieter ones a reason to show up.

-

+

Engagement that compounds over time.

-
-
- -
-
+
+ +
+

Courses

Build your course the way you teach.

Structure your content into chapters and lessons, in any order you want. Add your material, hit publish, and your members can start learning — right inside the community they already live in.

-

+

Courses that feel like yours, not a template.

-
@@ -292,78 +292,78 @@

Build your course the way you teach.

-
-
- Pricing -

Clear pricing plans
that scale with you

+
+
+ Pricing +

Clear pricing plans
that scale with you

-
-
- - - +
+
+ + +
- Two months free on yearly + Two months free on yearly
-
-
- -
-

STARTER

-
- $0 - /month +
+
+ +
+

STARTER

+
+ $0 + /month
-

Everything you need to launch your community.

- Get Started -
-

Up to 200 members

-

Fora subdomain

-

Community feed & chat

-

Courses & events

-

Member profiles

-

Analytics

+

Everything you need to launch your community.

+ Get Started +
+

Up to 200 members

+

Fora subdomain

+

Community feed & chat

+

Courses & events

+

Member profiles

+

Analytics

-
- -
-

PRO

-
- $0 - /month +
+ +
+

PRO

+
+ $0 + /month
-

For creators serious about their brand.

- Get Started -
-

Up to 5000 members

-

Custom domain

-

Community feed & chat

-

Courses & events

-

Member profiles

-

Analytics

+

For creators serious about their brand.

+ Get Started +
+

Up to 5000 members

+

Custom domain

+

Community feed & chat

+

Courses & events

+

Member profiles

+

Analytics

-
- -
-

ENTERPRISE

-

Custom price

-

For teams that need
more control.

- Contact us -
-

Unlimited members

-

Everything in Pro

-

Priority support

-

Dedicated onboarding

-

SLA & uptime guarantee

-

Custom contract

+
+ +
+

ENTERPRISE

+

Custom price

+

For teams that need
more control.

+ Contact us +
+

Unlimited members

+

Everything in Pro

+

Priority support

+

Dedicated onboarding

+

SLA & uptime guarantee

+

Custom contract

@@ -372,81 +372,81 @@

Clear pricing plans
that scale with you

+ [measured] .framer-2jfjwj{flex-flow:column;flex:2 0 0;…gap:8px…}: two columns at a + 1:2 ratio, categories and contact inset on the left, accordions on the right. -->
-
-
-
- FAQ -

Answers to the questions that come up most.

+
+
+
+ FAQ +

Answers to the questions that come up most.

-

Learn how Fora works, what's +

Learn how Fora works, what's included in the beta, what your members experience, and what to expect as the platform grows.

-
-
+
+
- - - + + +
-
- -
+
+ +
Got Questions?
-

Can't find what you're looking for? Reach out — we're fast.

-

Contact us →

+

Can't find what you're looking for? Reach out — we're fast.

+

Contact us →

-
-
- - -

Fora is a white-label community platform for +

Fora is a white-label community platform for creators, educators, and coaches. You get a fully branded space with courses, events, discussions, and members — all running on your own subdomain or custom domain.

-
- - -

Most communities are live in under 20 minutes. You +

Most communities are live in under 20 minutes. You pick a subdomain, customize your overview page, and invite your first members. No code, no infrastructure.

-
- - -

Not at all. Everything happens through a clean +

Not at all. Everything happens through a clean dashboard. The only technical step is adding a DNS record if you want a fully custom domain — and we walk you through it.

-
- - -

Yes. Fora is in beta and completely free. No credit +

Yes. Fora is in beta and completely free. No credit card, no trial period — just sign up and go. When paid plans launch, beta members get a permanent discount locked in.

-
- - -

You'll get early notice before anything changes. +

You'll get early notice before anything changes. Beta members are first to know, first to get access to paid plans, and first to lock in their discount.

@@ -457,41 +457,41 @@
Got Questions?
-
-
-
- Blog -

Ideas, updates, and practical AI workflows

+
+
+
+ Blog +

Ideas, updates, and practical AI workflows

- Visit blog → + Visit blog →
-
- - -
-
+ + +
+
Fora vs Mighty Networks: Full Comparison for Creators & Educators (2026)
-

Comparisons
Jun 3, 2026

+

Comparisons
Jun 3, 2026

 - - -
-
+ +
+
How to Launch an Online Community in 2026: A Step-by-Step Guide
-

Guides
Jun 3, 2026

+

Guides
Jun 3, 2026

 - - -
-
+ +
+
Best White-Label Community Platform for Coaches & Educators
-

Community Building
Jun 3, 2026

+

Community Building
Jun 3, 2026
@@ -499,46 +499,46 @@
Best White-Label Community Platform for Coaches & Educators
+ The mockup overflows its column by 272px and gets cut by the section + edge. It sits in a SIBLING container of the text: placed inside, it would + cover it. A 190px horizon band closes the section. -->
-
-
+
+
-

Your community is one sec away.

-

Fora is in beta and free to join. Set up your space, +

Your community is one sec away.

+

Fora is in beta and free to join. Set up your space, invite your first members, and see what it feels like when everything lives in one place — under your name.

- Start for free + Start for free
- -
diff --git a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/styles.css b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/styles.css index 3801d8a..4695e29 100644 --- a/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/styles.css +++ b/.cursor-plugin/plugins/fuse-design/skills/design-web/references/refs-design/fora-recode/styles.css @@ -1,1097 +1,1096 @@ /* ========================================================================= - fora.so — RÉFÉRENCE DE DESIGN (recode vanilla) + fora.so — DESIGN REFERENCE (vanilla recode) - [relevé] = lu littéralement dans l'export Framer. La forme citée en - commentaire est grep-able telle quelle dans la source. - [arbitrage] = choix de ce fichier, parce que la source ne donne pas la - valeur ou la pilote en JavaScript. + [measured] = read literally in the Framer export. The form quoted in the + comment is grep-able as is in the source. + [decided] = a choice of this file, because the source does not give the + value or drives it from JavaScript. - La source ne contient AUCUN @keyframes et AUCUN animation-timeline : tout - le mouvement vient du runtime Framer Motion + Lenis 1.3.19. Les PARAMÈTRES - d'animation sont en revanche sérialisés dans -