From 78e10dddda91ea90a7f1bef7828fcb8ee202f9c1 Mon Sep 17 00:00:00 2001 From: metaphorics <152830360+metaphorics@users.noreply.github.com> Date: Sat, 6 Jun 2026 22:40:18 +0900 Subject: [PATCH 01/40] refactor(lfg)!: drop the lfg skill Removed from the plugin; the legacy-cleanup registries now fingerprint and sweep stale installs on upgrade. BREAKING CHANGE: removes the lfg skill. Op: correct Restores: spec:fork-slimness (AGENTS.md Scope & Lineage) --- .../beta-promotion-orchestration-contract.md | 1 - .../skill-design/beta-skills-framework.md | 8 +- ...e-prefix-required-for-skills-and-agents.md | 7 +- .../ce-work-beta-promotion-checklist.md | 2 +- .../release-please-version-drift-recovery.md | 2 +- plugins/compound-engineering/AGENTS.md | 2 +- plugins/compound-engineering/README.md | 3 +- .../skills/ce-plan/references/plan-handoff.md | 2 +- .../ce-work/references/tracker-defer.md | 4 +- .../compound-engineering/skills/lfg/SKILL.md | 112 ------------- .../skills/lfg/references/review-followup.md | 44 ------ .../skills/lfg/references/tracker-defer.md | 149 ------------------ src/data/plugin-legacy-artifacts.ts | 1 + src/utils/legacy-cleanup.ts | 7 + tests/frontmatter.test.ts | 3 +- tests/review-skill-contract.test.ts | 53 ------- tests/skill-agent-ce-prefix.test.ts | 5 +- 17 files changed, 23 insertions(+), 382 deletions(-) delete mode 100644 plugins/compound-engineering/skills/lfg/SKILL.md delete mode 100644 plugins/compound-engineering/skills/lfg/references/review-followup.md delete mode 100644 plugins/compound-engineering/skills/lfg/references/tracker-defer.md diff --git a/docs/solutions/skill-design/beta-promotion-orchestration-contract.md b/docs/solutions/skill-design/beta-promotion-orchestration-contract.md index 1cc66dc15..f74f693d9 100644 --- a/docs/solutions/skill-design/beta-promotion-orchestration-contract.md +++ b/docs/solutions/skill-design/beta-promotion-orchestration-contract.md @@ -32,7 +32,6 @@ Treat promotion as an orchestration contract change, not a file rename. This pattern was applied when promoting the review beta (`ce-review-beta`, tracked as the legacy artifact `ce:review-beta`/`ce-review-beta` in the cleanup registry) into the stable `ce-code-review` skill. The caller contract: -- `lfg` -> `/ce-code-review mode:autofix` (enforced by `tests/review-skill-contract.test.ts`) - `slfg` parallel phase -> `/ce-code-review mode:report-only` (intended; not currently covered by a contract test) ## Prevention diff --git a/docs/solutions/skill-design/beta-skills-framework.md b/docs/solutions/skill-design/beta-skills-framework.md index a2aa17eb0..7f26ebc05 100644 --- a/docs/solutions/skill-design/beta-skills-framework.md +++ b/docs/solutions/skill-design/beta-skills-framework.md @@ -18,7 +18,7 @@ related: ## Problem -Core workflow skills like `ce-plan` are deeply chained (`ce-brainstorm` → `ce-plan` → `ce-work`) and orchestrated by `lfg` and `slfg`. Rewriting these skills risks breaking the entire workflow for all users simultaneously. There was no mechanism to let users trial new skill versions alongside stable ones. +Core workflow skills like `ce-plan` are deeply chained (`ce-brainstorm` → `ce-plan` → `ce-work`) and orchestrated by autonomous workflows. Rewriting these skills risks breaking the entire workflow for all users simultaneously. There was no mechanism to let users trial new skill versions alongside stable ones. Alternatives considered and rejected: - **Beta gate in SKILL.md** with config-driven routing (`beta: true` in `compound-engineering.local.md`): relies on prompt-level conditional routing which risks instruction blending, requires setup integration, and adds complexity to the skill files themselves. @@ -54,13 +54,13 @@ Beta skills must reference other beta skills by their beta names. For example, i ### What doesn't change - Stable skills are completely untouched -- `lfg`/`slfg` orchestration continues to use stable skills — no modification needed +- Autonomous orchestration continues to use stable skills — no modification needed - `ce-brainstorm` still hands off to stable `ce-plan` — no modification needed - `ce-work` consumes plan files from either version (reads the file, doesn't care which skill wrote it) ### Tradeoffs -**Simplicity over seamless integration.** Beta skills exist as standalone, manually-invoked skills. They won't be auto-triggered by `ce-brainstorm` handoffs or `lfg`/`slfg` orchestration without further surgery to those skills, which isn't worth the complexity for a trial period. +**Simplicity over seamless integration.** Beta skills exist as standalone, manually-invoked skills. They won't be auto-triggered by `ce-brainstorm` handoffs or autonomous workflows without further surgery, which isn't worth the complexity for a trial period. **Intended usage pattern:** A user can run `/ce-plan` for the stable output, then run `/ce-plan-beta` on the same input to compare the two plan documents side by side. The `-beta-plan.md` suffix ensures both outputs coexist in `docs/plans/` without collision. @@ -75,7 +75,7 @@ When the beta version is validated: 5. Restore stable plan file naming (remove `-beta` from the convention) 6. Delete the beta skill directory 7. Update README.md: remove from Beta Skills section, verify counts -8. Verify `lfg`/`slfg` work with the promoted skill +8. Verify autonomous workflows work with the promoted skill 9. Verify `ce-work` consumes plans from the promoted skill If the beta skill changed its invocation contract, promotion must also update all orchestration callers in the same PR instead of relying on the stable default behavior. See [beta-promotion-orchestration-contract.md](./beta-promotion-orchestration-contract.md) for the concrete review-skill example. diff --git a/docs/solutions/skill-design/ce-prefix-required-for-skills-and-agents.md b/docs/solutions/skill-design/ce-prefix-required-for-skills-and-agents.md index bd55d2641..25e053fca 100644 --- a/docs/solutions/skill-design/ce-prefix-required-for-skills-and-agents.md +++ b/docs/solutions/skill-design/ce-prefix-required-for-skills-and-agents.md @@ -23,7 +23,7 @@ related_pr: https://github.com/EveryInc/compound-engineering-plugin/pull/747 ## Problem -`plugins/compound-engineering/AGENTS.md` already stated that "all skills and agents use the `ce-` prefix to unambiguously identify them as compound-engineering components." But the rule was prose-only, and legacy skills sat unprefixed in the same directory as their `ce-`-prefixed siblings. The combination — a soft rule plus visible exceptions — let a new skill (`riffrec-feedback-analysis`) ship in PR #747 without the prefix. The user caught it post-merge of the first commit, requiring a rename commit on the same PR. (That skill is now `ce-riffrec-feedback-analysis`; the once-unprefixed `every-style-editor` and `file-todos` skills have since been removed, leaving `lfg` as the sole exemption.) +`plugins/compound-engineering/AGENTS.md` already stated that "all skills and agents use the `ce-` prefix to unambiguously identify them as compound-engineering components." But the rule was prose-only, and legacy skills sat unprefixed in the same directory as their `ce-`-prefixed siblings. The combination — a soft rule plus visible exceptions — let a new skill (`riffrec-feedback-analysis`) ship in PR #747 without the prefix. The user caught it post-merge of the first commit, requiring a rename commit on the same PR. (That skill is now `ce-riffrec-feedback-analysis`; the once-unprefixed `every-style-editor` and `file-todos` skills remain as legacy exemptions.) A prose convention that has visible counterexamples and no machine check is, in practice, an *advisory* convention. Any author skim-reading the directory listing sees an unprefixed skill next to `ce-brainstorm` and reasonably concludes the prefix is optional. @@ -47,10 +47,7 @@ const PREFIX = "ce-" // Exemptions from the ce- prefix rule. Add entries here only with a written // reason — the exemption list shouldn't become a silent junk drawer. -const SKILL_EXEMPTIONS = new Set([ - // lfg ships as the public command `/lfg` (see plugins/compound-engineering/README.md). - "lfg", -]) +const SKILL_EXEMPTIONS = new Set([]) const AGENT_EXEMPTIONS = new Set([]) ``` diff --git a/docs/solutions/skill-design/ce-work-beta-promotion-checklist.md b/docs/solutions/skill-design/ce-work-beta-promotion-checklist.md index d25b55326..beaf87b97 100644 --- a/docs/solutions/skill-design/ce-work-beta-promotion-checklist.md +++ b/docs/solutions/skill-design/ce-work-beta-promotion-checklist.md @@ -18,7 +18,7 @@ related: ## Problem -`ce-work-beta` is intentionally a manual-invocation beta skill. During beta, `ce-plan`, `ce-brainstorm`, `lfg`, `slfg`, and other workflow handoffs remain pointed at stable `ce-work` so the repo does not need to support two execution paths at once. +`ce-work-beta` is intentionally a manual-invocation beta skill. During beta, `ce-plan`, `ce-brainstorm`, and other workflow handoffs remain pointed at stable `ce-work` so the repo does not need to support two execution paths at once. That means promoting `ce-work-beta` to stable is not just a content copy. The rollout flips multiple contracts at once: diff --git a/docs/solutions/workflow/release-please-version-drift-recovery.md b/docs/solutions/workflow/release-please-version-drift-recovery.md index a78b2bbfc..d959fd6ca 100644 --- a/docs/solutions/workflow/release-please-version-drift-recovery.md +++ b/docs/solutions/workflow/release-please-version-drift-recovery.md @@ -183,7 +183,7 @@ Recovery used Path A (forward-sync to 3.0.7) because: - Path B would have orphaned those caches and triggered version-regression warnings - Path C would have reintroduced a `release-as` pin that had just been cleaned up -PR #678 applied the full Path A fix across five fields in four files and updated a stale test assertion that was also hiding behind the release-validate failure (commit `1f20c384` renumbered steps in `lfg/SKILL.md` but didn't update `tests/review-skill-contract.test.ts`). See PR #678's commits for the exact diff. +PR #678 applied the full Path A fix across five fields in four files and updated a stale test assertion that was also hiding behind the release-validate failure. See PR #678's commits for the exact diff. ## Prevention diff --git a/plugins/compound-engineering/AGENTS.md b/plugins/compound-engineering/AGENTS.md index 8c20de723..dba675384 100644 --- a/plugins/compound-engineering/AGENTS.md +++ b/plugins/compound-engineering/AGENTS.md @@ -88,7 +88,7 @@ Important: Just because the developer's installed plugin may be out of date, it' **Agents** follow the same convention: `ce-adversarial-reviewer`, `ce-learnings-researcher`, etc. When referencing agents from skills, use the bare `ce-` form (e.g., `ce-adversarial-reviewer`) — the `ce-` prefix is sufficient for uniqueness across plugins. -**The `ce-` prefix is required for every new skill and agent — no exceptions.** Three legacy skills (`every-style-editor`, `file-todos`, `lfg`) predate the rule and remain unprefixed; they are pinned in `tests/frontmatter.test.ts` as the only allowed exceptions. Do not add to that allowlist. When adding a new skill, the directory name, the SKILL.md `name:` frontmatter, and any README references must all start with `ce-`. The frontmatter test enforces this and will fail on a missing prefix. +**The `ce-` prefix is required for every new skill and agent — no exceptions.** Two legacy skills (`every-style-editor`, `file-todos`) predate the rule and remain unprefixed; they are pinned in `tests/frontmatter.test.ts` as the only allowed exceptions. Do not add to that allowlist. When adding a new skill, the directory name, the SKILL.md `name:` frontmatter, and any README references must all start with `ce-`. The frontmatter test enforces this and will fail on a missing prefix. ## Skill Design Principles diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 24b96306c..f27c46a07 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,7 +11,7 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 37 | -| Skills | 28 | +| Skills | 27 | ## Skills @@ -80,7 +80,6 @@ The primary entry points for engineering work, invoked as slash commands. Detail | Skill | Description | |-------|-------------| | `/ce-dogfood-beta` | Diff-scoped browser QA of the active branch: builds an exhaustive test matrix of every change, drives the app with agent-browser, then auto-fixes issues, adds regression tests, and commits each fix until green | -| `/lfg` | Full autonomous engineering workflow | ## Agents diff --git a/plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md b/plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md index 69a87a948..c857881d3 100644 --- a/plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md +++ b/plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md @@ -49,7 +49,7 @@ After all mutations in this run have settled (initial write, deepening synthesis ## 5.4 Post-Generation Options -**Pipeline mode:** If invoked from an automated workflow such as LFG or any `disable-model-invocation` context, skip the interactive menu below and return control to the caller immediately. The plan file has already been written, the confidence check has already run, and ce-doc-review has already run — the caller (e.g., lfg) determines the next step. +**Pipeline mode:** If invoked from an automated workflow such as LFG or any `disable-model-invocation` context, skip the interactive menu below and return control to the caller immediately. The plan file has already been written, the confidence check has already run, and ce-doc-review has already run — the caller determines the next step. **Path format:** Use absolute paths for chat-output file references — relative paths are not auto-linked as clickable in most terminals. diff --git a/plugins/compound-engineering/skills/ce-work/references/tracker-defer.md b/plugins/compound-engineering/skills/ce-work/references/tracker-defer.md index c08c7d93d..7d4ce88ac 100644 --- a/plugins/compound-engineering/skills/ce-work/references/tracker-defer.md +++ b/plugins/compound-engineering/skills/ce-work/references/tracker-defer.md @@ -1,6 +1,6 @@ # Tracker Detection and Defer Execution -This reference covers how residual actionable findings are filed in the project's tracker. Loaded by caller workflows (for example `ce-work` Residual Work Gate, or `lfg` residual handling) — not by `ce-code-review`, which stops after the report. +This reference covers how residual actionable findings are filed in the project's tracker. Loaded by caller workflows (for example `ce-work` Residual Work Gate) — not by `ce-code-review`, which stops after the report. --- @@ -18,7 +18,7 @@ Used by `ce-work` Residual Work Gate and similar caller flows when the user choo ### Non-interactive mode -Used by autonomous callers like `lfg` that must not prompt. All blocking questions are skipped; the fallback chain is executed silently in order. Behavior: +Used by autonomous callers that must not prompt. All blocking questions are skipped; the fallback chain is executed silently in order. Behavior: - No confirmation on the first generic-label Defer; proceed directly. - On execution failure, automatically fall to the next tier without prompting. Record the failure. diff --git a/plugins/compound-engineering/skills/lfg/SKILL.md b/plugins/compound-engineering/skills/lfg/SKILL.md deleted file mode 100644 index bf5ff494b..000000000 --- a/plugins/compound-engineering/skills/lfg/SKILL.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -name: lfg -description: Run the full autonomous engineering pipeline end-to-end (plan, work, code review, test, commit, push, open PR, watch CI, fix CI failures until green). Use only when the user explicitly requests hands-off execution of a software task and provides a feature description; do not auto-route casual conversation here. -argument-hint: "[feature description]" ---- - -CRITICAL: You MUST execute every step below IN ORDER. Do NOT skip any required step. Do NOT jump ahead to coding or implementation. The plan phase (step 1) MUST be completed and verified BEFORE any work begins. Violating this order produces bad output. - -When invoking any skill referenced below, resolve its name against the available-skills list the host platform provides and use that exact entry. Some platforms list skills under a plugin namespace (e.g., `compound-engineering:ce-plan`); others list the bare name. Invoking a short-form guess that isn't in the list will fail — always match a listed entry verbatim before calling the Skill/Task tool. - -1. Invoke the `ce-plan` skill with `$ARGUMENTS`. - - GATE: STOP. If ce-plan reported the task is non-software and cannot be processed in pipeline mode, stop the pipeline and inform the user that LFG requires software tasks. Otherwise, verify that the `ce-plan` workflow produced a plan file in `docs/plans/`. If no plan file was created, invoke `ce-plan` again with `$ARGUMENTS`. Do NOT proceed to step 2 until a written plan exists. **Record the plan file path** — it will be passed to ce-code-review in step 3. - -2. Invoke the `ce-work` skill. - - GATE: STOP. Verify that implementation work was performed - files were created or modified beyond the plan. Do NOT proceed to step 3 if no code changes were made. - -3. Invoke the `ce-code-review` skill with `mode:agent plan:`. - - Pass the plan file path from step 1 so ce-code-review can verify requirements completeness. Read the **Actionable Findings** summary the skill emits. - -4. **Apply and persist review fixes** (REQUIRED after step 3, before residual handoff) - - Load `references/review-followup.md` and execute step 4 there (mechanical apply + commit/push when changes exist). Do not proceed to step 5, run browser tests, or output DONE while eligible review fixes remain only in the working tree uncommitted. - -5. **Autonomous residual handoff** (only when step 3 reported one or more actionable `downstream-resolver` findings not applied in step 4; skip when it reported `Actionable findings: none.`) - - Do not prompt the user. This step embraces the autopilot contract: residuals must become durable before DONE, but the agent never stops to ask. - - 1. Load `references/tracker-defer.md` in **non-interactive mode**. Pass the residual actionable findings from step 3/4 (or the run artifact when the summary was truncated). - 2. Collect the structured return: `{ filed: [...], failed: [...], no_sink: [...] }`. - 3. Compose a `## Residual Review Findings` markdown section from the structured return: - - For each item in `filed`: a bullet with severity, file:line, title, and a link to the tracker ticket URL. - - For each item in `failed`: a bullet with severity, file:line, title, and the failure reason (e.g., `Defer failed: gh returned 401 — tracker unavailable`). - - For each item in `no_sink`: a bullet with severity, file:line, and title inlined verbatim so the PR body or fallback file is the durable record. - 4. Detect the current branch's open PR without prompting: - - ```bash - gh pr view --json number,url,body,state - ``` - - 5. If an open PR exists, update it directly with `gh`; do not load any confirmation-driven PR update skill. Append or replace the `## Residual Review Findings` section in the current PR body, write the new body to an OS temp file, then run: - - ```bash - gh pr edit PR_NUMBER --body-file BODY_FILE - ``` - - 6. If no open PR exists, create a tracked fallback file at `docs/residual-review-findings/.md` containing the composed section and the source PR-review run context. Stage only that file, commit it with `docs(review): record residual review findings`, and push the current branch. If an upstream exists, run `git push`. If no upstream exists, resolve a writable remote dynamically: prefer `origin` when present, otherwise use `git remote` and choose the first configured remote. Then run `git push --set-upstream HEAD`. This is the durable no-PR sink. Do not output DONE until either the existing PR body has been updated or this fallback file commit has been pushed. If both paths fail, stop and report the failed commands; do not silently proceed. - - Never block DONE on tracker filing failures once residuals have been durably recorded. A `no_sink` outcome is success only when the findings are present in the PR body or in the pushed fallback file. - -6. Invoke the `ce-test-browser` skill with `mode:pipeline`. - -7. Invoke the `ce-commit-push-pr` skill. - - This commits any remaining changes, pushes the branch, and opens a pull request. If step 5 already opened a PR (check with `gh pr view --json number,url,state 2>/dev/null`), skip PR creation but still commit and push any uncommitted changes. - -8. **CI watch and autofix loop** (only when an open PR exists for the current branch) - - Detect the PR; if none exists or `gh` is unavailable, skip this step entirely and proceed to step 9. - - ```bash - gh pr view --json number,url,state - ``` - - For up to **3 fix iterations**, repeat: - - 1. Wait for CI to complete: - - ```bash - gh pr checks --watch - ``` - - If the command exits 0, all checks passed. Break out of the loop and proceed to step 9. - - If it exits non-zero, one or more checks failed. Continue to (2). - - 2. Identify failing checks and pull their failure logs. Use `gh pr checks --json name,state,conclusion,workflow,link` to enumerate failures, then for each failing check read the run logs: - - ```bash - gh run view --log-failed - ``` - - where `` is parsed from the check's details URL or workflow run. - - 3. Read the failure logs, identify the root cause, and apply a fix in the working tree. Do NOT weaken, skip, or mock the failing assertion to make it pass — repair the actual issue. If the failure is a flaky test that has no fix path, document that as the residual outcome below rather than retrying without a code change. - - 4. Stage only the files you changed, commit, and push: - - ```bash - git add - git commit -m "fix(ci): " - git push - ``` - - 5. Return to iteration (1) with the next attempt counter. - - GATE: STOP iterating after 3 failed attempts. If CI is still red after 3 fix cycles: - - - Compose a `## CI Failures Unresolved` markdown section listing each remaining failing check, the failure summary, and the run/check URL. - - Append or replace this section in the PR body, write the new body to an OS temp file, then run: - - ```bash - gh pr edit PR_NUMBER --body-file BODY_FILE - ``` - - - Do NOT continue looping. The autopilot contract is "make residuals durable, then exit." Proceed to step 9. - -9. Output `DONE` when complete - -Start with step 1 now. Remember: plan FIRST, then work. Never skip the plan. diff --git a/plugins/compound-engineering/skills/lfg/references/review-followup.md b/plugins/compound-engineering/skills/lfg/references/review-followup.md deleted file mode 100644 index 7f9e1d0dd..000000000 --- a/plugins/compound-engineering/skills/lfg/references/review-followup.md +++ /dev/null @@ -1,44 +0,0 @@ -# Review followup (LFG step 3–4) - -`ce-code-review` is review-only. LFG applies eligible fixes itself, then commits. - -## Step 3 — invoke review - -``` -ce-code-review mode:agent plan: -``` - -Read the **Actionable Findings** summary and artifact path. - -Capture parsed JSON (`status`, `actionable_findings`, `findings`, `artifact_path`, `run_id`) or the markdown Actionable Findings section. If `status` is `failed`, stop and surface `reason`. - -## Step 4 — apply and persist review fixes - -### What to apply - -Apply a finding in the working tree only when **all** of the following hold: - -1. **`suggested_fix` is present** — concrete change shape from the reviewer. -2. **`confidence` is `100`, or `75` with cross-persona agreement noted in the report** — do not apply anchor-50 findings. -3. **The fix is mechanical** — one coherent change, no contract/permission/security posture change, no new public API shape, no behavior change that needs product sign-off. -4. **Evidence still matches the code** at the cited `file:line` before editing. - -Do not treat `autofix_class` as permission to auto-apply. - -### What not to apply - -- `autofix_class: manual` without a clear mechanical `suggested_fix` -- `autofix_class: advisory` — report-only -- `gated_auto` findings that change behavior, contracts, auth, or permissions -- Anything that needs a design conversation - -### Execution - -1. Filter `actionable_findings` (or markdown Actionable Findings) with the bar above. -2. Apply eligible fixes in the working tree in severity order (`#` stable from the review). -3. Run targeted tests when `requires_verification: true` on any applied finding. -4. If `git status --short` shows changes, stage only review-driven files, commit `fix(review): apply review findings`, and push before step 5. To push: if an upstream exists, run `git push`. If no upstream exists (common on a fresh feature branch, since step 7's `ce-commit-push-pr` has not run yet), resolve a writable remote dynamically: prefer `origin` when present, otherwise use `git remote` and choose the first configured remote. Then run `git push --set-upstream HEAD`. If no eligible fixes were applied, note explicitly and skip commit. - -## Step 5 — residual handoff - -Residuals are actionable findings **not** applied in step 4 — not leftovers from in-skill autofix. Use the Actionable Findings summary / artifact from step 3. diff --git a/plugins/compound-engineering/skills/lfg/references/tracker-defer.md b/plugins/compound-engineering/skills/lfg/references/tracker-defer.md deleted file mode 100644 index 3b088afd9..000000000 --- a/plugins/compound-engineering/skills/lfg/references/tracker-defer.md +++ /dev/null @@ -1,149 +0,0 @@ -# Tracker Detection and Defer Execution - -This reference covers how Defer actions file tickets in the project's tracker. It is loaded by `SKILL.md` when Interactive mode's routing question needs to decide whether to offer option C (File tickets), when the walk-through's Defer option executes, and when the bulk-preview of option C is shown. It is also loaded by autonomous callers (e.g., `lfg`) that need to file residual actionable findings without user prompts — see Execution Modes below. - ---- - -## Execution Modes - -Tracker-defer has two execution modes. The caller selects one; the detection, fallback chain, and ticket composition are shared. - -### Interactive mode (default) - -Used by `ce-code-review` Interactive mode's routing question, walk-through Defer actions, and bulk-preview option C. All user-facing prompts fire: - -- First Defer of the session with a generic (non-named) label confirms the effective tracker choice. -- Execution failures prompt with Retry / Fall back to next sink / Convert to Skip. -- Labels in the routing question reflect `named_sink_available` (name the tracker) vs fallback generics. - -### Non-interactive mode - -Used by autonomous callers like `lfg` that must not prompt. All blocking questions are skipped; the fallback chain is executed silently in order. Behavior: - -- No confirmation on the first generic-label Defer; proceed directly. -- On execution failure, automatically fall to the next tier without prompting. Record the failure. -- On total chain exhaustion (every tier failed or no sink available), return findings in the `no_sink` bucket so the caller can route them to another surface (e.g., inline them in a PR description). -- Return a structured result: `{ filed: [{ finding_id, tracker, url }], failed: [{ finding_id, tracker, reason }], no_sink: [{ finding_id, title, severity, file, line }] }`. - -The caller decides how to surface the result to the user. The non-interactive mode treats "no sink available" as a data-producing outcome, not a prompt trigger. - ---- - -## Detection - -The agent determines the project's tracker from whatever documentation is obvious. Primary sources: `CLAUDE.md` and `AGENTS.md` at the repo root and in relevant subdirectories. Supplementary signals (when primary documentation is ambiguous): `CONTRIBUTING.md`, `README.md`, PR templates under `.github/`, visible tracker URLs in the repo. - -A tracker can be surfaced via MCP tool (e.g., a Linear MCP server), CLI (e.g., `gh`), or direct API. All are acceptable. The detection output is a tuple with two availability flags — one for the named tracker specifically (drives label confidence in Interactive mode) and one for the full fallback chain (drives whether Defer is offered at all): - -``` -{ tracker_name, confidence, named_sink_available, any_sink_available } -``` - -Where: -- `tracker_name` — human-readable name ("Linear", "GitHub Issues", "Jira"), or `null` when detection cannot identify a specific tracker -- `confidence` — `high` when the tracker is named explicitly in documentation (or via a linked URL to a specific project/workspace) and is unambiguously the project's canonical tracker; `low` when the signal is thin, conflicting, or implied only -- `named_sink_available` — `true` only when the agent can actually invoke the detected tracker (MCP tool is loaded, CLI is authenticated, or API credentials are in environment); `false` when the tracker is documented but no tool reaches it, or when no tracker is found at all. Drives label confidence: inline tracker naming requires this to be `true`. -- `any_sink_available` — `true` when any tier in the fallback chain (named tracker or GitHub Issues via `gh`) can be invoked this session. Drives whether Defer is offered in Interactive mode, and drives the `no_sink` bucket in Non-interactive mode. - -Detection is reasoning-based. Do not maintain an enumerated checklist of files to read. Read the obvious sources and form a confident conclusion; when the obvious sources don't resolve, the label falls back to generic wording and the agent confirms with the user before executing (Interactive mode only). - ---- - -## Probe timing and caching - -Availability probes run **at most once per session** and **only when Defer execution is imminent**. Never speculatively at review start, never per-Defer, never per-walk-through-finding. The cached tuple is reused for every Defer action in the same run. - -Typical probe sequence: - -1. Read `CLAUDE.md` / `AGENTS.md` for tracker references. If nothing found, set `tracker_name = null`, `confidence = low`. -2. **Probe the named tracker when one was found.** For GitHub Issues, run `gh auth status` and `gh repo view --json hasIssuesEnabled`. For Linear or other MCP-backed trackers, verify the relevant MCP tool is loaded and responsive. For API-backed trackers, verify credentials in environment. Set `named_sink_available` from the probe result. -3. **Probe the GitHub Issues fallback to compute `any_sink_available`.** Even when the named tracker was found and probed, `gh` matters for the `no_sink` bucket decision so that a run with no documented tracker but working `gh` still offers Defer. - - If `named_sink_available = true`: `any_sink_available = true` (no further probes needed). - - Otherwise, probe GitHub Issues via `gh auth status` + `gh repo view --json hasIssuesEnabled` (skip if already probed in step 2). If it works, `any_sink_available = true`. - - Otherwise, `any_sink_available = false`. - -When Interactive mode's routing question is skipped entirely (R2 zero-findings case), no probes run. When the cached tuple is reused across a session, any `named_sink_available = true` from the session's first probe stays cached — do not re-probe per Defer. - ---- - -## Label logic (Interactive mode) - -- When `confidence = high` AND `named_sink_available = true`: the routing question's option C and the walk-through's per-finding Defer option both include the tracker name verbatim. Example: `File a Linear ticket per finding`, `Defer — file a Linear ticket`. -- When `any_sink_available = true` but either `confidence = low` or `named_sink_available = false` (a fallback tier is working instead): the labels read generically — `File an issue per finding`, `Defer — file a ticket`. Before executing the first Defer of the session, the agent confirms the effective tracker choice with the user using the platform's blocking question tool. -- When `any_sink_available = false`: option C is omitted from the routing question, option B (Defer) is omitted from the walk-through per-finding options, and the agent tells the user why in the routing question's stem. - -Non-interactive mode skips label decisions entirely — it acts silently on the detected sink. - ---- - -## Fallback chain - -When the named tracker is unavailable or no tracker is named, fall back in this order. Prefer the project's detected tracker; use `gh` only when no named tracker was found or the named one is unreachable. - -1. **Named tracker** (MCP tool, CLI, or API the agent can invoke directly, identified via Detection above) -2. **GitHub Issues via `gh`** — when `gh auth status` succeeds and the current repo has issues enabled (`gh repo view --json hasIssuesEnabled` returns `true`) -3. **No sink** — findings remain in the review report's residual-work section (Interactive mode) or are returned in the `no_sink` bucket for the caller to route (Non-interactive mode). The agent does not re-display them through a transient surface. - -Previously this chain included a third in-session fallback tier. That tier was removed because in-session tasks do not survive past the session and therefore do not meet the "durable filing" intent of a Defer action. When no durable tracker exists, the correct behavior is to leave findings in the report (Interactive) or return them to the caller (Non-interactive). - ---- - -## Ticket composition - -Every Defer action creates a ticket with the following content, adapted to the tracker's capabilities: - -- **Title:** the merged finding's `title` (schema-capped at 10 words). -- **Body:** - - Plain-English problem statement — reads the persona-produced `why_it_matters` from the contributing reviewer's artifact file at `/tmp/compound-engineering/ce-code-review//{reviewer}.json`, using the same `file + line_bucket(line, +/-3) + normalize(title)` matching agent mode uses (see SKILL.md Stage 6 detail enrichment). Falls back to the merged finding's `title`, `severity`, `file`, and `suggested_fix` (when present) when no artifact match is available — these fields are guaranteed in the merge-tier compact return. - - Suggested fix (when present in the finding's `suggested_fix`). - - Evidence (direct quotes from the reviewer's artifact). - - Metadata block: `Severity: `, `Confidence: `, `Reviewer(s): `, `Finding ID: `. -- **Labels** (when the tracker supports labels): severity tag (`P0`, `P1`, `P2`, `P3`) and, when the tracker convention supports it, a category label sourced from the reviewer name. -- **Length cap:** when the composed body would exceed a tracker's body length limit, truncate with `... (continued in ce-code-review run artifact: /tmp/compound-engineering/ce-code-review//)` and include the finding_id in both the truncated body and the metadata block so the artifact is discoverable. - -The finding_id is a stable fingerprint composed as `normalize(file) + line_bucket(line, +/-3) + normalize(title)` — the same fingerprint used by the merge pipeline. - ---- - -## Failure path - -When ticket creation fails at execution (API error, auth expiry mid-session, rate limit, malformed body rejected, 4xx/5xx response): - -**Interactive mode:** surface the failure inline and ask the user using the platform's blocking question tool. - -Stem: -> Defer failed: returned . How should the agent handle this finding? - -Options: -- `Retry on ` — re-attempt the same tracker once more (useful for transient errors) -- `Fall back to next sink` — move this finding's Defer to the next tier in the fallback chain (e.g., from Linear to GitHub Issues) -- `Convert to Skip — record the failure` — abandon this Defer, note the failure in the completion report's failure section, and continue the walk-through or bulk flow - -**Non-interactive mode:** do not prompt. Automatically fall through to the next tier. If every tier fails, record the finding in the `failed` bucket of the structured return and continue. If the chain exhausts with no sink ever available, the finding ends up in the `no_sink` bucket. - -When a high-confidence named tracker fails at execution, the cached `named_sink_available` is set to `false` for the rest of the session. Subsequent Defer actions fall straight through to the next tier without retrying a confirmed-broken sink. `any_sink_available` is only downgraded to `false` when every tier has been confirmed broken — a failed Linear call that succeeds via `gh` keeps `any_sink_available = true`. - -Only when `ToolSearch` explicitly returns no match or the tool call errors — or on a platform with no blocking question tool — fall back to numbered options and waiting for the user's reply (Interactive mode only). - ---- - -## Per-tracker behavior - -Concrete behavior per tracker at execution time. The agent may invoke any of these through the appropriate interface (MCP, CLI, or API) — the choice depends on what is available in the current environment. - -| Tracker | Interface | Invocation sketch | Body format | Labels | -|---------|-----------|-------------------|-------------|--------| -| Linear | MCP (preferred) or API | Create issue in the project/workspace identified by documentation; assign to the reporter if the MCP tool exposes user context | Markdown | Severity priority field if the MCP exposes it; otherwise include severity in body | -| GitHub Issues | `gh issue create` | Repo defaults to the current repo. Use `--label` for severity tag when labels exist; omit `--label` if the repo has no label fixture. Fall back to a label-less issue on first failure. | Markdown | `--label P0` / `--label P1` / etc. when labels exist | -| Jira | MCP or API | Create issue in the project identified by documentation; Jira's markdown dialect differs from GitHub's — use plain text in the body when MCP does not handle conversion | Plain text when MCP does not handle markdown | Severity priority field | -| No sink available | — | Interactive: Defer option omitted, findings remain in the report's residual-work section. Non-interactive: findings returned in the `no_sink` bucket for caller routing. | — | — | - -When uncertain, prefer "drop with explicit user-facing notice" over "pass through silently and hope." A Defer that produces no durable artifact and no user message is data loss. - ---- - -## Cross-platform notes - -The question-tool name varies by platform. In Interactive mode, use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension)). In Claude Code the tool should already be loaded from the Interactive-mode pre-load step — if it isn't, call `ToolSearch` with query `select:AskUserQuestion` now. Fall back to numbered options in chat only when the harness genuinely lacks a blocking tool — `ToolSearch` returns no match, the tool call explicitly fails, or the runtime mode does not expose it (e.g., Codex edit modes without `request_user_input`). A pending schema load is not a fallback trigger. Never silently skip the question. - -Non-interactive mode is platform-agnostic: it never prompts, so the platform's question tool is not relevant. diff --git a/src/data/plugin-legacy-artifacts.ts b/src/data/plugin-legacy-artifacts.ts index 6485e09c9..5f44e3df8 100644 --- a/src/data/plugin-legacy-artifacts.ts +++ b/src/data/plugin-legacy-artifacts.ts @@ -121,6 +121,7 @@ const EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN: Record = "ce-proof", "ce-promote", "ce-gemini-imagegen", + "lfg", "todo-create", "todo-resolve", "todo-triage", diff --git a/src/utils/legacy-cleanup.ts b/src/utils/legacy-cleanup.ts index c3d33e113..ef2b8611e 100644 --- a/src/utils/legacy-cleanup.ts +++ b/src/utils/legacy-cleanup.ts @@ -124,6 +124,9 @@ export const STALE_SKILL_DIRS = [ // Merged into ce-work (delegation mode absorbed into stable skill) "ce-work-beta", + + // Removed autonomous pipeline orchestrator (slim/ultra-minimal) + "lfg", ] /** Old agent names (used as generated skill dirs or flat .md files). */ @@ -363,6 +366,10 @@ const LEGACY_ONLY_SKILL_DESCRIPTIONS: Record = { "Create a git commit with a clear, value-communicating message. Use when the user says \"commit\", \"commit this\", \"save my changes\", \"create a commit\", or wants to commit staged or unstaged work. Produces well-structured commit messages that follow repo conventions when they exist, and defaults to conventional commit format otherwise.", "git-commit": "Create a git commit with a clear, value-communicating message. Use when the user says \"commit\", \"commit this\", \"save my changes\", \"create a commit\", or wants to commit staged or unstaged work. Produces well-structured commit messages that follow repo conventions when they exist, and defaults to conventional commit format otherwise.", + + // lfg was the autonomous end-to-end pipeline orchestrator (removed, no replacement). + "lfg": + "Run the full autonomous engineering pipeline end-to-end (plan, work, code review, test, commit, push, open PR, watch CI, fix CI failures until green). Use only when the user explicitly requests hands-off execution of a software task and provides a feature description; do not auto-route casual conversation here.", } /** diff --git a/tests/frontmatter.test.ts b/tests/frontmatter.test.ts index 51963ac5f..ef0329f2f 100644 --- a/tests/frontmatter.test.ts +++ b/tests/frontmatter.test.ts @@ -111,13 +111,12 @@ describe("frontmatter YAML validity", () => { // All compound-engineering skills (and agents) must use the `ce-` prefix // so they are unambiguously identifiable as compound-engineering // components. See plugins/compound-engineering/AGENTS.md "Naming - // Convention". A small allowlist preserves three pre-existing skills + // Convention". A small allowlist preserves two pre-existing skills // that predate the rule -- no new entries should be added. if (pluginRoot === "plugins/compound-engineering") { const SKILL_PREFIX_ALLOWLIST = new Set([ "every-style-editor", "file-todos", - "lfg", ]) test(`${pluginRoot}/${rel} skill name uses ce- prefix`, () => { const dirName = path.basename(path.dirname(rel)) diff --git a/tests/review-skill-contract.test.ts b/tests/review-skill-contract.test.ts index 28c819060..3faf2b0d0 100644 --- a/tests/review-skill-contract.test.ts +++ b/tests/review-skill-contract.test.ts @@ -579,13 +579,6 @@ describe("ce-code-review contract", () => { expect(stopGuardMatches?.length).toBeGreaterThanOrEqual(1) }) - test("orchestration callers invoke review-only code review", async () => { - const lfg = await readRepoFile("plugins/compound-engineering/skills/lfg/SKILL.md") - expect(lfg).toMatch(/ce-code-review[^\n]*mode:agent/) - expect(lfg).toContain("references/review-followup.md") - expect(lfg).not.toMatch(/mode:autofix/) - }) - test("ce-work documents review-findings followup after Tier 2", async () => { const followup = await readRepoFile( "plugins/compound-engineering/skills/ce-work/references/review-findings-followup.md", @@ -636,52 +629,6 @@ describe("ce-code-review contract", () => { } }) - test("lfg autonomously handles residuals via non-interactive tracker-defer and PR description", async () => { - const lfg = await readRepoFile("plugins/compound-engineering/skills/lfg/SKILL.md") - await expect(readRepoFile("plugins/compound-engineering/skills/lfg/references/tracker-defer.md")).resolves.toContain( - "Non-interactive mode", - ) - await expect(readRepoFile("plugins/compound-engineering/skills/lfg/references/tracker-defer.md")).resolves.not.toMatch( - /no-sink/, - ) - - // Autonomous residual handoff step exists between code review and test-browser. - expect(lfg).toContain("Apply and persist review fixes") - const followup = await readRepoFile("plugins/compound-engineering/skills/lfg/references/review-followup.md") - expect(followup).toContain("fix(review): apply review findings") - expect(lfg).toContain("references/review-followup.md") - expect(lfg).toContain("Autonomous residual handoff") - expect(lfg).toMatch(/Do not prompt the user/) - - // tracker-defer is invoked in non-interactive mode. - expect(lfg).toContain("references/tracker-defer.md") - expect(lfg).not.toContain("plugins/compound-engineering/skills/ce-code-review/references/tracker-defer.md") - - // Structured return buckets drive PR description content. - expect(lfg).toMatch(/filed/) - expect(lfg).toMatch(/failed/) - expect(lfg).toMatch(/no_sink/) - - // PR description update path is non-interactive and does not route through - // confirmation-driven PR update skills. The positive assertion on - // `gh pr edit` below is the actual check; a broad `not.toContain` would - // falsely trip on step 7's legitimate use of ce-commit-push-pr for the - // post-work commit/PR-open step. - expect(lfg).toContain("do not load any confirmation-driven PR update skill") - expect(lfg).toContain("gh pr edit PR_NUMBER --body-file BODY_FILE") - expect(lfg).toContain("## Residual Review Findings") - expect(lfg).toContain("docs/residual-review-findings/.md") - expect(lfg).toContain("prefer `origin` when present") - expect(lfg).toContain("choose the first configured remote") - expect(lfg).toContain("git push --set-upstream HEAD") - expect(lfg).not.toContain("git push --set-upstream origin HEAD") - expect(lfg).toContain("Do not output DONE until either the existing PR body has been updated or this fallback file commit has been pushed.") - - // Autopilot contract: never prompt, but require a durable sink before DONE. - expect(lfg).toContain("Do not prompt the user") - expect(lfg).toMatch(/Never block DONE on tracker filing failures/i) - }) - test("ce-code-review emits actionable findings summary for callers", async () => { const content = await readRepoFile("plugins/compound-engineering/skills/ce-code-review/SKILL.md") expect(content).toContain("### Emit actionable findings summary") diff --git a/tests/skill-agent-ce-prefix.test.ts b/tests/skill-agent-ce-prefix.test.ts index 1d1273917..b30c8e6c5 100644 --- a/tests/skill-agent-ce-prefix.test.ts +++ b/tests/skill-agent-ce-prefix.test.ts @@ -11,10 +11,7 @@ const REF = `plugins/compound-engineering/AGENTS.md "Naming Convention"` // Exemptions from the ce- prefix rule. Add entries here only with a written // reason — the exemption list shouldn't become a silent junk drawer. -const SKILL_EXEMPTIONS = new Set([ - // lfg ships as the public command `/lfg` (see plugins/compound-engineering/README.md). - "lfg", -]) +const SKILL_EXEMPTIONS = new Set([]) const AGENT_EXEMPTIONS = new Set([]) function frontmatterName(filePath: string): string { From bf948ef9715637925546ee554b0058e0ca752b61 Mon Sep 17 00:00:00 2001 From: metaphorics <152830360+metaphorics@users.noreply.github.com> Date: Sat, 6 Jun 2026 22:55:48 +0900 Subject: [PATCH 02/40] refactor(ce-clean-gone-branches)!: drop the ce-clean-gone-branches skill Removed from the plugin; the legacy-cleanup registries now fingerprint and sweep stale installs on upgrade. BREAKING CHANGE: removes the ce-clean-gone-branches skill. Op: correct Restores: spec:fork-slimness (AGENTS.md Scope & Lineage) --- docs/skills/README.md | 1 - docs/skills/ce-clean-gone-branches.md | 178 ------------------ docs/skills/ce-worktree.md | 3 +- plugins/compound-engineering/README.md | 3 +- .../skills/ce-clean-gone-branches/SKILL.md | 63 ------- .../ce-clean-gone-branches/scripts/clean-gone | 48 ----- src/data/plugin-legacy-artifacts.ts | 1 + src/utils/legacy-cleanup.ts | 12 ++ 8 files changed, 15 insertions(+), 294 deletions(-) delete mode 100644 docs/skills/ce-clean-gone-branches.md delete mode 100644 plugins/compound-engineering/skills/ce-clean-gone-branches/SKILL.md delete mode 100755 plugins/compound-engineering/skills/ce-clean-gone-branches/scripts/clean-gone diff --git a/docs/skills/README.md b/docs/skills/README.md index 264ba79a7..3370b4b0b 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -79,7 +79,6 @@ Invoked when a specific need arises — not part of any chain. | Skill | Description | |-------|-------------| | [`/ce-commit-push-pr`](./ce-commit-push-pr.md) | Go from working changes to an open PR with adaptive descriptions — four modes (full workflow / commit-only / description update / description-only generation) | -| [`/ce-clean-gone-branches`](./ce-clean-gone-branches.md) | Delete local branches whose remote tracking branch is gone, including any associated worktrees | | [`/ce-worktree`](./ce-worktree.md) | Create a git worktree at `.worktrees/` with `.env` copying, branch-aware dev-tool trust, and gitignore management | --- diff --git a/docs/skills/ce-clean-gone-branches.md b/docs/skills/ce-clean-gone-branches.md deleted file mode 100644 index a11d31014..000000000 --- a/docs/skills/ce-clean-gone-branches.md +++ /dev/null @@ -1,178 +0,0 @@ -# `ce-clean-gone-branches` - -> Delete local branches whose remote tracking branch has been deleted, including any associated worktrees. - -`ce-clean-gone-branches` is the **branch-hygiene** skill. After PRs merge upstream, the remote tracking branches go away — but the local branches stick around indefinitely, cluttering `git branch` and inflating `git fetch` time. This skill discovers those orphaned local branches via `git fetch --prune` + `git branch -vv` parsing, presents the list, asks for confirmation, then deletes them — including any associated worktrees. - -A simple, high-frequency utility. Run it whenever your branch list feels noisy. - ---- - -## TL;DR - -| Question | Answer | -|----------|--------| -| What does it do? | Discovers local branches whose remote tracking branch is `: gone]`, then deletes them on confirmation (worktrees first, then branches) | -| When to use it | "Clean up branches", "delete gone branches", "prune local branches" — periodic branch-list hygiene | -| What it produces | Removed worktrees, deleted local branches; nothing committed | -| Scope | Yes-or-no on the entire list — no per-branch picking | - ---- - -## The Problem - -After PRs merge, local branches accumulate: - -- **`git branch` becomes noisy** — 30+ local branches, most representing already-shipped work -- **`git fetch` and tab-completion get slower** — more refs to enumerate -- **Worktrees orphan** — worktrees attached to long-merged branches keep their disk space and tooling overhead -- **Manual cleanup is tedious** — `git branch -vv | grep gone` then `git branch -D` for each one, with worktree handling layered on top -- **Auto-generated worktree names** like `worktree-jolly-beaming-raven` make it unclear which orphans belong to what - -## The Solution - -`ce-clean-gone-branches` runs cleanup in three stages: - -- **Discovery** — `git fetch --prune` to refresh remote state, then parse `git branch -vv` for `: gone]` markers -- **Confirmation** — show the full list, ask yes-or-no on the entire list (no per-branch picking) -- **Deletion** — for each branch, remove its worktree first if one exists, then `git branch -D` - -A simple all-or-nothing decision keeps the skill fast. If you only want some branches gone, decline and use `git branch -D` directly for the ones you actually want. - ---- - -## What Makes It Novel - -### 1. Discovery via `git fetch --prune` + `: gone]` parsing - -The skill runs `git fetch --prune` first to refresh local knowledge of remote state, then parses `git branch -vv` for branches whose tracking branch shows `: gone]` — the canonical signal that the remote branch was deleted. Without the prune, local refs would still believe stale remote branches exist; the skill never relies on the user having pruned recently. - -### 2. Worktree-aware cleanup - -For each branch slated for deletion, the skill checks `git worktree list` for an associated worktree. If one exists and isn't the main repo root, it's removed first via `git worktree remove --force` before the branch itself is deleted. This avoids the "cannot delete branch — checked out in worktree" error that bare `git branch -D` would hit. - -### 3. All-or-nothing confirmation - -The user sees the full list and answers yes or no on the entire list. The skill **doesn't** offer multi-select or per-branch choices. Two reasons: - -- The list is usually small (5-20 branches); the cost of seeing them all and saying "yes" is low -- A multi-select adds UI overhead that doesn't pay off for a routine cleanup task - -If the user wants finer control, declining and running `git branch -D ` is fast. - -### 4. Reports as it goes - -While deleting, the skill prints each action — "Removed worktree: ...", "Deleted branch: ..." — so the user sees progress in real time. Final summary names the count. - ---- - -## Quick Example - -You haven't cleaned local branches in a while. You invoke `/ce-clean-gone-branches`. - -The skill runs `bash scripts/clean-gone`, which fetches with prune and parses `git branch -vv`. Output: 5 gone branches. - -```text -These local branches have been deleted from the remote: - - - feat/notification-mute - - fix/auth-redirect - - refactor/extract-service - - chore/upgrade-deps - - experiment/new-clustering - -Delete all of them? (y/n) -``` - -You answer yes. The skill processes each: - -- `feat/notification-mute` has a worktree at `.worktrees/feat-notification-mute`. Remove worktree first: ✓. Delete branch: ✓. -- `fix/auth-redirect` no worktree. Delete branch: ✓. -- ... - -Final summary: - -```text -Removed worktree: .worktrees/feat-notification-mute -Deleted branch: feat/notification-mute -Deleted branch: fix/auth-redirect -Deleted branch: refactor/extract-service -Deleted branch: chore/upgrade-deps -Deleted branch: experiment/new-clustering - -Cleaned up 5 branches. -``` - ---- - -## When to Reach For It - -Reach for `ce-clean-gone-branches` when: - -- Your `git branch` list is getting noisy after several PRs have merged -- You're noticing worktrees lingering for branches you no longer remember -- It's been a while since you cleaned up; periodic hygiene is overdue - -Skip `ce-clean-gone-branches` when: - -- You want to delete only specific branches → `git branch -D ` directly -- You want to keep a local branch even though remote is gone → decline the prompt -- You're not on a working copy with a remote configured → the skill needs a remote to compare against - ---- - -## Use as Part of the Workflow - -`ce-clean-gone-branches` is mostly standalone — it doesn't sit inside the chain. It's invoked when: - -- Several PRs have merged and the user wants to tidy local state -- Worktree creation is failing because of orphaned worktrees on dead branches -- The user is preparing to start a new line of work and wants a clean slate - ---- - -## Use Standalone - -Direct invocation with no arguments: - -- `/ce-clean-gone-branches` - -The skill discovers, asks, and deletes. No flags, no selection — just yes or no on the full list. - ---- - -## Reference - -| Step | Action | -|------|--------| -| 1 | Run `bash scripts/clean-gone` (fetches with prune, parses for `: gone]`) | -| 2 | Present the list of stale branches; ask yes/no on the entire list | -| 3 | For each confirmed branch: remove worktree if present, then `git branch -D` | -| 4 | Report results as deletions happen; final summary with count | - -If the script outputs `__NONE__`, the skill reports that no stale branches were found and stops. - ---- - -## FAQ - -**What's a "gone" branch?** -A local branch whose remote tracking branch was deleted upstream (typically because the PR merged and GitHub deleted the source branch). `git branch -vv` shows `: gone]` next to such branches. - -**Why all-or-nothing instead of per-branch picking?** -Because the list is usually small and reviewing them all takes seconds. A multi-select UI adds friction for a high-frequency task. If you need surgical control, decline and use `git branch -D ` for specific branches. - -**Why does it remove the worktree before deleting the branch?** -Because `git branch -D` on a checked-out branch (in a worktree) fails. The skill removes the worktree first to avoid that error. - -**What if a worktree has uncommitted changes?** -`--force` is used on `git worktree remove`, so uncommitted changes are discarded. If the branch has been "gone" (merged remotely and deleted), you almost certainly don't want lingering uncommitted changes there. If you do, decline the prompt and handle that worktree manually first. - -**What if the script fails or returns no branches?** -If no gone branches exist, the skill stops cleanly and reports "no stale branches found." If the script itself errors, the skill surfaces the error. - ---- - -## See Also - -- [`/ce-worktree`](./ce-worktree.md) — sibling skill for worktree creation; this skill cleans up after worktrees become orphaned diff --git a/docs/skills/ce-worktree.md b/docs/skills/ce-worktree.md index 0167f46b6..d9e04b526 100644 --- a/docs/skills/ce-worktree.md +++ b/docs/skills/ce-worktree.md @@ -180,7 +180,7 @@ Because `.envrc` can source other files that direnv doesn't validate. Auto-trust Run `cp .env* .worktrees//` from the main repo (not from inside the worktree, since branch names often contain slashes that confuse relative paths from inside). **How do I clean up a worktree?** -`cd "$(git rev-parse --show-toplevel)"` to leave the worktree, then `git worktree remove .worktrees/`. If the branch was deleted upstream, `/ce-clean-gone-branches` handles worktree-and-branch cleanup together. +`cd "$(git rev-parse --show-toplevel)"` to leave the worktree, then `git worktree remove .worktrees/`. If the branch was deleted upstream, use `git worktree remove` directly (no automated cleanup available). **Why `.worktrees/` and not somewhere else?** Predictability. Tooling that scans for worktrees, tab-completion, branch-to-path lookup all benefit from one canonical location. The directory is gitignored so it doesn't pollute git status. @@ -194,4 +194,3 @@ Yes — the new branch is created locally at the resolved base ref. The skill fe - [`/ce-work`](./ce-work.md) — calls this skill at Phase 1.2 when the user picks worktree mode for parallel features - [`/ce-code-review`](./ce-code-review.md) — recommends worktree for review concurrent with browser tests -- [`/ce-clean-gone-branches`](./ce-clean-gone-branches.md) — cleans up worktrees and branches together when the remote tracking branch is gone diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index f27c46a07..71bae1ddc 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,7 +11,7 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 37 | -| Skills | 27 | +| Skills | 26 | ## Skills @@ -43,7 +43,6 @@ The primary entry points for engineering work, invoked as slash commands. Detail | Skill | Description | |-------|-------------| -| [`/ce-clean-gone-branches`](../../docs/skills/ce-clean-gone-branches.md) | Clean up local branches whose remote tracking branch is gone | | [`/ce-commit-push-pr`](../../docs/skills/ce-commit-push-pr.md) | Commit, push, and open a PR with an adaptive description; also update an existing PR description, or generate a description on its own without committing; or commit only without pushing | | [`/ce-worktree`](../../docs/skills/ce-worktree.md) | Manage Git worktrees for parallel development | diff --git a/plugins/compound-engineering/skills/ce-clean-gone-branches/SKILL.md b/plugins/compound-engineering/skills/ce-clean-gone-branches/SKILL.md deleted file mode 100644 index 35f0fc073..000000000 --- a/plugins/compound-engineering/skills/ce-clean-gone-branches/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: ce-clean-gone-branches -description: Clean up local branches whose remote tracking branch is gone. Use when the user says "clean up branches", "delete gone branches", "prune local branches", "clean gone", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them. ---- - -# Clean Gone Branches - -Delete local branches whose remote tracking branch has been deleted, including any associated worktrees. - -## Workflow - -### Step 1: Discover gone branches - -Run the discovery script to fetch the latest remote state and identify gone branches: - -```bash -bash scripts/clean-gone -``` - -[scripts/clean-gone](./scripts/clean-gone) - -The script runs `git fetch --prune` first, then parses `git branch -vv` for branches marked `: gone]`. - -If the script outputs `__NONE__`, report that no stale branches were found and stop. - -### Step 2: Present branches and ask for confirmation - -Show the user the list of branches that will be deleted. Format as a simple list: - -``` -These local branches have been deleted from the remote: - - - feature/old-thing - - bugfix/resolved-issue - - experiment/abandoned - -Delete all of them? (y/n) -``` - -Wait for the user's answer using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the list in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. - -This is a yes-or-no decision on the entire list -- do not offer multi-selection or per-branch choices. - -### Step 3: Delete confirmed branches - -If the user confirms, delete each branch. For each branch: - -1. Check if it has an associated worktree (`git worktree list | grep "\\[$branch\\]"`) -2. If a worktree exists and is not the main repo root, remove it first: `git worktree remove --force "$worktree_path"` -3. Delete the branch: `git branch -D "$branch"` - -Report results as you go: - -``` -Removed worktree: .worktrees/feature/old-thing -Deleted branch: feature/old-thing -Deleted branch: bugfix/resolved-issue -Deleted branch: experiment/abandoned - -Cleaned up 3 branches. -``` - -If the user declines, acknowledge and stop without deleting anything. diff --git a/plugins/compound-engineering/skills/ce-clean-gone-branches/scripts/clean-gone b/plugins/compound-engineering/skills/ce-clean-gone-branches/scripts/clean-gone deleted file mode 100755 index da5b92b60..000000000 --- a/plugins/compound-engineering/skills/ce-clean-gone-branches/scripts/clean-gone +++ /dev/null @@ -1,48 +0,0 @@ -#!/usr/bin/env bash -# clean-gone: List local branches whose remote tracking branch is gone. -# Outputs one branch name per line, or nothing if none found. - -set -euo pipefail - -# Ensure we have current remote state -git fetch --prune 2>/dev/null - -# Find branches marked [gone] in tracking info. -# `git branch -vv` output format: -# * main abc1234 [origin/main] commit msg -# + feature-x def5678 [origin/feature-x: gone] commit msg -# old-branch 789abcd [origin/old-branch: gone] commit msg -# -# The leading column can be: ' ' (normal), '*' (current), '+' (worktree). -# We match lines containing ": gone]" to find branches whose remote is deleted. - -gone_branches=() - -while IFS= read -r line; do - # Skip the currently checked-out branch (marked with '*'). - # git branch -D cannot delete the active branch, and attempting it - # would halt cleanup before other stale branches are processed. - if [[ "$line" =~ ^\* ]]; then - continue - fi - - # Strip the leading marker character(s) and whitespace - # The branch name is the first non-whitespace token after the marker - branch_name=$(echo "$line" | sed 's/^[+* ]*//' | awk '{print $1}') - - # Validate: skip empty, skip if it looks like a hash or flag, skip HEAD - if [[ -z "$branch_name" ]] || [[ "$branch_name" =~ ^[0-9a-f]{7,}$ ]] || [[ "$branch_name" == "HEAD" ]]; then - continue - fi - - gone_branches+=("$branch_name") -done < <(git branch -vv 2>/dev/null | grep ': gone]') - -if [[ ${#gone_branches[@]} -eq 0 ]]; then - echo "__NONE__" - exit 0 -fi - -for branch in "${gone_branches[@]}"; do - echo "$branch" -done diff --git a/src/data/plugin-legacy-artifacts.ts b/src/data/plugin-legacy-artifacts.ts index 5f44e3df8..0d8721b21 100644 --- a/src/data/plugin-legacy-artifacts.ts +++ b/src/data/plugin-legacy-artifacts.ts @@ -27,6 +27,7 @@ const EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN: Record = "brainstorming", "ce-andrew-kane-gem-writer", "ce-changelog", + "ce-clean-gone-branches", "ce-deploy-docs", "ce-dspy-ruby", "ce-every-style-editor", diff --git a/src/utils/legacy-cleanup.ts b/src/utils/legacy-cleanup.ts index ef2b8611e..74eb33e83 100644 --- a/src/utils/legacy-cleanup.ts +++ b/src/utils/legacy-cleanup.ts @@ -127,6 +127,9 @@ export const STALE_SKILL_DIRS = [ // Removed autonomous pipeline orchestrator (slim/ultra-minimal) "lfg", + + // Removed branch-hygiene skill (slim/ultra-minimal) + "ce-clean-gone-branches", ] /** Old agent names (used as generated skill dirs or flat .md files). */ @@ -370,6 +373,15 @@ const LEGACY_ONLY_SKILL_DESCRIPTIONS: Record = { // lfg was the autonomous end-to-end pipeline orchestrator (removed, no replacement). "lfg": "Run the full autonomous engineering pipeline end-to-end (plan, work, code review, test, commit, push, open PR, watch CI, fix CI failures until green). Use only when the user explicitly requests hands-off execution of a software task and provides a feature description; do not auto-route casual conversation here.", + + // ce-clean-gone-branches was the branch-hygiene skill (removed, no replacement). + // Provide the historical description for both the removed skill and the legacy + // git-clean-gone-branches dir so cleanup can fingerprint installs from either + // era after the skill dir is gone. + "ce-clean-gone-branches": + "Clean up local branches whose remote tracking branch is gone. Use when the user says \"clean up branches\", \"delete gone branches\", \"prune local branches\", \"clean gone\", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.", + "git-clean-gone-branches": + "Clean up local branches whose remote tracking branch is gone. Use when the user says \"clean up branches\", \"delete gone branches\", \"prune local branches\", \"clean gone\", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.", } /** From 55e1c0ea542da030f2f31f7501876b10707a0f4d Mon Sep 17 00:00:00 2001 From: metaphorics <152830360+metaphorics@users.noreply.github.com> Date: Sat, 6 Jun 2026 23:09:14 +0900 Subject: [PATCH 03/40] refactor(ce-report-bug)!: drop the ce-report-bug skill Removed from the plugin; the legacy-cleanup registries now fingerprint and sweep stale installs on upgrade. BREAKING CHANGE: removes the ce-report-bug skill. Op: correct Restores: spec:fork-slimness (AGENTS.md Scope & Lineage) --- docs/skills/README.md | 1 - docs/skills/ce-release-notes.md | 1 - docs/skills/ce-report-bug.md | 254 ------------------ docs/skills/ce-update.md | 2 - plugins/compound-engineering/README.md | 3 +- .../skills/ce-report-bug/SKILL.md | 157 ----------- src/data/plugin-legacy-artifacts.ts | 1 + src/utils/legacy-cleanup.ts | 11 + 8 files changed, 13 insertions(+), 417 deletions(-) delete mode 100644 docs/skills/ce-report-bug.md delete mode 100644 plugins/compound-engineering/skills/ce-report-bug/SKILL.md diff --git a/docs/skills/README.md b/docs/skills/README.md index 3370b4b0b..f95c4acde 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -102,7 +102,6 @@ Invoked when a specific need arises — not part of any chain. | [`/ce-setup`](./ce-setup.md) | Diagnose environment, install missing tools, bootstrap project-local config — interactive onboarding in one flow | | [`/ce-update`](./ce-update.md) | Check the installed compound-engineering plugin version against `main` and recommend the update command (Claude Code only) | | [`/ce-release-notes`](./ce-release-notes.md) | Look up what shipped in recent compound-engineering plugin releases — summary or specific question with version citation | -| [`/ce-report-bug`](./ce-report-bug.md) | Report a bug in the compound-engineering plugin — structured intake, automatic env gathering, GitHub issue creation | --- diff --git a/docs/skills/ce-release-notes.md b/docs/skills/ce-release-notes.md index 444bda2a2..2d6b852a6 100644 --- a/docs/skills/ce-release-notes.md +++ b/docs/skills/ce-release-notes.md @@ -218,4 +218,3 @@ Specifically to prevent it from drifting through string interpolation or LLM rew ## See Also - [`/ce-update`](./ce-update.md) — checks plugin version; useful before asking what changed -- [`/ce-report-bug`](./ce-report-bug.md) — for filing issues against the plugin; checking release notes first can save the report diff --git a/docs/skills/ce-report-bug.md b/docs/skills/ce-report-bug.md deleted file mode 100644 index a376421ef..000000000 --- a/docs/skills/ce-report-bug.md +++ /dev/null @@ -1,254 +0,0 @@ -# `ce-report-bug` - -> Report a bug in the compound-engineering plugin — gathers structured information and creates a GitHub issue at `EveryInc/compound-engineering-plugin`. - -`ce-report-bug` is the **bug-filing** skill. It walks the user through six structured questions (category, component, what happened, expected behavior, repro steps, error messages), automatically gathers environment information (OS, plugin version, agent CLI version), formats a complete bug report, and creates a GitHub issue via `gh`. The skill makes filing a useful bug report fast — the alternative is opening GitHub, finding the right repo, remembering what to include, and typing it from scratch. - -Beta-style explicit-invocation only (`disable-model-invocation: true`). - ---- - -## TL;DR - -| Question | Answer | -|----------|--------| -| What does it do? | Gathers structured bug info via 6 questions, collects environment data automatically, files a GitHub issue at `EveryInc/compound-engineering-plugin` | -| When to use it | When something in the compound-engineering plugin doesn't work and you want to report it | -| What it produces | A GitHub issue URL (or a formatted bug report you can file manually if `gh` isn't available) | -| Privacy | Doesn't collect personal info, API keys, credentials, or private code | - ---- - -## The Problem - -Filing a useful bug report has high friction: - -- **Finding the right repo** — which org, which repo, which label? -- **Remembering what to include** — environment info, repro steps, error messages, expected vs actual behavior — easy to miss something the maintainer needs -- **Manual environment gathering** — running `uname`, finding plugin version, checking CLI version, formatting it all -- **No template** — every bug report starts from scratch; some are great, some are "it's broken" -- **Filing without `gh`** — without the CLI, the user has to copy-paste through the GitHub UI manually -- **Privacy concerns** — naïve env gathering risks including API keys or paths that reveal too much - -## The Solution - -`ce-report-bug` runs reporting as a structured intake → format → file flow: - -- **6 questions** in a structured order — category, component, actual, expected, repro steps, error messages -- **Automatic env gathering** — OS via `uname -a`, plugin version via manifest reading, agent CLI version via `--version` -- **Template-based formatting** — every report has the same shape, so maintainers can scan quickly -- **`gh issue create`** with the right repo, title prefix, and labels (or fallback without labels) -- **Manual-fallback** when `gh` is unavailable — formatted report displayed for the user to file by hand -- **Privacy by design** — only technical info; never personal info, credentials, or code - ---- - -## What Makes It Novel - -### 1. Six structured questions in a deliberate order - -The skill asks: - -1. **Bug category** (multiple choice) — Agent / Command / Skill / MCP server / Installation / Other -2. **Specific component** (free text) — name of the agent, command, skill, or MCP server -3. **What happened (actual behavior)** — clear description of what the user observed -4. **What should have happened (expected behavior)** — clear description of expected behavior -5. **Steps to reproduce** — what the user did before the bug occurred -6. **Error messages** — any error output - -The order matters: category and component first scope the bug; actual vs expected establishes the disconnect; repro steps + errors give the maintainer the diagnostic foothold. - -### 2. Automatic environment gathering - -The skill runs: - -- `uname -a` for OS info -- Reads plugin manifest from platform-specific location (Claude Code: `~/.claude/plugins/installed_plugins.json`; Codex: `.codex/plugins/`; etc.) -- Runs the platform's CLI version command (`claude --version`, `codex --version`, etc.) - -If any of these fail, the skill notes "unknown" and continues — don't block reporting on environment-collection issues. - -### 3. Single template, consistent shape - -Every report uses the same template: - -```markdown -## Bug Description -**Component:** [Type] - [Name] -**Summary:** [Brief] - -## Environment -- **Plugin Version:** ... -- **Agent Platform:** ... -- **Agent Version:** ... -- **OS:** ... - -## What Happened -... - -## Expected Behavior -... - -## Steps to Reproduce -1. ... - -## Error Messages -... - -## Additional Context -... - ---- -*Reported via `/ce-report-bug` skill* -``` - -The footer marks the report as skill-generated so the maintainer knows it followed the canonical template. - -### 4. `gh issue create` with the right scope - -The skill files via: - -```bash -gh issue create \ - --repo EveryInc/compound-engineering-plugin \ - --title "[compound-engineering] Bug: [description]" \ - --body "[formatted report]" \ - --label "bug,compound-engineering" -``` - -Right repo, right title prefix, right labels. If labels don't exist (some forks/clones may lack them), the skill retries without `--label` rather than failing. - -### 5. Manual fallback when `gh` is unavailable - -If `gh` isn't installed or authenticated, the skill displays the fully-formatted report to the user so they can paste it into the GitHub web UI manually. No friction lost — the reporting work is already done. - -### 6. Privacy by design - -The skill explicitly does **not** collect: - -- Personal information -- API keys or credentials -- Private code from projects -- File paths beyond basic OS info from `uname` - -Only technical information about the bug is included. This is documented in the skill so users know what's being shared. - -### 7. Explicit-invocation only - -`disable-model-invocation: true` prevents the skill from auto-firing on prose mentions of bugs. Bug reporting is a deliberate user choice — invoke `/ce-report-bug` directly. - ---- - -## Quick Example - -You hit a bug where `/ce-plan` produces a plan with U-IDs that aren't sequential. You invoke `/ce-report-bug`. - -The skill walks through 6 questions: - -1. **Category**: Skill not working -2. **Component**: ce-plan -3. **What happened**: "Plan was generated with U-IDs U1, U2, U4 — U3 was skipped without explanation." -4. **Expected**: "U-IDs should be sequential without gaps in initial generation." -5. **Repro**: "Run `/ce-plan` from a brainstorm doc with 4 implementation units. The third unit gets numbered U4 instead of U3." -6. **Error messages**: "None visible; just the wrong numbering." - -Environment gathering runs in the background: -- `uname -a`: macOS arm64 -- Plugin version: 3.4.1 -- Agent platform: Claude Code -- Agent version: claude-code 1.2.3 - -Formatted report goes to `gh issue create --repo EveryInc/compound-engineering-plugin --title "[compound-engineering] Bug: U-ID numbering skips U3 in initial plan generation" --body "..." --label "bug,compound-engineering"`. - -Returns: - -```text -Bug report submitted successfully! - -Issue: https://github.com/EveryInc/compound-engineering-plugin/issues/812 -Title: [compound-engineering] Bug: U-ID numbering skips U3 in initial plan generation - -Thank you for helping improve the compound-engineering plugin! -The maintainer will review your report and respond as soon as possible. -``` - ---- - -## When to Reach For It - -Reach for `ce-report-bug` when: - -- A skill, command, agent, or MCP integration in compound-engineering doesn't work as expected -- You want to report something the maintainer can action without follow-up questions -- You're not sure what details to include — the structured questions catch what's needed - -Skip `ce-report-bug` when: - -- The bug is in a different plugin or tool (this filing target is hardcoded to compound-engineering) -- It's a feature request, not a bug → file a discussion or feature-request issue manually -- You're not sure if it's a bug or expected — check `/ce-release-notes` first to see if behavior changed in a recent release - ---- - -## Use as Part of the Workflow - -`ce-report-bug` is a standalone utility — doesn't sit inside the chain. It's invoked when something goes wrong and the user wants the maintainer to know. - -Common companion skills: - -- **`/ce-update`** — check version first; you might be reporting a bug that's already fixed in a newer version -- **`/ce-release-notes`** — check whether the behavior changed recently; might be intended - ---- - -## Use Standalone - -Direct invocation: - -- `/ce-report-bug` — walks through the 6 questions -- `/ce-report-bug "brief description"` — uses the description as initial context; still walks through the structured questions for completeness - -The skill drives the intake. There's no skip-questions option — the structured intake is the value; if it's overkill for a one-line report, file via the GitHub UI directly. - ---- - -## Reference - -| Step | Action | -|------|--------| -| 1 | Gather bug info (6 structured questions) | -| 2 | Collect environment info (OS, plugin version, agent CLI version) | -| 3 | Format the bug report (consistent template) | -| 4 | Create GitHub issue via `gh` (with labels; fallback without) | -| 5 | Confirm submission and display issue URL | - -Repo target: `EveryInc/compound-engineering-plugin`. Title prefix: `[compound-engineering]`. Labels: `bug,compound-engineering` (with fallback to no labels if missing). - ---- - -## FAQ - -**What does the skill collect about my environment?** -Only technical info: OS string from `uname -a`, plugin version from the manifest, agent platform name, agent CLI version. No personal info, no API keys, no credentials, no private code. The report's `Environment` section shows exactly what's included. - -**What if `gh` isn't installed?** -The skill displays the fully-formatted bug report and asks you to file it manually via the GitHub web UI. No information is lost — the structured intake and formatting still happened. - -**Can I report a non-compound-engineering bug?** -This skill specifically files at `EveryInc/compound-engineering-plugin`. For other plugins or tools, file directly in their respective repos. The structure of this skill is generalizable, but the repo target is hardcoded. - -**What if labels don't exist on the repo?** -The skill retries without `--label`. Some forks or clones may not have the `bug` label set up; the report still files successfully without it. - -**Can I edit the report before it gets filed?** -The skill walks through the questions interactively, so you can refine each answer before moving on. Once the report is formatted, the skill files via `gh` directly. If you want manual review, decline `gh` and file via the web UI yourself with the formatted text. - -**Is it OK if I file the same bug twice?** -The skill doesn't deduplicate — it files what you ask. If you're worried about duplicates, search the issue tracker first. The maintainer can close duplicates as needed. - ---- - -## See Also - -- [`/ce-update`](./ce-update.md) — check plugin version; older versions may have fixed bugs -- [`/ce-release-notes`](./ce-release-notes.md) — check whether the behavior changed in a recent release; might not be a bug diff --git a/docs/skills/ce-update.md b/docs/skills/ce-update.md index b5141fb39..805b84432 100644 --- a/docs/skills/ce-update.md +++ b/docs/skills/ce-update.md @@ -126,7 +126,6 @@ Skip `ce-update` when: `ce-update` is a standalone utility — it doesn't sit inside the chain. It's invoked when version drift is suspected: -- **From `/ce-report-bug`** — checking version is the first thing a bug report should establish - **From the user directly** when the agent's behavior smells stale The output is read directly by the user — no downstream skill consumes it. @@ -185,5 +184,4 @@ The skill recognizes the case (`__CE_UPDATE_NOT_MARKETPLACE__` from the path-par ## See Also - [`ce-setup`](./ce-setup.md) — installs missing dependencies; complementary to version checks -- [`ce-report-bug`](./ce-report-bug.md) — reporting a bug; should establish version first - [`ce-release-notes`](./ce-release-notes.md) — summarize recent compound-engineering plugin releases diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 71bae1ddc..89a23f296 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,7 +11,7 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 37 | -| Skills | 26 | +| Skills | 25 | ## Skills @@ -51,7 +51,6 @@ The primary entry points for engineering work, invoked as slash commands. Detail | Skill | Description | |-------|-------------| | [`/ce-demo-reel`](../../docs/skills/ce-demo-reel.md) | Capture a visual demo reel (GIF demos, terminal recordings, screenshots) for PRs with project-type-aware tier selection | -| [`/ce-report-bug`](../../docs/skills/ce-report-bug.md) | Report a bug in the compound-engineering plugin | | [`/ce-resolve-pr-feedback`](../../docs/skills/ce-resolve-pr-feedback.md) | Resolve PR review feedback in parallel | | [`/ce-test-browser`](../../docs/skills/ce-test-browser.md) | Run browser tests on PR-affected pages | | [`/ce-setup`](../../docs/skills/ce-setup.md) | Diagnose environment, install missing tools, and bootstrap project config | diff --git a/plugins/compound-engineering/skills/ce-report-bug/SKILL.md b/plugins/compound-engineering/skills/ce-report-bug/SKILL.md deleted file mode 100644 index e168729a4..000000000 --- a/plugins/compound-engineering/skills/ce-report-bug/SKILL.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -name: ce-report-bug -description: Report a bug in the compound-engineering plugin -argument-hint: "[optional: brief description of the bug]" -disable-model-invocation: true ---- - -# Report a Compound Engineering Plugin Bug - -Report bugs encountered while using the compound-engineering plugin. This skill gathers structured information and creates a GitHub issue for the maintainer. - -## Step 1: Gather Bug Information - -Ask the user the following questions using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question: - -**Question 1: Bug Category** -- What type of issue are you experiencing? -- Options: Agent not working, Command not working, Skill not working, MCP server issue, Installation problem, Other - -**Question 2: Specific Component** -- Which specific component is affected? -- Ask for the name of the agent, command, skill, or MCP server - -**Question 3: What Happened (Actual Behavior)** -- Ask: "What happened when you used this component?" -- Get a clear description of the actual behavior - -**Question 4: What Should Have Happened (Expected Behavior)** -- Ask: "What did you expect to happen instead?" -- Get a clear description of expected behavior - -**Question 5: Steps to Reproduce** -- Ask: "What steps did you take before the bug occurred?" -- Get reproduction steps - -**Question 6: Error Messages** -- Ask: "Did you see any error messages? If so, please share them." -- Capture any error output - -## Step 2: Collect Environment Information - -Automatically gather environment details. Detect the coding agent platform and collect what is available: - -**OS info (all platforms):** -```bash -uname -a -``` - -**Plugin version:** Read the plugin manifest or installed plugin metadata. Common locations: -- Claude Code: `~/.claude/plugins/installed_plugins.json` -- Codex: `.codex/plugins/` or project config -- Other platforms: check the platform's plugin registry - -**Agent CLI version:** Run the platform's version command: -- Claude Code: `claude --version` -- Codex: `codex --version` -- Other platforms: use the appropriate CLI version flag - -If any of these fail, note "unknown" and continue — do not block the report. - -## Step 3: Format the Bug Report - -Create a well-structured bug report with: - -```markdown -## Bug Description - -**Component:** [Type] - [Name] -**Summary:** [Brief description from argument or collected info] - -## Environment - -- **Plugin Version:** [from plugin manifest/registry] -- **Agent Platform:** [e.g., Claude Code, Codex, Copilot, Pi, Kilo] -- **Agent Version:** [from CLI version command] -- **OS:** [from uname] - -## What Happened - -[Actual behavior description] - -## Expected Behavior - -[Expected behavior description] - -## Steps to Reproduce - -1. [Step 1] -2. [Step 2] -3. [Step 3] - -## Error Messages - -[Any error output] - -## Additional Context - -[Any other relevant information] - ---- -*Reported via `/ce-report-bug` skill* -``` - -## Step 4: Create GitHub Issue - -Use the GitHub CLI to create the issue: - -```bash -gh issue create \ - --repo EveryInc/compound-engineering-plugin \ - --title "[compound-engineering] Bug: [Brief description]" \ - --body "[Formatted bug report from Step 3]" \ - --label "bug,compound-engineering" -``` - -**Note:** If labels don't exist, create without labels: -```bash -gh issue create \ - --repo EveryInc/compound-engineering-plugin \ - --title "[compound-engineering] Bug: [Brief description]" \ - --body "[Formatted bug report]" -``` - -## Step 5: Confirm Submission - -After the issue is created: -1. Display the issue URL to the user -2. Thank them for reporting the bug -3. Let them know the maintainer (Kieran Klaassen) will be notified - -## Output Format - -``` -Bug report submitted successfully! - -Issue: https://github.com/EveryInc/compound-engineering-plugin/issues/[NUMBER] -Title: [compound-engineering] Bug: [description] - -Thank you for helping improve the compound-engineering plugin! -The maintainer will review your report and respond as soon as possible. -``` - -## Error Handling - -- If `gh` CLI is not installed or not authenticated: prompt the user to install/authenticate first -- If issue creation fails: display the formatted report so the user can manually create the issue -- If required information is missing: re-prompt for that specific field - -## Privacy Notice - -This skill does NOT collect: -- Personal information -- API keys or credentials -- Private code from projects -- File paths beyond basic OS info - -Only technical information about the bug is included in the report. diff --git a/src/data/plugin-legacy-artifacts.ts b/src/data/plugin-legacy-artifacts.ts index 0d8721b21..fa8057697 100644 --- a/src/data/plugin-legacy-artifacts.ts +++ b/src/data/plugin-legacy-artifacts.ts @@ -123,6 +123,7 @@ const EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN: Record = "ce-promote", "ce-gemini-imagegen", "lfg", + "ce-report-bug", "todo-create", "todo-resolve", "todo-triage", diff --git a/src/utils/legacy-cleanup.ts b/src/utils/legacy-cleanup.ts index 74eb33e83..03421ac8a 100644 --- a/src/utils/legacy-cleanup.ts +++ b/src/utils/legacy-cleanup.ts @@ -130,6 +130,10 @@ export const STALE_SKILL_DIRS = [ // Removed branch-hygiene skill (slim/ultra-minimal) "ce-clean-gone-branches", + + // Removed bug-filing skill (slim/ultra-minimal). The renamed-era + // "report-bug-ce" entry above stays; this is the current-era dir name. + "ce-report-bug", ] /** Old agent names (used as generated skill dirs or flat .md files). */ @@ -382,6 +386,13 @@ const LEGACY_ONLY_SKILL_DESCRIPTIONS: Record = { "Clean up local branches whose remote tracking branch is gone. Use when the user says \"clean up branches\", \"delete gone branches\", \"prune local branches\", \"clean gone\", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.", "git-clean-gone-branches": "Clean up local branches whose remote tracking branch is gone. Use when the user says \"clean up branches\", \"delete gone branches\", \"prune local branches\", \"clean gone\", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.", + + // ce-report-bug was the plugin bug-filing skill (removed, no replacement). + // currentSkillNameForLegacy normalizes the legacy "report-bug-ce" dir to + // "ce-report-bug", so this single entry fingerprints installs from both eras + // once the skill dir is gone. + "ce-report-bug": + "Report a bug in the compound-engineering plugin", } /** From c2b35b1f54ceeb366aed98d23c4b0968e788b1da Mon Sep 17 00:00:00 2001 From: metaphorics <152830360+metaphorics@users.noreply.github.com> Date: Sat, 6 Jun 2026 23:22:51 +0900 Subject: [PATCH 04/40] refactor(ce-strategy)!: drop the ce-strategy skill Removed from the plugin; the legacy-cleanup registries now fingerprint and sweep stale installs on upgrade. BREAKING CHANGE: removes the ce-strategy skill. Op: correct Restores: spec:fork-slimness (AGENTS.md Scope & Lineage) --- README.md | 3 - docs/skills/README.md | 10 - docs/skills/ce-brainstorm.md | 1 - docs/skills/ce-ideate.md | 1 - docs/skills/ce-plan.md | 1 - docs/skills/ce-strategy.md | 205 ------------------ plugins/compound-engineering/README.md | 5 +- .../skills/ce-strategy/SKILL.md | 97 --------- .../ce-strategy/references/interview.md | 143 ------------ .../references/strategy-template.md | 89 -------- src/data/plugin-legacy-artifacts.ts | 1 + src/utils/legacy-cleanup.ts | 7 + 12 files changed, 9 insertions(+), 554 deletions(-) delete mode 100644 docs/skills/ce-strategy.md delete mode 100644 plugins/compound-engineering/skills/ce-strategy/SKILL.md delete mode 100644 plugins/compound-engineering/skills/ce-strategy/references/interview.md delete mode 100644 plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md diff --git a/README.md b/README.md index 15d43950a..895b1e826 100644 --- a/README.md +++ b/README.md @@ -28,15 +28,12 @@ The point is not ceremony. The point is leverage. A good brainstorm makes the pl ## Workflow -`/ce-strategy` is upstream of the loop -- it captures the product's target problem, approach, persona, metrics, and tracks as a short durable anchor at `STRATEGY.md`. Ideate, brainstorm, and plan read it as grounding when present, so strategy choices flow into feature conception, prioritization, and spec. - The core loop is: brainstorm the requirements, plan the implementation, work through the plan, review the result, compound the learning, then repeat with better context. Use `/ce-ideate` before the loop when you want the agent to generate and critique bigger ideas before choosing one to brainstorm. It produces a ranked ideation artifact, not requirements, plans, or code. | Skill | Purpose | |-------|---------| -| `/ce-strategy` | Create or maintain `STRATEGY.md` -- the product's target problem, approach, persona, key metrics, and tracks. Read as grounding by ideate, brainstorm, and plan | | `/ce-ideate` | Optional big-picture ideation: generate and critically evaluate grounded ideas, then route the strongest one into brainstorming | | `/ce-brainstorm` | Interactive Q&A to think through a feature or problem and write a right-sized requirements doc before planning | | `/ce-plan` | Turn feature ideas into detailed implementation plans | diff --git a/docs/skills/README.md b/docs/skills/README.md index f95c4acde..c46364d4f 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -42,16 +42,6 @@ The steps of every engineering iteration. `/ce-ideate` runs only when you need t --- -## Around the Loop - -Skills that anchor, feed, or maintain the loop without being steps inside it. - -| Skill | Description | -|-------|-------------| -| [`/ce-strategy`](./ce-strategy.md) | Create or maintain `STRATEGY.md` — the upstream anchor read by `ce-ideate`, `ce-brainstorm`, and `ce-plan` as grounding | - ---- - ## On-Demand Invoked when a specific need arises — not part of any chain. diff --git a/docs/skills/ce-brainstorm.md b/docs/skills/ce-brainstorm.md index b3a16ee31..ab2f5ade9 100644 --- a/docs/skills/ce-brainstorm.md +++ b/docs/skills/ce-brainstorm.md @@ -207,4 +207,3 @@ Yes — a domain-agnostic facilitator preserves the one-question-at-a-time disci - [`ce-plan`](./ce-plan.md) — turn the requirements doc into an implementation plan - [`ce-doc-review`](./ce-doc-review.md) — persona-based review of the requirements doc - [`ce-work`](./ce-work.md) — execute lightweight changes directly from a brainstorm -- [`ce-strategy`](./ce-strategy.md) — anchor brainstorms to a documented product strategy diff --git a/docs/skills/ce-ideate.md b/docs/skills/ce-ideate.md index 1433aa05f..d24e96d40 100644 --- a/docs/skills/ce-ideate.md +++ b/docs/skills/ce-ideate.md @@ -204,5 +204,4 @@ A subject-identification gate asks one scope question when the prompt refers onl - [`ce-brainstorm`](./ce-brainstorm.md) — once you've picked a survivor, brainstorm the chosen direction into a requirements doc - [`ce-plan`](./ce-plan.md) — once requirements are clear, plan the implementation -- [`ce-strategy`](./ce-strategy.md) — anchor ideation to a documented product strategy - [`ce-doc-review`](./ce-doc-review.md) — review the saved ideation artifact for clarity and completeness diff --git a/docs/skills/ce-plan.md b/docs/skills/ce-plan.md index e49073b18..2b93206d1 100644 --- a/docs/skills/ce-plan.md +++ b/docs/skills/ce-plan.md @@ -232,4 +232,3 @@ Yes — and it's increasingly common. Universal-planning preserves the U-ID conc - [`ce-work`](./ce-work.md) — execute the plan U-ID by U-ID - [`ce-doc-review`](./ce-doc-review.md) — persona-based review of the plan - [`ce-debug`](./ce-debug.md) — bug-shaped prompts route here -- [`ce-strategy`](./ce-strategy.md) — anchor plans to documented product strategy diff --git a/docs/skills/ce-strategy.md b/docs/skills/ce-strategy.md deleted file mode 100644 index 83621f8c0..000000000 --- a/docs/skills/ce-strategy.md +++ /dev/null @@ -1,205 +0,0 @@ -# `ce-strategy` - -> Create or maintain `STRATEGY.md` — a short, durable anchor that captures what the product is, who it serves, how it succeeds, and where the team is investing. - -`ce-strategy` is the **upstream anchor** skill. It produces and maintains a single canonical document at the repo root (peer of `README.md`) that downstream skills read as grounding. The document is short and structured on purpose — good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc. - -The compound-engineering ideation chain is `/ce-ideate → /ce-brainstorm → /ce-plan → /ce-work`. `STRATEGY.md` sits **upstream of the chain** — `ce-ideate`, `ce-brainstorm`, and `ce-plan` all read it as grounding when it exists, weighting their suggestions toward the active tracks and stated approach. - ---- - -## TL;DR - -| Question | Answer | -|----------|--------| -| What does it do? | Runs an interview with pushback rules, then writes/updates `STRATEGY.md` at the repo root | -| When to use it | Starting a new product; updating direction; "what are we working on?"; before kicking off ideation if no strategy exists yet | -| What it produces | `STRATEGY.md` with target problem, approach, persona, key metrics, tracks, optional milestones / non-goals / marketing | -| What's next | `/ce-ideate`, `/ce-brainstorm`, `/ce-plan` — all consult the doc as grounding | - ---- - -## The Problem - -Most teams either don't have a strategy doc, or have one that's so long nobody reads it. Failure shapes: - -- **Missing entirely** — every new piece of work re-litigates "are we even working on the right thing?" -- **Slogan, not strategy** — "we delight users" tells the agent (and humans) nothing actionable -- **Goals dressed up as strategy** — "grow ARR by 30%" is a goal, not a guiding choice -- **Feature lists in place of guiding policy** — "we're building X, Y, and Z" doesn't say *why* -- **Stale and untouched** — the strategy doc was written once and forgotten; it now describes a product the team isn't building anymore -- **Too long to scan** — a 20-page strategy nobody opens during day-to-day work doesn't anchor anything - -A good strategy doc is short, sharp, and read often. The hard part is producing one — most "write a strategy" prompts collapse into prose generation that papers over weak thinking. - -## The Solution - -`ce-strategy` runs an interview with explicit pushback rules: - -- **Anchor, not plan** — strategy is what the product is and why; features belong in `ce-brainstorm`, schedules belong in the issue tracker -- **Rigor in the questions, not the headings** — the section headers are plain English; the interview enforces the discipline -- **Short is a feature** — the template is constrained; expansion is pushed back on -- **Durable across runs** — re-runs update in place, preserving what's working and only revisiting weak sections -- **Pushback rules per section** — each section has named anti-patterns and probe questions that push past slogans, goals-as-strategy, and feature lists - -Inspired by Richard Rumelt's *Good Strategy Bad Strategy* — specifically his kernel of diagnosis, guiding policy, and coherent action. The interview questions are designed to push past the patterns Rumelt calls "bad strategy." - ---- - -## What Makes It Novel - -### 1. Pushback discipline in the interview - -For each section, the skill asks the opening question, then applies named pushback rules — pushing past fluff, slogans, vanity goals, and feature lists. Two rounds of pushback per section maximum; if the answer is still weak after that, capture what the user gave and note the section is worth revisiting next run. The pushback is the core of the skill — without it, the interview becomes passive transcription. - -### 2. Updates in place — durable across runs - -Re-running the skill on an existing `STRATEGY.md` doesn't rewrite from scratch. Phase 2 reads the existing doc, summarizes current state in 3-5 lines so the user sees what's on file, and asks which section to revisit (or jumps directly when the argument names a section). Sections the user confirms are still accurate are left untouched. The `last_updated` field in YAML frontmatter is updated to today. Strong sections aren't second-guessed; weak ones get the full pushback. - -### 3. Read by downstream skills as grounding - -When `STRATEGY.md` exists at the repo root, downstream skills read it: - -- **`ce-ideate`** — codebase-scan grounding agent reads it; ideation weights toward strategy-aligned directions automatically -- **`ce-brainstorm`** — Phase 1.1 constraint check reads it; product/scope decisions stay anchored to active tracks -- **`ce-plan`** — repo-research-analyst reads it; plan flags decisions that pull away from active tracks or the stated approach - -The doc is a peer of `README.md` (canonical, well-known location at the repo root) so the skills find it predictably. - -### 4. Rumelt-inspired structure - -The "Target problem / Our approach / Tracks" structure follows Rumelt's kernel: **diagnosis** (what's the situation, what's broken, what does it cost), **guiding policy** (the chosen approach, the strategic bet), **coherent action** (the active tracks of work that flow from the policy). The interview questions are designed to push past slogans toward this kernel. - -### 5. Bounded section count - -The required template is five sections (Target problem, Our approach, Who it's for, Key metrics, Tracks). Three optional sections (Milestones, Not working on, Marketing) are available but pushed back on when they don't carry weight. The constraint is the feature — strategy that needs 12 sections isn't strategy. - -### 6. Frontmatter for staleness tracking - -`STRATEGY.md` carries a `last_updated` field in YAML frontmatter. Downstream skills can flag the doc as potentially stale based on age; re-running the skill updates the timestamp. - ---- - -## Quick Example - -You're starting a new product and want a strategy doc before kicking off `ce-ideate`. You invoke `/ce-strategy`. - -The skill checks for an existing `STRATEGY.md` (none found) and announces "Strategy doc not found — let's write it." It reads `references/interview.md` and runs the interview in section order. - -**Target problem.** "What problem are you solving and for whom?" You answer "we help teams ship faster." The pushback fires: that's a slogan. "Whose teams? Shipping what? What does 'faster' mean — saving time per task, fewer bugs, less coordination overhead?" You sharpen: "we help engineering managers at 50-200 person companies cut PR-review cycle time from days to hours." That's specific enough. - -**Our approach.** "What's the strategic bet — the choice that shapes everything else?" You answer "use AI." The pushback fires: that's a tool, not a bet. "What's the bet about AI specifically — that AI can review better than juniors? That AI can pre-process review concerns before humans see them? That review doesn't need humans at all?" You sharpen. - -The interview proceeds through Who it's for, Key metrics, Tracks. Two rounds of pushback per section maximum. After all required sections are captured, the skill reads `references/strategy-template.md`, fills it in, presents the full draft in chat, offers one round of edits, then writes to `STRATEGY.md`. - -Phase 3 notes the doc is now in place and `ce-ideate`, `ce-brainstorm`, and `ce-plan` will pick it up on their next run. Suggests `/ce-ideate` as a natural next step. - ---- - -## When to Reach For It - -Reach for `ce-strategy` when: - -- You're starting a new product and want a strategy doc before kicking off ideation -- The product direction has shifted and the existing strategy is stale -- "What are we working on?" keeps coming up because the answer isn't documented anywhere -- A specific section feels weak and you want to revisit it (`/ce-strategy approach`) -- A downstream skill (`ce-ideate`, `ce-brainstorm`) flagged the absence of `STRATEGY.md` as missing grounding - -Skip `ce-strategy` when: - -- The strategy is on file and still accurate — re-running adds noise without value -- You're trying to plan a single feature → `/ce-brainstorm` -- You're trying to schedule work → that's the issue tracker, not strategy -- You want a roadmap with dates → strategy is direction; roadmaps are sequencing - ---- - -## Use as Part of the Workflow - -`ce-strategy` is upstream of the chain. The recommended sequence on a new product or major direction shift: - -```text -/ce-strategy → /ce-ideate (consults STRATEGY.md) → /ce-brainstorm → /ce-plan → /ce-work - ↑ - all read STRATEGY.md as grounding -``` - -The downstream skills don't *require* `STRATEGY.md` — they work without it. But when the doc exists, the active tracks and stated approach pull ideation, brainstorming, and planning toward strategy-aligned directions automatically. When `STRATEGY.md` is absent, `ce-ideate` can still ground in the codebase, but it has no signal about what *kind* of work matters most right now. - ---- - -## Use Standalone - -The skill is always invoked standalone — strategy isn't downstream of any other skill in the chain. - -- **First run** — `/ce-strategy` (no `STRATEGY.md` exists) -- **Targeted update** — `/ce-strategy approach` jumps directly to that section -- **Open update** — `/ce-strategy` (file exists, no argument) asks which section(s) to revisit - ---- - -## Output Artifact - -```text -STRATEGY.md (repo root, peer of README.md) -``` - -Sections (required unless noted): - -- **Target problem** — the diagnosis: what's broken, for whom, and what it costs -- **Our approach** — the guiding policy: the strategic bet that shapes everything -- **Who it's for** — the persona; specific enough that design decisions can reference it -- **Key metrics** — what the product measures itself by -- **Tracks** — coherent action: the active tracks of work -- **Milestones** _(optional)_ — meaningful upcoming markers -- **Not working on** _(optional)_ — explicit non-goals; useful when the team faces "should we do X?" pressure -- **Marketing** _(optional)_ — positioning and messaging direction when relevant - -YAML frontmatter carries `last_updated: YYYY-MM-DD`. The doc is short by design — typically 1-2 pages, not a chapter book. - ---- - -## Reference - -| Argument | Effect | -|----------|--------| -| _(empty)_ | First run if no `STRATEGY.md`; otherwise asks which section to revisit | -| `
` | e.g., `metrics`, `approach`, `tracks` — jumps to that section | -| `` | e.g., "metrics for retention" — focuses the revisit | - ---- - -## FAQ - -**Why is the doc so short?** -Because long strategy docs aren't read. The discipline forces sharp answers to a small number of questions. If you find yourself wanting more sections, the answer is usually "those belong in ce-brainstorm or the issue tracker, not in strategy." - -**What's the difference between strategy and a roadmap?** -Strategy is direction (what we're doing and why). A roadmap is sequencing (what's coming when). Strategy lives in `STRATEGY.md`; roadmaps live in the issue tracker, planning tools, or whatever the team uses for scheduling. The skill explicitly stays in the strategy lane. - -**What if my answers are weak?** -The skill applies pushback rules per section — two rounds maximum. If the answer is still weak after that, the skill captures what you gave and notes the section is worth revisiting next run. Strategy is iterative; it doesn't have to be perfect on first write. - -**Why does the doc go at the repo root?** -So downstream skills can find it predictably without configuration. Like `README.md`, `STRATEGY.md` is a canonical, well-known location. - -**What if I don't want downstream skills to read it?** -They will if it exists. The behavior is intentional — anchoring the chain to a stated strategy is the value. If you want to suppress this, delete the doc; you can recreate it later. - -**Is it useful for a non-software product?** -Yes — the structure (target problem, approach, persona, metrics, tracks) generalizes to any product. The pushback rules apply equally to a SaaS feature roadmap, a consulting practice, or a non-profit initiative. - ---- - -## Learn More - -The "Target problem / Our approach / Tracks" structure is informed by Richard Rumelt's *Good Strategy Bad Strategy* — specifically his kernel of diagnosis, guiding policy, and coherent action. The interview questions in `references/interview.md` are designed to push past the patterns Rumelt calls "bad strategy": fluff, goals dressed up as strategy, and feature lists in place of a guiding choice. The book is the recommended follow-up reading if the distinction between a slogan and a strategy isn't yet sharp. - ---- - -## See Also - -- [`ce-ideate`](./ce-ideate.md) — reads `STRATEGY.md` as grounding for ideation -- [`ce-brainstorm`](./ce-brainstorm.md) — reads it for constraint awareness during scope work -- [`ce-plan`](./ce-plan.md) — reads it; flags plan decisions that pull away from active tracks diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 89a23f296..99be1ba6f 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,7 +11,7 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 37 | -| Skills | 25 | +| Skills | 24 | ## Skills @@ -19,11 +19,8 @@ The primary entry points for engineering work, invoked as slash commands. Detail ### Core Workflow -`ce-strategy` anchors the loop upstream. - | Skill | Description | |-------|-------------| -| [`/ce-strategy`](../../docs/skills/ce-strategy.md) | Create or maintain `STRATEGY.md` — the product's target problem, approach, persona, key metrics, and tracks. Re-runnable to update. Read as grounding by `/ce-ideate`, `/ce-brainstorm`, and `/ce-plan` when present | | [`/ce-ideate`](../../docs/skills/ce-ideate.md) | Optional big-picture ideation: generate and critically evaluate grounded ideas, then route the strongest one into brainstorming | | [`/ce-brainstorm`](../../docs/skills/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a right-sized requirements doc before planning. Pass `output:html` to write the doc as a single self-contained HTML file instead of markdown (exclusive — md OR html, never both) | | [`/ce-plan`](../../docs/skills/ce-plan.md) | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking. Pass `output:html` to write the plan as a single self-contained HTML file instead of markdown (exclusive — md OR html, never both) | diff --git a/plugins/compound-engineering/skills/ce-strategy/SKILL.md b/plugins/compound-engineering/skills/ce-strategy/SKILL.md deleted file mode 100644 index 30634cd54..000000000 --- a/plugins/compound-engineering/skills/ce-strategy/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: ce-strategy -description: "Create or maintain STRATEGY.md - the product's target problem, approach, users, key metrics, and tracks of work. Use when starting a new product, updating direction, or when prompts like 'write our strategy', 'update the roadmap', 'what are we working on', or 'set up the strategy doc' come up. Also triggers when ce-ideate, ce-brainstorm, or ce-plan need upstream grounding and no strategy doc exists yet." -argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']" ---- - -# Product Strategy - -**Note: The current year is 2026.** Use this when dating the strategy document. - -`ce-strategy` produces and maintains `STRATEGY.md` - a short, durable anchor document that captures what the product is, who it serves, how it succeeds, and where the team is investing. It lives at the repo root as a canonical, well-known file (peer of `README.md`). Downstream skills (`ce-ideate`, `ce-brainstorm`, `ce-plan`) read it as grounding when it exists. - -The document is short and structured on purpose. Good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc. - -## Interaction Method - -Default to the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. - -Ask one question at a time. Prefer free-form responses for the substantive sections (problem, approach, persona); reserve single-select for routing decisions (which section to revisit). Each option label must be self-contained. - -## Focus Hint - - #$ARGUMENTS - -Interpret any argument as an optional focus: a section name to revisit (`metrics`, `approach`, `tracks`) or a scope hint. With no argument, proceed open-ended and let the file state decide the path. - -## Core Principles - -1. **Anchor, not plan.** Strategy is what the product is and why. Features belong in `ce-brainstorm`; schedules belong in the issue tracker. Do not let either creep into the doc. -2. **Rigor in the questions, not the headings.** The section headers are plain English. The interview questions enforce strategy discipline. -3. **Short is a feature.** The template is constrained. Adding sections costs more than it looks like. Push back on expansion. -4. **Durable across runs.** This skill is rerunnable. On a second run it updates in place, preserves what is working, and only challenges sections that look stale or weak. - -## Execution Flow - -### Phase 0: Route by File State - -Read `STRATEGY.md` using the native file-read tool. - -- **File does not exist** -> First run. Go to Phase 1. -- **File exists and argument names a specific section** -> Targeted update. Go to Phase 2. -- **File exists, no argument** -> Ask which section(s) to revisit, then Phase 2. - -Announce the path in one line: "Strategy doc not found - let's write it." or "Found existing strategy - let's review and update." - -### Phase 1: First-Run Interview - -Read `references/interview.md`. This load is non-optional - the pushback rules, anti-pattern examples, and quality bar for each section live there. Improvising from memory produces a passive transcription instead of a strategy doc. - -Run the interview in the section order of the final document: - -1. Target problem -2. Our approach -3. Who it's for -4. Key metrics -5. Tracks -6. Milestones (optional) -7. Not working on (optional) -8. Marketing (optional) - -For each section, ask the opening question, apply the pushback rules, and capture the final answer in the user's own language. Do not skip the pushback step - it is the core of the skill. Two rounds of pushback per section maximum; capture what the user has given after that and note the section is worth revisiting on the next run. - -When all required sections (1-5) are captured, read `references/strategy-template.md`, fill it in, and present the full draft in chat before writing. Offer one round of edits. Then write to `STRATEGY.md`. - -### Phase 2: Update Run - -Read the existing `STRATEGY.md` thoroughly. Summarize current state in 3-5 lines so the user sees what is on file. - -If the argument named a specific section, jump to that section in `references/interview.md`. Preserve all other sections exactly. Apply pushback as if this were a first run - do not rubber-stamp existing weak content just because it is already written. - -If no specific target, ask the user which section to revisit using the blocking question tool. Options: - -- "Target problem" -- "Our approach" -- "Who it's for" -- "Metrics, tracks, or other" - -For each revisited section, re-interview with full pushback. For sections the user confirms are still accurate, leave them untouched. Update the `last_updated` value in the YAML frontmatter to today's ISO date. - -Write the updated doc back to `STRATEGY.md`. - -### Phase 3: Downstream Handoff - -After writing, note in one line where the file lives and that `ce-ideate`, `ce-brainstorm`, and `ce-plan` will pick it up as grounding on their next run. - -If no downstream skill has run yet on this repo, suggest `ce-ideate` or `ce-brainstorm` skills as a next step. - -## What This Skill Does Not Do - -- Does not update the issue tracker or reconcile in-flight work. Strategy is the doc; execution lives elsewhere. -- Does not prioritize the backlog. Prioritization is a separate workflow. -- Does not write product requirements or implementation plans - those are `ce-brainstorm` and `ce-plan`. -- Does not compute metric values. It records which metrics matter and where they live, not what they read today. - -## Learn More - -The "Target problem / Our approach / Tracks" structure is informed by Richard Rumelt's *Good Strategy Bad Strategy* - specifically his kernel of diagnosis, guiding policy, and coherent action. The interview questions in `references/interview.md` are designed to push past the patterns he calls "bad strategy": fluff, goals dressed up as strategy, and feature lists in place of a guiding choice. The book is the recommended follow-up reading if the distinction between a slogan and a strategy is not yet sharp. diff --git a/plugins/compound-engineering/skills/ce-strategy/references/interview.md b/plugins/compound-engineering/skills/ce-strategy/references/interview.md deleted file mode 100644 index 4cb5d5b3c..000000000 --- a/plugins/compound-engineering/skills/ce-strategy/references/interview.md +++ /dev/null @@ -1,143 +0,0 @@ -# Strategy Interview - -Loaded by `SKILL.md` at the start of Phase 1 and revisited per-section in Phase 2. Every section below maps one-to-one to a section in `strategy-template.md`. - -For each section: ask the opening question, evaluate the answer against the quality bar, push back when it falls into a named anti-pattern, and capture the final answer in the user's own language. - -## Overall Rules - -1. **Ask, don't prescribe.** Do not offer menu options for open answers (problem, approach, persona). Use free-form responses. Reserve multi-select for routing decisions. -2. **Push back once, maybe twice.** If the first answer is weak, name the specific issue and ask a sharper question. If the second answer is still weak, capture what the user has given and note in the draft that the section is worth revisiting. Do not let the interview spiral. -3. **Quote the user back at them.** When challenging an answer, use the user's own words verbatim. Paraphrasing softens the challenge and is easier to dismiss. -4. **Keep each answer to 1-3 sentences.** Longer answers are usually hiding something vague. If the user writes a paragraph, ask them to pick the sentence that matters most. -5. **Don't leak the anti-pattern names.** The user does not need to hear "that's a vanity metric" - just ask the sharper question that follows. - ---- - -## 1. Target Problem - -**Opening question:** "What's the core problem this product solves - and what makes that problem hard?" - -Strong answers name a specific situation the target user is in, identify what makes the situation hard *right now* (a crux, a constraint, something that isn't easy to route around), and are falsifiable - you could imagine the problem being absent and know the difference. - -**Anti-patterns and pushback:** - -- **Goal stated as problem** ("the problem is we need to grow revenue") -> "That's a goal, not a problem. What's in the world that's making that goal hard to achieve? Whose situation are you changing?" -- **Vague wish** ("people need better tools for X") -> "Whose situation specifically? Doing what? What do they try today, and why doesn't it work?" -- **Symptom, not cause** ("users churn after 30 days") -> "That's a symptom. What's happening in their world that makes them stop caring? What's the underlying condition?" -- **Too broad** ("communication at work is broken") -> "That's a civilization-scale problem. Narrow it to a situation you can actually affect - which users, doing what, when does it hurt most?" -- **Feature-shaped** ("there's no good way to do [specific workflow] with AI") -> "That's a missing feature, not the underlying problem. What outcome do users want that the feature would give them?" - -**Capture:** One or two sentences naming the user's situation and the crux. No solution language. - ---- - -## 2. Our Approach - -**Opening question:** "Given that problem, what's your approach - the commitment or principle that makes it tractable?" - -This is the guiding choice: how the product competes or operates, so that many downstream decisions become easier. It is not the product and it is not a feature list. - -Strong answers are a choice (implying alternatives explicitly *not* pursued), are general enough to direct many decisions but specific enough to rule things out, and sound more like "we win by [doing X differently]" than "we do [a list of things]". - -**Anti-patterns and pushback:** - -- **Fluff / values** ("we're customer-obsessed and move fast") -> "Those are values, not an approach. What are you doing *differently* from the other products users could pick? If the answer applies to any company, it's not your approach." -- **Feature list** ("we're building AI-powered X, Y, and Z") -> "That's a feature list. What's the underlying bet that makes you pick those features over others? What principle is guiding what you ship?" -- **Product description as approach** ("we use AI to draft replies") -> "That's what the product does, but what's the *choice* inside it? Every competitor will say the same thing. Your approach should name what you're doing that the obvious alternative isn't - is it a grounding choice, a trust-building commitment, a workflow bet? What are you betting on that they're not?" -- **Goal restated** ("our approach is to be the market leader") -> "That's still the goal. How does the product win? What choice are you making that competitors aren't?" -- **Multiple approaches at once** ("we're going deep on enterprise, self-serve, and a consumer app") -> "Pick one as the guiding approach. The others may still get work, but one of them organizes the rest. Which is it?" -- **Doesn't connect to the problem** (problem: "users can't trust AI output"; approach: "build a fast, beautiful UI") -> "How does that approach solve the problem you named? If there's no line between them, one of the two is wrong." - -**Capture:** One or two sentences. Ideally ends with or implies "...so that [outcome tied to the problem]". - ---- - -## 3. Who It's For - -**Opening question:** "Who is the primary user, and what job are they hiring this product to do?" - -Jobs-to-be-done framing - the user isn't a demographic, they're someone in a situation trying to make progress. - -Strong answers name one primary persona (additional personas allowed but secondary), identify them by role or situation rather than demographic, and state a concrete job as a verb phrase. - -**Anti-patterns and pushback:** - -- **Too many primary personas** ("it's for founders, PMs, engineers, and designers") -> "If it's for everyone, it's for no one. Who matters most? The others can still benefit, but one of them drives the product decisions." -- **Demographic framing** ("25-45 year old professionals") -> "That's a demographic, not a user. What are they trying to do that makes them pick up this product?" -- **Role without situation** ("PMs") -> "PMs doing what? Running a roadmap review? Writing a spec at midnight? Convincing a skeptical eng lead? The situation is where the product matters." -- **Generic job** ("they want to be more productive") -> "Productive at what specifically? They're hiring this product to do *what*? The more specific, the better the product decisions downstream." - -**Capture:** Persona name plus JTBD sentence. Example: "Solo founders running their own roadmap. They're hiring the product to keep strategy and execution aligned without a PM on staff." - ---- - -## 4. Key Metrics - -**Opening question:** "What 3-5 metrics will tell you whether the approach is working?" - -Metrics are the feedback loop. Bad metrics create the illusion of progress while the product gets worse. - -Strong answers stay at 3-5 (not 10), mix leading and lagging (something that moves weekly and something that moves quarterly), and could plausibly regress if the product got worse. - -**Anti-patterns and pushback:** - -- **Vanity metrics** ("total signups, total pageviews, cumulative users") -> "Those can all go up while the product gets worse. What moves when users actually get value?" -- **Too many** ("here are 12 metrics we watch") -> "A dashboard isn't a strategy. Pick the 3-5 you'd stake the quarter on. What are the others telling you that those don't?" -- **Outputs, not outcomes** ("ship velocity, deploys per week") -> "Those measure the team, not the product. If the team doubled velocity but users didn't care, would you call it a win?" -- **Can only go up** ("cumulative hours saved") -> "A metric that can only go up doesn't tell you much. What's the rate, the ratio, or the thing that can regress?" -- **Unmeasurable** ("user delight") -> "How specifically? If you can't define how you'd check it on a Tuesday, it's aspirational, not a metric." - -**Capture:** A list of 3-5. Each with a one-line definition. Note where each is measured (analytics, DB, qualitative, etc.) if known. If measurement is undefined, ask: "Where does this metric live today? If nowhere, is this something you can start measuring?" - ---- - -## 5. Tracks - -**Opening question:** "What are the 2-4 tracks of work you're investing in to execute the approach?" - -Tracks are the coherent-actions half of the strategy kernel - concrete areas of investment that flow from the approach. They are not feature lists and not personal todo items. Each track is a named *domain of work*. - -Strong answers stay at 2-4 (not 8, not 1), connect clearly back to the approach, and are broad enough that multiple features live inside each one. - -**Anti-patterns and pushback:** - -- **Feature list in disguise** ("track 1: Slack integration; track 2: mobile app; track 3: dark mode") -> "Those are features. What's the *investment area* each one lives inside? 'Integrations' might be one track, with Slack, Teams, and Discord as candidates inside it." -- **Too many tracks** ("we have 7 tracks this quarter") -> "With 7 tracks, every track is starved for attention. Which 3 are load-bearing? The others either fold in or drop." -- **Doesn't connect to approach** (approach: "win by being the easiest to onboard"; track: "enterprise SSO") -> "How does that track serve the approach? If it's a separate bet, name it as one. If it's load-bearing for onboarding, explain the link." -- **Too vague** ("improve the product") -> "Every track is 'improve the product.' What's the specific investment area that's different from the others?" -- **One track only** -> "With one track, there's no real choice being made. What are the 2-3 things the product needs to be good at, and how are they different?" - -**Capture:** 2-4 tracks. For each: a name, a one-line purpose, and a short note on why this serves the approach. - ---- - -## 6. Milestones (optional) - -**Opening question:** "Are there any dated milestones worth anchoring - a launch, a fundraise, a conference, a renewal? Skip if none apply." - -Only capture externally visible, real milestones. Avoid turning this into an internal schedule. - -Default is to skip. Do not push the user to invent milestones. If they name some, capture them verbatim with dates. - ---- - -## 7. Not Working On (optional) - -**Opening question:** "Is there anything you've explicitly decided *not* to do right now that's worth naming? This is for things the team keeps being tempted by." - -Clarity tool, not a blocker list. Skip by default. If the user names items, one sentence each. Do not encourage a long list. - ---- - -## 8. Marketing (optional) - -**Opening question:** "Any positioning or narrative language you want the doc to carry - a one-liner, a tagline, a key message? Skip if not yet." - -Skip by default. Keep to 2-3 lines if present. - ---- - -## After the Interview - -Once sections 1-5 are captured (and any optional sections the user engaged with), read `strategy-template.md` and fill it in. Present the full draft in chat before writing. Offer one edit round. Then write to `STRATEGY.md`. diff --git a/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md b/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md deleted file mode 100644 index ad38ccdf8..000000000 --- a/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md +++ /dev/null @@ -1,89 +0,0 @@ -# Strategy Template - -Loaded by `SKILL.md` after the interview is complete. Fill it in using the captured answers and write to `STRATEGY.md`. - -## Rules for filling in - -- Use the user's own language where possible. Do not paraphrase into generic PM-speak. -- Each section stays compact. The whole doc should read in under 5 minutes. -- Section order is locked. Do not add new top-level sections. -- Optional sections: delete entirely if unused. Do not leave empty headers. -- Set `last_updated` in the YAML frontmatter to today's ISO date (YYYY-MM-DD). Do not duplicate the date in prose. -- Set `name` in the frontmatter to the product or initiative name (the same value used in the H1 title). - -## Template - -The block below is the literal file to write (minus this line and the fences). Replace every `{{placeholder}}` with the captured answer. Delete any optional section whose placeholder wasn't answered. - -~~~markdown ---- -name: {{product_name}} -last_updated: {{YYYY-MM-DD}} ---- - -# {{product_name}} Strategy - -## Target problem - -{{1-2 sentence diagnosis. Names the user situation and the crux that makes it hard. No solution language.}} - -## Our approach - -{{1-2 sentence guiding policy. What this product commits to, so that the target problem becomes tractable.}} - -## Who it's for - -**Primary:** {{Persona name}} - {{one-sentence JTBD, e.g. "They're hiring {{product_name}} to..."}} - - - -## Key metrics - -- **{{metric 1 name}}** - {{one-line definition; where it's measured}} -- **{{metric 2 name}}** - {{...}} -- **{{metric 3 name}}** - {{...}} - - - -## Tracks - -### {{Track 1 name}} - -{{One line: what this track is - the investment area, not a feature list.}} - -_Why it serves the approach:_ {{one line}} - - - -## Milestones - -- **{{YYYY-MM-DD}}** - {{milestone}} - - - -## Not working on - -- {{one line per item}} - - - -## Marketing - -**One-liner:** {{single-sentence pitch}} - -**Key message:** {{2-3 lines if useful}} - - -~~~ - -## Post-write checklist - -Before confirming the write, scan the draft for: - -- [ ] Frontmatter present at the top with `name` and `last_updated` keys. -- [ ] `last_updated` carries today's date in ISO format (YYYY-MM-DD). -- [ ] No section has more than 4 sentences except Tracks (where each track has its own short block). -- [ ] No placeholders remain (`{{...}}`). -- [ ] Optional sections with no content have been deleted, not left empty. -- [ ] Metric count is between 3 and 5. Track count is between 2 and 4. -- [ ] Target problem and Our approach are connected - one clearly responds to the other. diff --git a/src/data/plugin-legacy-artifacts.ts b/src/data/plugin-legacy-artifacts.ts index fa8057697..4bc043890 100644 --- a/src/data/plugin-legacy-artifacts.ts +++ b/src/data/plugin-legacy-artifacts.ts @@ -124,6 +124,7 @@ const EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN: Record = "ce-gemini-imagegen", "lfg", "ce-report-bug", + "ce-strategy", "todo-create", "todo-resolve", "todo-triage", diff --git a/src/utils/legacy-cleanup.ts b/src/utils/legacy-cleanup.ts index 03421ac8a..58050fb51 100644 --- a/src/utils/legacy-cleanup.ts +++ b/src/utils/legacy-cleanup.ts @@ -134,6 +134,9 @@ export const STALE_SKILL_DIRS = [ // Removed bug-filing skill (slim/ultra-minimal). The renamed-era // "report-bug-ce" entry above stays; this is the current-era dir name. "ce-report-bug", + + // Removed upstream-anchor strategy skill (slim/ultra-minimal) + "ce-strategy", ] /** Old agent names (used as generated skill dirs or flat .md files). */ @@ -393,6 +396,10 @@ const LEGACY_ONLY_SKILL_DESCRIPTIONS: Record = { // once the skill dir is gone. "ce-report-bug": "Report a bug in the compound-engineering plugin", + + // ce-strategy was the upstream-anchor strategy skill (removed, no replacement). + "ce-strategy": + "Create or maintain STRATEGY.md - the product's target problem, approach, users, key metrics, and tracks of work. Use when starting a new product, updating direction, or when prompts like 'write our strategy', 'update the roadmap', 'what are we working on', or 'set up the strategy doc' come up. Also triggers when ce-ideate, ce-brainstorm, or ce-plan need upstream grounding and no strategy doc exists yet.", } /** From f5c832e1f010b33674566cf4f6d03a1cbda1f646 Mon Sep 17 00:00:00 2001 From: metaphorics <152830360+metaphorics@users.noreply.github.com> Date: Sat, 6 Jun 2026 23:35:55 +0900 Subject: [PATCH 05/40] refactor(ce-dogfood-beta)!: drop the ce-dogfood-beta skill Removed from the plugin; the legacy-cleanup registries now fingerprint and sweep stale installs on upgrade. BREAKING CHANGE: removes the ce-dogfood-beta skill. Op: correct Restores: spec:fork-slimness (AGENTS.md Scope & Lineage) --- plugins/compound-engineering/README.md | 8 +- .../skills/ce-dogfood-beta/SKILL.md | 187 ------------------ .../references/dogfood-report-template.md | 72 ------- .../references/test-matrix-taxonomy.md | 62 ------ src/data/plugin-legacy-artifacts.ts | 1 + src/utils/legacy-cleanup.ts | 7 + 6 files changed, 9 insertions(+), 328 deletions(-) delete mode 100644 plugins/compound-engineering/skills/ce-dogfood-beta/SKILL.md delete mode 100644 plugins/compound-engineering/skills/ce-dogfood-beta/references/dogfood-report-template.md delete mode 100644 plugins/compound-engineering/skills/ce-dogfood-beta/references/test-matrix-taxonomy.md diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 99be1ba6f..718483a2e 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,7 +11,7 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 37 | -| Skills | 24 | +| Skills | 23 | ## Skills @@ -70,12 +70,6 @@ The primary entry points for engineering work, invoked as slash commands. Detail | [`/ce-doc-review`](../../docs/skills/ce-doc-review.md) | Review documents using parallel persona agents for role-specific feedback | | [`/ce-simplify-code`](../../docs/skills/ce-simplify-code.md) | Simplify recent code changes for reuse, quality, and efficiency — parallel reviewers find issues, fixes applied, behavior verified by tests | -### Beta / Experimental - -| Skill | Description | -|-------|-------------| -| `/ce-dogfood-beta` | Diff-scoped browser QA of the active branch: builds an exhaustive test matrix of every change, drives the app with agent-browser, then auto-fixes issues, adds regression tests, and commits each fix until green | - ## Agents Agents are specialized subagents invoked by skills — you typically don't call these directly. diff --git a/plugins/compound-engineering/skills/ce-dogfood-beta/SKILL.md b/plugins/compound-engineering/skills/ce-dogfood-beta/SKILL.md deleted file mode 100644 index 1229d4118..000000000 --- a/plugins/compound-engineering/skills/ce-dogfood-beta/SKILL.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -name: ce-dogfood-beta -description: "[BETA] Dogfood the active branch end-to-end as a QA engineer. Diffs the branch against main, builds an exhaustive browser test matrix of every change (full user journeys, not just features), drives the app with agent-browser, then auto-fixes issues, adds regression tests, and commits each fix until the matrix is green. Use when you want a hands-off 'test everything we just built and make it actually work' pass before shipping." -disable-model-invocation: true -argument-hint: "[PR number, branch name, or blank for current branch] [--port PORT]" ---- - -# Dogfood (Beta) - -Act as a QA engineer who dogfoods the **active branch** end-to-end: understand every change, test every change in a real browser as a user would, and fix what's broken — autonomously — until the branch is genuinely ready. - -This is **diff-scoped**, not whole-app exploration. You test what *this branch* introduced or modified versus `main`. (For full-app exploratory QA, use the `dogfood` skill instead.) - -## Use `agent-browser` Only For Browser Automation - -This workflow drives the browser exclusively through the `agent-browser` CLI. Do not use Chrome MCP tools (`mcp__claude-in-chrome__*`), any browser MCP integration, or other built-in browser-control tools. If the platform offers multiple ways to control a browser, always choose `agent-browser`. Use the direct binary, never `npx agent-browser` (the direct binary uses the fast Rust client). - -## Prerequisites - -- A local dev server you can start (`bin/dev`, `rails server`, `npm run dev`, etc.). -- `agent-browser` installed. Check: - - ```bash - command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED" - ``` - - If not installed, run the `ce-setup` skill to install dependencies, then resume. Do not continue without it. - -## Reusing Compound-Engineering Skills - -`ce-dogfood-beta` is an orchestrator. Prefer delegating to existing CE skills over re-deriving their behavior: - -| When | Skill | Why | -|------|-------|-----| -| Phase 0 isolation | `ce-worktree` | Run the dogfood in an isolated worktree so the main checkout stays clean. | -| agent-browser missing | `ce-setup` | Installs `agent-browser` and other deps. | -| A failure's root cause is non-obvious | `ce-debug` | Systematic root-cause analysis instead of guess-and-check. | -| Committing each fix | `ce-commit-push-pr` (commit-only mode) | Consistent, well-scoped commit messages without pushing. | -| A bug reveals a reusable lesson | `ce-compound` | Capture the learning so the team compounds knowledge. | - -Reuse `ce-test-browser`'s mechanics for port detection and dev-server startup (see Phase 3) rather than reinventing them. - -## Workflow - -``` -0. Scope Pick the branch, get onto it (offer worktree), never touch main -1. Analyze Diff branch vs main, understand every change -2. Map+Matrix Map user flows as Mermaid flowcharts, then derive the test matrix as a task list -3. Serve Detect port, start dev server, open agent-browser -4. Execute Work the matrix one item at a time with agent-browser -5. Fix loop On failure: fix -> add regression test -> commit -> continue -6. Report Write durable doc to docs/dogfood-reports/ (flows, matrix, fixes, learnings, verdict) -``` - -### Phase 0: Scope and Get on the Right Branch - -Parse `$ARGUMENTS`: a PR number, a branch name, or blank (use current branch). Strip `--port PORT` if present. - -1. Resolve the target branch: - - **PR number:** `gh pr checkout ` (probe for an existing worktree first). - - **Branch name:** check it out (probe for an existing worktree first). - - **Blank:** use the current branch. -2. **Refuse to run on `main`/`master`.** If the resolved branch is the trunk, stop and tell the user — there is no diff to dogfood. -3. **Offer isolation.** Ask whether to run in a git worktree so the main checkout stays untouched (use the platform's blocking question tool). If yes, hand off to `ce-worktree`; if no, continue in place. -4. **Resume if a prior run exists.** Look for an existing report at `docs/dogfood-reports/*--dogfood.md`. If one is found with unfinished scenarios, ask whether to resume it or start fresh. To resume, re-hydrate the task list from its matrix (Pass/Fixed/Skipped stay done; Pending/Blocked/in-progress become the remaining work) and continue from there. - -### Resumability (stop and return at any point) - -This workflow is designed to be interrupted and resumed. Two pieces of state make that safe: - -- **The task list** (`TaskCreate`/`TaskUpdate`) is the live to-do — one task per matrix scenario. Mark each `in_progress` when you start it and `completed` only when it genuinely passes. -- **The report doc** at `docs/dogfood-reports/--dogfood.md` is the durable checkpoint that survives across sessions. **Create it as soon as the matrix exists (end of Phase 2)** with every scenario listed as `Pending`, and **update it incrementally** — after each scenario is judged and after each fix is committed — not only at the end. - -Because tasks are session-scoped but the report doc is on disk, the report is the source of truth for resuming. Always keep the two in sync so a later run (or a teammate) can pick up exactly where this one stopped. - -### Phase 1: Analyze Changes - -Pull the full diff against `main` and read it carefully — you cannot test what you don't understand. - -```bash -git diff --name-only main...HEAD # what changed -git diff main...HEAD # how it changed -``` - -Build a mental model of every change: new features, modified behavior, new routes/views/components, touched data flows. Note anything that produces user-visible behavior — that is what the matrix must cover. - -**Ground in the product's personas and vision.** Look for persona and vision context so flows can be judged from real users' eyes, not just "does it work." Check, in order: `STRATEGY.md` (its "Who it's for" section names the primary persona and their job-to-be-done), `VISION.md`, and any persona docs (e.g. `docs/personas/`, `PERSONAS.md`). Capture the 1-3 primary personas and what each cares about. If none exist, infer a reasonable primary persona from the product and the diff, and say so in the report. - -### Phase 2: Map the Flows, Then Build the Matrix - -The quality of the whole dogfood depends on this phase. Do not jump straight to a flat list of pages. First **understand the user flows the diff touches**, then derive the matrix from them. A matrix built without a flow model tests pages in isolation and misses the journey — the email that "sends" but lands in the wrong thread. - -#### 2a. Map the user flows (required) - -For every user-visible change, trace the **complete journey** end to end and draw it. Map each flow as a **Mermaid `flowchart`** so the journey is explicit and reviewable before any testing happens — entry point, each user action, branch points (success / validation error / empty / permission-denied), side effects (emails, jobs, notifications), and the true end state. - -> Email example: it's not enough that "an email sends." Does it go to the *right* recipient? When the user clicks through, does the app land on and scroll to the *right* message? Does the content make sense? Does the whole flow align with the product's vision and UX? The flowchart must carry the click-through and its destination, not stop at "email sent." - -```mermaid -flowchart TD - A[User opens /threads] --> B[Clicks 'Reply'] - B --> C{Form valid?} - C -->|No| D[Inline validation error shown] - C -->|Yes| E[Reply saved] - E --> F[Notification email sent to thread participants] - E --> G[UI scrolls to new reply, focus on it] - F --> H[Recipient clicks email link] - H --> I{Lands on correct thread + scrolls to the reply?} -``` - -Produce one flowchart per distinct journey. Cover the happy path **and** the branch points (error, empty, boundary, permission). These diagrams ARE the understanding — they become the spine of the matrix and belong in the final report. - -#### 2b. Derive the matrix from the flows - -Walk each flowchart and turn every node and branch into one or more test scenarios. Read `references/test-matrix-taxonomy.md` for the full set of dimensions (journeys, functional checks, experiential checks, edge/error/empty states, accessibility, responsiveness). Cover both **functional** ("does it work?") and **experiential** ("does it feel right and align with the product?"). - -Map changed files to concrete routes (views -> their pages, components -> pages rendering them, layouts -> all pages, stylesheets -> visual regression on key pages) and attach those routes to the flows that exercise them. - -**Load the matrix as a task list** (`TaskCreate`), one task per scenario, so progress is tracked and nothing is skipped. Order tasks by flow, following the flowcharts, not by file. - -### Phase 3: Detect Port and Start the Dev Server - -Determine the port (priority: explicit `--port` > `AGENTS.md`/`CLAUDE.md` > `package.json` dev script > `.env*` `PORT=` > default `3000`). If a server is already listening, reuse it; otherwise start the project's dev command in the background and wait for the port to come up. This is the same mechanism `ce-test-browser` uses — follow its Phase 5–6 logic. - -```bash -agent-browser open "http://localhost:${PORT}" -agent-browser snapshot -i -``` - -### Phase 4: Execute the Matrix - -Work the task list **one item at a time**. For each scenario, mark the task `in_progress`, then: - -1. **Document** what you're testing (the journey and the expected outcome). -2. **Drive it** with agent-browser — navigate, snapshot for interactive refs, click, fill, submit, follow the journey to its real end state: - - ```bash - agent-browser open "http://localhost:${PORT}/" - agent-browser snapshot -i - agent-browser click @e1 - agent-browser fill @e2 "value" - agent-browser screenshot .png - agent-browser errors # check console/page errors - ``` - -3. **Judge** both correctness and experience: right data, right destination, sensible content, no console errors, and does it feel aligned with the product? -4. **Walk it as each persona.** Re-run the journey in your head from each primary persona's perspective (from Phase 1) and ask where they'd feel a **paper cut** — a small friction that wouldn't fail a functional test but degrades the experience: a confusing label, an extra click, an unexpected jump, a slow-feeling step, missing feedback, copy that doesn't match how that persona thinks. A scenario can be functionally `Pass` yet still carry paper cuts. Note each paper cut, which persona feels it, and its severity. -5. **Record** pass/fail plus any paper cuts, with specifics. Mark the task `completed` only when it genuinely passes (paper cuts are logged, not blockers — fix the sharp ones in Phase 5, surface the rest in the report). - -**External-interaction flows** (OAuth, real email delivery, payments, SMS) can't be fully driven headlessly — pause and ask the user to verify that leg, then continue. - -### Phase 5: Fix Loop (Autonomous) - -When a scenario fails, **fix it and prove it** — but first decide whether the fix is yours to make autonomously or a human's to decide. - -**Judge the size of the fix before touching code.** Auto-fix when the change is small, well-understood, and low-risk: a clear bug with an obvious correct fix, contained to a few files, no schema/architecture/product trade-off. **Do not auto-fix** when the change is large or ambiguous — it requires an architectural or schema decision, changes product behavior or UX intent, spans many files, has plausible competing solutions, or you're not confident the "right" answer is unambiguous. Forcing a big judgment call autonomously is worse than escalating it. - -**For autonomous fixes:** - -1. Investigate the root cause. If it's non-obvious, use `ce-debug`. -2. Apply the fix in the code. -3. **Add an automated regression test** that fails before the fix and passes after, so the bug can't return. -4. Commit the fix with a clear message (use `ce-commit-push-pr` in commit-only mode). One logical fix per commit. -5. Re-run the failing scenario in the browser to confirm it now passes; then continue the matrix. -6. If the bug carried a reusable lesson, capture it with `ce-compound`. - -**For changes too big to make autonomously:** do not implement. Record it in the report's **Decisions for a human** section with: what's broken, why it's not a safe autonomous fix, the options you see (with trade-offs), and your recommendation. Mark the scenario `Blocked (human decision)` in the matrix, then continue with the rest. Never make a large, irreversible, or product-altering change just to clear a matrix item. - -Keep iterating until every task is `completed` or explicitly `Blocked (human decision)`. Re-test anything a fix might have affected (watch for regressions in adjacent journeys). - -### Phase 6: Write the Report Artifact - -The report doc was created at the end of Phase 2 and updated incrementally throughout (see Resumability). When the matrix is green (or every remaining item is explicitly blocked), **finalize** it at `docs/dogfood-reports/--dogfood.md` in the repo under test, then surface a short summary in chat with the file path. - -Use `references/dogfood-report-template.md` as the shape — the same way plans and brainstorms are captured from a template. The finalized artifact must include: - -1. **Diff Summary** — what changed between the branch and `main`. -2. **Personas** — the primary personas evaluated against (and their source: STRATEGY.md / VISION.md / inferred). -3. **Flows tested** — the Mermaid flowcharts from Phase 2a, so the journeys are preserved. -4. **Test Matrix & Results** — every scenario: what was tested, pass/fail, issue found, fix applied, commit SHA. -5. **What was fixed** — each bug, its root cause, the fix, the regression test added, and the commit. -6. **Paper cuts (by persona)** — experiential friction found, which persona feels each, severity, and whether fixed or deferred. -7. **Decisions for a human** — issues too big to fix autonomously: what's broken, why it was escalated, options with trade-offs, and a recommendation. -8. **Learnings** — reusable lessons worth carrying forward (feed substantial ones to `ce-compound`). -9. **Final Status** — readiness verdict, plus anything still blocked or needing human verification. - -Use repo-relative paths in the doc, never absolute paths, so it stays portable. diff --git a/plugins/compound-engineering/skills/ce-dogfood-beta/references/dogfood-report-template.md b/plugins/compound-engineering/skills/ce-dogfood-beta/references/dogfood-report-template.md deleted file mode 100644 index 3531731c8..000000000 --- a/plugins/compound-engineering/skills/ce-dogfood-beta/references/dogfood-report-template.md +++ /dev/null @@ -1,72 +0,0 @@ -# Dogfood Report — - -> Diff-scoped browser QA of `` vs `main`. Generated by `/ce-dogfood-beta` on . - -## Diff Summary - - - -## Personas - - - -- **** — - -## Flows Tested - - - -```mermaid -flowchart TD - A[Entry point] --> B[User action] - B --> C{Branch point?} - C -->|No| D[Error / empty / denied state] - C -->|Yes| E[Result + side effects] - E --> F[True end state] -``` - -## Test Matrix & Results - -| # | Flow | Journey / Scenario | Status | Issue | Fix | Commit | -|---|------|--------------------|--------|-------|-----|--------| -| 1 | | | Pass | - | - | - | -| 2 | | | Fixed | | | abc123 | -| 3 | | | Blocked (needs human verify) | | | | - -Status values: `Pending`, `Pass`, `Fixed`, `Skipped`, `Blocked (needs human verify)`, `Blocked (human decision)`. Start every scenario at `Pending` so this table doubles as the resume checkpoint. - -## What Was Fixed - -For each issue found and fixed: - -### — `` -- **Symptom:** -- **Root cause:** -- **Fix:** -- **Regression test:** - -## Console Errors - - - -## Human Verifications - - - -## Decisions for a Human - - - -### -- **What's broken:** -- **Why escalated:** -- **Options:**