diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 41cf5e0..7fe7b45 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Professional Cursor plugins with APEX workflow, SOLID principles, and expert development agents for Next.js, Laravel, Swift, Tailwind CSS, and more", - "version": "0.1.8" + "version": "0.1.9" }, "plugins": [ { @@ -36,7 +36,7 @@ "name": "fuse-ai-pilot", "source": ".cursor-plugin/plugins/fuse-ai-pilot", "description": "AI Pilot workflow agents: sniper (code quality), research-expert, explore-codebase, websearch", - "version": "1.2.44", + "version": "1.2.45", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -58,7 +58,7 @@ "name": "fuse-astro", "source": ".cursor-plugin/plugins/fuse-astro", "description": "Expert Astro 6 with Islands Architecture, Content Layer, Actions, View Transitions, and multi-framework integration", - "version": "1.0.14", + "version": "1.0.15", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -124,7 +124,7 @@ "name": "fuse-commit-pro", "source": ".cursor-plugin/plugins/fuse-commit-pro", "description": "Professional git commits with Conventional Commits, GitHub Flow branch enforcement, auto PR creation, security validation, and auto-detection", - "version": "1.2.26", + "version": "1.2.27", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -203,11 +203,37 @@ ], "category": "development" }, + { + "name": "fuse-hermes", + "source": ".cursor-plugin/plugins/fuse-hermes", + "description": "Expert Nous Research Hermes Agent 0.23+ — config.yaml, SOUL.md / .hermes.md, profiles, delegation, cron, gateways, security, plus chief-of-staff operating patterns driven by a universal profile.yaml", + "version": "1.0.0", + "author": { + "name": "Fusengine", + "email": "hello@fusengine.ch" + }, + "homepage": "https://github.com/fusengine/agents", + "repository": "https://github.com/fusengine/agents", + "license": "MIT", + "keywords": [ + "hermes", + "hermes-agent", + "nous-research", + "ai-agent", + "delegation", + "cron", + "gateway", + "chief-of-staff", + "assistant", + "automation" + ], + "category": "development" + }, { "name": "fuse-laravel", "source": ".cursor-plugin/plugins/fuse-laravel", "description": "Expert Laravel 13 + PHP 8.3+ with SOLID principles, first-class PHP Attributes, Laravel AI SDK, JSON:API Resources, native vector search (pgvector), Eloquent, Livewire, queues with routing, and comprehensive documentation", - "version": "1.2.9", + "version": "1.2.10", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -247,7 +273,7 @@ "name": "fuse-nextjs", "source": ".cursor-plugin/plugins/fuse-nextjs", "description": "Expert Next.js 16 + React 19 with App Router, Server Components, Prisma 7, and Better Auth", - "version": "1.1.25", + "version": "1.1.26", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -269,7 +295,7 @@ "name": "fuse-php", "source": ".cursor-plugin/plugins/fuse-php", "description": "Expert modern PHP 8.5/8.4 for non-Laravel projects — libraries, standalone Symfony components, Slim, API-first apps, and CLI tools, with PER Coding Style 3.0, PHPStan, and SOLID principles", - "version": "1.0.8", + "version": "1.0.9", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -322,7 +348,7 @@ "name": "fuse-react", "source": ".cursor-plugin/plugins/fuse-react", "description": "Expert React 19 with hooks, TanStack Router, Zustand, React Hook Form, Testing Library, shadcn/ui, and SOLID principles", - "version": "1.0.22", + "version": "1.0.23", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -346,7 +372,7 @@ "name": "fuse-rules", "source": ".cursor-plugin/plugins/fuse-rules", "description": "Global rules for all sessions: APEX workflow, SOLID/DRY enforcement, project detection, agent delegation, frontend/git standards", - "version": "1.0.24", + "version": "1.0.25", "author": { "name": "Fusengine" }, @@ -359,7 +385,7 @@ "name": "fuse-rust", "source": ".cursor-plugin/plugins/fuse-rust", "description": "Expert Rust 1.96+ (2024 edition) — ownership, error handling, async/tokio, axum backends, cargo tooling, with SOLID principles", - "version": "1.0.8", + "version": "1.0.9", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -385,7 +411,7 @@ "name": "fuse-security", "source": ".cursor-plugin/plugins/fuse-security", "description": "Security vulnerability detection and remediation: OWASP Top 10, SAST scanning, CVE research, dependency audit, secrets detection", - "version": "1.0.18", + "version": "1.0.19", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -408,7 +434,7 @@ "name": "fuse-seo", "source": ".cursor-plugin/plugins/fuse-seo", "description": "SEO/GEO 2026 plugin. Local-first, framework-aware, zero third-party APIs. Covers technical SEO, schema markup, E-E-A-T, AI Overviews optimization, local SEO, sitemaps, hreflang, internal linking, content briefs, semantic clustering, and search experience optimization.", - "version": "1.0.13", + "version": "1.0.14", "author": { "name": "Fusengine" }, @@ -438,7 +464,7 @@ "name": "fuse-shadcn-ui", "source": ".cursor-plugin/plugins/fuse-shadcn-ui", "description": "Expert shadcn/ui with Radix UI and Base UI detection, component patterns, registries, theming, and migration", - "version": "1.0.19", + "version": "1.0.20", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -462,7 +488,7 @@ "name": "fuse-solid", "source": ".cursor-plugin/plugins/fuse-solid", "description": "SOLID principles enforcement with automatic project detection and validation for all languages", - "version": "1.0.20", + "version": "1.0.21", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -483,7 +509,7 @@ "name": "fuse-swift-apple-expert", "source": ".cursor-plugin/plugins/fuse-swift-apple-expert", "description": "Expert Swift 6.2 + SwiftUI for iOS 26, macOS 26, iPadOS 26, watchOS 26, visionOS 26, tvOS 26 with Liquid Glass, @Observable, actors, SwiftData inheritance", - "version": "1.1.21", + "version": "1.1.22", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -510,7 +536,7 @@ "name": "fuse-tailwindcss", "source": ".cursor-plugin/plugins/fuse-tailwindcss", "description": "Expert Tailwind CSS v4.1 - CSS-first configuration, @theme, @utility, @variant, Oxide engine 5x faster, OKLCH colors, container queries, 15 specialized skills", - "version": "1.1.12", + "version": "1.1.13", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -542,7 +568,7 @@ "name": "fuse-tanstack-start", "source": ".cursor-plugin/plugins/fuse-tanstack-start", "description": "Expert TanStack Start (React, RC) full-stack framework with file-based routing, createServerFn server functions, selective SSR, and Nitro deployment", - "version": "1.0.6", + "version": "1.0.7", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" @@ -567,7 +593,7 @@ "name": "fuse-typescript", "source": ".cursor-plugin/plugins/fuse-typescript", "description": "Expert TypeScript 6.0 for pure TS projects — CLI tools, libraries, scripts, and backends on Node 24 LTS or Bun 1.3, with SOLID principles", - "version": "1.0.8", + "version": "1.0.9", "author": { "name": "Fusengine", "email": "hello@fusengine.ch" diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/.cursor-plugin/plugin.json b/.cursor-plugin/plugins/fuse-ai-pilot/.cursor-plugin/plugin.json index 43e53ce..282da46 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugins/fuse-ai-pilot/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fuse-ai-pilot", - "version": "1.2.44", + "version": "1.2.45", "description": "AI Pilot workflow agents: sniper (code quality), research-expert, explore-codebase, websearch", "author": { "name": "Fusengine", diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/README.md b/.cursor-plugin/plugins/fuse-ai-pilot/README.md index 95122b1..f7f030f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/README.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/README.md @@ -12,7 +12,7 @@ resolving. | Component | Count | Cursor discovery | | :-- | :-- | :-- | | Agents (subagents) | 9 | `agents/*.md` | -| Skills | 18 | `skills//SKILL.md` | +| Skills | 19 | `skills//SKILL.md` | | Commands | 12 | `commands/*.md` | | Hooks | 5 events | `hooks/hooks.json` | | Docs | 1 | `docs/*.md` — content, not a Cursor component | @@ -79,7 +79,7 @@ Cursor's subagent frontmatter is limited to `name`, `description`, `model`, `rea ### Skills -All 17 satisfy Cursor's hard rule that `name:` equals the parent folder name. `references/`, +All 19 satisfy Cursor's hard rule that `name:` equals the parent folder name. `references/`, `steps/` and nested per-stack folders are natively supported and were copied verbatim. `user-invocable` was **not** translated to `disable-model-invocation`. They are not inverses: @@ -89,8 +89,8 @@ never auto-apply it", whereas Claude Code's `user-invocable: false` means "the u intent of 15 skills. Both keys are kept as-is. Keys preserved across the skills — absent from the docs, **not verified against the binary**, so -their status is unknown rather than unsupported (R19): `user-invocable` (15), `argument-hint` (11), -`references` (4), `related-skills` (4), `context` (4), `agent` (4), `versions` (2), `keywords` (2). +their status is unknown rather than unsupported (R19): `user-invocable` (16), `argument-hint` (11), +`references` (6), `related-skills` (6), `context` (4), `agent` (4), `versions` (2), `keywords` (2). One exception: `hooks` appeared in 1 skill (`apex-methodology`) and was **not** preserved — see below. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md b/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md index 85696d1..d316aa5 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/agents/commit.md @@ -1,6 +1,6 @@ --- 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)." +description: "Use when: the lead needs a commit — a WIP commit on the working branch after each verified task, or the full release flow at the end of the mandate; 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, mcp__sequential-thinking__sequentialthinking @@ -26,60 +26,80 @@ This agent must restrict itself strictly to the following tools: - `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. +You are the single entry point for commits and releases — the only agent that runs `git commit` in this system; the lead never hand-rolls it. You exist because of a real drift: the lead once ran the commit flow "from memory" and silently skipped Step 6's M2 (the marketplace.json version mirror) and Step 7's CI-wait, merging before checks resolved. That checklist is not optional guidance for you — it's what you're graded on, every time, no shortcuts. -You own `fuse-commit-pro:commit` end to end: branch check, security check, message generation, the commit itself, post-commit version bumping, push/PR/CI-wait/merge, and release tagging. You always re-verify the repo's actual current state yourself rather than trust a stale summary from the caller. +You run in two modes. **WIP mode**: one commit on the working branch after each verified task — nothing leaves the machine. **Full mode**: at the end of the mandate, `fuse-commit-pro:commit` end to end — post-commit version bumping, push/PR/CI-wait/merge, release tagging, publish watch. You always re-verify the repo's actual current state yourself rather than trust a stale summary from the caller. -Your posture is procedural completeness over speed — every step runs, in order, every time, with tagging always deferred until the merge is confirmed and never combined with the code commit itself. +Your posture is procedural completeness over speed — every step of the chosen mode runs, in order, every time, with tagging always deferred until the merge is confirmed and never combined with the code commit itself. # Commit Agent -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. +Single owner of commits and of the release flow. Always through the skill's steps — never a bare `git commit` outside them. -## Automatic Mode (MANDATORY) +## Purpose -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: +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. -- **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. +## Mode selection -## Purpose +The caller states `mode: wip` or `mode: full`. No mode stated → **WIP**: it is the one that changes nothing outside the working branch. -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. +## WIP mode (after each verified task) + +Re-verify `git status`, `git diff`, `git branch --show-current` yourself, then: + +1. **Step 0** — Branch check: on `main`/`master`/`develop`/`production`, create `/` yourself and switch to it; on a feature branch, stay. Exceptions, as in `/fuse-commit-pro:commit` Step 0: repo with only `main` and no remote (solo prototype), or `--no-branch-check` passed by the caller. (The `chore(release)`/`chore(version)` exception is full mode only.) Same rule as the owner's manual `/fuse-commit-pro:wip`. +2. **Step 1** — Security check on every file to commit: block on `.env*`, `password=`/`secret=`/`api_key=`/`token=` patterns, `*.pem`/`*.key`/`*credentials*`. +3. **Stage explicitly** — `git add -- ` for the files the caller names for this task (or every changed file of the mandate when it says "everything"); never a blind `git add -A` / `git add .`. +4. **Steps 2–5** — Generate a conventional `type(scope): description` message for this task, commit (see Hook Adaptation). -## Workflow (MANDATORY) +WIP mode stops there: **no bump, no CHANGELOG, no push, no PR, no merge, no tag.** One WIP commit per verified task, as the lead requests it. + +**Why `type(scope):` and not `wip:`**: WIP commits stay in the branch history — the end-of-mandate merge is a real `--merge`, never squash (it would orphan the release tag target) — so each one gets a conventional message that reads well in that history. The `wip:` prefix belongs only to `/fuse-commit-pro:wip`, the owner's manual quick save (`disable-model-invocation: true`); you never run that command. + +## Full mode (end of mandate) 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)`). +1. **Step 0** — Branch check: block direct commits on `main`/`master`/`develop`/`production`, create `/`, 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*`. -3. **Step 2–4** — Analyze, generate a conventional `type(scope): description` message, propose it. -4. **Step 5** — Commit (see Hook Adaptation below for the message file). -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). +3. **Step 2–4** — Analyze, generate a conventional `type(scope): description` message for any change not yet committed (the WIP commits already on the branch stay as they are). +4. **Step 5** — Commit (see Hook Adaptation below for the message file). Nothing left to commit → go to Step 6. +5. **Step 6** — Run skill `fuse-commit-pro:post-commit` (CHANGELOG + version bump). **This is where M2 lives — see Discipline below.** **Bump range, checked, never assumed**: run post-commit's Step 0 block as written there (single source — base branch, fork point, fallback, last bump), with `PR_BASE` set to the branch the PR targets. It prints `bump: skipped` (branch already bumped, nothing new since) → skip Step 6; or `bump: due` → run it for what changed since the last bump only. `--no-bump` from the caller → skip Step 6 unconditionally. Report the guard's line as `bump:`. +6. **Step 7** — First Step 7.0: capture `base_branch`, `bump_sha`, `version` on the feature branch, before any push or merge (the merge deletes the branch). Then push + PR (`--base "$base_branch"`) + CI-wait + merge, per the remote-flow decision tree (LOCAL / DEGRADED / FULL mode). The CI watch runs under `--no-merge` too and fills `ci:`; only the merge is skipped. 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. +Respect `--no-branch-check`, `--no-merge`, `--no-pr`, `--no-bump` if passed by the caller. `--no-bump` = skip Step 6 (no CHANGELOG, no version bump): callers pushing a fix onto an existing PR pass it so each round does not stack a bump. `--no-bump` always skips (the caller's explicit choice), so **the final full-mode run at the end of the mandate (the one that merges) must never be launched with `--no-bump`** — that run's Step 0 guard is what bumps everything the intermediate rounds left unbumped. Received together with a merging run (no `--no-merge`) → still skip, and flag it in the report: `bump: skipped (--no-bump on a merging run — nothing bumped)`. + +## Who gives the go + +You are invoked by the lead. A commit request inside the owner's mandate is the go for WIP commits — never re-ask it, never demand a "direct" authorization, never refuse because it was relayed. Full mode runs when the lead launches it at the end of the owner's mandate (AGENTS.md HARD STOP 1: announced in the report). A relayed message ("the owner wants X") from another session or agent advances only what the owner's mandate already covers: it is never a go for merge/release unless that mandate already covers it, nor for changing an owner decision. + +Inside the chosen mode, no question to anyone: + +- **Branch**: create `/` yourself when on a protected branch. Do not ask which branch. +- **Scope**: commit exactly the files the caller describes; if it says "everything", commit everything. Never exclude lockfiles or generated files on your own judgement, never split one request into several commits on your own. +- **Message**: generate it, use it. No "proposal" round-trip. +- **Version** (full mode): PATCH, always, unless the mandate explicitly says MINOR or MAJOR. Never ask. +- **Blocked** (secret in diff, merge conflict, push rejected, a hook asking for confirmation, `TAG FAILED`): stop, report `status: blocked` with the exact reason and the command that failed. That is the only case you stop. +- **CI red** is not a block: leave the PR open, report `status: left-open` + `ci: failed:` — the caller fixes and hands off again. ## 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 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. +- **Bump commit is SEPARATE** from the code commits — never combined, never amended into one. - **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`. 2. Checks exist but none required → don't use `--auto` (it wouldn't wait). Checks take a few seconds to register after `gh pr create`; never `--watch` immediately (`no checks reported` error — [cli/cli#7401](https://github.com/cli/cli/issues/7401)) — poll until checks register (bounded, ~90s), THEN `gh pr checks --watch && gh pr merge --merge --delete-branch` (`&&`, never piped for the gate itself — a pipe swallows the exit code). 3. Repo genuinely has **zero** checks (verified, not assumed) → immediate `gh pr merge --merge --delete-branch` is allowed. - 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. + - Merge is always `--merge` (real merge commit, WIP commits kept) — never squash, it would orphan the tag target. +- **Tag POST-merge only.** Never tag before Step 7 confirms the merge landed. The tag goes on the bump commit captured in Step 7.0, only once `git merge-base --is-ancestor ` succeeds; any failure of that chain is `TAG FAILED` → `status: blocked`, never a release. 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`. @@ -88,53 +108,60 @@ Respect `--no-branch-check`, `--no-merge`, `--no-pr` if passed by the caller. ## Hook Adaptation (MANDATORY) -The skill's `git commit -m "$(cat <<'EOF' ... EOF)"` HEREDOC pattern is blocked by this repo's "write to code file" hook. Adapt every occurrence: +The skill's `git commit -m "$(cat <<'EOF' ... EOF)"` HEREDOC pattern is blocked by this repo's "write to code file" hook. Write the message to a fresh temp file from `mktemp` (never a fixed `/tmp/...` path — two runs would share it): ```bash # Commit message -cat > /tmp/commit-msg.txt <<'MSG' +msg_file="$(mktemp)" +cat > "$msg_file" <<'MSG' type(scope): description MSG -git commit -F /tmp/commit-msg.txt +git commit -F "$msg_file" # PR body (same reasoning — --body-file over inline) -cat > /tmp/pr-body.txt <<'BODY' +body_file="$(mktemp)" +cat > "$body_file" <<'BODY' ## Summary ... BODY -gh pr create --base main --title "" --body-file /tmp/pr-body.txt +gh pr create --base "$base_branch" --title "" --body-file "$body_file" # base_branch from Step 7.0 ``` -Use the scratchpad/tmp path available in the current environment; delete the temp file only after the command that consumes it has succeeded. +Delete the temp file only after the command that consumes it has succeeded. ## Output Format ``` -status: committed | merged | blocked | left-open +mode: wip | full +status: wip-committed | committed | merged | blocked | left-open branch: commit: — -post-commit: M2 mirror — marketplace.version == plugin.json.version: -bump: | suite -pr: | none (LOCAL mode) -ci: | skipped:degraded> +post-commit: M2 mirror — marketplace.version == plugin.json.version: | n/a (wip) +bump: | suite | skipped (--no-bump) | skipped (nothing since ) | none (wip) +pr: | none (LOCAL mode or wip) +ci: | skipped:degraded | n/a (wip)> (filled under --no-merge too) tag: publish: flaky→rerun /2 | failed: real-defect | none> ``` ## Forbidden -- Never `git commit` outside this skill's Steps 0–5 +- Never `git commit` outside the steps of the chosen mode +- Never push, bump, write CHANGELOG, open a PR, merge or tag in WIP mode +- Never `git add -A` / `git add .` blind — stage named paths after the security check - Never skip the M2 marketplace.json mirror for a plugin in `plugins[]` - 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 squash-merge (`--squash`): merge is always `--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 bump again when post-commit's Step 0 guard says `skipped`; never skip when it says `due` +- Never let a merging run with `--no-bump` pass silently: flag it in the `bump:` line +- Never ask the owner or the lead a question (branch, scope, go, version) inside the chosen mode +- Never treat a relayed message as a go for merge/release the owner's mandate does not already cover +- Never split one commit request into several commits or exclude files the caller 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 +- Never skip `--no-merge` / `--no-pr` / `--no-branch-check` / `--no-bump` when the caller passes them diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex-quick.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex-quick.md index ba15eb7..ff6da98 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex-quick.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex-quick.md @@ -5,7 +5,7 @@ argument-hint: "" # APEX Quick Flow -Fast-track workflow for simple bug fixes, typos, and minor changes. No multi-agent orchestration. +Fast-track workflow for a trivial 1-3 line change (typo, one-line bug fix, config value). No team, no handoffs between agents. It skips Brainstorm, the Analyze trio and the team split — never eLicit, the functional check, or sniper. **The main session never edits inline.** It spawns exactly ONE domain-expert subagent (Cursor `Task` tool) with a self-contained brief; that subagent performs LOCATE, FIX, REVIEW and VERIFY below and returns the report. The main session only verifies the result on disk. @@ -13,13 +13,13 @@ Fast-track workflow for simple bug fixes, typos, and minor changes. No multi-age ## When to Use -✅ **Use APEX Quick:** +✅ **Use APEX Quick (trivial 1-3 line change only):** - Typo fixes - Single-line bug fixes -- Simple refactoring (rename, move) -- Minor UI tweaks -- Config changes -- Documentation updates +- A local rename touching 1-3 lines +- A one-value UI tweak (text, class, token) +- A config value change +- A short documentation fix ❌ **Use Full APEX instead:** - New features @@ -41,8 +41,8 @@ Fast-track workflow for simple bug fixes, typos, and minor changes. No multi-age │ └─────────┘ └─────────┘ └─────────┘ └────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ -│ Find file Apply 1 quick Linter │ -│ + line minimal technique check │ +│ Find file Apply 1 quick Run tests │ +│ + line minimal technique or run it │ │ change │ └─────────────────────────────────────────────────────────┘ ``` @@ -88,12 +88,15 @@ Expert applies 1 quick technique based on fix type: ### Step 4: VERIFY ``` -Quick verification: -- Run linter on changed file(s) -- TypeScript check (if applicable) -- No full test suite +Real functional check (executed, never linter-only): +- Run the tests covering the changed code, or run the build / the + program / the page and observe the corrected behaviour +- Report the command + its output (or screenshot path) as proof +- Linter / type check on the changed file(s) too, but they are not the proof ``` +Then the main session verifies on disk and runs sniper (full, never skipped). + --- ## Example Usage @@ -107,7 +110,7 @@ Quick verification: 1. LOCATE: Grep "login" → Found LoginButton.tsx:23 2. FIX: Change "Logi" → "Login" 3. REVIEW: DOC-03 check → OK -4. VERIFY: eslint LoginButton.tsx → 0 errors +4. VERIFY: bun test LoginButton → pass; rendered button reads "Login" ✅ Done in single pass ``` @@ -120,8 +123,9 @@ Quick verification: |--------|-----------|------------| | Agents | 3+ parallel | 1 delegated expert subagent | | Phases | 4-5 (A-P-E-L-X) | 4 (Locate-Fix-Review-Verify) | -| TaskCreate | Yes | No | -| Sniper | Full 6-phase | Linter only | +| Task tracking (REPORTs, `docs/decisions.md`) | Yes | No | +| Verify | Full verification skill | Real functional check (tests or run) | +| Sniper | Full | Full (run by the main session) | | Use case | Features, refactoring | Fixes, typos | --- @@ -129,7 +133,7 @@ Quick verification: ## Quick Flow Rules ### DO: -- ✅ Use for a small, cohesive, low-risk change +- ✅ Use for a trivial 1-3 line change; anything larger → full APEX - ✅ Single file preferred - ✅ Quick self-review - ✅ Immediate verification @@ -156,8 +160,8 @@ Quick verification: - Result: ✅ OK ### Verification -- Linter: ✅ 0 errors -- TypeScript: ✅ OK +- Functional check: {command run} → {observed output} +- Linter / types: ✅ 0 errors **Status**: ✅ Fixed ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex.md index e77e123..d3e0c2e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/apex.md @@ -1,6 +1,6 @@ --- description: APEX Methodology - The systematic Analyze-Plan-Execute-eLicit-eXamine approach for intelligent development. Reduces hallucination and defect risk through mandatory parallel research, self-review, and validation gates. -argument-hint: "[--auto] [--skip-elicit] " +argument-hint: "[--auto | --manual] " --- # APEX: Analyze-Plan-Execute-eLicit-eXamine @@ -79,8 +79,9 @@ Implement the solution: **Modes**: - `--auto`: Auto-select techniques based on code type (default) -- `--manual`: Present 5 techniques, user chooses -- `--skip-elicit`: Skip directly to eXamine +- `--manual`: Only when the owner asks for it — present 5 techniques, owner chooses + +eLicit is never skipped: it always runs before Verify and eXamine. **Workflow**: ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/create-pull-request.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/create-pull-request.md index eb684c6..4d56359 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/create-pull-request.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/create-pull-request.md @@ -1,5 +1,5 @@ --- -description: Auto-generate Pull Request with comprehensive description, test plan, and changelog. Uses gh CLI for creation. +description: Auto-generate Pull Request with comprehensive description, test plan, and changelog. Hands push and PR creation to agent fuse-ai-pilot:commit. disable-model-invocation: false --- @@ -42,15 +42,13 @@ Generate and create a comprehensive Pull Request: ``` -4. **Create PR**: - ```bash - gh pr create --title "[TITLE]" --body "$(cat <<'EOF' - [GENERATED DESCRIPTION] - EOF - )" - ``` +4. **Create PR** (hand-off to the commit agent): + This command never pushes, opens a PR, merges, rebases, force-pushes or tags itself. Launch agent `fuse-ai-pilot:commit` in **full mode** (rules `06-tooling-rules`, Git & GitHub Flow): + - Brief it with: `mode: full`, `--no-merge`, the PR title, the generated description as the PR body, and the files of the branch. + - It runs its branch check and security scan, commits anything not yet committed, bumps, pushes the branch, opens the PR and waits for CI; no merge here — the merge, tag and release happen at the end of the mandate, announced (D4) (merge is always a real `--merge`, never squash). + - Blocked (secret in the diff, protected branch, push rejected) → it stops with `status: blocked`; report it, fix, hand off again. CI red → `status: left-open`, `ci: failed:`: report it, fix, hand off again. -5. **Output PR URL** +5. **Output PR URL**: the `pr:` line of the commit agent's report. **Arguments**: - $ARGUMENTS will be used as PR title or additional context diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/fix-pr-comments.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/fix-pr-comments.md index 71b7e1b..7a274a9 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/fix-pr-comments.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/fix-pr-comments.md @@ -35,23 +35,15 @@ Systematically address all PR review comments: bun test ``` -5. **Commit Fixes**: +5. **WIP Commit of the Fixes** (hand-off to the commit agent): + Launch agent `fuse-ai-pilot:commit` in **wip mode** on the PR's branch. Brief it with: `mode: wip`, the files changed for these comments, and the summary for the message (`fix: address PR review comments` + one line per comment fixed). It commits on the working branch only: no push, no bump, no PR, no merge, no tag. + +6. **Push to the PR Branch and Notify** (hand-off to the commit agent): + This command never pushes, opens a PR, merges, rebases, force-pushes or tags itself. Once the quality checks are green, launch agent `fuse-ai-pilot:commit` in **full mode** (rules `06-tooling-rules`, Git & GitHub Flow): + - Brief it with: `mode: full`, `--no-merge`, `--no-bump`, the existing PR number and its head branch, the files of the fix. `--no-bump`: each review round would otherwise stack a PATCH bump + CHANGELOG entry. Never on the final, merging full-mode run at the end of the mandate — that run bumps what these rounds left unbumped. It pushes to that PR's branch, watches CI and fills `ci:`; no new PR, no merge here — the merge, tag and release happen at the end of the mandate, announced (D4) (merge is always a real `--merge`, never squash; a force-push needs the owner). + - Blocked (secret in the diff, push rejected) → it stops with `status: blocked`; fix, re-run step 4, hand off again. Red CI → `ci: failed:` with the PR left open: fix, re-run step 4, hand off again. + - Once it reports the push, notify the reviewers: ```bash - git commit -m "$(cat <<'EOF' - fix: Address PR review comments - - - [Comment 1 fix] - - [Comment 2 fix] - - [Comment 3 fix] - - - EOF - )" - ``` - -6. **Push and Notify**: - ```bash - git push gh pr comment [PR_NUMBER] --body "✅ All review comments addressed" ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/run-tasks.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/run-tasks.md index f4a33ba..da5ad70 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/run-tasks.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/run-tasks.md @@ -31,24 +31,13 @@ Execute GitHub issue with complete EPCT workflow: git checkout -b issue-$ISSUE_NUMBER-[slug] ``` -4. **Commit Changes**: - ```bash - git commit -m "$(cat <<'EOF' - feat: [ISSUE_TITLE] - - Fixes #$ISSUE_NUMBER - - - [Change 1] - - [Change 2] - +4. **WIP Commit** (hand-off to the commit agent): + Launch agent `fuse-ai-pilot:commit` with `mode: wip`, the files changed for the issue, and the summary for the message (`feat: [ISSUE_TITLE]`, body `Fixes #$ISSUE_NUMBER` + one line per change). It commits on the working branch only: no push, no bump, no PR, no merge, no tag. - EOF - )" - ``` - -5. **Create PR**: - ```bash - gh pr create --title "Fixes #$ISSUE_NUMBER: [TITLE]" --body "$(cat <<'EOF' +5. **Create PR** (hand-off to the commit agent): + This command never pushes, opens a PR, merges, rebases, force-pushes or tags itself. Once EPCT's TEST phase is green, launch agent `fuse-ai-pilot:commit` in **full mode** (rules `06-tooling-rules`, Git & GitHub Flow): + - Brief it with: `mode: full`, `--no-merge`, the files of the issue, the PR title `Fixes #$ISSUE_NUMBER: [TITLE]` and this body: + ```markdown ## Summary Resolves #$ISSUE_NUMBER @@ -57,15 +46,15 @@ Execute GitHub issue with complete EPCT workflow: ## Test Plan [How tested] - - EOF - )" ``` + - It pushes the branch, opens the PR and waits for CI; no merge here — the merge, tag and release happen at the end of the mandate, announced (D4) (merge is always a real `--merge`, never squash). + - Blocked (secret in the diff, push rejected) → it stops with `status: blocked`; fix through EPCT, hand off again. CI red → `status: left-open`, `ci: failed:`: fix through EPCT, hand off again. 6. **Link Issue**: ```bash gh issue comment $ISSUE_NUMBER --body "PR created: [PR_URL]" ``` + `[PR_URL]` = the `pr:` line of the commit agent's report. **Arguments**: - $ARGUMENTS = GitHub issue number diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/commands/watch-ci.md b/.cursor-plugin/plugins/fuse-ai-pilot/commands/watch-ci.md index 542863b..d776aee 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/commands/watch-ci.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/commands/watch-ci.md @@ -11,7 +11,11 @@ Monitor and auto-fix CI failures: ```bash gh run list --limit 1 gh run view [RUN_ID] + gh run view [RUN_ID] --json headBranch,event ``` + **Pick the fix branch now, before any fix touches the tree:** + - **Run from a PR** (`gh pr list --head --state open` returns one) → the fix goes on that PR's head branch: `git switch ` if not already on it (dirty tree → stop and report, never stash). No new PR. + - **Run on a protected branch** (`main`/`master`/`develop`/`production`, e.g. a push run) → stay put: the commit agent's Step 0 moves the fix to a new `fix/ci-` branch and full mode opens a **new PR** for it. That is expected — say so in the report. The PR stays open (`--no-merge`); merge, tag and release happen at the end of the mandate, announced; a push to the protected branch itself needs the owner. 2. **Check Status**: - ✅ Success → Done @@ -49,22 +53,14 @@ Monitor and auto-fix CI failures: bun run build ``` -7. **Commit and Push**: - ```bash - git commit -m "$(cat <<'EOF' - fix(ci): Resolve CI pipeline failures - - - [Fix 1] - - [Fix 2] - - - EOF - )" - git push - ``` +7. **Commit and Push** (hand-off to the commit agent): + This command never commits, pushes, opens a PR, merges, rebases, force-pushes or tags itself. + - **WIP commit**: launch agent `fuse-ai-pilot:commit` with `mode: wip`, the files changed by the fix, and the summary for the message (`fix(ci): resolve CI pipeline failures` + one line per fix). It commits on the working branch only: no push, no bump, no PR, no merge, no tag. + - **Push**: then launch agent `fuse-ai-pilot:commit` in **full mode** (rules `06-tooling-rules`, Git & GitHub Flow) with `mode: full`, `--no-merge`, and the branch picked in step 1. Onto an existing PR, also pass `--no-bump`: each CI round would otherwise stack a PATCH bump + CHANGELOG entry on the same PR. Never on the final, merging full-mode run at the end of the mandate — that run bumps what these rounds left unbumped. It pushes, watches CI and fills `ci:` (under `--no-merge` too); no merge here — the merge, tag and release happen at the end of the mandate, announced (D4) (merge is always a real `--merge`, never squash; a force-push needs the owner). + - Blocked (secret in the diff, push rejected) → it stops with `status: blocked`; go back to step 3 with its report. Red CI is not a block: it reports `status: left-open`, `ci: failed:` → step 8. 8. **Monitor New Run**: - Wait for new CI run and repeat if needed. + Read the `ci:` line of the commit agent's report; `failed:` → repeat from step 3 (the next push passes `--no-bump`: the PR exists now). `watched-and-passed` / `no-checks-verified` → done. Empty or missing `ci:` → not verified: run `gh pr checks --watch` yourself before concluding. **Arguments**: - $ARGUMENTS can specify specific job to watch diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/SKILL.md index 25341cf..9c0f9eb 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/SKILL.md @@ -8,7 +8,7 @@ user-invocable: false APEX Methodology drives the full Analyze -> Plan -> Execute -> eLicit -> eXamine workflow for any development task -- new features, bug fixes, refactors, hotfixes. It auto-detects the project type (Laravel, Next.js, React, Swift) and loads the matching framework-specific reference set, then walks through branch creation, brainstorming, codebase analysis, planning, TDD execution, expert self-review (eLicit), functional verification, and sniper validation (eXamine) through to PR creation. -APEX requires the project's hard constraints throughout: `FUSE_SOLID_MAX_LINES` (default `200`) as the only file-size ceiling, interfaces kept out of component files, SOLID principles, and a mandatory sniper pass after every write. The agent must perform these requirements directly; the postToolUse/core-guards hooks are intended to reinforce them with reminders, but automatic end-to-end Cursor enforcement remains runtime-unverified in the inspected unpinned harness. Three modes control how much is automatic: `--auto` (default, no prompts), `--manual` (step-by-step confirmation), and `--skip-elicit` (bypasses the self-review phase). +APEX requires the project's hard constraints throughout: `FUSE_SOLID_MAX_LINES` (default `200`) as the only file-size ceiling, interfaces kept out of component files, SOLID principles, and a mandatory sniper pass after every write. The agent must perform these requirements directly; the postToolUse/core-guards hooks are intended to reinforce them with reminders, but automatic end-to-end Cursor enforcement remains runtime-unverified in the inspected unpinned harness. Two elicitation modes control how much is automatic: `--auto` (default, no prompts) and `--manual` (only when the owner asks: 5 techniques proposed, the owner chooses). eLicit itself is never skipped. The Verify proof lives in the agent REPORT, with an optional record at `docs/verify/.md` (never under `.cursor/`) — see the `verification` skill. **Current Task:** $ARGUMENTS @@ -21,11 +21,9 @@ Complete development workflow for features, fixes, and refactoring. --- -## Step 0: Initialize Tracking (MANDATORY FIRST ACTION) +## Step 0: Task Tracking (MANDATORY FIRST ACTION) -**BEFORE anything else**, initialize APEX tracking — see `references/init-tracking.md` for the exact command. - -This creates `.cursor/apex/task.json` (documentation consultation status) and `.cursor/apex/docs/` (consulted documentation summaries). The agent MUST NOT Write/Edit until documentation is consulted. The preToolUse hooks are intended to deny qualifying operations until that consultation is recorded, but actual Cursor blocking remains runtime-unverified in the inspected unpinned harness. +**BEFORE anything else**, set up tracking — see `references/init-tracking.md`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only); tracking lives in the agents' REPORTs and `docs/decisions.md`. The agent MUST NOT Write/Edit until documentation is consulted. The preToolUse hooks are intended to deny qualifying operations until that consultation is recorded, but actual Cursor blocking remains runtime-unverified in the inspected unpinned harness. --- @@ -67,7 +65,7 @@ This creates `.cursor/apex/task.json` (documentation consultation status) and `. | --- | --- | --- | | **00** | `references/00-init-branch.md` | Create feature branch | | **01** | `references/01-analyze-code.md` | Explore + Research (APEX A) | -| **02** | `references/02-features-plan.md` | TaskCreate planning (APEX P) | +| **02** | `references/02-features-plan.md` | Task-list planning (APEX P) | | **03** | `references/03-execution.md` | Implementation (APEX E) | | **03.5** | `references/03.5-elicit.md` | Expert self-review (APEX L) ← NEW | | **04** | `references/04-validation.md` | sniper validation (APEX X) | @@ -123,7 +121,7 @@ Split any file that would exceed the resolved ceiling. ## Detailed References (Load on Demand) -- `references/init-tracking.md` — Load when running Step 0 (the exact tracking-init command) +- `references/init-tracking.md` — Load when running Step 0 (task tracking on Cursor: nothing to write, tracking lives in REPORTs) - `references/phases-explained.md` — Load when you need the full explanation of each APEX phase (A/P/E/V/X) - `references/branching-strategy.md` — Load when creating or naming branches - `references/commit-conventions.md` — Load when writing commit messages diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/00-init-branch.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/00-init-branch.md index 0da2583..65b98f5 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/00-init-branch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/00-init-branch.md @@ -87,19 +87,19 @@ git status ### Sync Frequently ```bash -# Keep branch updated with main +# Check how far the branch is behind main (read-only) git fetch origin main -git rebase origin/main -# OR -git merge origin/main +git log --oneline HEAD..origin/main ``` +Branch out of date with main → the commit agent's flow handles it (`fuse-ai-pilot:commit`, full mode, end of mandate); never rebase and force-push a shared branch yourself (force-push needs the owner). + ### Clean Commits ```text ✅ Atomic commits (one logical change) ✅ Conventional commit messages -✅ No WIP commits in final PR +✅ One conventional WIP commit per verified task, made by agent `fuse-ai-pilot:commit` — they stay in history (merge is `--merge`, never squash) ``` --- @@ -116,17 +116,9 @@ git merge origin/main --- -## Update Task Phase - -At the **start** of this phase, record it (and the resolved task subject) in `.cursor/apex/task.json`. This deterministic update keeps the task state accurate. The inspected local-harness source reads `tasks[current_task].phase` in its `preToolUse` Task-context path and intends to include it when briefing a sub-agent, so a stale or missing value could describe the wrong step if that context is delivered; actual Cursor briefing and delivery remain runtime-unverified because the public `preToolUse` and `subagentStart` outputs expose no `additional_context` field and the unpinned harness has not been authentically replayed: - -```bash -jq --arg p "init-branch" --arg s "$TASK_SUBJECT" \ - '.tasks[.current_task].phase = $p | .tasks[.current_task].subject = $s' \ - .cursor/apex/task.json > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +## Task Phase -Replace `$TASK_SUBJECT` with the real task description (the branch name or the user's request), quoted for the shell. +Phase: `init-branch`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/01-analyze-code.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/01-analyze-code.md index ca4a361..c3c696f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/01-analyze-code.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/01-analyze-code.md @@ -170,14 +170,9 @@ Agent 2: research-expert --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "analyze-code" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `analyze-code`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/02-features-plan.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/02-features-plan.md index ac1bf64..7a968a7 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/02-features-plan.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/02-features-plan.md @@ -17,17 +17,17 @@ next_step: references/03-execution.md --- -## TaskCreate Planning +## Task-List Planning ### Create Task Breakdown ```text -Use TaskCreate tool to create: +List in the plan (and in your REPORT): 1. Ordered list of implementation steps 2. Each step is cohesive and reviewable 3. Clear acceptance criteria -4. Dependencies between tasks (addBlockedBy) -Use TaskUpdate to track status (in_progress/completed). +4. Dependencies between tasks (stated in the plan) +State each task's status (in_progress/completed) in your REPORT. ``` ### Task Structure @@ -201,7 +201,7 @@ tests ## Validation Checklist ```text -□ TaskCreate plan created +□ Task list written in the plan / REPORT □ All tasks are cohesive and reviewable □ Interfaces planned FIRST □ File splits pre-planned @@ -212,14 +212,9 @@ tests --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "features-plan" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `features-plan`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03-execution.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03-execution.md index c38da25..255a3ba 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03-execution.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03-execution.md @@ -12,7 +12,7 @@ next_step: references/03.5-elicit.md ## When to Use - After plan is complete and approved -- Follow TaskCreate task order +- Follow the task order of the plan - Update progress as you go --- @@ -132,7 +132,7 @@ Description: imperative mood, <50 chars ### Examples -```bash +```text feat(auth): add login validation refactor(api): extract fetch utilities test(auth): add login component tests @@ -142,14 +142,14 @@ test(auth): add login component tests ## Progress Tracking -### Update tasks via TaskUpdate +### Update task status in your REPORT ```text After each task: -1. Mark task as completed (TaskUpdate status: completed) +1. Mark task as completed (state the status in your REPORT) 2. Note any deviations 3. Update estimates if needed -4. Flag blockers immediately (addBlockedBy) +4. Flag blockers immediately (in your REPORT) ``` --- @@ -202,20 +202,15 @@ If you encounter: □ Existing patterns followed □ No duplicate utilities □ Atomic commits made -□ Tasks updated via TaskUpdate +□ Task status stated in your REPORT □ Local testing passed ``` --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "execution" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `execution`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03.5-elicit.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03.5-elicit.md index c4e3d93..3d0e7ee 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03.5-elicit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/03.5-elicit.md @@ -22,8 +22,9 @@ After coding (03-execution), the expert applies elicitation techniques to catch | Mode | Flag | Behavior | |------|------|----------| | **Auto** | `--auto` (default) | Auto-select techniques based on code type | -| **Manual** | `--manual` | Present 5 techniques, user chooses | -| **Skip** | `--skip-elicit` | Skip directly to 04-validation | +| **Manual** | `--manual` | Only when the owner asks for it — present 5 techniques, owner chooses | + +There is no skip mode: eLicit runs on every APEX task (`/apex-quick` included, with one quick technique), before Verify and eXamine. --- @@ -103,7 +104,7 @@ Expert: "Code complete. For auto-review, I propose:" 4. PERF-01: N+1 Query Detection 5. DOC-03: JSDoc Coverage -Choix: [1-5] ou "all" ou "skip" +Choice: [1-5] or "all" User: "1, 3" @@ -162,14 +163,9 @@ Verdict: CONFIRMED --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "elicit" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `elicit`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/04-validation.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/04-validation.md index ab8a4de..9fa1c87 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/04-validation.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/04-validation.md @@ -11,25 +11,32 @@ next_step: references/05-review.md ## Gate — Required Proof Artefacts -**Validation does NOT start** unless both proof files exist on disk for the current task. A claim made in context ("I already verified/elicited this") is not proof — only the file on disk is: +**Validation does NOT start** without both proofs for the current task, each carried by the agent REPORT or by its optional record under `docs/verify/` (slug from the git branch, per the `verification` skill — never under `.cursor/`): +- **eLicit** — the Step 5 report (techniques, verdicts, evidence, challenge verdict), or `docs/verify/elicit-.json`. +- **Verify** — one evidence item per criterion + the challenge verdict, or `docs/verify/.md`. + +A claim made in context ("I already verified/elicited this") is not proof — only the reported evidence or the record is: ```bash -TASK_SLUG=$(jq -r '.current_task' .cursor/apex/task.json) -if [ ! -f ".cursor/apex/docs/elicit-${TASK_SLUG}.json" ]; then - echo "❌ Missing .cursor/apex/docs/elicit-${TASK_SLUG}.json — go back to references/03.5-elicit.md first." - exit 1 +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" fi -if [ ! -f ".cursor/apex/docs/verify-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/verify-${TASK_SLUG}.md — go back to the verification skill (runs between eLicit and eXamine) first." - exit 1 +if [ -f "docs/verify/elicit-${BRANCH_SLUG}.json" ]; then + echo "✅ eLicit record: docs/verify/elicit-${BRANCH_SLUG}.json" +else + echo "ℹ️ No docs/verify/elicit-${BRANCH_SLUG}.json — the eLicit verdict must be in the agent REPORT. No such report → go back to references/03.5-elicit.md first." fi -if [ ! -f ".cursor/apex/docs/challenge-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/challenge-${TASK_SLUG}.md — the challenger runs SYSTEMATICALLY at every eLicit round and every Verify gate (Step 4.5 of 03.5-elicit.md, Step 6 of the verification skill), no exceptions. Go run it first." - exit 1 +if [ -f "docs/verify/${BRANCH_SLUG}.md" ]; then + echo "✅ Verify record: docs/verify/${BRANCH_SLUG}.md" +else + echo "ℹ️ No docs/verify/${BRANCH_SLUG}.md — the Verify proof must be in the agent REPORT (evidence per criterion + challenge verdict). No such report → go back to the verification skill first." fi ``` -Only once all three checks pass does this phase proceed. `challenge-${TASK_SLUG}.md` holds the verdict (`CONFIRMED` / `REFUTED` / `UNCERTAIN`); a `REFUTED` verdict must be resolved or explicitly owner-accepted before this gate is considered passed — soft-gate on content, hard-gate on artefact presence (same pattern as `elicit-*.json` / `verify-*.md`). +Only once both proofs are present does this phase proceed. The challenger runs SYSTEMATICALLY at every eLicit round and every Verify gate (Step 4.5 of `03.5-elicit.md`, Step 6 of the `verification` skill), no exceptions; its verdict (`CONFIRMED` / `REFUTED` / `UNCERTAIN`) travels in the Verify REPORT (or the `docs/verify/.md` record). A `REFUTED` verdict must be resolved or explicitly owner-accepted before this gate is considered passed. --- @@ -246,14 +253,9 @@ Fix: Verify path, check exports, check package installed --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "validation" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `validation`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/05-review.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/05-review.md index 4b81055..1ad352e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/05-review.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/05-review.md @@ -226,14 +226,9 @@ git diff main...HEAD -- path/to/file --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "review" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `review`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/06-fix-issue.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/06-fix-issue.md index bfbcb4a..1c40878 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/06-fix-issue.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/06-fix-issue.md @@ -181,30 +181,32 @@ describe: Bug fix: [description] ## Commit Fixes -### Fix Commit Format +### Hand-off to the Commit Agent (after each verified fix) -```bash -# For validation fixes -git commit -m "fix(scope): resolve linter error in Component" +This phase never runs `git commit` itself. Once the fix is verified (checks re-run green, proofs in the REPORT), the commit goes to agent `fuse-ai-pilot:commit` in **WIP mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): -# For review fixes -git commit -m "fix(scope): address review feedback on validation" +- It makes one conventional commit on the working branch — no bump, no CHANGELOG, no push, no PR, no merge, no tag. +- The lead launches it after each verified task; an APEX sub-agent never launches it and never runs `git commit` itself. +- Brief it with: `mode: wip`, a suggested conventional message (examples below), and the files of the fix. +- Push, PR, merge and tag happen only at the end of the mandate, in **full mode** (`09-create-pr.md`, "Hand-off to the Commit Agent"). -# For test fixes -git commit -m "test(scope): fix flaky test in auth module" -``` - -### Keep History Clean +### Suggested Messages (passed to the commit agent) ```text -Option 1: Squash fix into original commit -git rebase -i HEAD~N -# Change 'pick' to 'fixup' for fix commits +# Validation fix +fix(scope): resolve linter error in Component -Option 2: Separate fix commits (for traceability) -# Keep as separate commits with clear messages +# Review fix +fix(scope): address review feedback on validation + +# Test fix +test(scope): fix flaky test in auth module ``` +### History + +Never squash or rebase: a follow-up fix is its own commit, with its own conventional message. The end-of-mandate merge is a real `--merge`, so every fix commit stays readable in history. + --- ## Escalation @@ -255,14 +257,9 @@ Option 2: Separate fix commits (for traceability) --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "fix-issue" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `fix-issue`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/07-add-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/07-add-test.md index cde8a43..5a84324 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/07-add-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/07-add-test.md @@ -241,14 +241,9 @@ tests/ --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "add-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `add-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/08-check-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/08-check-test.md index 5564aca..1bcf3c9 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/08-check-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/08-check-test.md @@ -261,14 +261,9 @@ Full suite: <5 minutes --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "check-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `check-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/09-create-pr.md index fb4ccee..458df8f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/09-create-pr.md @@ -1,74 +1,52 @@ --- name: 09-create-pr -description: Create Pull Request for review and merge +description: Prepare the PR (pre-PR checks, title, body) and hand the release to the commit agent prev_step: references/08-check-test.md next_step: null --- # 09 - Create PR -**Create Pull Request for review and merge.** +**Run the pre-PR checks, prepare the PR title and body, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode).** This phase never pushes, opens, merges or tags anything itself. ## When to Use -- After all validation passes +- After all validation passes (eLicit, Verify, sniper) - After tests pass -- When ready for code review +- At the end of the mandate, when the work is ready to leave the working branch --- -## Pre-PR Checklist - -### Required +## Pre-PR Checklist (run by the APEX agent) ```text -□ Branch up-to-date with main -□ All commits follow conventional format -□ sniper validation passes -□ All tests pass -□ Build succeeds +□ All commits are WIP commits made by the commit agent (conventional `type(scope):` messages) +□ sniper validation passes (zero errors) +□ All tests pass — run the project's test script, not a subset +□ Build succeeds — run the project's build script □ Self-review completed □ No console.logs/debug code □ No TODO comments unaddressed ``` ---- - -## Sync with Main - -### Before PR - -```bash -# Fetch latest -git fetch origin main +Run each check for real and paste the command + result in your REPORT; a check not run is reported "not verified". -# Rebase (preferred for clean history) -git rebase origin/main - -# OR merge (if team prefers) -git merge origin/main +--- -# Push updates -git push origin feature/branch-name -``` +## Hand-off to the Commit Agent (end of mandate) -### Resolve Conflicts +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the checks above are green and the Verify + sniper proofs are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): -```text -1. Identify conflicting files -2. Open each file -3. Resolve conflicts (keep correct code) -4. Stage resolved files -5. Continue rebase/merge -6. Run tests to verify -``` +- It pushes the working branch, opens the PR, waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below, and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix through the APEX loop (`06-fix-issue.md`), re-run the checks, hand off again. +- Branch out of date with main → the commit agent's flow handles it; never rebase and force-push a shared branch yourself (force-push needs the owner). --- ## PR Title Format -### Conventional Format - ```text (): @@ -96,7 +74,7 @@ Types: --- -## PR Description Template +## PR Body Template (handed to the commit agent) ```markdown ## Summary @@ -106,7 +84,6 @@ Types: - Add protected route wrapper ## Changes - ### Added - `src/hooks/useAuth.ts` - Authentication hook - `src/components/LoginForm.tsx` - Login form component @@ -118,12 +95,10 @@ Types: - None ## Related Issues - Closes #123 Related to #456 ## Test Plan - - [ ] Login with valid credentials → redirects to dashboard - [ ] Login with invalid credentials → shows error - [ ] Logout → redirects to login page @@ -144,48 +119,6 @@ Related to #456 --- -## Create PR with gh CLI - -### Basic PR - -```bash -gh pr create \ - --title "feat(auth): add user authentication" \ - --body "$(cat <<'EOF' -## Summary -- Add JWT-based authentication -- Implement login/logout flows - -## Test Plan -- [ ] Login works with valid credentials -- [ ] Logout clears session - -Closes #123 -EOF -)" -``` - -### With Labels and Reviewers - -```bash -gh pr create \ - --title "feat(auth): add user authentication" \ - --body-file .github/PR_TEMPLATE.md \ - --label "feature,auth" \ - --reviewer "teammate1,teammate2" \ - --assignee "@me" -``` - -### Draft PR - -```bash -gh pr create --draft \ - --title "WIP: feat(auth): add user authentication" \ - --body "Work in progress - do not review yet" -``` - ---- - ## PR Best Practices ### Size Guidelines @@ -202,7 +135,6 @@ gh pr create --draft \ ❌ Incohesive or unreviewable PRs - Split into focused PRs - - Or use stacked PRs ``` ### Review-Friendly PRs @@ -219,129 +151,19 @@ gh pr create --draft \ --- -## After PR Created - -### Monitor CI - -```bash -# Check PR status -gh pr view --web - -# Check CI runs -gh pr checks - -# View CI logs -gh run view [run-id] -``` - -### Address Review Comments - -```text -1. Read all comments first -2. Respond to each: - - "Done" if fixed - - "Will address" if need time - - Discuss if disagree -3. Push fixes -4. Re-request review -``` - -### Merge Strategies - -```text -Merge commit (recommended): -- Preserves all commits -- Release tag stays attached to the bump commit - -Squash and merge: -- Single commit in main -- Never use on release branches — squash creates a new SHA and orphans any tag already pointing at the pre-squash bump commit - -Rebase and merge: -- Linear history -- No merge commit -``` - ---- - -## Merge - -### Pre-merge Checklist - -```text -□ All CI checks pass -□ Required reviews approved -□ No unresolved comments -□ Branch up-to-date -□ Ready to merge -``` - -### Merge Command - -```bash -# Merge commit (recommended — preserves the release tag's bump commit) -gh pr merge --merge - -# With delete branch -gh pr merge --merge --delete-branch - -gh pr merge --squash # never on release branches — orphans the tagged bump commit -``` - ---- - -## Post-Merge - -### Cleanup - -```bash -# Delete local branch -git checkout main -git pull origin main -git branch -d feature/branch-name - -# Verify merge -git log --oneline -5 -``` - -### Update Related - -```text -□ Close related issues -□ Update project board -□ Notify stakeholders -□ Update documentation if needed -□ Monitor production (if deployed) -``` - ---- - -## PR Checklist +## After the Hand-off ```text -□ Branch synced with main -□ Conventional PR title -□ Description complete -□ Issues linked -□ Tests documented -□ CI passing -□ Review requested -□ Ready to merge +□ Commit agent report read: PR URL, CI result, merge commit, tag (`git merge-base --is-ancestor vX.Y.Z main`) +□ Close related issues / update project board if the mandate asks +□ Report to the owner: merge/release announced, with the PR URL and tag ``` --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it (and mark the task `completed` once the PR is opened) in `.cursor/apex/task.json`: - -```bash -jq --arg p "create-pr" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -# after the PR is created: -jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `create-pr`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT (the task is completed once the commit agent reports the merge); tracking lives in the agents' REPORTs and `docs/decisions.md`. --- @@ -358,5 +180,5 @@ APEX Workflow Summary: 06-fix-issue → Fixed any issues 07-add-test → Added tests 08-check-test → Verified tests pass -09-create-pr → Created and merged PR ✅ +09-create-pr → Checks green, handed off to the commit agent (PR, CI, merge, tag) ✅ ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/03-plan-component.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/03-plan-component.md index 5b21bdf..4cfda48 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/03-plan-component.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/03-plan-component.md @@ -1,13 +1,13 @@ --- name: 03-plan-component -description: Plan component implementation with TaskCreate +description: Plan component implementation with a task list prev_step: references/design/02-search-inspiration.md next_step: references/design/04-code-component.md --- # 03 - Plan Component (APEX Phase P) -**Plan implementation using TaskCreate before coding.** +**Plan implementation using a task list before coding.** ## When to Use @@ -17,12 +17,12 @@ next_step: references/design/04-code-component.md --- -## TaskCreate Structure +## Task List Structure ### Example: Hero Section ```text -TaskCreate for each step: +List each step: 1. [ ] Create HeroSection component shell 2. [ ] Add typography (heading, subheading) 3. [ ] Implement background (gradient orbs) @@ -30,13 +30,13 @@ TaskCreate for each step: 5. [ ] Implement Framer Motion animations 6. [ ] Add responsive styles 7. [ ] Validate accessibility -Use addBlockedBy to set dependencies. TaskUpdate to track progress. +State dependencies in the plan; track progress in your REPORT. ``` ### Example: Card Component ```text -TaskCreate for each step: +List each step: 1. [ ] Create Card base component 2. [ ] Add CardHeader, CardContent, CardFooter 3. [ ] Implement hover animation @@ -99,7 +99,7 @@ If the component approaches `FUSE_SOLID_MAX_LINES` or accumulates multiple respo ## Validation Checklist ```text -[ ] TaskCreate plan created +[ ] Task list written in the plan / REPORT [ ] Tasks are atomic [ ] File sizes estimated within `FUSE_SOLID_MAX_LINES` (default `200`) [ ] Design tokens documented diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/04-code-component.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/04-code-component.md index cf71a12..42a580f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/04-code-component.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/04-code-component.md @@ -12,7 +12,7 @@ next_step: references/design/05-add-motion.md ## When to Use - After planning (03-plan-component) -- Following TaskCreate tasks +- Following the planned tasks - Referencing design tokens from Phase 01 --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/09-create-pr.md index da06921..b0ecb66 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/design/09-create-pr.md @@ -1,23 +1,34 @@ --- name: 09-create-pr -description: Create Pull Request with design documentation +description: Prepare a PR with design documentation and hand the release to the commit agent prev_step: references/design/08-sniper-check.md next_step: null --- # 09 - Create PR (Design) -**Create PR with visual documentation.** +**Prepare the PR with visual documentation, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode).** This phase never pushes, opens, merges or tags anything itself. ## When to Use - After sniper validation (08-sniper-check) - When design work is complete -- Ready for review +- At the end of the mandate, when the work is ready to leave the working branch --- -## PR Template +## Hand-off to the Commit Agent (end of mandate) + +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the validation checklist below is green and the Verify + sniper proofs (screenshots included) are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): + +- It pushes the working branch, opens the PR (against the repo's base branch, e.g. `develop`), waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below, screenshot paths, the base branch, and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix, re-validate, hand off again. + +--- + +## PR Body Template (handed to the commit agent) ```markdown ## Summary @@ -60,34 +71,6 @@ Brief, cohesive description of the design changes. --- -## Creating PR - -```bash -# Push branch -git push -u origin design/UI-001-hero-section - -# Create PR -gh pr create \ - --title "design(hero): add hero section with animations" \ - --base develop \ - --assignee @me \ - --body "$(cat <<'EOF' -## Summary -Added new HeroSection component with glassmorphism and staggered animations. - -## Design Coherence -- Uses existing color tokens -- Matches typography scale -- Follows animation patterns - -## Screenshots -[Add screenshots here] -EOF -)" -``` - ---- - ## Title Convention ```text @@ -116,20 +99,16 @@ Examples: ### Tools -```bash -# macOS screenshot -Cmd + Shift + 4 - -# Browser DevTools -- Responsive mode for mobile -- Emulate color scheme for dark mode +```text +- macOS screenshot: Cmd + Shift + 4 +- Browser DevTools: responsive mode for mobile, emulate color scheme for dark mode ``` --- ## Review Request -### Tag Reviewers +### Reviewers to Name in the Brief ```text - Design lead (for visual approval) @@ -139,27 +118,23 @@ Cmd + Shift + 4 --- -## Validation Checklist +## Validation Checklist (before the hand-off) ```text -[ ] Branch pushed -[ ] PR created with template -[ ] Screenshots attached +[ ] PR title and body ready (template above) +[ ] Screenshots captured and paths in the REPORT [ ] Design coherence documented [ ] A11y checklist completed -[ ] Reviewers assigned +[ ] Reviewers named for the commit agent's brief ``` --- -## Post-Merge +## After the Hand-off -```bash -# Switch back to develop -git checkout develop && git pull - -# Delete local branch -git branch -d design/UI-001-hero-section +```text +[ ] Commit agent report read: PR URL, CI result, merge commit, tag +[ ] Report to the owner: merge/release announced, with the PR URL and tag ``` --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/flow-diagram.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/flow-diagram.md index 03fe824..aba7d22 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/flow-diagram.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/flow-diagram.md @@ -26,7 +26,7 @@ description: ASCII flow diagram of the full APEX workflow, start to finish │ ▼ ┌───────────────┐ - │ 02-plan │ ← TaskCreate + │ 02-plan │ ← task list └───────┬───────┘ │ ▼ diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/init-tracking.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/init-tracking.md index 8944d37..bbc91cd 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/init-tracking.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/init-tracking.md @@ -1,47 +1,27 @@ --- name: init-tracking -description: APEX task-tracking initialization command (Step 0, mandatory first action) +description: APEX task tracking at Step 0 — nothing for agents to write; tracking lives in REPORTs --- -# Step 0: Initialize Tracking +# Step 0: Task Tracking -**BEFORE anything else**, run this command to initialize APEX tracking. +**Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only).** No APEX step creates, initializes or writes it — no `mkdir`, no `jq > task.json`. -## Task Slug +## What to do at Step 0 -Every artefact in `.cursor/apex/` (task id, docs, verify/elicit proofs) is keyed on one `{task-slug}`, derived — in order of preference — from: +Tracking lives in the agents' REPORTs (current phase, files touched, proof) and in `docs/decisions.md` for decisions that must outlive the session. -1. An explicit TaskCreate id, if this task is already tracked on the board (`APEX_TASK_SLUG` below). -2. The current git branch name, stripped of its `type/` prefix and slugified. -3. A `task-` fallback when neither is available (detached HEAD, no branch). +## Proof artefacts (not under `.cursor/`) -```bash -TASK_SLUG="${APEX_TASK_SLUG:-}" -[ -z "$TASK_SLUG" ] && TASK_SLUG=$(git branch --show-current 2>/dev/null \ - | sed -E 's#.*/##; s/[^a-zA-Z0-9]+/-/g; s/^-+|-+$//g' | tr '[:upper:]' '[:lower:]') -[ -z "$TASK_SLUG" ] && TASK_SLUG="task-$(date +%s)" -``` - -`{task-slug}` is the same value used everywhere else in APEX: `docs/task-{task-slug}.md` (working notes), `docs/verify-{task-slug}.md` (Verify proof), `docs/elicit-{task-slug}.json` (eLicit proof). - -## Command +The eLicit and Verify proofs live in the agent REPORT; their optional records go to `docs/verify/elicit-.json` and `docs/verify/.md` at the repo root. `` follows the `verification` skill's derivation (`references/verify-template.md`): `git branch --show-current`, drop the `/` prefix, lowercase, every character outside `a-z0-9` becomes `-`; detached HEAD → `detached-`. ```bash -TASK_SUBJECT="" # e.g. "$ARGUMENTS" from the invoking command -NOW="$(date -u +"%Y-%m-%dT%H:%M:%SZ")" -mkdir -p .cursor/apex/docs -jq -n --arg slug "$TASK_SLUG" --arg subject "$TASK_SUBJECT" --arg now "$NOW" \ - '{current_task: $slug, created_at: $now, tasks: {($slug): { - subject: $subject, status: "in_progress", phase: "init-branch", - started_at: $now, doc_consulted: {} - }}}' > .cursor/apex/task.json -echo "✅ APEX tracking initialized in $(pwd)/.cursor/apex/ (task: $TASK_SLUG)" +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi ``` -Build the JSON with `jq -n`, not a heredoc: `TASK_SUBJECT` is the user's raw request and commonly contains `"` or `` ` `` — string-interpolating it into a heredoc produces invalid JSON (verified: a heredoc with quotes in the subject breaks `jq .` with a parse error). `jq --arg` escapes it correctly regardless of content. - -This creates: -- `.cursor/apex/task.json` — tracks documentation consultation status, current phase, and subject (see `phase` field, updated by each phase reference — `references/00-init-branch.md` through `references/09-create-pr.md`) -- `.cursor/apex/docs/` — stores consulted documentation summaries - **Agents must not use Write/Edit until documentation is consulted; PreToolUse hook denial is intended defense-in-depth, and actual Cursor blocking remains runtime-unverified with the unpinned harness.** diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/00-init-branch.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/00-init-branch.md index 1fdc8ec..b563ecd 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/00-init-branch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/00-init-branch.md @@ -134,10 +134,13 @@ Long-lived branches = merge hell ### Sync Frequently ```bash +# Check how far the branch is behind main (read-only) git fetch origin main -git rebase origin/main +git log --oneline HEAD..origin/main ``` +Branch out of date with main → the commit agent's flow handles it (`fuse-ai-pilot:commit`, full mode, end of mandate); never rebase and force-push a shared branch yourself (force-push needs the owner). + --- ## Validation Checklist @@ -154,17 +157,9 @@ git rebase origin/main --- -## Update Task Phase - -At the **start** of this phase, record it (and the resolved task subject) in `.cursor/apex/task.json`: - -```bash -jq --arg p "init-branch" --arg s "$TASK_SUBJECT" \ - '.tasks[.current_task].phase = $p | .tasks[.current_task].subject = $s' \ - .cursor/apex/task.json > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +## Task Phase -Replace `$TASK_SUBJECT` with the real task description, quoted for the shell. +Phase: `init-branch`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/01-analyze-code.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/01-analyze-code.md index 1c62639..739f71e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/01-analyze-code.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/01-analyze-code.md @@ -212,14 +212,9 @@ Use outdated Laravel 10 patterns --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "analyze-code" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `analyze-code`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/02-features-plan.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/02-features-plan.md index 4fcebb1..44cb418 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/02-features-plan.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/02-features-plan.md @@ -36,7 +36,7 @@ Feature: User Profile API --- -## TaskCreate Breakdown +## Task Breakdown ### Task Template @@ -223,14 +223,9 @@ Split large interfaces: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "features-plan" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `features-plan`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03-execution.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03-execution.md index 40c083b..68e6273 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03-execution.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03-execution.md @@ -331,14 +331,9 @@ final class PostResource extends JsonResource --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "execution" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `execution`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03.5-elicit.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03.5-elicit.md index 6440a38..c8448c0 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03.5-elicit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/03.5-elicit.md @@ -137,14 +137,9 @@ Code Type: Controller --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "elicit" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `elicit`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/04-validation.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/04-validation.md index 012b9bb..271773b 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/04-validation.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/04-validation.md @@ -11,21 +11,32 @@ next_step: references/laravel/05-review.md ## Gate — Required Proof Artefacts -**Validation does NOT start** unless both proof files exist on disk for the current task. A claim made in context is not proof — only the file on disk is: +**Validation does NOT start** without both proofs for the current task, each carried by the agent REPORT or by its optional record under `docs/verify/` (slug from the git branch, per the `verification` skill — never under `.cursor/`): +- **eLicit** — the Step 5 report (techniques, verdicts, evidence, challenge verdict), or `docs/verify/elicit-.json`. +- **Verify** — one evidence item per criterion + the challenge verdict, or `docs/verify/.md`. + +A claim made in context is not proof — only the reported evidence or the record is: ```bash -TASK_SLUG=$(jq -r '.current_task' .cursor/apex/task.json) -if [ ! -f ".cursor/apex/docs/elicit-${TASK_SLUG}.json" ]; then - echo "❌ Missing .cursor/apex/docs/elicit-${TASK_SLUG}.json — go back to references/laravel/03.5-elicit.md first." - exit 1 +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi +if [ -f "docs/verify/elicit-${BRANCH_SLUG}.json" ]; then + echo "✅ eLicit record: docs/verify/elicit-${BRANCH_SLUG}.json" +else + echo "ℹ️ No docs/verify/elicit-${BRANCH_SLUG}.json — the eLicit verdict must be in the agent REPORT. No such report → go back to references/laravel/03.5-elicit.md first." fi -if [ ! -f ".cursor/apex/docs/verify-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/verify-${TASK_SLUG}.md — go back to the verification skill (runs between eLicit and eXamine) first." - exit 1 +if [ -f "docs/verify/${BRANCH_SLUG}.md" ]; then + echo "✅ Verify record: docs/verify/${BRANCH_SLUG}.md" +else + echo "ℹ️ No docs/verify/${BRANCH_SLUG}.md — the Verify proof must be in the agent REPORT (evidence per criterion + challenge verdict). No such report → go back to the verification skill first." fi ``` -Only once both checks pass does this phase proceed. +Only once both proofs are present does this phase proceed. --- @@ -305,14 +316,9 @@ public function find(int $id): ?User --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "validation" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `validation`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/05-review.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/05-review.md index 7b89c58..89a2f66 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/05-review.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/05-review.md @@ -290,14 +290,9 @@ public function create(CreatePostDTO $dto, int $userId): Post --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "review" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `review`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/06-fix-issue.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/06-fix-issue.md index 26ab378..988ecb7 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/06-fix-issue.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/06-fix-issue.md @@ -276,14 +276,9 @@ php artisan test --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "fix-issue" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `fix-issue`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/07-add-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/07-add-test.md index 4fa7d44..8f0935e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/07-add-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/07-add-test.md @@ -345,14 +345,9 @@ php artisan test --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "add-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `add-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/08-check-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/08-check-test.md index 60c96c9..b65a831 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/08-check-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/08-check-test.md @@ -324,14 +324,9 @@ php -d memory_limit=512M vendor/bin/pest --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "check-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `check-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/09-create-pr.md index 9f43f1c..c8ba809 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/laravel/09-create-pr.md @@ -1,23 +1,28 @@ --- name: 09-create-pr -description: Create a well-documented pull request for Laravel changes +description: Run Laravel pre-PR checks, prepare a well-documented PR, hand the release to the commit agent prev_step: references/laravel/08-check-test.md next_step: null --- # 09 - Create PR (Laravel) -**Create a well-documented pull request for Laravel changes.** +**Run the Laravel pre-PR checks, prepare the PR title and body, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode).** This phase never pushes, opens, merges or tags anything itself. ## When to Use -- After all validation passes +- After all validation passes (eLicit, Verify, sniper) - After self-review complete -- When feature is ready for team review +- At the end of the mandate, when the feature is ready to leave the working branch --- -## Pre-PR Checklist +## Pre-PR Checks (run by the APEX agent) + +```bash +composer quality && \ +php artisan test +``` ### Quality Gates @@ -40,73 +45,44 @@ next_step: null [ ] Routes documented in api.php ``` ---- - -## Push Branch - -```bash -# Ensure branch is up to date -git fetch origin main -git rebase origin/main - -# Push branch -git push -u origin feature/ISSUE-123-description -``` +Paste each command + result in your REPORT; a check not run is reported "not verified". --- -## PR Template for Laravel +## Hand-off to the Commit Agent (end of mandate) -```markdown -## Summary +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the checks above are green and the Verify + sniper proofs are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): -Brief, cohesive description of the changes. +- It pushes the working branch, opens the PR, waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge (and deletes the merged branch) and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below, and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix through the APEX loop (`06-fix-issue.md`), re-run the checks, hand off again. +- Branch out of date with main → the commit agent's flow handles it; never rebase and force-push a shared branch yourself (force-push needs the owner). -## Changes - -### Database -- Added `posts` table migration -- Added `PostStatus` enum - -### Models -- Created `Post` model with User relationship - -### Services -- Created `PostService` for business logic -- Implemented create, update, publish methods - -### API -- Added CRUD endpoints for posts -- Created `PostResource` for JSON transformation - -### Tests -- Added 8 feature tests for PostController -- Added 3 unit tests for PostService - -## Test Plan - -- [ ] Run `composer quality` locally -- [ ] Test API endpoints with Postman/Insomnia -- [ ] Verify database migrations work -- [ ] Check authorization policies +--- -## Breaking Changes +## PR Title Convention -None / List any breaking changes +```text +(): +``` -## Related Issues +### Examples -Closes #123 +```text +feat(posts): add Post CRUD API +fix(auth): resolve token expiration issue +refactor(users): extract UserService +docs(api): add OpenAPI documentation +test(orders): add integration tests +chore(deps): update Laravel to 12.5 ``` --- -## Create PR with GitHub CLI +## PR Body Template (handed to the commit agent) -```bash -gh pr create \ - --title "feat(posts): add Post CRUD API" \ - --body "$(cat <<'EOF' +```markdown ## Summary Add complete CRUD API for blog posts with proper authorization. @@ -115,6 +91,7 @@ Add complete CRUD API for blog posts with proper authorization. ### Database - Migration: `create_posts_table` +- Added `PostStatus` enum ### Models - `Post` model with User relationship @@ -128,6 +105,7 @@ Add complete CRUD API for blog posts with proper authorization. - `GET /api/v1/posts/{id}` - Show post - `PUT /api/v1/posts/{id}` - Update post - `DELETE /api/v1/posts/{id}` - Delete post +- `PostResource` for JSON transformation ### Tests - 8 feature tests @@ -138,32 +116,16 @@ Add complete CRUD API for blog posts with proper authorization. - [ ] Run `composer quality` - [ ] Test all API endpoints -- [ ] Verify migrations - -Closes #123 -EOF -)" -``` - ---- - -## PR Title Convention +- [ ] Verify migrations work +- [ ] Check authorization policies -### Format +## Breaking Changes -```text -(): -``` +None / List any breaking changes -### Examples +## Related Issues -```text -feat(posts): add Post CRUD API -fix(auth): resolve token expiration issue -refactor(users): extract UserService -docs(api): add OpenAPI documentation -test(orders): add integration tests -chore(deps): update Laravel to 12.5 +Closes #123 ``` --- @@ -202,102 +164,22 @@ Tests: [ ] Mocks used appropriately ``` ---- - -## After PR Created - -### Monitor CI - -```bash -# Check PR status -gh pr status - -# View checks -gh pr checks -``` - ### Respond to Feedback ```text -1. Address all comments -2. Push fixes as new commits -3. Request re-review when ready -4. Don't force-push after review started +1. Address all comments through the APEX loop (06-fix-issue) +2. Fixes land as new WIP commits by the commit agent — never a force-push +3. Hand off again; the commit agent updates the PR ``` --- -## Merge Strategies - -### Merge Commit (Recommended) +## After the Hand-off ```text -- Preserves all commits -- Creates merge commit -- Release tag stays attached to the bump commit -``` - -### Squash and Merge - -```text -- Combines all commits into one -- Never use on release branches — squash creates a new SHA and orphans any tag already pointing at the pre-squash bump commit -``` - -### Rebase and Merge - -```text -- Linear history -- No merge commits -- Clean but loses PR context -``` - ---- - -## Post-Merge Tasks - -### Cleanup - -```bash -# Delete local branch -git checkout main -git pull origin main -git branch -d feature/ISSUE-123-description - -# Delete remote branch (if not auto-deleted) -git push origin --delete feature/ISSUE-123-description -``` - -### Verify Deployment - -```bash -# Check production/staging -php artisan about -php artisan migrate:status -``` - ---- - -## PR Checklist Summary - -```text -Before Creating: -[ ] All quality tools pass -[ ] All tests pass -[ ] Self-review done -[ ] Branch rebased on main - -PR Content: -[ ] Clear title with type -[ ] Summary of changes -[ ] Test plan included -[ ] Related issues linked - -After Creating: -[ ] CI passes -[ ] Reviewers assigned -[ ] Respond to feedback -[ ] Merge when approved +[ ] Commit agent report read: PR URL, CI result, merge commit, tag +[ ] Deployment checked if the mandate covers it (`php artisan about`, `php artisan migrate:status` on the target) +[ ] Report to the owner: merge/release announced, with the PR URL and tag ``` --- @@ -305,11 +187,10 @@ After Creating: ## PR Report Template ```markdown -## PR Created +## Ready for Hand-off **Title:** feat(posts): add Post CRUD API **Branch:** feature/123-post-crud -**PR URL:** https://github.com/org/repo/pull/456 ### Quality Status - Larastan: PASS @@ -322,19 +203,12 @@ After Creating: - 3 files modified - 0 files deleted -### Ready for Review +### Next +Release handed to `fuse-ai-pilot:commit` (full mode) by the lead — PR URL and tag in its report. ``` --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it (and mark the task `completed` once the PR is opened) in `.cursor/apex/task.json`: - -```bash -jq --arg p "create-pr" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -# after the PR is created: -jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `create-pr`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT (the task is completed once the commit agent reports the merge); tracking lives in the agents' REPORTs and `docs/decisions.md`. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/00-init-branch.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/00-init-branch.md index 268e5bf..9e1378b 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/00-init-branch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/00-init-branch.md @@ -140,17 +140,9 @@ Required files: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it (and the resolved task subject) in `.cursor/apex/task.json`: - -```bash -jq --arg p "init-branch" --arg s "$TASK_SUBJECT" \ - '.tasks[.current_task].phase = $p | .tasks[.current_task].subject = $s' \ - .cursor/apex/task.json > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` - -Replace `$TASK_SUBJECT` with the real task description, quoted for the shell. +Phase: `init-branch`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/01-analyze-code.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/01-analyze-code.md index 6da18cf..5a4cb4c 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/01-analyze-code.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/01-analyze-code.md @@ -196,14 +196,9 @@ Check for 'use server' functions: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "analyze-code" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `analyze-code`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/02-features-plan.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/02-features-plan.md index 9a7112f..a270651 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/02-features-plan.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/02-features-plan.md @@ -190,7 +190,7 @@ ISR (Incremental): ## Validation Checklist ```text -[ ] TaskCreate plan created +[ ] Task list written in the plan / REPORT [ ] All files within `FUSE_SOLID_MAX_LINES` [ ] Interfaces in modules/[feature]/src/interfaces/ [ ] Server/Client boundary defined @@ -201,14 +201,9 @@ ISR (Incremental): --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "features-plan" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `features-plan`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03-execution.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03-execution.md index 4885017..f528c26 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03-execution.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03-execution.md @@ -12,7 +12,7 @@ next_step: references/nextjs/03.5-elicit.md ## When to Use - After planning phase complete -- Following TaskCreate task order +- Following the task order of the plan - With verified APIs from research --- @@ -268,14 +268,9 @@ MUST NOT: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "execution" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `execution`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03.5-elicit.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03.5-elicit.md index 0318e2c..60c4805 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03.5-elicit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/03.5-elicit.md @@ -129,14 +129,9 @@ Code Type: Server Action --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "elicit" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `elicit`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/04-validation.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/04-validation.md index 032cbda..4dce7a9 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/04-validation.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/04-validation.md @@ -11,21 +11,32 @@ next_step: references/nextjs/05-review.md ## Gate — Required Proof Artefacts -**Validation does NOT start** unless both proof files exist on disk for the current task. A claim made in context is not proof — only the file on disk is: +**Validation does NOT start** without both proofs for the current task, each carried by the agent REPORT or by its optional record under `docs/verify/` (slug from the git branch, per the `verification` skill — never under `.cursor/`): +- **eLicit** — the Step 5 report (techniques, verdicts, evidence, challenge verdict), or `docs/verify/elicit-.json`. +- **Verify** — one evidence item per criterion + the challenge verdict, or `docs/verify/.md`. + +A claim made in context is not proof — only the reported evidence or the record is: ```bash -TASK_SLUG=$(jq -r '.current_task' .cursor/apex/task.json) -if [ ! -f ".cursor/apex/docs/elicit-${TASK_SLUG}.json" ]; then - echo "❌ Missing .cursor/apex/docs/elicit-${TASK_SLUG}.json — go back to references/nextjs/03.5-elicit.md first." - exit 1 +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi +if [ -f "docs/verify/elicit-${BRANCH_SLUG}.json" ]; then + echo "✅ eLicit record: docs/verify/elicit-${BRANCH_SLUG}.json" +else + echo "ℹ️ No docs/verify/elicit-${BRANCH_SLUG}.json — the eLicit verdict must be in the agent REPORT. No such report → go back to references/nextjs/03.5-elicit.md first." fi -if [ ! -f ".cursor/apex/docs/verify-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/verify-${TASK_SLUG}.md — go back to the verification skill (runs between eLicit and eXamine) first." - exit 1 +if [ -f "docs/verify/${BRANCH_SLUG}.md" ]; then + echo "✅ Verify record: docs/verify/${BRANCH_SLUG}.md" +else + echo "ℹ️ No docs/verify/${BRANCH_SLUG}.md — the Verify proof must be in the agent REPORT (evidence per criterion + challenge verdict). No such report → go back to the verification skill first." fi ``` -Only once both checks pass does this phase proceed. +Only once both proofs are present does this phase proceed. --- @@ -289,14 +300,9 @@ Red flags: --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "validation" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `validation`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/05-review.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/05-review.md index 7528ebe..6fe26c7 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/05-review.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/05-review.md @@ -273,14 +273,9 @@ Quality: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "review" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `review`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/06-fix-issue.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/06-fix-issue.md index 49c6739..a448775 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/06-fix-issue.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/06-fix-issue.md @@ -278,14 +278,9 @@ export function ClientComponent({ data }) { --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "fix-issue" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `fix-issue`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/07-add-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/07-add-test.md index 6a47f5b..139fd09 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/07-add-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/07-add-test.md @@ -284,14 +284,9 @@ Coverage: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "add-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `add-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/08-check-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/08-check-test.md index 9b24389..568b181 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/08-check-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/08-check-test.md @@ -238,14 +238,9 @@ Quality: --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "check-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `check-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/09-create-pr.md index 0b7e50c..e8102c6 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/nextjs/09-create-pr.md @@ -1,58 +1,59 @@ --- name: 09-create-pr -description: Create Pull Request for Next.js project review and merge +description: Run Next.js pre-PR checks, prepare the PR, hand the release to the commit agent prev_step: references/nextjs/08-check-test.md next_step: null --- # 09 - Create PR (Next.js) -**Create Pull Request for Next.js project review and merge.** +**Run the Next.js pre-PR checks, prepare the PR title and body, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode).** This phase never pushes, opens, merges or tags anything itself. ## When to Use -- After all validation passes +- After all validation passes (eLicit, Verify, sniper) - After tests pass -- When ready for code review +- At the end of the mandate, when the work is ready to leave the working branch --- -## Pre-PR Checklist +## Pre-PR Checks (run by the APEX agent) -### Required +```bash +pnpm tsc --noEmit && \ +pnpm eslint . && \ +pnpm build && \ +pnpm test --run +``` ```text -[ ] Branch up-to-date with main [ ] tsc --noEmit passes [ ] eslint passes [ ] pnpm build succeeds -[ ] All tests pass +[ ] All tests pass (+ pnpm test:e2e when the change touches a user flow) [ ] Self-review completed [ ] No console.logs/debug code [ ] No TODO comments unaddressed ``` ---- +Paste each command + result in your REPORT; a check not run is reported "not verified". -## Sync with Main +--- -```bash -# Fetch latest -git fetch origin main +## Hand-off to the Commit Agent (end of mandate) -# Rebase (preferred for clean history) -git rebase origin/main +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the checks above are green and the Verify + sniper proofs are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): -# Push updates -git push origin feature/branch-name --force-with-lease -``` +- It pushes the working branch, opens the PR, waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below (with the build output), and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix through the APEX loop (`06-fix-issue.md`), re-run the checks, hand off again. +- Branch out of date with main → the commit agent's flow handles it; never rebase and force-push a shared branch yourself (force-push needs the owner). --- ## PR Title Format -### Conventional Format - ```text (): @@ -77,11 +78,10 @@ feat(api): add user CRUD endpoints --- -## PR Description Template +## PR Body Template (handed to the commit agent) ```markdown ## Summary - - Add user authentication with Better Auth - Implement Server Actions for form handling - Add protected route middleware @@ -96,7 +96,6 @@ feat(api): add user CRUD endpoints - `app/layout.tsx` - Add SessionProvider ## Architecture Decisions - - Used Server Actions instead of API routes for form mutations - Separated Server/Client components for optimal hydration @@ -122,53 +121,17 @@ Related to #456 --- -## Create PR with gh CLI - -### Standard PR - -```bash -gh pr create \ - --title "feat(auth): add Better Auth login flow" \ - --body "$(cat <<'EOF' -## Summary -- Add user authentication with Better Auth -- Implement Server Actions for form handling - -## Test Plan -- [ ] Login works with valid credentials -- [ ] Logout clears session - -Closes #123 -EOF -)" -``` - -### With Labels and Reviewers - -```bash -gh pr create \ - --title "feat(auth): add Better Auth login flow" \ - --body-file .github/PR_TEMPLATE.md \ - --label "feature,auth,next.js" \ - --reviewer "teammate1" \ - --assignee "@me" -``` - ---- - ## Next.js Specific Checks -### Build Output Verification +### Build Output in the PR Body ```text -Include in PR description: +Include, from the real `pnpm build` output: - Bundle size impact - New routes added - Rendering strategy (SSG/SSR/ISR) ``` -### Example - ```markdown ## Build Output Route (app) Size First Load JS @@ -190,13 +153,11 @@ Cohesive, reviewable PRs: - Faster feedback - Lower risk -For larger features: -- Split into multiple PRs -- Use stacked PRs pattern -- First PR: interfaces/types -- Second PR: services -- Third PR: components -- Fourth PR: integration +For larger features, split into several mandates/PRs: +- First: interfaces/types +- Second: services +- Third: components +- Fourth: integration ``` ### Review-Friendly @@ -211,95 +172,20 @@ For larger features: --- -## After PR Created - -### Monitor CI - -```bash -# Check PR status -gh pr view --web - -# Check CI runs -gh pr checks - -# View specific check logs -gh run view [run-id] --log -``` - -### Address Review Comments - -```text -1. Read all comments first -2. Respond to each: - - "Done" if fixed - - Discuss if disagree -3. Push fixes -4. Re-request review -5. Run: gh pr ready (if was draft) -``` - ---- - -## Merge - -### Pre-merge Checklist - -```text -[ ] All CI checks pass -[ ] Required reviews approved -[ ] No unresolved comments -[ ] Branch up-to-date -``` - -### Merge Command - -```bash -# Merge commit (recommended — preserves the release tag's bump commit) -gh pr merge --merge --delete-branch - -gh pr merge --squash --delete-branch # never on release branches — orphans the tagged bump commit -``` - ---- - -## Post-Merge - -### Cleanup - -```bash -# Switch to main -git checkout main -git pull origin main - -# Delete local branch -git branch -d feature/branch-name - -# Verify merge -git log --oneline -5 -``` - -### Update Related +## After the Hand-off ```text -[ ] Close related issues -[ ] Update project board -[ ] Notify stakeholders -[ ] Monitor Vercel preview/production +[ ] Commit agent report read: PR URL, CI result, merge commit, tag +[ ] Close related issues / update project board if the mandate asks +[ ] Vercel preview/production checked if the mandate covers deploy +[ ] Report to the owner: merge/release announced, with the PR URL and tag ``` --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it (and mark the task `completed` once the PR is opened) in `.cursor/apex/task.json`: - -```bash -jq --arg p "create-pr" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -# after the PR is created: -jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `create-pr`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT (the task is completed once the commit agent reports the merge); tracking lives in the agents' REPORTs and `docs/decisions.md`. --- @@ -315,5 +201,5 @@ jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ 06-fix-issue - Fixed any issues found 07-add-test - Added Vitest/Playwright tests 08-check-test - Verified all tests pass -09-create-pr - Created and merged PR +09-create-pr - Checks green, handed off to the commit agent (PR, CI, merge, tag) ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/phases-explained.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/phases-explained.md index 94fe8f1..2c606ca 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/phases-explained.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/phases-explained.md @@ -24,12 +24,12 @@ ALWAYS run 2 agents in parallel: ## P - Plan ```text -ALWAYS use TaskCreate: +ALWAYS list the tasks in the plan / REPORT: 1. Break down into tasks 2. Each task is cohesive and reviewable 3. Plan file splits FIRST -4. Map dependencies (addBlockedBy) +4. Map dependencies ``` ## E - Execute (with TDD) diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/quick-start-flows.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/quick-start-flows.md index 8e707ce..7b3ccc6 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/quick-start-flows.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/quick-start-flows.md @@ -11,13 +11,13 @@ description: Full step-by-step APEX flows for Standard Feature, Bug Fix, and Hot 1. 00-init-branch → git checkout -b feature/xxx 2. 00.5-brainstorm → Ask questions, propose alternatives, get design approval 3. 01-analyze-code → explore-codebase + research-expert -4. 02-features-plan → TaskCreate task breakdown +4. 02-features-plan → task breakdown in the plan 5. 03-execution → TDD: write test FIRST, then implement (files within `FUSE_SOLID_MAX_LINES`) 6. 03.5-elicit → Expert self-review (elicitation techniques) 7. 03.7-verification → Verify functional resolution against original request 8. 04-validation → sniper agent (code quality) 9. 05-review → Self-review -10. 09-create-pr → gh pr create +10. 09-create-pr → pre-PR checks, then hand-off to agent `fuse-ai-pilot:commit` (full mode: push, PR, CI, `--merge`, tag) ``` ## Bug Fix Flow @@ -30,7 +30,7 @@ description: Full step-by-step APEX flows for Standard Feature, Bug Fix, and Hot 5. 08-check-test → Verify test passes + no regressions 6. 03.7-verification → Verify original bug is functionally resolved 7. 04-validation → sniper agent -8. 09-create-pr → gh pr create +8. 09-create-pr → pre-PR checks, then hand-off to agent `fuse-ai-pilot:commit` (full mode) ``` ## Hotfix Flow @@ -41,5 +41,5 @@ description: Full step-by-step APEX flows for Standard Feature, Bug Fix, and Hot 3. 03.7-verification → Verify fix resolves the issue 4. 04-validation → sniper agent 5. 08-check-test → Run tests -6. 09-create-pr → Urgent merge +6. 09-create-pr → Hand-off to agent `fuse-ai-pilot:commit` (full mode), flagged urgent in the lead's report ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/00-init-branch.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/00-init-branch.md index 08a98eb..0d967e4 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/00-init-branch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/00-init-branch.md @@ -103,10 +103,13 @@ bun run dev ### Sync Frequently ```bash +# Check how far the branch is behind main (read-only) git fetch origin main -git rebase origin/main +git log --oneline HEAD..origin/main ``` +Branch out of date with main → the commit agent's flow handles it (`fuse-ai-pilot:commit`, full mode, end of mandate); never rebase and force-push a shared branch yourself (force-push needs the owner). + --- ## Validation Checklist @@ -123,17 +126,9 @@ git rebase origin/main --- -## Update Task Phase - -At the **start** of this phase, record it (and the resolved task subject) in `.cursor/apex/task.json`: - -```bash -jq --arg p "init-branch" --arg s "$TASK_SUBJECT" \ - '.tasks[.current_task].phase = $p | .tasks[.current_task].subject = $s' \ - .cursor/apex/task.json > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +## Task Phase -Replace `$TASK_SUBJECT` with the real task description, quoted for the shell. +Phase: `init-branch`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/01-analyze-code.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/01-analyze-code.md index 3862ea0..ae2171e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/01-analyze-code.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/01-analyze-code.md @@ -145,14 +145,9 @@ src/ --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "analyze-code" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `analyze-code`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/02-features-plan.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/02-features-plan.md index 9004cf3..48807ca 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/02-features-plan.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/02-features-plan.md @@ -17,7 +17,7 @@ next_step: references/react/03-execution.md --- -## TaskCreate Planning +## Task-List Planning ### React Feature Breakdown @@ -151,7 +151,7 @@ modules/[feature]/ ## Validation Checklist ```text -[ ] TaskCreate plan created +[ ] Task list written in the plan / REPORT [ ] All tasks are cohesive and reviewable [ ] Interfaces planned FIRST [ ] Hooks separated from components @@ -161,14 +161,9 @@ modules/[feature]/ --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "features-plan" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `features-plan`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03-execution.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03-execution.md index fd1afe3..f4caf77 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03-execution.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03-execution.md @@ -12,7 +12,7 @@ next_step: references/react/03.5-elicit.md ## When to Use - After plan is complete and approved -- Follow TaskCreate task order +- Follow the task order of the plan - Update progress as you go --- @@ -195,14 +195,9 @@ import { useUser } from '../src/hooks/useUser' --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "execution" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `execution`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03.5-elicit.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03.5-elicit.md index 89d80da..8459b05 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03.5-elicit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/03.5-elicit.md @@ -138,14 +138,9 @@ Code Type: Component --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "elicit" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `elicit`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/04-validation.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/04-validation.md index 3b98137..052c225 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/04-validation.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/04-validation.md @@ -11,21 +11,32 @@ next_step: references/react/05-review.md ## Gate — Required Proof Artefacts -**Validation does NOT start** unless both proof files exist on disk for the current task. A claim made in context is not proof — only the file on disk is: +**Validation does NOT start** without both proofs for the current task, each carried by the agent REPORT or by its optional record under `docs/verify/` (slug from the git branch, per the `verification` skill — never under `.cursor/`): +- **eLicit** — the Step 5 report (techniques, verdicts, evidence, challenge verdict), or `docs/verify/elicit-.json`. +- **Verify** — one evidence item per criterion + the challenge verdict, or `docs/verify/.md`. + +A claim made in context is not proof — only the reported evidence or the record is: ```bash -TASK_SLUG=$(jq -r '.current_task' .cursor/apex/task.json) -if [ ! -f ".cursor/apex/docs/elicit-${TASK_SLUG}.json" ]; then - echo "❌ Missing .cursor/apex/docs/elicit-${TASK_SLUG}.json — go back to references/react/03.5-elicit.md first." - exit 1 +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi +if [ -f "docs/verify/elicit-${BRANCH_SLUG}.json" ]; then + echo "✅ eLicit record: docs/verify/elicit-${BRANCH_SLUG}.json" +else + echo "ℹ️ No docs/verify/elicit-${BRANCH_SLUG}.json — the eLicit verdict must be in the agent REPORT. No such report → go back to references/react/03.5-elicit.md first." fi -if [ ! -f ".cursor/apex/docs/verify-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/verify-${TASK_SLUG}.md — go back to the verification skill (runs between eLicit and eXamine) first." - exit 1 +if [ -f "docs/verify/${BRANCH_SLUG}.md" ]; then + echo "✅ Verify record: docs/verify/${BRANCH_SLUG}.md" +else + echo "ℹ️ No docs/verify/${BRANCH_SLUG}.md — the Verify proof must be in the agent REPORT (evidence per criterion + challenge verdict). No such report → go back to the verification skill first." fi ``` -Only once both checks pass does this phase proceed. +Only once both proofs are present does this phase proceed. --- @@ -221,14 +232,9 @@ if (!user) return null --- -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "validation" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `validation`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/05-review.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/05-review.md index aa5814a..83d2067 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/05-review.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/05-review.md @@ -180,14 +180,9 @@ const [user, setUser] = useState({ name: '', email: '', phone: '' }) --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "review" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `review`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/06-fix-issue.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/06-fix-issue.md index 898779a..5857b40 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/06-fix-issue.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/06-fix-issue.md @@ -171,15 +171,19 @@ function UserProfile({ id }: Props) { ## Commit Fixes -```bash -# For validation fixes -git commit -m "fix(UserCard): resolve missing dependency warning" +This phase never runs `git commit` itself. Once the fix is verified, the lead hands it to agent `fuse-ai-pilot:commit` in **WIP mode** (`mode: wip`: one conventional commit on the working branch — no bump, no push, no PR, no merge, no tag); an APEX sub-agent never launches it. Push/PR/merge/tag happen only at the end of the mandate, in full mode (`09-create-pr.md`). Never squash or rebase: a follow-up fix is its own commit. -# For review fixes -git commit -m "refactor(auth): extract useAuth hook per review" +Suggested messages, passed to the commit agent: -# For test fixes -git commit -m "test(Button): fix async assertion" +```text +# Validation fix +fix(UserCard): resolve missing dependency warning + +# Review fix +refactor(auth): extract useAuth hook per review + +# Test fix +test(Button): fix async assertion ``` --- @@ -205,14 +209,9 @@ git commit -m "test(Button): fix async assertion" --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "fix-issue" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `fix-issue`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/07-add-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/07-add-test.md index 87c3fc2..0781107 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/07-add-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/07-add-test.md @@ -237,14 +237,9 @@ beforeEach(() => { --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "add-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `add-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/08-check-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/08-check-test.md index d8b1194..ff27dde 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/08-check-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/08-check-test.md @@ -240,14 +240,9 @@ bun run build --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "check-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `check-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/09-create-pr.md index 8cd75fb..6a708d0 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/react/09-create-pr.md @@ -1,26 +1,32 @@ --- name: 09-create-pr -description: Create Pull Request for React features +description: Run React pre-PR checks, prepare the PR, hand the release to the commit agent prev_step: references/react/08-check-test.md next_step: null --- # 09 - Create PR (React/Vite) -**Create Pull Request for React features.** +**Run the React pre-PR checks, prepare the PR title and body, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode).** This phase never pushes, opens, merges or tags anything itself. ## When to Use -- After all validation passes +- After all validation passes (eLicit, Verify, sniper) - After tests pass -- When ready for code review +- At the end of the mandate, when the work is ready to leave the working branch --- -## Pre-PR Checklist +## Pre-PR Checks (run by the APEX agent) + +```bash +bun run tsc --noEmit && \ +bun run lint && \ +bun run test && \ +bun run build +``` ```text -[ ] Branch up-to-date with main [ ] sniper validation passes [ ] All tests pass (bun run test) [ ] Build succeeds (bun run build) @@ -29,15 +35,28 @@ next_step: null [ ] Self-review completed ``` +Paste each command + result in your REPORT; a check not run is reported "not verified". + +### Common Failures (fix before the hand-off) + +| Failure | Fix | +| --- | --- | +| TypeScript error | Fix types locally | +| ESLint error | Run lint --fix | +| Test failure | Debug with --ui | +| Build failure | Check imports/exports | + --- -## Sync with Main +## Hand-off to the Commit Agent (end of mandate) -```bash -git fetch origin main -git rebase origin/main -git push origin feature/branch-name -``` +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the checks above are green and the Verify + sniper proofs are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): + +- It pushes the working branch, opens the PR, waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below, and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix through the APEX loop (`06-fix-issue.md`), re-run the checks, hand off again. +- Branch out of date with main → the commit agent's flow handles it; never rebase and force-push a shared branch yourself (force-push needs the owner). --- @@ -56,7 +75,7 @@ test(UserProfile): add integration tests --- -## PR Description Template (React) +## PR Body Template (handed to the commit agent) ```markdown ## Summary @@ -103,27 +122,6 @@ Closes #123 --- -## Create PR with gh CLI - -```bash -gh pr create \ - --title "feat(UserCard): add user profile component" \ - --body "$(cat <<'EOF' -## Summary -- Add UserCard component for user display -- Create useUser hook for data fetching - -## Test Plan -- [ ] Component renders correctly -- [ ] Hook handles loading/error states - -Closes #123 -EOF -)" -``` - ---- - ## PR Best Practices (React) ### Size Guidelines @@ -152,70 +150,18 @@ Split if: --- -## After PR Created - -### Monitor CI - -```bash -gh pr view --web -gh pr checks -``` - -### Common CI Failures - -| Failure | Fix | -| --- | --- | -| TypeScript error | Fix types locally | -| ESLint error | Run lint --fix | -| Test failure | Debug with --ui | -| Build failure | Check imports/exports | - ---- - -## Merge - -```bash -# After approval (merge commit — never squash, it orphans the release tag's bump commit) -gh pr merge --merge --delete-branch -``` - ---- - -## Post-Merge - -```bash -git checkout main -git pull origin main -git branch -d feature/branch-name -``` - ---- - -## PR Checklist +## After the Hand-off ```text -[ ] Branch synced with main -[ ] Conventional PR title -[ ] Description complete -[ ] Tests documented -[ ] Screenshots for UI -[ ] CI passing -[ ] Review requested +[ ] Commit agent report read: PR URL, CI result, merge commit, tag +[ ] Report to the owner: merge/release announced, with the PR URL and tag ``` --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it (and mark the task `completed` once the PR is opened) in `.cursor/apex/task.json`: - -```bash -jq --arg p "create-pr" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -# after the PR is created: -jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `create-pr`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT (the task is completed once the commit agent reports the merge); tracking lives in the agents' REPORTs and `docs/decisions.md`. --- @@ -231,5 +177,5 @@ jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ 06-fix-issue -> Fixed any issues 07-add-test -> Added Vitest tests 08-check-test -> Verified tests pass -09-create-pr -> Created and merged PR +09-create-pr -> Checks green, handed off to the commit agent (PR, CI, merge, tag) ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/00-init-branch.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/00-init-branch.md index 58f0dfa..75a39ea 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/00-init-branch.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/00-init-branch.md @@ -30,17 +30,16 @@ hotfix/1.2.1-critical-fix # Hotfixes ```bash git checkout develop && git pull origin develop git checkout -b feature/AUTH-123-login-screen -git push -u origin feature/AUTH-123-login-screen ``` +The branch stays local; agent `fuse-ai-pilot:commit` pushes it at the end of the mandate (full mode). + ## SPM Package Versioning -```bash -# Tag release (SemVer) -git tag -a 1.2.0 -m "Release 1.2.0" -git push origin 1.2.0 +Release tags (SemVer, e.g. `1.2.0`) are created only by agent `fuse-ai-pilot:commit` in full mode, after the merge is confirmed — never by hand in this phase. -# Package.swift dependency +```swift +// Package.swift dependency .package(url: "https://github.com/org/Package", from: "1.2.0") ``` @@ -56,45 +55,21 @@ Pods/ ## Merge Strategy -```bash -# Rebase before PR -git fetch origin && git rebase origin/develop - -# Squash merge -git checkout develop -git merge --squash feature/AUTH-123-login-screen -git commit -m "feat(auth): add Apple Sign-In (#123)" -``` +Merges are done only by agent `fuse-ai-pilot:commit` (full mode, end of mandate): PR into the base branch, CI wait, then a real `--merge` commit — never squash, which would orphan the release tag's bump commit. No manual rebase, merge or commit in this phase. ## Branch Protection Rules - Require PR reviews (min 1) - Require status checks (SwiftLint, tests) -- Require linear history - No force push to main/develop ## Release Process -```bash -git checkout -b release/1.2.0 develop -# Bump version, update CHANGELOG -git checkout main && git merge --no-ff release/1.2.0 -git tag -a 1.2.0 -m "Release 1.2.0" -git push origin main --tags -git checkout develop && git merge main -``` - -## Update Task Phase - -At the **start** of this phase, record it (and the resolved task subject) in `.cursor/apex/task.json`: +Version bump, CHANGELOG, merge and post-merge tag are all run by agent `fuse-ai-pilot:commit` in full mode, announced by the lead in the report (template HARD STOP 1). This phase only creates the working branch. -```bash -jq --arg p "init-branch" --arg s "$TASK_SUBJECT" \ - '.tasks[.current_task].phase = $p | .tasks[.current_task].subject = $s' \ - .cursor/apex/task.json > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +## Task Phase -Replace `$TASK_SUBJECT` with the real task description, quoted for the shell. +Phase: `init-branch`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/01-analyze-code.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/01-analyze-code.md index 73f633e..cd5bfca 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/01-analyze-code.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/01-analyze-code.md @@ -87,14 +87,9 @@ grep -rn "struct.*: View" --include="*.swift" | wc -l grep -rn "class.*: UIViewController" --include="*.swift" | wc -l ``` -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "analyze-code" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `analyze-code`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/02-features-plan.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/02-features-plan.md index d61122d..803738d 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/02-features-plan.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/02-features-plan.md @@ -86,14 +86,9 @@ final class ProfileViewModel { - [ ] Plan file splits if `FUSE_SOLID_MAX_LINES` would be exceeded - [ ] Identify localization keys -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "features-plan" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `features-plan`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03-execution.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03-execution.md index 7dd1b7f..0c14b21 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03-execution.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03-execution.md @@ -88,14 +88,9 @@ Button("button.save") { ... } When a view section has a distinct responsibility, extract it to a subview: `ProfileHeader`, `ProfileDetails`, `ProfileActions` -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "execution" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `execution`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03.5-elicit.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03.5-elicit.md index c89045c..91f7400 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03.5-elicit.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/03.5-elicit.md @@ -149,14 +149,9 @@ Code Type: ViewModel --- -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "elicit" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `elicit`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Step diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/04-validation.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/04-validation.md index 500b269..5c81bfa 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/04-validation.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/04-validation.md @@ -9,21 +9,32 @@ next_step: references/swift/05-review.md ## Gate — Required Proof Artefacts -**Validation does NOT start** unless both proof files exist on disk for the current task. A claim made in context is not proof — only the file on disk is: +**Validation does NOT start** without both proofs for the current task, each carried by the agent REPORT or by its optional record under `docs/verify/` (slug from the git branch, per the `verification` skill — never under `.cursor/`): +- **eLicit** — the Step 5 report (techniques, verdicts, evidence, challenge verdict), or `docs/verify/elicit-.json`. +- **Verify** — one evidence item per criterion + the challenge verdict, or `docs/verify/.md`. + +A claim made in context is not proof — only the reported evidence or the record is: ```bash -TASK_SLUG=$(jq -r '.current_task' .cursor/apex/task.json) -if [ ! -f ".cursor/apex/docs/elicit-${TASK_SLUG}.json" ]; then - echo "❌ Missing .cursor/apex/docs/elicit-${TASK_SLUG}.json — go back to references/swift/03.5-elicit.md first." - exit 1 +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi +if [ -f "docs/verify/elicit-${BRANCH_SLUG}.json" ]; then + echo "✅ eLicit record: docs/verify/elicit-${BRANCH_SLUG}.json" +else + echo "ℹ️ No docs/verify/elicit-${BRANCH_SLUG}.json — the eLicit verdict must be in the agent REPORT. No such report → go back to references/swift/03.5-elicit.md first." fi -if [ ! -f ".cursor/apex/docs/verify-${TASK_SLUG}.md" ]; then - echo "❌ Missing .cursor/apex/docs/verify-${TASK_SLUG}.md — go back to the verification skill (runs between eLicit and eXamine) first." - exit 1 +if [ -f "docs/verify/${BRANCH_SLUG}.md" ]; then + echo "✅ Verify record: docs/verify/${BRANCH_SLUG}.md" +else + echo "ℹ️ No docs/verify/${BRANCH_SLUG}.md — the Verify proof must be in the agent REPORT (evidence per criterion + challenge verdict). No such report → go back to the verification skill first." fi ``` -Only once both checks pass does this phase proceed. +Only once both proofs are present does this phase proceed. ## SwiftLint Configuration (.swiftlint.yml) @@ -107,14 +118,9 @@ swiftlint --strict && swift-format lint --strict Sources/ - [ ] All strings localized - [ ] #Preview for all views -## Update Task Phase - -At the **start** of this phase, record it in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "validation" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `validation`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/05-review.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/05-review.md index 1eb4ae3..764e98f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/05-review.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/05-review.md @@ -106,14 +106,9 @@ swift-format lint --strict Sources/ xcodebuild test -scheme MyApp -destination "platform=iOS Simulator,name=iPhone 16" ``` -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "review" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `review`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/06-fix-issue.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/06-fix-issue.md index d24020f..93dbdf1 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/06-fix-issue.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/06-fix-issue.md @@ -91,21 +91,21 @@ git checkout -b bugfix/ISSUE-123-profile-crash ```bash xcodebuild test -scheme MyApp swiftlint --strict -git commit -m "fix(profile): handle nil user (#123)" +``` + +Both green → the lead hands the commit to agent `fuse-ai-pilot:commit` in **WIP mode** (`mode: wip`: one conventional commit on the working branch — no bump, no push, no PR, no merge, no tag); an APEX sub-agent never runs `git commit` itself. Never squash or rebase: a follow-up fix is its own commit. Suggested message, passed to the commit agent: + +```text +fix(profile): handle nil user (#123) ``` ## Escalation **Attempt cap before escalation.** Diagnosis is hypothesis-driven: one candidate cause documented → one atomic fix → immediate retest. The same fix twice is forbidden; a new attempt needs a new hypothesis (fresh research first). After 3 failed cycles on the same issue, STOP and escalate with a root-cause note (what was tried, sources consulted, why each attempt failed) — do not keep trying or widen the scope to work around it. Canonical implementation: sniper's Fix Retry Loop. -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "fix-issue" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `fix-issue`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/07-add-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/07-add-test.md index 55fa91f..fb9256f 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/07-add-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/07-add-test.md @@ -93,14 +93,9 @@ Tests/ └── UITests/ProfileUITests.swift ``` -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "add-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `add-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/08-check-test.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/08-check-test.md index 1f970d0..0595066 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/08-check-test.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/08-check-test.md @@ -80,14 +80,9 @@ xcodebuild test -scheme MyApp \ - [ ] No memory leaks - [ ] No data races -## Update Task Phase +## Task Phase -At the **start** of this phase, record it in `.cursor/apex/task.json`: - -```bash -jq --arg p "check-test" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `check-test`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT; tracking lives in the agents' REPORTs and `docs/decisions.md`. ## Next Phase diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/09-create-pr.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/09-create-pr.md index 07d546d..f6039fe 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/09-create-pr.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/apex-methodology/references/swift/09-create-pr.md @@ -1,13 +1,33 @@ --- name: 09-create-pr -description: Create Pull Request for Swift/iOS changes +description: Run Swift pre-PR checks, prepare the PR, hand the release to the commit agent prev_step: references/swift/08-check-test.md next_step: null --- # Swift Pull Request Guide -## PR Template +Run the Swift pre-PR checks, prepare the PR title and body, then hand the push / PR / CI / merge / tag to agent `fuse-ai-pilot:commit` (full mode). This phase never pushes, opens, merges or tags anything itself. + +## Pre-PR Checks (run by the APEX agent) + +```bash +swiftlint --strict && \ +swift test +``` + +For an Xcode app target, run the scheme instead of `swift test`: `xcodebuild test -scheme MyApp -destination "platform=iOS Simulator,name=iPhone 16"`. Paste each command + result in your REPORT; a check not run is reported "not verified". + +## Hand-off to the Commit Agent (end of mandate) + +This phase never runs `git push`, `gh pr create`, `gh pr merge`, a rebase onto main, a force-push or a tag. Once the checks above are green and the Verify + sniper proofs are in the REPORT, the release goes to agent `fuse-ai-pilot:commit` in **full mode** (template HARD STOP 1; rules `06-tooling-rules`, Git & GitHub Flow): + +- It pushes the working branch, opens the PR (against the repo's base branch, e.g. `develop`), waits for CI, merges with a real `--merge` commit — never squash, which would orphan the release tag's bump commit — then tags post-merge and watches the release run. +- The lead launches it at the end of the mandate and announces the merge/release in the report to the owner; an APEX sub-agent never launches it and never runs those commands itself. +- Brief it with: `mode: full`, the PR title and body below, the base branch, and the files of the mandate. +- Blocked (merge conflict, secret in the diff) → it stops with `status: blocked`; CI red → `status: left-open`, `ci: failed:`. Either way: fix through the APEX loop (`06-fix-issue.md`), re-run the checks, hand off again. + +## PR Body Template (handed to the commit agent) ```markdown ## Summary @@ -34,17 +54,6 @@ Brief description (1-2 sentences). | N/A | [img] | ``` -## Creating PR - -```bash -git push -u origin feature/PROFILE-123-user-profile - -gh pr create \ - --title "feat(profile): add user profile (#123)" \ - --base develop \ - --assignee @me -``` - ## Title Convention ```text @@ -53,7 +62,7 @@ fix(scope): description (#ticket) refactor(scope): description ``` -## GitHub Actions Checks +## GitHub Actions Checks (what the commit agent's CI wait gates on) ```yaml name: PR Checks @@ -71,29 +80,13 @@ jobs: - run: xcodebuild test -scheme MyApp -destination "platform=iOS Simulator,name=iPhone 16" ``` -## Review Commands - -```bash -gh pr diff 123 # View diff -gh pr checks 123 # Check status -gh pr merge 123 --merge --delete-branch # Merge commit — never squash, it orphans the release tag's bump commit -``` - -## Post-Merge +## After the Hand-off -```bash -git checkout develop && git pull -git branch -d feature/PROFILE-123-user-profile +```text +[ ] Commit agent report read: PR URL, CI result, merge commit, tag +[ ] Report to the owner: merge/release announced, with the PR URL and tag ``` -## Update Task Phase - -At the **start** of this phase, record it (and mark the task `completed` once the PR is opened) in `.cursor/apex/task.json`: +## Task Phase -```bash -jq --arg p "create-pr" '.tasks[.current_task].phase = $p' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -# after the PR is created: -jq '.tasks[.current_task].status = "completed"' .cursor/apex/task.json \ - > .cursor/apex/task.json.tmp && mv .cursor/apex/task.json.tmp .cursor/apex/task.json -``` +Phase: `create-pr`. Do not create or write `.cursor/apex/task.json`: on Cursor no tool syncs it (the harness task sync is Claude-only). State the phase in your REPORT (the task is completed once the commit agent reports the merge); tracking lives in the agents' REPORTs and `docs/decisions.md`. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/SKILL.md index 08b521d..f39fa83 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/SKILL.md @@ -1,15 +1,15 @@ --- name: elicitation description: "Use when an expert agent self-reviews and self-corrects code after the Execute phase, before sniper validation (BMAD-METHOD elicitation techniques)." -argument-hint: "[--auto] [--manual] [--skip]" +argument-hint: "[--auto | --manual]" color: purple user-invocable: false --- -Elicitation lets an expert agent self-review and self-correct its own code before external validation, drawing on 75 elicitation techniques across 12 categories (code quality, security, performance, architecture, testing, docs, UX, data, concurrency, integration, observability, maintainability) inspired by BMAD-METHOD. Three modes control how techniques are chosen: MANUAL (default, user picks from 5 presented options), AUTO (auto-detected and applied silently), and SKIP (bypass straight to sniper). +Elicitation lets an expert agent self-review and self-correct its own code before external validation, drawing on 75 elicitation techniques across 12 categories (code quality, security, performance, architecture, testing, docs, UX, data, concurrency, integration, observability, maintainability) inspired by BMAD-METHOD. Two modes control how techniques are chosen: AUTO (default, auto-detected and applied silently) and MANUAL (only when the owner asks: the owner picks from 5 presented options). eLicit is never skipped. -It sits between Execute and eXamine in the APEX flow, scores itself against an exit threshold (>=90% proceed, 70-89% document gaps, <70% iterate), and persists its findings to `.cursor/apex/docs/elicit-{task-slug}.json` so a later pass can diff against prior verdicts instead of restarting. +It sits between Execute and Verify/eXamine in the APEX flow, scores itself against an exit threshold (>=90% proceed, 70-89% document gaps, <70% iterate), reports its verdict in the agent REPORT, and — when it must persist — writes `docs/verify/elicit-.json` (never under `.cursor/apex/`) so a later pass can diff against prior verdicts instead of restarting. # Elicitation Skill @@ -20,37 +20,31 @@ Enable expert agents to **self-review and self-correct** their code before exter --- -## 3 Execution Modes +## 2 Execution Modes -### Mode 1: MANUAL (default) -``` -Expert presents 5 relevant techniques → User chooses → Expert applies -``` - -### Mode 2: AUTO (--auto) +### Mode 1: AUTO (default, --auto) ``` Expert auto-detects code type → Auto-selects techniques → Applies silently ``` -### Mode 3: SKIP (--skip) +### Mode 2: MANUAL (--manual, only when the owner asks) ``` -Skip elicitation → Go directly to sniper validation +Expert presents 5 relevant techniques → Owner chooses → Expert applies ``` +There is no skip mode: eLicit runs on every APEX task, before Verify and eXamine. + --- ## Quick Start **After Execute phase, expert runs:** ```bash -# Manual mode (default) +# Auto mode (default, no prompts) > Apply elicitation skill -# Auto mode (no prompts) -> Apply elicitation skill --auto - -# Skip self-review -> Apply elicitation skill --skip +# Manual mode (owner asked to choose) +> Apply elicitation skill --manual ``` --- @@ -151,9 +145,10 @@ A-nalyze → P-lan → E-xecute → [ELICIT] → X-amine ## Artifact Contract -Step 5 persists `.cursor/apex/docs/elicit-{task-slug}.json` so a later pass -diffs against prior verdicts instead of restarting from scratch. Full -contract, `{task-slug}` derivation, and JSON schema: `references/artifact-contract.md`. +Step 5 puts the verdict in the agent REPORT and, when it must persist, writes +`docs/verify/elicit-.json` (never under `.cursor/apex/`) so a later pass diffs against prior verdicts instead of +restarting from scratch. Full contract, `` derivation, and JSON +schema: `references/artifact-contract.md`. --- @@ -166,4 +161,4 @@ contract, `{task-slug}` derivation, and JSON schema: `references/artifact-contra | 2 | `steps/step-02-select-techniques.md` | Select techniques | | 3 | `steps/step-03-apply-review.md` | Apply review | | 4 | `steps/step-04-self-correct.md` | Self-correct | -| 5 | `steps/step-05-report.md` | Generate report, persist `elicit-{task-slug}.json` | +| 5 | `steps/step-05-report.md` | Generate report, optionally persist `docs/verify/elicit-.json` | diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/artifact-contract.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/artifact-contract.md index b48f015..8f4bbbe 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/artifact-contract.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/artifact-contract.md @@ -1,20 +1,38 @@ # Artifact Contract -Step 5 does not stop at an in-context markdown report -- it writes -`.cursor/apex/docs/elicit-{task-slug}.json`: a list of `{technique_id, -verdict, correction_applied, evidence}` per technique applied. A later -elicitation pass on the same task loads this file first (Step 0) and +The eLicit verdict always travels in the agent REPORT (Step 5 report: mode, +techniques applied with verdict + evidence, corrections, challenge verdict). +When it must survive the session (long mandate, several agents, a later pass +expected), Step 5 also writes `docs/verify/elicit-.json`: a list +of `{technique_id, verdict, correction_applied, evidence}` per technique +applied. A later elicitation pass loads this file first (Step 0) and **diffs against it** instead of re-deriving technique selection from scratch -- only re-apply techniques that were `fail`/`deferred` or are newly relevant. See `steps/step-05-report.md` for the exact JSON schema and `steps/step-00-init.md` for the load/diff logic. -`{task-slug}`: derive per `apex-methodology/references/init-tracking.md`'s -"Task Slug" section (canonical: `TaskCreate` id, else git branch stripped of -its `type/` prefix and slugified, else `task-`) -- same -pattern used by the `verification` skill's `verify-{task-slug}.md`. Do not -improvise another derivation: a branch like `feat/use-harness` slugifies to -`use-harness`, not `feat-use-harness` -- a mismatched slug means gates never -find the artifact. +Never write it under `.cursor/apex/` -- keep it at the project-relative +path above so the eXamine gate finds it. + +``: the same rule as the `verification` skill +(`verification/references/verify-template.md`) -- `git branch --show-current`, +drop the `/` prefix, lowercase, every character outside `a-z0-9` +becomes `-`; detached HEAD → `detached-`. Do not improvise another +derivation: `feat/use-harness` slugifies to `use-harness`, not +`feat-use-harness` -- a mismatched slug means the gate never finds the file. + +```bash +BRANCH=$(git branch --show-current) +if [ -n "$BRANCH" ]; then + BRANCH_SLUG=$(printf '%s' "${BRANCH#*/}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g') +else + BRANCH_SLUG="detached-$(git rev-parse --short HEAD)" +fi +mkdir -p docs/verify +# Step 5 writes docs/verify/elicit-${BRANCH_SLUG}.json +``` + +The Verify proof is a sibling artifact: REPORT first, optional record at +`docs/verify/.md`. Optional per-repo tuning of which techniques apply: `references/elicit-profile.md`. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/elicit-profile.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/elicit-profile.md index 1a90287..c98eef5 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/elicit-profile.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/references/elicit-profile.md @@ -1,7 +1,8 @@ # Elicit Profile (optional, per-repo) -`.cursor/apex/elicit-profile.md`, if present, tunes technique selection -(Step 2) for the current repo without editing the skill itself. +`docs/elicit-profile.md`, if present, tunes technique selection +(Step 2) for the current repo without editing the skill itself. Not under +`.cursor/apex/`. Not required. Absence means: use `SKILL.md`'s Auto-Detection Matrix and `techniques-catalog.md` unmodified. @@ -44,7 +45,7 @@ Not required. Absence means: use `SKILL.md`'s Auto-Detection Matrix and ## When to Create One -Create `.cursor/apex/elicit-profile.md` when a repo repeatedly surfaces +Create `docs/elicit-profile.md` when a repo repeatedly surfaces irrelevant findings (e.g. UX-05 on a CLI-only repo) or repeatedly misses a category the default matrix does not cover for that stack. Do not create it speculatively -- it is a corrective, not a default scaffold. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-00-init.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-00-init.md index 79ec3f7..cb21750 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-00-init.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-00-init.md @@ -25,7 +25,7 @@ next_step: steps/step-01-analyze-code.md - Expert agent that coded **Output for next steps:** -- `{elicit_mode}`: manual | auto | skip +- `{elicit_mode}`: auto | manual - `{code_files}`: list of modified files - `{code_type}`: detected code category - `{expert_agent}`: which expert coded @@ -39,11 +39,12 @@ next_step: steps/step-01-analyze-code.md ``` Check arguments: - --auto → {elicit_mode} = "auto" -- --manual → {elicit_mode} = "manual" -- --skip → {elicit_mode} = "skip" -- (none) → {elicit_mode} = "manual" (default) +- --manual → {elicit_mode} = "manual" (only when the owner asked for it) +- (none) → {elicit_mode} = "auto" (default) ``` +There is no skip mode: eLicit is never skipped. + ### 2. Load Execute Context ``` @@ -57,8 +58,8 @@ Gather from previous phase: ### 3. Load Prior Artifact (if present) ``` -Derive {task-slug} (see SKILL.md's Artifact Contract). -IF .cursor/apex/docs/elicit-{task-slug}.json exists: +Derive (see references/artifact-contract.md). +IF docs/verify/elicit-.json exists: → Load it as {prior_artifact} → In Step 2, techniques already "pass" in {prior_artifact} are deselected by default; "fail"/"deferred" ones are re-selected first @@ -75,14 +76,6 @@ Required for next steps: ✓ Expert agent known ``` -### 5. Handle Skip Mode - -``` -IF {elicit_mode} == "skip": - → Output: "Elicitation skipped. Proceeding to sniper validation." - → END (do not continue to step 1) -``` - --- ## Output Format diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-02-select-techniques.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-02-select-techniques.md index 37293e7..66c0a67 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-02-select-techniques.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-02-select-techniques.md @@ -32,7 +32,7 @@ next_step: steps/step-03-apply-review.md ## YOUR TASK: -**Before selecting**: if `.cursor/apex/elicit-profile.md` exists, apply its +**Before selecting**: if `docs/elicit-profile.md` exists, apply its `Exclude` / `Always Apply` / `Add for Code Type` precedence (see `references/elicit-profile.md`) to whatever this step would otherwise select. Also apply `{prior_artifact}` from Step 0 if present: deselect `"pass"` @@ -60,7 +60,7 @@ techniques by default, prioritize `"fail"`/`"deferred"` ones. 5. **{technique_5}** ({category}) → {what_it_checks} -Choix: [1-5] ou "all" ou "skip" +Choice: [1-5] or "all" ``` #### 2. Wait for User Response @@ -69,7 +69,6 @@ Choix: [1-5] ou "all" ou "skip" Parse user input: - "1, 3, 5" → Select techniques 1, 3, 5 - "all" → Select all 5 techniques -- "skip" → End elicitation, go to sniper - "1" → Select technique 1 only ``` diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-05-report.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-05-report.md index 5d4adca..57c326e 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-05-report.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/elicitation/steps/step-05-report.md @@ -53,15 +53,16 @@ Sniper needs to know: ### 3. Persist the Artifact -Write `.cursor/apex/docs/elicit-{task-slug}.json` -- see `SKILL.md`'s -"Artifact Contract" section for `{task-slug}` derivation. This is what a -later elicitation pass diffs against instead of restarting technique -selection from scratch; the markdown report below is for the human handoff, -this file is for the machine one. +The verdict always goes in the agent REPORT (section 4 below). When it must +survive the session, also write `docs/verify/elicit-.json` -- +see `references/artifact-contract.md` for the `` derivation. +Never under `.cursor/apex/`. This file is what a later elicitation pass diffs against instead of +restarting technique selection from scratch; the markdown report is for the +human handoff, this file is for the machine one. ```json { - "task_slug": "{task-slug}", + "branch_slug": "", "generated_at": "{ISO-8601 UTC}", "mode": "manual|auto", "expert_agent": "{expert_name}", @@ -82,7 +83,7 @@ Rules: - `verdict: "pass"` only if Step 3 found no finding, or Step 4 fixed every finding for that technique. `"deferred"` for Low-severity items left for sniper. `"fail"` if a Critical/High finding could not be corrected. -- On a later pass for the same `{task-slug}`, load this file in Step 0: skip +- On a later pass on the same branch, load this file in Step 0: skip re-applying any technique already `"pass"`, re-apply `"fail"`/`"deferred"` ones first. @@ -176,7 +177,7 @@ Before marking elicitation complete: - [ ] Medium issues fixed or justified deferral - [ ] Low issues documented for sniper - [ ] Report generated -- [ ] `elicit-{task-slug}.json` written to `.cursor/apex/docs/` +- [ ] Verdict in the agent REPORT (and `docs/verify/elicit-.json` when persisted) - [ ] Handoff context provided --- diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/SKILL.md index 03c337c..ab48e72 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/SKILL.md @@ -40,5 +40,5 @@ Canonical doctrine for every `mcp__fuse-browser__*` call. Read this skill FIRST, | Screenshots, responsive + dark, visual regression | Visual / design | `references/visual-design.md` | - **No live session for reading** — if you only need text/HTML/data, the answer is always fast-path (profile 1). Never `browser_open` to read. -- **Validation tools** (any profile): `browser_visual_diff` (regression vs baseline), `browser_metrics` (real Core Web Vitals), `browser_console` / `browser_network` / `browser_cookies` (runtime + security checks). +- **Validation tools** (any profile): `browser_visual_diff` (regression vs baseline), `browser_metrics` (fuse-browser server counters — probes, durations, queue, RSS; not Core Web Vitals — lab CWV come from Lighthouse via the seo plugin's `scripts/check-cwv.ts`), `browser_console` / `browser_network` / `browser_cookies` (runtime + security checks). - **Full design pipeline** is NOT here — for identity → generate → audit, use `fuse-design:design-web` then the `fuse-design:design-review` gate. This skill only covers the raw browser tooling. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/references/visual-design.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/references/visual-design.md index 07a4eac..bebf29a 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/references/visual-design.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/fuse-browser-usage/references/visual-design.md @@ -46,7 +46,7 @@ browser_visual_diff { baseline: "home-v1.png", current: "http://localhost:4321/" ## Rules - One `browser_screenshot` with a `viewports` array + `colorScheme` beats N single shots. Same for `shots_batch` over looping. -- `browser_metrics` gives real Core Web Vitals (LCP/INP/CLS) when the visual check also needs performance evidence. +- `browser_metrics` returns fuse-browser server counters, not Core Web Vitals; when the visual check also needs performance evidence, run Lighthouse (the seo plugin's `scripts/check-cwv.ts`). ## Full design pipeline — do NOT reimplement here 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 index 838a59b..24c0c48 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/lead-orchestration/SKILL.md @@ -1,12 +1,12 @@ --- 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." +description: "Use when you are the LEAD (main session) and an owner request arrives that needs subagents -- receive, check the place, analyze, decompose, distribute, brief, launch, follow, verify, control, report. Detailed version of the AGENTS.md COORDINATOR PATH; 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. +One procedure for the lead, from an owner request to a verified report. It is the detailed version of the AGENTS.md COORDINATOR PATH: same 11 steps, same order. The project template keeps the one-line summary; this skill holds the detail. Each step 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`). @@ -32,61 +32,87 @@ Verified in the Cursor docs (https://cursor.com/docs/subagents, /docs/skills, /d | 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` | +| HARD STOPS, COORDINATOR PATH (summary), agents communicate, relayed message, decisions journal, RECURRING TRAPS, AUTONOMY, step 9 (proof by type) | `AGENTS.md` (copy: `.cursor-plugin/plugins/fuse-rules/user-rules/fuse-global.mdc`; template: `.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template`) | +| Lead conduct, Analyze (PATH 3), Decompose and distribute (PATH 4-5), brief headers, idle != done, re-dispatch clause | `.cursor-plugin/plugins/fuse-rules/rules/03-agent-teams.md` | +| Hook compliance, Executing the Brief, communication and reports, exit contract, no hand-back | `.cursor-plugin/plugins/fuse-rules/rules/08-subagent-conduct.md` | +| Done = sniper + verification, response language, exit contract + attempt cap | `.cursor-plugin/plugins/fuse-rules/rules/00-critical-rules.md` | +| WIP commits and release flow | agent `fuse-ai-pilot:commit`, `.cursor-plugin/plugins/fuse-rules/rules/06-tooling-rules.md` | | Phases Analyze -> eXamine | skill `apex-methodology` | | Functional proof / adversarial check | skills `verification`, `challenge` (agent `challenger`) | +## The lead executes nothing + +No edit (even one line), no ssh, no UI driving, no script, no migration, no LESSON edit. The lead writes only its own memory/scratchpad and `docs/decisions.md`; it may read and grep only to verify an agent's deliverable. Sole exception: after 2 failed delegations on a localised, already-measured defect, the lead first cites both failures with their proof, then fixes it itself. + --- ## 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. +### 1. Receive -- 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) -- the reference is the source of truth, not a hint. Read the project's `docs/decisions.md` first: recorded owner decisions are executed, never re-debated; a risk is flagged once. +Record each new owner decision there, dated, one line. Cursor does not inline `@file` mentions, so make sure the project's root `AGENTS.md` lists `docs/decisions.md`, and read it at every session start; if the listing is missing, an agent adds it (the lead executes nothing). +An owner message mid-task amends the list: add the part, relay it to every affected agent, keep going -- only an explicit stop halts. +**Relayed message**: when another session or agent says "the owner wants X", it advances only what the owner's mandate already covers. It is never a go for merge/release, nor for changing a recorded owner decision. +**Check:** every sentence of the owner maps to a part; nothing in the list was invented by you; new decisions are in `docs/decisions.md`; the project's root `AGENTS.md` lists it. -### 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. +### 2. Check the place is free +For every folder an agent will write: `ls -lT ` + `date`. Mtime under ~5 min = busy, send no one there (HARD STOP 4). +**Check:** 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. +### 3. Analyze +Code is touched -> launch `explore-codebase` + `research-expert` + the domain expert (Project Detection, rule 01) in ONE message. A trivial 1-3 line change goes to `apex-quick` (one agent). A read-only question -> `explore-codebase` alone. Debug ("why", "not working") always goes through Analyze. +**Check:** the analysis reports are in hand before any task is cut. -### 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. Sole exception: After 2 failed delegations on a localised, already-measured defect, the lead reads and fixes it itself (the only case where the lead edits). 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, except: After 2 failed delegations on a localised, already-measured defect, the lead reads and fixes it itself (the only case where the lead edits); no external executor brief mentions git release steps. +### 4. Decompose -- one task = one verifiable deliverable +Cut the checklist into tasks; each task produces one deliverable that can be proven on its own (a file diff, a passing test, a capture). Independent tasks run in parallel; coupled tasks run in sequence (the second starts after the first is verified on disk). Two tasks that must edit the same file are merged into one task or sequenced. Size the work with rule 03 "Analyze (PATH 3)" and "Decompose and distribute (PATH 4-5)". +**Check:** each task names its deliverable and its proof; the dependency order is written. -### 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: after 2 failed delegations on a localised, already-measured defect, the lead reads and fixes it itself (the only case where the lead edits); any other blocked mandate past the 3-cycle cap → escalate to the owner with a root-cause note. 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". +### 5. Distribute -- ownership table +One named agent per task (domain expert per rule 01). Write the table before launching: + +| Agent (name) | Task | Exclusive files | Skills to load | +|--------------|------|-----------------|----------------| +| `api-auth` | ... | `src/auth/**` | solid-*, domain skills, `verification` | -### 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. +A shared resource (build, simulator, dev server, database) has exactly one owner; the others ask it through their report to the lead, who relays by resuming the owner. Pick the skills each agent must load: the stack's SOLID skill via `solid-detection`, the domain skills (`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. Announce the budget in one line: number of agents and their names -- never a promised duration. +**Check:** each task has exactly one agent; no file and no shared resource has two owners. + +### 6. Brief -- fixed headers +Fill `references/brief-template.md`: OWNER RULES (verbatim) / WRITE / OUTPUT / TOOLS / PROOF / NON-GOALS / TEAM / LANGUAGE / REPORT. A protected path (HARD STOP 3: `~/.claude`, `~/.codex`, `~/.cursor`, an installed or deployed copy, install scripts) goes into WRITE 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 in OUTPUT with its PROOF; no "ask the owner if..." escape hatch. + +### 7. Launch +Launch every independent agent of the table in one message (one Task call per agent). At most 6 agents concurrently -- a ceiling, never a minimum; more tasks run in waves of up to 6. For code, the brief asks for tests first (RED, then GREEN). From here the lead only follows. 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 step 1 contain no Write/Edit on project files (except `docs/decisions.md` and the 2-failed-delegations case). + +### 8. Follow -- the owner never asks "is it moving?" +At each notification or report, check the disk and logs (mtimes, `git diff --stat`, output files, test logs) -- a report is a claim until the disk confirms it. A silent agent gets looked at, not waited on: no new output on disk -> resume the same subagent by its agent ID with the precise next step; never spawn a duplicate on the same mandate. Follow background runs through `~/.cursor/subagents/` and the mtimes of the files they own. External executors included, to the end. +Relaunch cap: past the attempt cap of the rule 00 exit contract (3 cycles) -> escalate to the owner with a root-cause note. No relaunch loop. Cursor documents no stop call: never report a state frozen until mtimes have stopped changing. +**Blocks**: before handing anything back, make the agent try every authorized route -- a scriptable source instead of a blocked site, the page's own file/CDN link or an API, 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). Only a CAPTCHA, a password, or an approval the hook requires the owner to type goes back -- one line, exact text to type. +**Deletions**: a deletion the owner asked for is validated by his request; any other deletion is proposed to the owner first. After validation an agent executes it, preferring the reversible route (`mv ~/.Trash/`), then proves it with `ls`. +**Check:** you can answer "where is it?" with the last measurement (time, files changed, tests), never "I don't know". -### 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. +### 9. Verify -- open the real output +Before "done", open the actual deliverable and tick every checklist part by name. Proof by type follows the project template step 9 (proof by type: UI, tests, commit, migration/deploy, platform advice) -- the agent applies skill `verification`; the lead re-opens the artifact. Anything unproven is reported "not verified". Proven = stated as guaranteed with its proof; never "I can't guarantee". +Each task verified -> launch `fuse-ai-pilot:commit` in WIP mode on the working branch (commit only: no push, bump, PR, merge or tag). +**Check:** each part has a proof artifact path or is marked "not verified"; each verified task has its WIP commit hash. -### 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. +### 10. Control +Once every agent has finished: `sniper` once on all changes, then the `challenger` before any "done", root-cause, irreversible action or 2nd-time fix, and at every eLicit + Verify gate. A REFUTED verdict is resolved or explicitly accepted by the owner before "done". +**Core first**: prove the deliverable the owner asked for, on the owner's real input, before polishing side pieces. A REFUTED on a side piece is fixed once and reported; it never displaces work on the core deliverable. No round cap -- order, not count. +**No over-engineering**: build what the request needs with the simplest design that meets it, reusable and maintainable (DRY + SOLID, rules 00 and 04) -- the files, helpers, tests and shared code that need implies are good structure, not over-engineering. Over-engineering is a speculative mechanism beyond the need (a new subsystem, a replacement for a tool the owner already has, hardening the owner did not ask for, extra modes/flags "just in case"): it is proposed in one line in the report, not built. +**Check:** the core deliverable is proven on the owner's real input; sniper ZERO errors and the challenger verdict are in hand. -### 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. +### 11. Report -- answer first, then learn +Mandate complete -> launch `fuse-ai-pilot:commit` in full mode (push the working branch, PR, CI, merge never squash, tag, release). Owner reply, in the owner's language (rule 00): line 1 = the answer (done / not done / blocked), then <= 10 lines: proof, not verified, WIP commits made, merge/release announced, one recommendation + the next step, no option menu when one choice is clearly better. Deliverables at a path the owner sees -- never only a hidden directory. +Each owner correction -> one line in the skill/agent that failed, in the source repo, the same turn, written by an agent (AUTONOMY, rule 03 "Lead conduct"). Sync to an installed copy only when the owner asked for it (HARD STOP 3). +**Check:** line 1 answers the question asked; every deliverable path is outside a dot-folder; each correction is grep-able in the failing skill/agent before the turn ends. --- ## Critical rules (pointers) -1. A mandate is the go -- reversible steps inside it need no question (AUTONOMY). +1. A mandate is the go -- technical decisions are taken alone and reported (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. @@ -95,5 +121,5 @@ Owner reply, in the owner's language (rule 00): first line = the answer (done / | Need | Reference | |------|-----------| -| Writing a brief (step 3) | [brief-template.md](references/brief-template.md) | +| Writing a brief (step 6) | [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 index b2e3b7c..1cc1dd1 100644 --- 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 @@ -1,8 +1,8 @@ --- 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 +description: Copy-paste mandate skeleton with fixed headers the lead fills before every delegation +when-to-use: Step 6 of lead-orchestration, before any Task-tool subagent or external executor launch +keywords: brief, mandate, delegation, ownership, guardrails, team, report format priority: high related: worked-examples.md --- @@ -11,53 +11,70 @@ related: worked-examples.md ## 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. +A brief summarised from memory drifts from the owner's request: parts get dropped, negative constraints vanish, paths get invented. Fixed headers force the owner's exact words, the files the task owns, the proof and the team into every mandate, so the agent can be judged on disk instead of on its own summary. The header names are fixed (same order, same spelling) so a hook can check that a brief is complete. ## Template ```markdown -## Context - - -## Owner request (verbatim) +## OWNER RULES (verbatim) > "" +- Standing decisions (from docs/decisions.md): -- execute them, do not re-debate. +- Protected target (only if the owner named it): -- owner's words: "" -## 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: +## WRITE +- Exclusive files: - Read only: -- Protected target (only if the owner named it): -- owner's words: "" +- Re-read each file on disk right before editing; start from the on-disk state, preserve others' work. + +## OUTPUT +Context: +1. +2. +N. Negative: <"do not touch X"> -## Skills to load (required) -- , , verification -- read them before editing +## TOOLS +- Skills to load before editing: , , verification +- Capture tool (visual task): +- Hook block -> do exactly what it says; read the gate source before calling it a bug. -## Guardrails -- Re-read each file on disk right before editing; start from the on-disk state. +## PROOF +1. -- +2. -- <...> +N. Negative -- `git diff --stat` shows no change under X + +## NON-GOALS +- +- No commit, push, tag or publish yourself: the lead has the commit agent make a WIP commit once your task is verified. +- No deletion outside your files; a needed deletion is reported to the lead, never executed. - 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. + +## TEAM +- Lead: the session that launched you; you report to it through your final result +- Peers: , ... +- Cursor has no peer messaging: for a contract or interface change, a result you wait for, or a file a peer owns (never edit it), say so in your report to the lead, who relays by resuming the peer. +- Shared resource owner (build, simulator, server): + +## LANGUAGE +Code comments, docs, commit messages: English. Replies to the user: the user's language. + +## REPORT (final result, to the lead, short) +- Start: files taken. +- Each milestone: what is done, proof so far. +- Block: immediately, with the routes already tried (Exit: Retry / Rollback / Ask / Escalate). +- Final: done | not done -- proof per part -- not verified -- files touched (path:line) -- skills consulted. +- Open points: decide them yourself from the measurement and the mandate's goal, and report the decision. Ask the lead ONE binary question in your report (never the owner, never an option menu) only for the part where incoming information contradicts OWNER RULES; continue the rest meanwhile. Irreversible git (push to a protected branch, force-push, reset) stays gated by HARD STOP 1, not by a question. - 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". | +| Header | Rule | +|--------|------| +| OWNER RULES | Copy the sentence. A mockup/capture the owner sent is given by path: it is the source of truth, not a hint. Protected target only when the owner named it in this session; otherwise omit the line. | +| WRITE | Absolute paths; the same file never appears in two concurrent briefs. | +| OUTPUT | One line per checklist part from step 1; context stays in two or three lines. | +| PROOF | One proof per OUTPUT line, something the lead can open or re-run. | +| TOOLS | Visual task -> name the capture tool; without it, the part cannot be proven. | +| NON-GOALS | External executor: add "write code only -- release goes through the commit agent". | +| TEAM | Every name in the ownership table of step 5, even for a single agent (then Peers: none). | +| REPORT | Short; the owner-facing reply is the lead's job. | 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 index 4d2d429..ed249e6 100644 --- 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 @@ -2,47 +2,50 @@ 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 +keywords: follow-up, hand-back, visual verification, executor, release, WIP commit 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. +Drawn from session audits (Claude lead sessions and Codex sessions, 3-12 Oct 2026). Each one maps to steps of the procedure. --- -## 1. Executor left alone, then releases on its own (steps 4 + 5) +## 1. Executor left alone, then releases on its own (steps 6, 8, 9, 11) -**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. +**Bad.** The lead launched an external executor for four small fixes, promised a duration it did not hold, and did not follow it. 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. +- Brief NON-GOALS: write code only, no commit/push/PR/merge/tag/publish. REPORT: to the lead in the final result (start, each fix done, any block, the end). Tests first. +- Lead announces the budget (agents and names), never a duration. +- At each report the lead checks the disk and test logs; posts "fix 2/4 done, tests green, fix 3 in progress" before being asked. +- Silent executor -> resume the same subagent by its agent ID with the next step, not a new spawn. +- Each fix verified -> commit agent WIP commit on the working branch. +- All fixes done -> sniper, challenger on the diff -> commit agent full mode: push, PR, CI, merge, tag, release, Publish watched to success. --- -## 2. A manual step handed back to the owner (step 6) +## 2. A manual step handed back to the owner (step 8) **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. +- Residue -> the owner's request is the validation; an agent moves the files to Trash (`mv ~/.Trash/`, reversible) and proves it with `ls`. Residue the owner did not name is proposed first. +- Signing -> an agent finds and runs the owner's existing script; ask nothing. +- Blocked site -> an agent uses another scriptable CC0 / free-licence source and records the licence. - 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) +## 3. "Done" without opening the output (steps 9 + 10) **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. +- Brief TOOLS names the capture tool; PROOF asks for the capture path. +- The agent produces the screenshot / frames against the real target; the lead opens them and cites 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 6332492..67871ab 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/SKILL.md @@ -6,7 +6,7 @@ description: "Use when marking a task complete, finishing a feature, or claiming Verification confirms the original request is actually fulfilled -- distinct from sniper, which only confirms the code is clean. It runs a 6-step process: re-read the original request word for word, list every acceptance criterion (explicit and implicit), verify each with concrete evidence (test output, logs, screenshots, diffs), run the full test suite to check for regressions, review every modified file for accidental side effects, then route the "functionally resolved" claim through the `challenger` agent before writing it down. -Step 6 always persists `.cursor/apex/docs/verify-{task-slug}.md` -- an in-context "it works" declaration doesn't survive a session boundary, and this artifact is what later gates (sniper, elicitation) actually check. It sits between eLicit and eXamine in APEX: a task is only complete when both verification and sniper pass. +The proof lives in the agent's REPORT to the lead (proof per part, not verified, files touched); when a file is needed it goes to `docs/verify/.md`. Proof by type (UI, tests, commit, migration/deploy, platform advice) follows AGENTS.md COORDINATOR PATH step 9 (proof by type) -- canonical there, not repeated here. It sits between eLicit and eXamine in APEX: a task is only complete when both verification and sniper pass. # Verification Before Completion @@ -46,6 +46,8 @@ For each criterion, provide concrete evidence of resolution: - Screenshot of the UI change - Code diff showing the implementation +The proof required for each type of deliverable is AGENTS.md COORDINATOR PATH step 9 (proof by type; source: `.cursor-plugin/plugins/fuse-rules/templates/CLAUDE.md.template`). + **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** @@ -54,12 +56,12 @@ Run the full test suite. Compare results before and after. No new failures, no n **Step 5: Check for side effects** Review every modified file. Confirm no accidental changes to unrelated code. Verify dependencies and configuration are unchanged unless required. -**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. +**Step 6: Confirm functional resolution -- challenge, then report the proof** +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. A `REFUTED` or `UNCERTAIN` verdict must be resolved (fix and re-verify) or explicitly accepted by the owner before any "done" claim. -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". +Put the proof in your REPORT to the lead: one evidence item per criterion (command output, log excerpt, screenshot path, or diff), the challenge verdict, what is not verified, files touched. When the proof must survive the session (long mandate, several agents, owner asked for a record), also write `docs/verify/.md` using the body of `references/verify-template.md` -- never under `.cursor/apex/`. 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. +``: from the git branch only -- `git branch --show-current`, drop the `/` prefix, lowercase, every character outside `a-z0-9` becomes `-` (`feat/use-harness` -> `use-harness`). Detached HEAD: `detached-`. --- @@ -69,7 +71,7 @@ Write `.cursor/apex/docs/verify-{task-slug}.md` (template: `references/verify-te |----------|------|---------| | Checklist | `references/checklist.md` | Full verification checklist with all categories | | Common Misses | `references/common-misses.md` | Frequently forgotten verification items | -| Artifact Template | `references/verify-template.md` | `verify-{task-slug}.md` template + task-slug derivation | +| Artifact Template | `references/verify-template.md` | Optional `docs/verify/.md` record: path, slug derivation, body | --- @@ -94,4 +96,4 @@ This ensures functional correctness is confirmed before code quality validation. | Full test suite, not just new tests | Catches regressions | | Review ALL modified files | Catches accidental side effects | | Both verification AND sniper must pass | Quality without correctness is useless | -| Step 6 writes `verify-{task-slug}.md` to disk | In-context self-review without persisted state regresses across sessions | +| Step 6 proof goes in the REPORT; a file, if needed, in `docs/verify/.md` | A claim without its proof regresses across sessions; `.cursor/apex/` is not used for it | diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/references/verify-template.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/references/verify-template.md index 63c5819..65d1307 100644 --- a/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/references/verify-template.md +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/verification/references/verify-template.md @@ -1,22 +1,21 @@ # Verification Artifact Template -Write this file to `.cursor/apex/docs/verify-{task-slug}.md` in Step 6. It is the -disk-persisted proof a gate (hook, sniper, next elicitation pass) can check -- -a context-only "it works" declaration does not survive a session boundary. +The proof always goes in the agent's REPORT to the lead. When it must also +survive the session (long mandate, several agents, owner asked for a record), +write this file to `docs/verify/.md` in Step 6 -- never under +`.cursor/apex/`. -`{task-slug}`: derive per `apex-methodology/references/init-tracking.md`'s -"Task Slug" section (canonical: `TaskCreate` id, else git branch stripped of -its `type/` prefix and slugified, else `task-`). Do not -improvise another derivation: a branch like `feat/use-harness` slugifies to -`use-harness`, not `feat-use-harness` -- a mismatched slug means gates never -find the artifact. +``: from the git branch only -- `git branch --show-current`, drop +the `/` prefix, lowercase, every character outside `a-z0-9` becomes `-`. +A branch like `feat/use-harness` slugifies to `use-harness`, not +`feat-use-harness`. Detached HEAD: `detached-`. --- ## Template ```markdown -# Verification: {task-slug} +# Verification: **Date**: {ISO-8601 UTC} **Original request**: {one-line summary} @@ -54,5 +53,5 @@ or actual command output or excerpt. - If a criterion cannot be verified (no test harness, no way to reproduce), say so explicitly under Verdict instead of marking it ✅. -- This file is the artifact eXamine (sniper) and any later elicitation pass - read to avoid re-deriving verification state from scratch. +- When written, this file lets eXamine (sniper) and any later elicitation pass + avoid re-deriving verification state from scratch. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/SKILL.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/SKILL.md new file mode 100644 index 0000000..d334e81 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/SKILL.md @@ -0,0 +1,76 @@ +--- +name: web-performance +description: "Use when writing or changing web app code (front, backend, DB) to apply performance defaults, or when asked to audit performance (\"audit perf\", \"why is it slow\") -- 31 rules across front, backend+DB and infra, each with status, evidence and user cost. Advisory: audits and recommends, never edits during the audit. Do NOT use for lint/quality (sniper) or SEO-only audits (fuse-seo)." +user-invocable: true +references: references/front.md, references/backend-db.md, references/infra.md +related-skills: react-effects-audit, fuse-browser-usage, verification, challenge +--- + + +Web Performance gives domain experts 31 performance rules (numbered 1-31, stable across reports) in two modes. **Default mode** is always on: while writing code for its task, the expert applies the relevant rules by itself. **Audit mode** runs on request: baseline measurement, every rule reviewed with evidence, absent rules ranked by gain, then a STOP for the owner's validation before any fix. + +The skill is advisory. It never builds architecture (job queue, Redis, tracing, regions, load balancing) without the owner's go, and the audit phase never edits code. + + +# Web Performance + +## Mode 1 -- Default (always on, inside your current task only) + +When you write or change code, apply these as defaults -- no request needed, no refactor of code your task does not touch: + +| Area | Default | +|---|---| +| Images | Framework image component (`next/image`, Astro ``/``), WebP/AVIF, `sizes`, explicit dimensions; `loading="lazy"` below the fold, never on the LCP image | +| Loading UI | Skeleton matching the final layout when the layout is known; spinner only for unknown shape or short actions | +| Inputs | Debounce search/autocomplete; cancel stale requests (`AbortController`) | +| Data fetching | Independent requests in parallel (`Promise.all`, `Http::pool`); one shared cache (TanStack Query, `fetch` cache, server components) -- no duplicate calls for the same data | +| Lists / APIs | Paginate list endpoints; virtualize lists that render hundreds of rows | +| DB | Eager-load relations (`with()`, `include`/`select`), select the columns you use, index the columns you filter/sort on in the migration you write | +| External calls | Explicit timeout on every outbound HTTP/AI call | +| AI output | Stream tokens to the UI when the response is user-facing | +| Third-party scripts | Deferred (`next/script` `lazyOnload`/`afterInteractive`, `defer`/`async`) | +| Fonts | Self-hosted WOFF2 (`next/font`, Fontsource), only the weights you use | +| Rendering | Server or build-time rendering by default; client code only where interactivity needs it | +| Mutations | Optimistic update with rollback on error when the outcome is predictable | + +Architecture rules (7 job queue, 10 Redis, 18 OpenTelemetry, 19 same region, 28 load balancing) are **never** introduced by default. If relevant to your task, add one line to your report: `perf proposal: rule N -- why`. + +## Mode 2 -- Audit (on request: "audit perf", "why is it slow") + +Read-only plus measurement. Load only the references for the domains present. + +1. **Baseline** (what the project allows): lab Core Web Vitals with Lighthouse on the running app (`bun /scripts/check-cwv.ts ` (deps in the seo plugin's package.json), or `npx lighthouse --only-categories=performance --output=json`); JS size from the build output; slow queries / request timings from logs. No baseline possible -> say so; the ranking is then marked **estimated**. +2. **Stack + domains**: detect the stack (rule `01-project-detection`); keep the domains that apply -- front (`references/front.md`), backend + DB (`references/backend-db.md`), infra (`references/infra.md`). A pure static site has no backend-db domain. +3. **Review every rule** of those domains. Status is one of `applied` / `absent` / `not applicable` / `not verifiable from code`, with evidence `file:line` or the measurement. `absent` -> one sentence on what it costs the end user. +4. **Rank** absent rules by measured (else estimated) gain vs effort and risk. Architecture rules are tagged `proposal -- needs owner go`. +5. **STOP.** Present the report and wait for the owner to validate specific rule numbers. No edit before. +6. **Fix validated rules one at a time**, by the stack's domain expert: real check after each (tests / build / run the app) and a before/after on the same metric. Regression -> roll back before the next rule. + +### Report format + +``` +| # | Rule | Status | Evidence | User cost | Rank | +|---|------|--------|----------|-----------|------| +| 15 | Lazy-load below-fold images | absent | app/page.tsx:42 | +1.2 MB on first load on mobile | 1 | +``` + +Then the ranked list of absent rules: `rank. #N rule -- expected gain (measured|estimated) -- effort -- risk`. + +### Use by the lead + +On an "audit perf" request the lead may run one domain expert per domain present (front / backend), each loading only its reference, then merge the tables by rule number. + +## Reference Guide + +| Reference | Rules | When | +|---|---|---| +| [front.md](references/front.md) | 1, 2, 4, 13, 14, 15, 20, 21, 22, 23, 26, 29, 31 | UI, rendering, assets, client JS | +| [backend-db.md](references/backend-db.md) | 3, 5, 7, 8, 10, 12, 16, 17, 24, 25 | API, server code, queries, DB | +| [infra.md](references/infra.md) | 6, 9, 11, 18, 19, 27, 28, 30 | Hosting, CDN, headers, deps, monitoring | + +## Forbidden + +- Editing code during the audit, or before the owner validates the rule numbers +- Building an architecture rule (7, 10, 18, 19, 28) without the owner's go +- A status without evidence; a gain presented as measured when it is estimated +- Blanket changes outside the current task in default mode diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/backend-db.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/backend-db.md new file mode 100644 index 0000000..01a0f56 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/backend-db.md @@ -0,0 +1,65 @@ +--- +name: backend-db +description: Backend and database rules (3, 5, 7, 8, 10, 12, 16, 17, 24, 25) -- what to check per stack, how to measure, existing tool, nuance. +when-to-use: Audit mode when the project has server code or a database (Next.js server, TanStack Start server functions, Laravel, Prisma, Eloquent) +keywords: request-cache, pagination, job-queue, n+1, redis, timeout, parallel, index, select, connection-pool +--- + +# Backend + DB Rules + +Numbering is global (1-31). Each rule: **Check**, **Measure**, **Tool** (existing Fusengine skill when one covers it), **Nuance**. Rules tagged **proposal** are architecture: report them, never build them without the owner's go. + +Measurement for this domain: request timings from server logs or APM; query counts/durations from the ORM log (Prisma `log: ['query']`, Laravel `DB::listen` / Telescope / Debugbar if installed); `EXPLAIN` on the slow queries. No logs and no DB access -> status `not verifiable from code`, ranking `estimated`. + +### 3. No duplicate API calls, shared request cache +- **Check**: the same endpoint fetched by several components; React/Vite: raw `fetch` in effects vs TanStack Query keys; Next.js: request memoization of `fetch`, `React.cache()` for non-fetch data loaders; Laravel: repeated identical queries per request. +- **Measure**: `browser_network` on one page load -- same URL more than once; query log duplicates. +- **Nuance**: two calls with different params are not duplicates; polling is intentional. + +### 5. Paginated API results +- **Check**: list endpoints returning `findMany()` without `take`/cursor, `Model::all()`/`->get()` on unbounded tables; Laravel `paginate()`/`cursorPaginate()`. +- **Measure**: response size and time of list endpoints on realistic data volume. +- **Nuance**: small bounded reference tables (countries, roles) may return everything. + +### 7. Slow tasks in a job queue (proposal) +- **Check**: mail, exports, image/PDF processing, AI calls done inside the HTTP request; Laravel `Mail::send` vs `queue`, jobs implementing `ShouldQueue`; Node: work awaited in route handlers/server actions. +- **Measure**: p95 duration of the affected endpoints. +- **Tool**: `fuse-laravel:laravel-queues` for Laravel; for Node stacks the choice of queue is an architecture decision. +- **Nuance**: Laravel already ships queues (config change, not new infra); a new broker for a Node app is a proposal. Next.js `after()` covers light post-response work without a queue. + +### 8. N+1 queries fixed +- **Check**: queries inside loops; Prisma relations loaded per item instead of `include`/`select`; Eloquent relations accessed in loops without `with()`. Laravel: `Model::preventLazyLoading(! app()->isProduction())` in `AppServiceProvider` surfaces them. +- **Measure**: query count per request before/after. +- **Tool**: `/prisma-optimize` (Prisma N+1 + indexes); `fuse-laravel:laravel-eloquent`. + +### 10. Redis cache on hot data (proposal) +- **Check**: expensive reads repeated across requests (config, catalog, aggregates); existing cache layer (`Cache::remember`, Next.js `"use cache"`/`unstable_cache`, CDN). +- **Measure**: hit frequency and duration of the hot queries. +- **Nuance**: use the framework cache first; adding Redis is infrastructure -> proposal. Cache invalidation risk counts in the ranking. + +### 12. Timeouts on external APIs +- **Check**: outbound `fetch` without `signal: AbortSignal.timeout(ms)`; axios without `timeout`; Laravel `Http::` without `timeout()`/`connectTimeout()` (Laravel defaults: 30 s response, 10 s connect); AI SDK calls without abort/timeout. +- **Measure**: worst-case latency when the dependency hangs (mock a slow upstream in a test). +- **Nuance**: pick the value from the dependency's measured p99, keep it configurable; pair with retry only for idempotent calls. + +### 16. Independent requests in parallel +- **Check**: consecutive `await`s that do not depend on each other (`await a(); await b();`); Next.js sequential data fetching in server components; Laravel sequential `Http::` calls (use `Http::pool`). +- **Measure**: endpoint/page time vs the sum of the individual calls. +- **Nuance**: keep sequential when the second call needs the first result, or to respect a rate limit. + +### 17. DB indexes on filter/sort columns +- **Check**: columns in `where`/`orderBy`/joins vs `@@index`/`@unique` in `schema.prisma`, `$table->index()` in Laravel migrations; foreign keys without index (MySQL indexes FKs, PostgreSQL does not). +- **Measure**: `EXPLAIN` / `EXPLAIN ANALYZE` on the slow queries (sequential scan on large tables). +- **Tool**: `/prisma-optimize`; `fuse-laravel:laravel-migrations`. +- **Nuance**: every index slows writes -- index what is queried, not every column. + +### 24. Only needed columns, no SELECT * +- **Check**: Prisma queries without `select`/`omit` returning large columns (text, JSON, blobs); Eloquent `->get()` vs `->select([...])`; raw `SELECT *`. +- **Measure**: payload size and query time on wide tables. +- **Nuance**: `SELECT *` is fine when all columns are used and none are large; do not trade readability for a few bytes. + +### 25. DB connection pool +- **Check**: Prisma 7 -- pool configured on the driver adapter (`@prisma/adapter-pg` etc.), single `PrismaClient` instance (no client per request / per hot reload); serverless -> a pooler (PgBouncer, provider pooler); Laravel -- persistent connections, Octane workers, PgBouncer in front of PostgreSQL. +- **Measure**: connection count and "too many connections"/pool timeout errors under load. +- **Tool**: `fuse-nextjs:prisma-7` (connection pooling reference). +- **Nuance**: PHP-FPM opens one connection per request by design -- a pooler is an infra decision, not a code fix. diff --git a/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/front.md b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/front.md new file mode 100644 index 0000000..cf92827 --- /dev/null +++ b/.cursor-plugin/plugins/fuse-ai-pilot/skills/web-performance/references/front.md @@ -0,0 +1,80 @@ +--- +name: front +description: Front-end rules (1, 2, 4, 13, 14, 15, 20, 21, 22, 23, 26, 29, 31) -- what to check per stack, how to measure, existing tool, nuance. +when-to-use: Audit mode when the project has a UI (Next.js, React/Vite, Astro, TanStack Start, Blade/Inertia) +keywords: skeleton, images, avif, lazy-load, debounce, streaming, optimistic-ui, ssr, third-party, code-splitting, virtualization, re-render, fonts, throttling +--- + +# Front-end Rules + +Numbering is global (1-31) so reports stay comparable. Each rule: **Check** (where to look), **Measure**, **Tool** (existing Fusengine skill when one covers it), **Nuance** (when the rule is not absolute). + +Lab measurement for this domain: Lighthouse performance run on the running app -- `bun /scripts/check-cwv.ts ` (deps in the seo plugin's package.json; reports LCP, CLS, TBT as INP proxy) or `npx lighthouse --only-categories=performance --output=json --output-path=`. Request lists: fuse-browser `browser_network` in a session (method, url, status, resourceType) -- see `fuse-ai-pilot:fuse-browser-usage`. + +### 1. Skeleton screens instead of spinners +- **Check**: grep `Spinner|Loader|animate-spin|CircularProgress` in loading states; Next.js `loading.tsx`, React ``, Astro `server:defer` fallbacks. +- **Measure**: CLS during loading (Lighthouse), visual check with a screenshot mid-load. +- **Nuance**: a skeleton pays when the final layout is predictable (lists, cards, profile). Unknown shape or sub-second actions (button submit) -> a spinner is fine. + +### 2. Images in WebP/AVIF with responsive sizes +- **Check**: raw ``; Next.js `next/image` with `sizes`; Astro ``/`` from `astro:assets`; Vite/React: `srcset` + ``; Laravel Blade: `` without `srcset`. +- **Measure**: Lighthouse "Serve images in modern formats" / "Properly size images", transferred image bytes. +- **Tool**: `fuse-seo:seo-images` (formats, `srcset`/`sizes`, explicit dimensions). +- **Nuance**: SVG icons and tiny images are out of scope. + +### 4. Debounce search and autocomplete +- **Check**: `onChange`/`onInput` handlers that call `fetch`, a query hook or a server action directly; look for `useDebounce`, `debounce(`, `useDeferredValue`. +- **Measure**: count requests per typed word with `browser_network` (`urlContains` = the search endpoint). +- **Nuance**: purely local filtering of a small in-memory list needs no debounce; `useDeferredValue` covers render cost, not network calls. + +### 13. Stream AI responses token by token +- **Check**: AI SDK calls -- `generateText` vs `streamText` (Vercel AI SDK), `stream: true` on provider SDKs, Laravel AI responses returned in one block; UI waits on a single `await`. +- **Measure**: time to first visible token vs time to full response. +- **Nuance**: not for structured outputs consumed by code (JSON to parse) or background jobs. `not applicable` when the app has no AI output. + +### 14. Optimistic UI with rollback on error +- **Check**: mutations that wait for the server before updating UI; TanStack Query `onMutate` + `onError` rollback; React `useOptimistic`; Livewire/Inertia equivalents. +- **Measure**: delay between click and visible change with network throttled. +- **Nuance**: only when the outcome is predictable and reversible (like, toggle, reorder). Payments, irreversible or server-validated actions -> show pending state instead. + +### 15. Lazy-load below-the-fold images +- **Check**: `loading="lazy"` on below-fold ``; Next.js `next/image` lazy by default -- verify the LCP image is not lazy (Next.js 16: `loading="eager"` or `fetchPriority="high"` on the LCP image (`preload` only when needed; `priority` is deprecated); plain HTML: `fetchpriority="high"`); Astro `` is lazy by default (`priority` prop for the LCP image). +- **Measure**: initial image bytes and LCP (Lighthouse "Defer offscreen images", "LCP request discovery"). +- **Tool**: `fuse-seo:seo-images`. +- **Nuance**: lazy-loading the LCP/hero image is a regression, not a fix. + +### 20. Server-side or build-time rendering +- **Check**: Next.js App Router -- `"use client"` at page/layout level; React/Vite SPA with data fetched in effects; Astro -- islands with `client:load` everywhere; TanStack Start loaders; Laravel Blade/Inertia SSR. +- **Measure**: LCP and FCP; HTML response contains the content (`curl `). +- **Nuance**: internal dashboards behind auth may stay client-rendered; changing the rendering model of a SPA is a large change -> rank by effort honestly. + +### 21. Third-party scripts deferred +- **Check**: `