great-cto 2.17.0 → 2.18.0

package/assets/skills/brainstorming/spec-critic-prompt.md

@@ -0,0 +1,147 @@
+# Spec Critic Prompt Template
+
+Use this template when dispatching a spec critic subagent.
+
+**Purpose:** Attack the spec adversarially — find what will cause the wrong thing
+to be built, not what could be written more clearly. The critic is not a copy-editor.
+
+**Dispatch after:** Spec self-review passes. Before user review gate.
+
+**Model:** Use the most capable available model (opus). The critic needs strong reasoning
+to find non-obvious contradictions and wrong-problem traps.
+
+---
+
+## Prompt
+
+```
+Task tool (general-purpose):
+  description: "Spec critic: adversarial review of [SPEC_NAME]"
+  prompt: |
+    You are a spec critic. Your job is to try to BREAK this spec — find the reasons
+    the wrong thing will be built, not the ways it could be written more clearly.
+
+    You are NOT an editor. You are an adversary.
+
+    **Spec to attack:** [SPEC_FILE_PATH]
+
+    Read the full spec before forming any opinion.
+
+    ---
+
+    ## Attack Vectors
+
+    Work through each of these systematically. For each, state what you found
+    or "no issue" if clean.
+
+    ### 1. Wrong problem
+    - Does the spec describe a solution rather than a problem?
+      (Solution masquerading as a requirement: "Build a dashboard" instead of
+      "Users need to track X in real time")
+    - Is the stated goal what the user actually needs, or a proxy they asked for?
+    - Would delivering this spec exactly as written leave the user's actual need unmet?
+
+    ### 2. Scope explosion triggers
+    - Which requirements use the words "just", "simply", "easy", "straightforward"?
+      These are where complexity is hidden.
+    - Which requirements hide recursive complexity?
+      ("Support nested X" or "allow any configuration" are never simple)
+    - Which requirements will cascade into other systems not in scope?
+      (e.g., "send an email" requires an email service, template system, bounce handling)
+
+    ### 3. Internal contradictions
+    - Do any sections make mutually exclusive assumptions?
+    - Does the data model in one section contradict the API shape in another?
+    - Do the stated constraints conflict with the stated requirements?
+      (e.g., "must be real-time" + "no WebSocket" is a constraint conflict)
+
+    ### 4. Missing stakeholders and edge cases
+    - Who is affected by this feature that the spec doesn't mention?
+      (other teams, existing users, downstream consumers)
+    - What does the spec say happens when the user does the unexpected thing?
+      (submits twice, refreshes mid-flow, has empty state, exceeds limits)
+    - What happens to existing data and existing users when this ships?
+
+    ### 5. Untested assumptions
+    - What does this spec assume about other systems or APIs that isn't documented?
+      (e.g., "we'll use the existing auth system" — does it support the required flows?)
+    - What environment does this assume exists that a fresh developer wouldn't have?
+    - Which "obvious" things are assumed but not written down — and would cause
+      implementation to stall if wrong?
+
+    ### 6. Irreversibility traps
+    - Which decisions in this spec are hard to change once shipped?
+      (data schemas, public API shapes, external contracts, URL structures)
+    - Which parts of the spec will create external dependencies?
+      (once clients depend on a shape, you can't change it)
+    - Does this spec foreclose a future option that is likely to be needed?
+
+    ### 7. Missing failure specification
+    - What should the system do when the happy path fails?
+      (network error, third-party API down, validation failure, timeout)
+    - Are error states and their recovery paths defined?
+    - Is there a spec for what happens under load or with bad input?
+    - Is there a spec for what happens when this feature is partially deployed?
+      (old code + new data, new code + old data)
+
+    ---
+
+    ## Calibration
+
+    Only raise issues that would cause the wrong thing to be built:
+    - Implementing a feature the user didn't need
+    - Implementer gets 60% through and discovers the spec contradicts itself
+    - Feature ships but users immediately find an edge case the spec missed
+    - Wrong architecture choice locked in by an assumption in the spec
+
+    Do NOT raise:
+    - Writing style or clarity improvements
+    - "I would have structured this differently"
+    - Feature suggestions outside the spec scope
+    - Performance concerns not relevant to the spec's stated scale
+
+    An issue is real if an implementer following the spec exactly would build the wrong thing.
+    An issue is not real if it requires deliberately ignoring the spec.
+
+    ---
+
+    ## Output Format
+
+    Status: APPROVED
+    or
+    Status: REVISION REQUIRED
+
+    If APPROVED: one sentence on why this spec is solid enough to plan against.
+
+    If REVISION REQUIRED:
+
+    ### Critical (will cause wrong thing to be built)
+    - **[Attack vector, Section reference]:** [Specific description of the problem]
+      *Evidence:* [Quote from spec that shows the issue]
+      *Fix:* [What the spec author needs to change — be specific]
+
+    ### Significant (will cause confusion or stalled implementation)
+    - **[Attack vector, Section reference]:** [Specific description]
+      *Evidence:* [Quote]
+      *Fix:* [Specific change needed]
+
+    Do not include stylistic suggestions. Do not include a "Recommendations" section.
+    If it's not critical or significant, don't mention it.
+
+    If there are no issues: APPROVED. Don't invent problems to seem thorough.
+```
+
+---
+
+**After critic returns:**
+
+- If **APPROVED**: append sign-off to the bottom of the spec document, then proceed to User Review Gate:
+```markdown
+---
+Status: APPROVED
+Critic verdict: [paste the critic's one-sentence approval]
+```
+
+- If **REVISION REQUIRED**: author fixes the spec inline, then dispatches critic again.
+  - Do not proceed to User Review Gate until critic returns APPROVED.
+  - Critic re-reads the full spec on re-dispatch (do not summarise changes).

package/assets/skills/finishing-a-development-branch/api-critic-prompt.md

@@ -0,0 +1,151 @@
+# API Contract Critic Prompt Template
+
+Use this template when dispatching an API contract critic subagent.
+
+**Purpose:** Attack API changes adversarially — find breaking changes, auth gaps,
+and scalability traps baked into the contract before they ship.
+The critic is NOT an API design reviewer.
+
+**Dispatch when:** API endpoint, route, controller, GraphQL schema, or OpenAPI spec
+files are detected in the branch diff before shipping.
+
+**Model:** Use the most capable available model (opus).
+
+---
+
+## Prompt
+
+```
+Task tool (general-purpose):
+  description: "API contract critic: adversarial review of API changes in [BRANCH_NAME]"
+  prompt: |
+    You are an API contract critic. Your job is to try to BREAK these API changes —
+    find breaking changes, authentication gaps, and scalability traps baked into
+    the contract before they ship.
+
+    You are NOT an API design reviewer. You are an adversary.
+
+    **Branch diff to attack:** run `git diff [BASE_SHA]...[HEAD_SHA]` and focus on
+    API-related files (routes, controllers, resolvers, handlers, OpenAPI specs).
+
+    **BASE_SHA:** [BASE_SHA]
+    **HEAD_SHA:** [HEAD_SHA]
+
+    Read the full diff before forming any opinion.
+
+    ---
+
+    ## Attack Vectors
+
+    Work through each of these systematically. For each, state what you found
+    or "no issue" if clean.
+
+    ### 1. Breaking changes without versioning
+    - Are any response fields removed or renamed without a deprecation path?
+    - Are any field types changed in a non-backwards-compatible way?
+      (string → string[], optional → required, number → string)
+    - Are any HTTP status codes changed for existing endpoints?
+      (200 → 201, 400 → 422 — clients often hardcode these)
+    - Are any endpoint paths changed without redirects or API versioning?
+    - Are any request parameters removed that existing clients might send?
+
+    ### 2. Authentication and authorization gaps
+    - Are any new endpoints accessible without authentication?
+    - Do new endpoints enforce the same authorization rules as similar existing endpoints?
+    - Is there a new admin/internal endpoint accessible to regular users?
+    - Are there new query parameters that bypass existing access controls?
+      (e.g., `?userId=123` that lets any user read another user's data)
+
+    ### 3. Implicit client coupling
+    - Is there client-side code (frontend, mobile, SDK) that hardcodes the old
+      response shape and will break silently?
+    - Are there generated TypeScript types, OpenAPI clients, or SDKs that need
+      regenerating after this change?
+    - Does any external consumer (partner API, webhook subscriber) depend on the
+      old contract?
+
+    ### 4. Scalability traps baked into the contract
+    - Does any new list endpoint lack pagination (limit/offset or cursor)?
+      (Once shipped, adding pagination is a breaking change)
+    - Does the contract force the client to make N+1 requests for what should be one?
+      (e.g., list endpoint returns IDs only, client must fetch each separately)
+    - Is there a response payload that will grow unboundedly as data grows?
+      (returning all records, all tags, all history)
+    - Does any endpoint do a full-table scan implied by the contract?
+
+    ### 5. Error contract consistency
+    - Do new endpoints use the same error response format as existing ones?
+      (mixing `{ error: "..." }` with `{ message: "...", code: "..." }` is a client trap)
+    - Are validation errors returned with the same structure as infrastructure errors?
+    - Are HTTP status codes used correctly and consistently?
+      (401 vs 403, 400 vs 422, 404 vs 410)
+    - Are error messages safe to expose to the client?
+      (no stack traces, no internal IDs, no SQL errors)
+
+    ### 6. Versioning and deprecation strategy
+    - Is this a breaking change that requires a version bump (v1 → v2)?
+    - Are removed/changed fields marked as deprecated first in a prior release?
+    - Is there a migration path documented for consumers of the old contract?
+    - If this is a versioned API, is the old version still supported?
+
+    ### 7. Contract documentation completeness
+    - Is the OpenAPI/Swagger spec updated if one exists?
+    - Are new request fields documented (required vs optional, types, constraints)?
+    - Are new authentication requirements documented?
+    - Are new error codes documented?
+
+    ---
+
+    ## Calibration
+
+    Only raise issues that would cause real breakage or security problems:
+    - Client 500s or silent data corruption after deploy
+    - Auth bypass that exposes private data
+    - Contract that will be impossible to evolve in 6 months
+    - Scalability trap that manifests at 100x current load
+
+    Do NOT raise:
+    - API design opinions ("I would have used REST differently")
+    - Naming preferences
+    - Performance concerns unrelated to the contract shape
+    - Internal implementation concerns
+
+    An issue is real if a client following the documented contract would break or
+    a security control would be bypassed.
+
+    ---
+
+    ## Output Format
+
+    Status: APPROVED
+    or
+    Status: REVISION REQUIRED
+
+    If APPROVED: one sentence on why these API changes are safe to ship.
+
+    If REVISION REQUIRED:
+
+    ### Critical (will cause client breakage or security issue)
+    - **[Attack vector, Endpoint/file:line]:** [Specific description of the problem]
+      *Evidence:* [Quote from diff that shows the issue]
+      *Fix:* [What the author needs to change — be specific]
+
+    ### Significant (will cause future pain or operational risk)
+    - **[Attack vector, Endpoint/file:line]:** [Specific description]
+      *Evidence:* [Quote]
+      *Fix:* [Specific change needed]
+
+    Do not include stylistic suggestions. Do not include a "Recommendations" section.
+    If it's not critical or significant, don't mention it.
+
+    If there are no issues: APPROVED. Don't invent problems to seem thorough.
+```
+
+---
+
+**After critic returns:**
+
+- If **APPROVED**: proceed to merge/PR options.
+- If **REVISION REQUIRED**: fix the API changes, then dispatch critic again.
+  - Do not ship until critic returns APPROVED.
+  - Critic re-reads the full diff on re-dispatch.

package/assets/skills/finishing-a-development-branch/schema-critic-prompt.md

@@ -0,0 +1,146 @@
+# Schema Critic Prompt Template
+
+Use this template when dispatching a schema critic subagent.
+
+**Purpose:** Attack DB migrations adversarially — find what will cause data loss,
+table locks, or a broken rollback path in production.
+The critic is NOT a schema design reviewer.
+
+**Dispatch when:** Migration files are detected in the branch diff before shipping.
+
+**Model:** Use the most capable available model (opus).
+
+---
+
+## Prompt
+
+```
+Task tool (general-purpose):
+  description: "Schema critic: adversarial review of migrations in [BRANCH_NAME]"
+  prompt: |
+    You are a schema critic. Your job is to try to BREAK these database migrations —
+    find what will cause data loss, table locks, or a broken rollback path in production.
+
+    You are NOT a schema design reviewer. You are an adversary.
+
+    **Migration files to attack:** [MIGRATION_FILE_PATHS]
+
+    Read each migration file fully before forming any opinion.
+    Also read the rollback/down migration if it exists.
+
+    ---
+
+    ## Attack Vectors
+
+    Work through each of these systematically. For each, state what you found
+    or "no issue" if clean.
+
+    ### 1. Irreversibility and rollback
+    - Does a rollback/down migration exist for every up migration?
+    - Can the rollback be run safely AFTER the up migration has already processed
+      production data? (i.e., does the rollback DROP data that was created by the up?)
+    - Is the migration idempotent? Can it be run twice without error?
+    - Are there irreversible operations (DROP COLUMN, DROP TABLE, data transformation)
+      with no recovery path?
+
+    ### 2. Lock duration and table availability
+    - Which ALTER TABLE statements will acquire an exclusive lock?
+    - On a table with millions of rows, how long will that lock be held?
+    - Are there index creations that should use CREATE INDEX CONCURRENTLY?
+    - Are there operations that should use a shadow table / online schema change tool?
+    - Will this migration cause a maintenance window or can it run zero-downtime?
+
+    ### 3. Backwards compatibility window
+    - Will the OLD application code (already deployed) break if this migration runs
+      before the new code deploy? (Column renamed/removed that old code reads)
+    - Does the migration assume the new code is already deployed?
+    - Is there a safe deployment order? (migrate-first or code-first)
+    - For the window where old code + new schema coexist: does the old code crash,
+      silently corrupt data, or continue working?
+
+    ### 4. Data safety
+    - Does any transformation step overwrite data without a backup or reversible step first?
+    - Are there type changes (e.g., VARCHAR → INT) that will silently truncate or fail
+      on existing values that don't fit?
+    - Does adding NOT NULL without DEFAULT assume all existing rows will be updated first?
+      (On a live table this is a data error, not just a schema error)
+    - Are there UPDATE or DELETE statements on existing data? Is the WHERE clause correct?
+      (A missing WHERE clause is the most common production disaster)
+
+    ### 5. Constraint and index ordering
+    - Are foreign key constraints added BEFORE the referenced data exists?
+    - Are indexes created BEFORE or AFTER bulk inserts?
+      (Creating indexes after bulk insert is 10x faster)
+    - Are NOT NULL constraints applied before the column is populated?
+    - Are unique constraints applied before duplicates are resolved?
+
+    ### 6. Query performance after migration
+    - Is there a query in the codebase that will do a full table scan after this migration?
+      (e.g., a new foreign key column without an index, a new filterable column without an index)
+    - Does removing an index break a query that the ORM generates automatically?
+    - Are new join columns indexed on both sides?
+
+    ### 7. Multi-tenant, multi-region, and environment concerns
+    - Does this migration run per-tenant (row-level) or globally?
+      (If per-tenant and there are 1000 tenants, running time = 1000x)
+    - Are there timezone assumptions in DEFAULT NOW() or timestamp transformations?
+    - Will this migration produce different results in dev vs staging vs prod
+      due to different data volumes or existing records?
+    - If this migration seeds data, will it conflict with existing seed data in non-prod?
+
+    ---
+
+    ## Calibration
+
+    Only raise issues that would cause real production harm:
+    - Table locked for >5 seconds on a live table
+    - Data loss with no recovery path
+    - Old application code crashes after migration runs
+    - Migration fails midway with no clean rollback
+    - Silent data corruption
+
+    Do NOT raise:
+    - Naming preferences
+    - Schema design opinions ("I would have normalised this differently")
+    - Performance concerns that are not caused by this migration
+    - Theoretical future concerns unrelated to this migration
+
+    An issue is real if running this migration on a production database would cause it.
+    An issue is not real if it requires the production database to be in an unusual state.
+
+    ---
+
+    ## Output Format
+
+    Status: APPROVED
+    or
+    Status: REVISION REQUIRED
+
+    If APPROVED: one sentence on why this migration is safe to run in production.
+
+    If REVISION REQUIRED:
+
+    ### Critical (will cause production harm)
+    - **[Attack vector, Migration file:line]:** [Specific description of the problem]
+      *Evidence:* [Quote from migration that shows the issue]
+      *Fix:* [What the author needs to change — be specific]
+
+    ### Significant (will cause confusion or operational risk)
+    - **[Attack vector, Migration file:line]:** [Specific description]
+      *Evidence:* [Quote]
+      *Fix:* [Specific change needed]
+
+    Do not include stylistic suggestions. Do not include a "Recommendations" section.
+    If it's not critical or significant, don't mention it.
+
+    If there are no issues: APPROVED. Don't invent problems to seem thorough.
+```
+
+---
+
+**After critic returns:**
+
+- If **APPROVED**: proceed to merge/PR options.
+- If **REVISION REQUIRED**: fix the migration, then dispatch critic again.
+  - Do not ship until critic returns APPROVED.
+  - Critic re-reads the full migration on re-dispatch (do not summarise changes).

package/assets/skills/writing-plans/arch-critic-prompt.md

@@ -0,0 +1,151 @@
+# Architecture Critic Prompt Template
+
+Use this template when dispatching an architecture critic subagent.
+
+**Purpose:** Attack the proposed file structure and architectural approach — find what
+will cause the implementation to collapse, not what could be named differently.
+The critic is not a code style reviewer.
+
+**Dispatch after:** File map is designed. Before tasks are written.
+
+**Model:** Use the most capable available model (opus). The critic needs strong reasoning
+to find non-obvious coupling and scalability traps.
+
+---
+
+## Prompt
+
+```
+Task tool (general-purpose):
+  description: "Architecture critic: adversarial review of [PLAN_NAME] file structure"
+  prompt: |
+    You are an architecture critic. Your job is to try to BREAK the proposed file
+    structure and architectural approach — find the reasons the implementation will
+    collapse, not the ways the names could be improved.
+
+    You are NOT a code style reviewer. You are an adversary.
+
+    **Plan (file map section) to attack:** [PLAN_FILE_PATH]
+
+    Read the File Map section of the plan. Also read the Goal and Architecture
+    summary. Do not read the task steps — you are attacking the structure, not
+    the implementation details.
+
+    ---
+
+    ## Attack Vectors
+
+    Work through each of these systematically. For each, state what you found
+    or "no issue" if clean.
+
+    ### 1. Wrong abstraction level
+    - Are files split too finely? (ceremony overhead: 8 files each doing 10 lines)
+    - Are files too coarse? (one file doing 5 unrelated things)
+    - Does the module structure map to the problem domain, or to implementation
+      convenience? (domain-driven is harder to get wrong)
+    - Are there files that will inevitably grow into god modules because there's
+      nowhere else for related code to live?
+
+    ### 2. Missing cross-cutting concerns
+    - Where does authentication and authorization live? Is it enforced at every
+      external entry point, or added ad-hoc?
+    - Where does error handling and logging live? Are they afterthoughts that
+      every module will implement differently?
+    - Where does caching live? Can it be added without changing all callers?
+    - Are there infrastructure concerns (retry, timeout, circuit-breaker) that
+      need a home but don't have one?
+
+    ### 3. Circular dependencies and tight coupling
+    - Does any proposed import create a dependency cycle?
+      (FileA imports FileB imports FileC imports FileA)
+    - Are there two files that will always change together?
+      (This signals they should be one file, or one needs to own the contract)
+    - Does any high-level module import from a low-level module that imports back?
+
+    ### 4. Test isolation
+    - Can each module be unit-tested without standing up the rest of the system?
+    - Are there hidden dependencies (globals, singletons, filesystem, network)
+      that will make mocking painful?
+    - Does the architecture make testing the happy path easy but error paths require
+      a full integration test?
+    - Are there modules with no clear unit test seam?
+
+    ### 5. Interface leakage
+    - Does any module expose implementation details in its interface?
+      (e.g., returns a DB row object instead of a domain type)
+    - Are there internal types being passed across module boundaries?
+    - Would changing the internals of FileA require changing FileB's tests?
+
+    ### 6. Scalability shape
+    - Which module becomes the bottleneck at 10x current load?
+    - Is state stored in-process in a way that prevents horizontal scaling?
+    - Is there a synchronous step on the critical path that blocks everything else?
+    - Does the architecture assume a single process / single machine?
+
+    ### 7. Deployment and evolution
+    - What is the deployment unit? Can FileA's changes be deployed without FileB?
+    - Which architectural decisions are hardest to change in 6 months?
+      (e.g., data storage choice, protocol choice, schema shape)
+    - Does this architecture support the next obvious feature extension,
+      or will it require restructuring?
+
+    ---
+
+    ## Calibration
+
+    Only raise issues that would cause real implementation collapse:
+    - Circular import that causes a runtime error on startup
+    - Module that can't be unit-tested without running a database
+    - Architectural decision that forecloses the next obvious feature
+    - Design where adding auth requires touching every file
+
+    Do NOT raise:
+    - Naming preferences
+    - "I would have split this differently"
+    - Performance concerns that aren't architectural (micro-optimisations)
+    - File organisation preferences unrelated to coupling or testability
+
+    An issue is real if an implementer following the file map exactly would hit it.
+    An issue is not real if it requires deliberately ignoring the file map.
+
+    ---
+
+    ## Output Format
+
+    Status: APPROVED
+    or
+    Status: REVISION REQUIRED
+
+    If APPROVED: one sentence on why this architecture is solid enough to write
+    tasks against.
+
+    If REVISION REQUIRED:
+
+    ### Critical (will cause implementation collapse)
+    - **[Attack vector, File reference]:** [Specific description of the problem]
+      *Evidence:* [Quote from plan's file map that shows the issue]
+      *Fix:* [What the plan author needs to change — be specific]
+
+    ### Significant (will cause confusion or rework)
+    - **[Attack vector, File reference]:** [Specific description]
+      *Evidence:* [Quote]
+      *Fix:* [Specific change needed]
+
+    Do not include stylistic suggestions. Do not include a "Recommendations" section.
+    If it's not critical or significant, don't mention it.
+
+    If there are no issues: APPROVED. Don't invent problems to seem thorough.
+```
+
+---
+
+**After critic returns:**
+
+- If **APPROVED**: append sign-off comment after the File Map table, then proceed to writing tasks:
+```markdown
+<!-- arch-critic: APPROVED -->
+```
+
+- If **REVISION REQUIRED**: author fixes the file map inline, then dispatches critic again.
+  - Do not start writing tasks until critic returns APPROVED.
+  - Critic re-reads the full plan file map on re-dispatch (do not summarise changes).

package/dist/companion.js

@@ -19,6 +19,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { dim, success, log, warn } from "./ui.js";
 import { enablePlugin } from "./settings.js";
+import { semverDescending } from "./semver.js";
 export const COMPANION_PLUGINS = [
     {
         name: "superpowers",
@@ -48,7 +49,7 @@ function isAlreadyInstalled(name) {
     }
 }
 /** Detect the latest semver tag from a remote repo without cloning. */
-function detectLatestTag(repoUrl) {
+export function detectLatestTag(repoUrl) {
     try {
         const out = execFileSync("git", ["ls-remote", "--tags", repoUrl], {
             encoding: "utf-8",
@@ -59,16 +60,7 @@ function detectLatestTag(repoUrl) {
             .split("\n")
             .map((line) => line.match(/refs\/tags\/v?([0-9]+\.[0-9]+\.[0-9]+)(?!\^)/)?.[1])
             .filter((t) => !!t)
-            .sort((a, b) => {
-            const pa = a.split(".").map(Number);
-            const pb = b.split(".").map(Number);
-            for (let i = 0; i < 3; i++) {
-                const d = (pb[i] ?? 0) - (pa[i] ?? 0);
-                if (d !== 0)
-                    return d;
-            }
-            return 0;
-        });
+            .sort(semverDescending);
         return tags[0] ?? null;
     }
     catch {

package/dist/main.js

@@ -99,6 +99,8 @@ function parseArgs(argv) {
             args.command = "report";
         else if (a === "leash")
             args.command = "leash";
+        else if (a === "upgrade")
+            args.command = "upgrade";
         // Slash-commands surfaced as CLI subcommands so users get a clear hint
         // instead of a confusing usage error. These work only in the chat plugin.
         else if (a === "start" || a === "audit" || a === "inbox" || a === "digest" ||
@@ -366,6 +368,7 @@ ${bold("Usage:")}
   npx great-cto mcp [--sse --port N]
   npx great-cto adapt [--dry-run]
   npx great-cto serve [--port 3142]
+  npx great-cto upgrade [superpowers|beads]  Re-clone companions to latest tag + re-apply overlays
   npx great-cto help
   npx great-cto version
 
@@ -379,6 +382,12 @@ ${bold("Register:")}
                                (auto-discovered after /audit or /start, but
                                 run this if the project doesn't appear in board)
 
+${bold("Upgrade:")}
+  great-cto upgrade              Upgrade superpowers + beads to latest, re-apply critic overlays
+  great-cto upgrade superpowers  Upgrade superpowers only
+  great-cto upgrade beads        Upgrade beads only
+  ${dim("(Safe to run any time — idempotent if already on latest)")}
+
 ${bold("Scan (AI-security):")}
   great-cto scan                       AI-specific scan of cwd (OWASP LLM Top 10)
   great-cto scan ./src --severity high Filter by minimum severity
@@ -681,6 +690,12 @@ async function runInit(args) {
                 warn(`  install manually: claude plugin install github.com/obra/${r.name === "superpowers" ? "superpowers" : ""} or github.com/steveyegge/beads`);
             }
         }
+        // Apply bundled critic overlays (idempotent — skips already-applied changes)
+        try {
+            const { applyOverlays } = await import("./overlay.js");
+            applyOverlays();
+        }
+        catch { /* best-effort — overlay failure must not block init */ }
     }
     // ── 4c. bootstrap skills catalog (v1.0.140+) ─────────────
     // Clone external skill repos + run skill-discover.sh so agents have
@@ -867,6 +882,38 @@ async function tryInstallLeash(forceUpdate = false) {
         warn("llm-leash install failed — run `great-cto leash install` manually later");
     }
 }
+async function runUpgrade(rawArgv) {
+    const { upgradePlugin, upgradeAll } = await import("./upgrade.js");
+    const { COMPANION_PLUGINS } = await import("./companion.js");
+    // Optional positional: great-cto upgrade [plugin-name]
+    const upgradeIdx = rawArgv.indexOf("upgrade");
+    const pluginArg = upgradeIdx >= 0 ? rawArgv[upgradeIdx + 1] : undefined;
+    const targetPlugin = pluginArg && !pluginArg.startsWith("--") ? pluginArg : undefined;
+    let results;
+    if (targetPlugin) {
+        const plugin = COMPANION_PLUGINS.find((p) => p.name === targetPlugin);
+        if (!plugin) {
+            error(`unknown plugin '${targetPlugin}'. Valid: ${COMPANION_PLUGINS.map((p) => p.name).join(", ")}`);
+            return 2;
+        }
+        results = [await upgradePlugin(plugin)];
+    }
+    else {
+        results = await upgradeAll();
+    }
+    for (const r of results) {
+        if (r.status === "upgraded") {
+            success(`${r.name} ${r.fromVersion} → ${r.toVersion}`);
+        }
+        else if (r.status === "already_latest") {
+            log(`  ${dim(`${r.name} ${r.toVersion} already at latest (overlays re-applied)`)}`);
+        }
+        else {
+            warn(`${r.name} skipped — ${r.reason ?? "unknown reason"}`);
+        }
+    }
+    return 0;
+}
 async function main() {
     const rawArgv = process.argv.slice(2);
     const args = parseArgs(rawArgv);
@@ -1005,6 +1052,16 @@ async function main() {
             process.exit(2);
         }
     }
+    if (args.command === "upgrade") {
+        try {
+            const code = await runUpgrade(rawArgv);
+            process.exit(code);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
     if (args.command === "chat-only-hint") {
         const tried = args._slashTried || "<command>";
         error(`'${tried}' is a chat slash command, not a CLI subcommand.`);

package/dist/overlay.js

@@ -0,0 +1,227 @@
+/**
+ * overlay.ts — applies great-cto bundled critic overlays to the installed
+ * superpowers plugin.
+ *
+ * Two idempotent operations:
+ * 1. Copy 4 critic prompt files from package assets into superpowers cache
+ * 2. Patch 3 upstream SKILL.md files (detect → skip if already applied)
+ *
+ * Called after every superpowers install and from `great-cto upgrade`.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, readdirSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { semverDescending } from "./semver.js";
+export const CRITIC_ASSETS = [
+    {
+        assetRelPath: "brainstorming/spec-critic-prompt.md",
+        skillRelPath: "skills/brainstorming/spec-critic-prompt.md",
+    },
+    {
+        assetRelPath: "writing-plans/arch-critic-prompt.md",
+        skillRelPath: "skills/writing-plans/arch-critic-prompt.md",
+    },
+    {
+        assetRelPath: "finishing-a-development-branch/schema-critic-prompt.md",
+        skillRelPath: "skills/finishing-a-development-branch/schema-critic-prompt.md",
+    },
+    {
+        assetRelPath: "finishing-a-development-branch/api-critic-prompt.md",
+        skillRelPath: "skills/finishing-a-development-branch/api-critic-prompt.md",
+    },
+];
+export const SKILL_PATCHES = [
+    // ── brainstorming/SKILL.md ─────────────────────────────────────────────
+    // Insert spec-critic dispatch block immediately before the User Review Gate section.
+    // Anchor: "\n\n**User Review Gate:**" — this section header is stable across
+    // upstream versions regardless of what precedes it in the Self-Review section.
+    {
+        skillRelPath: "skills/brainstorming/SKILL.md",
+        detectString: "spec-critic-prompt.md",
+        searchString: "\n\n**User Review Gate:**",
+        replaceWith: "\n\n" +
+            "**After self-review passes, dispatch spec critic:**\n\n" +
+            "Dispatch the spec-critic subagent (`./spec-critic-prompt.md`) now.\n" +
+            "Substitute all placeholders before dispatching:\n" +
+            "- Replace `[SPEC_FILE_PATH]` with the absolute path to the saved spec document\n" +
+            "- Replace `[SPEC_NAME]` in the description field with the spec filename (e.g., `2026-05-22-auth-design`)\n\n" +
+            "- If REVISION REQUIRED: fix each issue inline, re-dispatch (critic re-reads full spec, not just diff)\n" +
+            "- If APPROVED: append `Status: APPROVED` sign-off to the spec document, proceed to User Review Gate\n\n" +
+            "Do not proceed to the user review gate until the critic returns APPROVED.\n\n" +
+            "**User Review Gate:**",
+    },
+    // ── writing-plans/SKILL.md ─────────────────────────────────────────────
+    // Insert Architecture Critic section before Bite-Sized Task Granularity.
+    {
+        skillRelPath: "skills/writing-plans/SKILL.md",
+        detectString: "arch-critic-prompt.md",
+        searchString: "## Bite-Sized Task Granularity",
+        replaceWith: "## Architecture Critic\n\n" +
+            "After designing the File Map, dispatch an architecture critic subagent using `./arch-critic-prompt.md`.\n" +
+            "When dispatching, substitute all placeholders:\n" +
+            "- Replace `[PLAN_FILE_PATH]` with the absolute path to the plan document\n" +
+            "- Replace `[PLAN_NAME]` in the description field with the plan filename\n\n" +
+            "**The critic's job is adversarial:** find coupling traps, missing cross-cutting concerns,\n" +
+            "circular dependencies, and untestable designs that would cause the implementation to collapse.\n" +
+            "The critic is NOT a naming reviewer — stylistic feedback is noise.\n\n" +
+            "**Dispatch:** Use model `opus`.\n\n" +
+            "**If critic returns REVISION REQUIRED:**\n" +
+            "- Fix the file map inline in the plan document\n" +
+            "- Re-dispatch the critic (it re-reads the full file map, not just the diff)\n" +
+            "- Repeat until APPROVED\n\n" +
+            "**If critic returns APPROVED:** append `<!-- arch-critic: APPROVED -->` as a comment\n" +
+            "after the File Map table, then proceed to writing bite-sized tasks.\n\n" +
+            "**Do not write tasks until the architecture critic approves.** Structural errors found\n" +
+            "after tasks are written cascade into every task — far cheaper to catch at the file map stage.\n\n" +
+            "## Bite-Sized Task Granularity",
+    },
+    // ── finishing-a-development-branch/SKILL.md ────────────────────────────
+    // Insert Step 1.5 Pre-Ship Critics between Step 1 (tests) and Step 2 (base branch).
+    {
+        skillRelPath: "skills/finishing-a-development-branch/SKILL.md",
+        detectString: "schema-critic-prompt.md",
+        searchString: "**If tests pass:** Continue to Step 2.\n\n### Step 2:",
+        replaceWith: "**If tests pass:** Continue to Step 1.5.\n\n" +
+            "### Step 1.5: Pre-Ship Critics\n\n" +
+            "Before presenting merge/PR options, check whether the branch contains schema or API changes\n" +
+            "that require adversarial review.\n\n" +
+            "**Detect migration files** (checks only actual migration/schema files, not docs about them):\n" +
+            "```bash\n" +
+            "BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)\n" +
+            "git diff --name-only \"$BASE\" HEAD \\\n" +
+            "  | grep -E \"^(db/migrate/|migrations/|database/migrations/|.*\\.sql$)\" | head -20\n" +
+            "```\n\n" +
+            "If any files match, confirm with a brief list before dispatching:\n" +
+            "```\n" +
+            "Detected migration files: [list]. Run schema critic? (y to proceed, n to skip)\n" +
+            "```\n\n" +
+            "If confirmed → **dispatch schema critic:** use `./schema-critic-prompt.md`.\n" +
+            "Substitute all placeholders: `[MIGRATION_FILE_PATHS]` = list of detected files,\n" +
+            "`[BRANCH_NAME]` = current branch name (`git branch --show-current`).\n\n" +
+            "- If REVISION REQUIRED: fix the migration, re-dispatch (critic re-reads full migration)\n" +
+            "- If APPROVED: proceed\n\n" +
+            "**Detect API contract files** (routes, controllers, GraphQL, OpenAPI specs only — not test files):\n" +
+            "```bash\n" +
+            "BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)\n" +
+            "git diff --name-only \"$BASE\" HEAD \\\n" +
+            "  | grep -E \"^(src/routes/|src/controllers/|src/resolvers/|app/controllers/|api/|graphql/schema)\" \\\n" +
+            "  | grep -v '__tests__\\|\\.test\\.\\|\\.spec\\.' | head -20\n" +
+            "```\n\n" +
+            "If any files match, confirm with a brief list before dispatching:\n" +
+            "```\n" +
+            "Detected API files: [list]. Run API contract critic? (y to proceed, n to skip)\n" +
+            "```\n\n" +
+            "If confirmed → **dispatch API contract critic:** use `./api-critic-prompt.md`.\n" +
+            "Substitute all placeholders: `[BASE_SHA]` = output of `git merge-base HEAD main`,\n" +
+            "`[HEAD_SHA]` = output of `git rev-parse HEAD`, `[BRANCH_NAME]` = `git branch --show-current`.\n\n" +
+            "- If REVISION REQUIRED: fix the API changes, re-dispatch\n" +
+            "- If APPROVED: proceed\n\n" +
+            "**If neither detected or both skipped:** proceed to Step 2 directly.\n\n" +
+            "**Do not proceed to Step 2 until all dispatched critics return APPROVED.**\n\n" +
+            "### Step 2:",
+    },
+];
+/** Returns the assets/skills directory path, relative to the compiled dist/ output. */
+export function getAssetsDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/overlay.js → ../assets/skills/
+    return join(here, "..", "assets", "skills");
+}
+/**
+ * Returns the path to the highest installed superpowers version directory, or null.
+ * Sorts by semver descending so the latest version wins when multiple exist.
+ */
+export function findSuperpowersDir() {
+    const base = join(homedir(), ".claude", "plugins", "cache", "local", "superpowers");
+    if (!existsSync(base))
+        return null;
+    try {
+        const versions = readdirSync(base)
+            .filter((v) => v.trim() !== "")
+            .sort(semverDescending);
+        return versions.length > 0 ? join(base, versions[0]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Copy 4 critic prompt files from the bundled assets into the superpowers
+ * cache. Always overwrites — the asset is the source of truth.
+ */
+export function copyCriticFiles(superpowersDir, assetsDir) {
+    const copied = [];
+    const skipped = [];
+    for (const asset of CRITIC_ASSETS) {
+        const src = join(assetsDir, asset.assetRelPath);
+        const dest = join(superpowersDir, asset.skillRelPath);
+        if (!existsSync(src)) {
+            skipped.push(`${asset.assetRelPath} (asset missing)`);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(src, dest);
+        copied.push(asset.skillRelPath);
+    }
+    return { copied, skipped };
+}
+/**
+ * Apply 3 idempotent patches to upstream SKILL.md files.
+ * Each patch checks for its `detectString` first — if present, the patch is
+ * already applied and the file is skipped. If the `searchString` anchor is
+ * not found (upstream changed significantly), a warning is emitted and the
+ * file is skipped rather than corrupted.
+ */
+export function patchSkillFiles(superpowersDir) {
+    const patched = [];
+    const skipped = [];
+    const warnings = [];
+    for (const patch of SKILL_PATCHES) {
+        const filePath = join(superpowersDir, patch.skillRelPath);
+        if (!existsSync(filePath)) {
+            warnings.push(`${patch.skillRelPath} not found — skipping patch`);
+            continue;
+        }
+        const content = readFileSync(filePath, "utf-8");
+        if (content.includes(patch.detectString)) {
+            skipped.push(patch.skillRelPath);
+            continue;
+        }
+        if (!content.includes(patch.searchString)) {
+            warnings.push(`${patch.skillRelPath} — anchor string not found (upstream may have changed); skipping`);
+            continue;
+        }
+        writeFileSync(filePath, content.replace(patch.searchString, patch.replaceWith), "utf-8");
+        patched.push(patch.skillRelPath);
+    }
+    return { patched, skipped, warnings };
+}
+/**
+ * Apply all overlays to the installed superpowers plugin.
+ *
+ * @param superpowersDirOverride - Pass an explicit path (used by `upgrade` command).
+ *   Defaults to auto-detecting the installed superpowers version directory.
+ */
+export function applyOverlays(superpowersDirOverride) {
+    const dir = superpowersDirOverride ?? findSuperpowersDir();
+    const assetsDir = getAssetsDir();
+    if (!dir) {
+        return {
+            superpowersDir: null,
+            copiedFiles: [],
+            patchedFiles: [],
+            skippedFiles: [],
+            warnings: ["superpowers not installed — skipping overlay"],
+        };
+    }
+    const { copied, skipped: skippedCopy } = copyCriticFiles(dir, assetsDir);
+    const { patched, skipped: skippedPatch, warnings } = patchSkillFiles(dir);
+    return {
+        superpowersDir: dir,
+        copiedFiles: copied,
+        patchedFiles: patched,
+        skippedFiles: [...skippedCopy, ...skippedPatch],
+        warnings,
+    };
+}

package/dist/semver.js

@@ -0,0 +1,12 @@
+/** Shared semver utilities. */
+/** Compare two semver strings descending (highest first). */
+export function semverDescending(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const d = (pb[i] ?? 0) - (pa[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}

package/dist/upgrade.js

@@ -0,0 +1,111 @@
+/**
+ * upgrade.ts — force re-clone companion plugins to their latest semver tag,
+ * then re-apply great-cto overlays.
+ *
+ * `great-cto upgrade [plugin]`
+ *   plugin: "superpowers" | "beads" | undefined → all
+ */
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { COMPANION_PLUGINS, installCompanionPlugin, detectLatestTag } from "./companion.js";
+import { applyOverlays } from "./overlay.js";
+import { semverDescending } from "./semver.js";
+function getPluginCacheDir(name) {
+    return join(homedir(), ".claude", "plugins", "cache", "local", name);
+}
+/** Returns the highest installed semver version for a plugin, or null. */
+function getInstalledVersion(name) {
+    const base = getPluginCacheDir(name);
+    if (!existsSync(base))
+        return null;
+    try {
+        const versions = readdirSync(base)
+            .filter((v) => v.trim() !== "")
+            .sort(semverDescending);
+        return versions.length > 0 ? versions[0] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Force-upgrade a single companion plugin to its latest semver tag.
+ * If already on the latest tag, re-applies overlays and returns `already_latest`.
+ */
+export async function upgradePlugin(plugin) {
+    const { name, repoUrl } = plugin;
+    const currentVersion = getInstalledVersion(name);
+    const latestTag = detectLatestTag(repoUrl);
+    const latestVersion = latestTag ?? "main";
+    // Already on latest — just re-apply overlays in case they were missing
+    if (currentVersion && currentVersion === latestVersion) {
+        if (name === "superpowers") {
+            applyOverlays(join(getPluginCacheDir(name), currentVersion));
+        }
+        return { name, status: "already_latest", fromVersion: currentVersion, toVersion: latestVersion };
+    }
+    // Remove ALL existing version directories so installCompanionPlugin's
+    // isAlreadyInstalled guard always returns null and the clone proceeds fresh.
+    const cacheDir = getPluginCacheDir(name);
+    if (existsSync(cacheDir)) {
+        try {
+            const existingVersions = readdirSync(cacheDir).filter((v) => v.trim() !== "");
+            for (const v of existingVersions) {
+                rmSync(join(cacheDir, v), { recursive: true, force: true });
+            }
+        }
+        catch (e) {
+            return {
+                name,
+                status: "skipped",
+                fromVersion: currentVersion ?? "—",
+                toVersion: latestVersion,
+                reason: `failed to remove old versions: ${e.message}`,
+            };
+        }
+    }
+    // Re-install via companion installer (handles clone + settings enable).
+    // All version dirs were removed above, so isAlreadyInstalled returns null
+    // and the clone always proceeds fresh.
+    const result = installCompanionPlugin(plugin);
+    if (result.status === "skipped") {
+        return {
+            name,
+            status: "skipped",
+            fromVersion: currentVersion ?? "—",
+            toVersion: latestVersion,
+            reason: result.reason,
+        };
+    }
+    // "installed" | "already_present" → plugin is present; apply overlays
+    if (name === "superpowers") {
+        const newDir = join(getPluginCacheDir(name), result.version);
+        applyOverlays(newDir);
+    }
+    return {
+        name,
+        status: "upgraded",
+        fromVersion: currentVersion ?? "—",
+        toVersion: result.version,
+    };
+}
+/** Upgrade all companion plugins. Never throws — best-effort for each. */
+export async function upgradeAll() {
+    const results = [];
+    for (const plugin of COMPANION_PLUGINS) {
+        try {
+            results.push(await upgradePlugin(plugin));
+        }
+        catch (e) {
+            results.push({
+                name: plugin.name,
+                status: "skipped",
+                fromVersion: "—",
+                toVersion: "—",
+                reason: e.message,
+            });
+        }
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",
@@ -69,6 +69,7 @@
   "files": [
     "index.mjs",
     "dist/",
+    "assets/",
     "agentshield-rules/",
     "postinstall.mjs",
     "README.md"