@aperant/framework 0.6.4 → 0.6.5

package/dist/cli/task/worktree-cleanup.mjs

@@ -10,13 +10,84 @@
  *   'auto'  → merge back into base_branch, then remove the worktree + branch
  */
 import { execFileSync } from 'node:child_process';
+/**
+ * Truncate a thrown git error to its first 3 stderr/message lines for
+ * surfacing in cleanup envelopes. Extracted from the original inline
+ * duplication at the auto-mode merge-error catch.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function shortErr(err) {
+    return (err?.stderr || err?.message || '').toString().trim().split('\n').slice(0, 3).join(' ');
+}
+/**
+ * Sanitize an error message for inclusion in returned envelopes: first line
+ * only, absolute paths replaced with a placeholder to avoid leaking local
+ * filesystem layout.
+ *
+ * @param {string} msg
+ * @returns {string}
+ */
+function sanitizeErrMsg(msg) {
+    return msg
+        .split('\n')[0]
+        .replace(/\/[^\s:'"]+/g, '<path>')
+        .trim();
+}
+/**
+ * Run `git <args>` with up to 3 attempts and ~200ms backoff when the
+ * thrown error's stderr names `.git/index.lock`. Other errors propagate
+ * on the first failure. Two concurrent `task close-merged` invocations
+ * from different terminals race on git's internal index.lock;
+ * retry-on-EEXIST handles that without an app-level mutex (which
+ * wouldn't prevent the underlying git race anyway).
+ *
+ * Sleep uses the same Atomics.wait pattern as withFileLock in
+ * util/fs-lock.mjs to park the event loop without spinning the CPU.
+ *
+ * @param {string[]} args
+ * @param {object} opts - forwarded to execFileSync
+ * @returns {string} stdout
+ */
+function runGitWithRetry(args, opts) {
+    const maxAttempts = 3;
+    const backoffMs = 200;
+    let lastErr = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return execFileSync('git', args, opts);
+        }
+        catch (err) {
+            lastErr = err;
+            const stderrText = String(err?.stderr ?? '');
+            if (!/index\.lock/i.test(stderrText) || attempt === maxAttempts) {
+                throw err;
+            }
+            try {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoffMs);
+            }
+            catch {
+                /* runtime without SharedArrayBuffer — fall through, retry immediately */
+            }
+        }
+    }
+    // Unreachable — the loop either returns or throws.
+    throw lastErr;
+}
 /**
  * @param {object} task - closed task record with worktree_path/branch/base_branch.
  * @param {string} mode - 'never' | 'ask' | 'auto'
  * @param {string} targetDir - main-repo project directory (cwd for git ops).
+ * @param {object} [opts]
+ * @param {boolean} [opts.prMerged=false] - true when the PR has been confirmed
+ *   merged on the remote. Skips local merge-back regardless of merge strategy
+ *   (merge / squash / rebase). Instead: fetch + ff-only the base branch, then
+ *   GC worktree + branch. Defaults to false so existing callers retain
+ *   byte-identical legacy behavior.
  * @returns {object|null} cleanup report block, or null if no worktree on task.
  */
-export function computeWorktreeCleanup(task, mode, targetDir) {
+export function computeWorktreeCleanup(task, mode, targetDir, opts = {}) {
     if (!task?.worktree_path)
         return null;
     const wtPath = task.worktree_path;
@@ -32,16 +103,131 @@ export function computeWorktreeCleanup(task, mode, targetDir) {
         };
     }
     if (mode === 'ask') {
+        // When the PR is already merged on the remote, teach humans the
+        // fetch + ff-only recipe instead of the legacy local-merge recipe
+        // (which corrupts main when local task ref is stale or the PR used
+        // squash/rebase).
+        const cleanupCmd = opts.prMerged === true
+            ? `git fetch origin '${baseBranch}' && git checkout '${baseBranch}' && git merge --ff-only 'origin/${baseBranch}' && git worktree remove '${wtPath}' && git branch -d '${taskBranch}'`
+            : `git checkout '${baseBranch}' && git merge --no-edit '${taskBranch}' && git worktree remove '${wtPath}' && git branch -d '${taskBranch}'`;
         return {
             mode,
             worktree_path: wtPath,
             branch: taskBranch,
             base_branch: baseBranch,
             action: 'pending',
-            cleanup_command: `git checkout ${baseBranch} && git merge --no-edit ${taskBranch} && git worktree remove ${wtPath} && git branch -d ${taskBranch}`,
+            cleanup_command: cleanupCmd,
+            ...(opts.prMerged === true ? { pr_merged_remotely: true } : {}),
+        };
+    }
+    // mode === 'auto' && opts.prMerged === true.
+    // Trust origin as the merge authority. Method-agnostic across merge,
+    // squash, and rebase: fetch + checkout + ff-only, then GC. Never
+    // local-merge the task branch when GitHub already merged the PR.
+    if (opts.prMerged === true) {
+        let fetchOk = false;
+        let ffOk = false;
+        let branchDeleted = false;
+        const warnings = [];
+        try {
+            runGitWithRetry(['fetch', 'origin', baseBranch, '--no-tags'], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+            fetchOk = true;
+        }
+        catch (err) {
+            // Offline or network-error. Skip ff-only; user must
+            // `git pull --ff-only` later. Cleanup still proceeds.
+            warnings.push(`fetch_failed: ${sanitizeErrMsg(shortErr(err))}`);
+        }
+        try {
+            runGitWithRetry(['checkout', baseBranch], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+        }
+        catch (err) {
+            // Couldn't switch to base branch (e.g. fresh clone where base
+            // doesn't exist locally). Surface and abort cleanup; preserve
+            // local repo state — do NOT GC the worktree+branch.
+            return {
+                mode,
+                worktree_path: wtPath,
+                branch: taskBranch,
+                base_branch: baseBranch,
+                action: 'checkout_failed',
+                error: shortErr(err),
+                message: `Could not checkout ${baseBranch}; local repo state preserved. Resolve and re-run.`,
+            };
+        }
+        if (fetchOk) {
+            try {
+                runGitWithRetry(['merge', '--ff-only', `origin/${baseBranch}`], {
+                    cwd: targetDir,
+                    encoding: 'utf-8',
+                    stdio: 'pipe',
+                });
+                ffOk = true;
+            }
+            catch (err) {
+                // ff-only failed → local base has commits not on origin. Do
+                // NOT auto-resolve; warn and leave local at its current
+                // commit. Worktree + branch GC still runs.
+                warnings.push(`ff_only_failed: ${sanitizeErrMsg(shortErr(err))}`);
+            }
+        }
+        try {
+            runGitWithRetry(['worktree', 'remove', wtPath], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+        }
+        catch {
+            try {
+                runGitWithRetry(['worktree', 'remove', '--force', wtPath], {
+                    cwd: targetDir,
+                    encoding: 'utf-8',
+                    stdio: 'pipe',
+                });
+            }
+            catch {
+                /* worktree already gone or unreachable */
+            }
+        }
+        try {
+            runGitWithRetry(['branch', '-d', taskBranch], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+            branchDeleted = true;
+        }
+        catch (err) {
+            // Squash/rebase strategies leave the local task branch as
+            // "not fully merged" (different SHAs from origin). Surface as
+            // a warning rather than force-delete; user can `git branch -D`
+            // manually if they want.
+            warnings.push(`branch_delete_failed: ${sanitizeErrMsg(shortErr(err))}`);
+        }
+        return {
+            mode,
+            worktree_path: wtPath,
+            branch: taskBranch,
+            base_branch: baseBranch,
+            action: 'pr_merged_remotely_cleaned',
+            fetched: fetchOk,
+            fast_forwarded: ffOk,
+            branch_deleted: branchDeleted,
+            ...(warnings.length ? { warnings } : {}),
         };
     }
-    // mode === 'auto' — attempt merge-back in the main repo (never in the worktree).
+    // mode === 'auto' (legacy) — attempt merge-back in the main repo
+    // (never in the worktree). Direct `task close` callers without
+    // --pr-merged-remotely hit this path; byte-identical legacy behavior.
     let mergeOk = false;
     let mergeError = null;
     try {
@@ -58,12 +244,7 @@ export function computeWorktreeCleanup(task, mode, targetDir) {
         mergeOk = true;
     }
     catch (err) {
-        mergeError = (err.stderr || err.message || '')
-            .toString()
-            .trim()
-            .split('\n')
-            .slice(0, 3)
-            .join(' ');
+        mergeError = shortErr(err);
         // Abort the failed merge so the main repo is left clean.
         try {
             execFileSync('git', ['merge', '--abort'], {

package/dist/cli/task/worktree-cleanup.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"worktree-cleanup.mjs","sourceRoot":"","sources":["../../../src/cli/task/worktree-cleanup.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"worktree-cleanup.mjs","sourceRoot":"","sources":["../../../src/cli/task/worktree-cleanup.mjs"],"names":[],"mappings":"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"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.5.0",
+  "version": "0.6.4",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",

package/dist/plugin/agents/apt-planner.md

@@ -26,7 +26,7 @@ Before planning, discover project context:
 
 **Rationalizations (R4):** Read `.aperant/rationalizations/claude-opus-4-6.md` once at session start. It catalogues observed planner failure modes — especially ceremonialization (plan prose treated as progress) and postcondition triviality (`postcondition: "true"` rubber stamps). Every postcondition you emit must be a real, evaluable predicate.
 
-**Multi-runtime install awareness:** Plans that touch shipped framework files (skills/agents/hooks under `packages/framework/`) must respect the multi-runtime install pipeline. Each canonical file ships with an `apt-skill-version: {{APT_VERSION}}` header (substituted at install time) and is reflected in per-runtime `apt-file-manifest.json` files. Drift is detected per-file (header_mismatch, hash_mismatch, missing_header, missing_file) by `apt-tools check-version` — not via a single global version string. After modifying any canonical file, callers must re-run `apt-tools init . --<runtime>` (or `/apt:update`) so the manifest stays in sync.
+**Multi-runtime install awareness:** Plans that touch shipped framework files (skills/agents/hooks under `packages/framework/`) must respect the multi-runtime install pipeline. Each canonical file ships with an `apt-skill-version: {{APT_VERSION}}` header (substituted at install time) and is reflected in per-runtime `apt-file-manifest.json` files. Drift is detected per-file (header_mismatch, hash_mismatch, missing_header, missing_file) by `apt-tools check-version` — not via a single global version string. After modifying any canonical file, callers must re-run `apt-tools init . --<runtime>` (or `/apt:update`) so the manifest stays in sync. **Note (0.6.1):** when an agent re-runs install, the call must include `--team`/`--solo` plus the runtime flag (or `--yes`) — non-TTY `init` no longer silently defaults to `visibility:'solo'`. Without an explicit Class A flag the command exits 2 with a `requires_input` envelope.
 </project_context>
 
 <environment>

package/dist/plugin/skills/apt/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -139,13 +140,118 @@ Show current state summary and autonomy flags (`--supervised`, `--guided`, `--au
 
 The user invoked a specific skill by name (e.g., `/apt plan`, `/apt resume`,
 `/apt:ship`). The router matched the first word against the installed skill
-set and filled in `skill`, `skill_args`, `spawn_agent`, and `agent`.
+set and filled in `skill`, `skill_args`, `spawn_agent`, `agent`, AND
+`task_context` + (optional) `default_track`.
 
-**If `spawn_agent` is true:**
-Spawn the appropriate agent from the routing result. Pass `skill_args` as context.
+Dispatch on `task_context` — never just on `spawn_agent`. The four-branch
+policy below is hardcoded contract; do NOT improvise. See
+`docs/frameworks/spec-gaps.md#g25` for the defect that motivated this.
 
-**If `spawn_agent` is false:**
-Invoke the skill directly: call `apt:{skill}` with `skill_args`.
+### Missing `task_context` — fail-closed
+
+When the envelope's `task_context` is null (the `?? null` fallback in
+`route.mjs:skillIndex.taskContextOf`), print verbatim and STOP. Do NOT
+invoke the skill:
+
+```
+[APT] ERROR — skill "apt:{skill}" has no task_context declared in SKILL.md frontmatter.
+       Cannot dispatch safely until the policy is set. Run /apt:author-skill validate
+       packages/framework/skills/apt-{skill}/SKILL.md to see required keys.
+```
+
+**Note:** In practice, a skill missing `task_context` is dropped by
+`discoverSkills` during the Zod schema validation step and will never reach
+the skill-passthrough branch — it will be absent from `knownSlugs`. The
+user sees the skill disappear silently from routing; run
+`apt-tools route .` to surface dropped skills logged to
+`.aperant/logs/route-dropped.jsonl`. The `task_context: null` path is
+reachable if the field is marked optional in a future schema version —
+this error fires in that case.
+
+### `task_context = none`
+
+No task semantics. Invoke the skill directly with `skill_args` (or spawn
+`agent` when `spawn_agent` is true). No `task create`, no worktree banner.
+
+### `task_context = self-managed`
+
+The skill manages its own task / worktree lifecycle (e.g. `apt:run` calls
+`task create` in its own Step 2; `apt:pr-review` sets up a PR-scoped
+worktree). Dispatch identically to `none` — the skill's own SKILL.md is
+responsible for any task record + worktree banner.
+
+### `task_context = create-new`
+
+Resolve the track, then create a fresh task record before invoking the skill.
+
+**Track resolution chain (first match wins):**
+
+1. Explicit user flag in `skill_args` — `--quick` → `QUICK`, `--deep` → `DEEP`,
+   `--debug` → `DEBUG`.
+2. `envelope.default_track` if present (the skill's declared default).
+3. Per-slug hardcoded fallback:
+   - `quick` → `QUICK`
+   - `debug` → `DEBUG`
+   - `plan` → `STANDARD`
+   - everything else with `task_context: create-new` → `STANDARD`
+
+Then run:
+
+```bash
+node packages/framework/bin/apt-tools.mjs task create . --description "{slug}" --track {track} --autonomy {autonomy} [--scope {scope}]
+```
+
+**Security note:** Do NOT interpolate `{skill_args}` directly into `--description "..."`. `skill_args` is verbatim user input and can contain double-quote characters that break out of the argument boundary and inject extra flags (e.g. `--autonomy`, `--scope`). The task slug is sufficient as the description; `skill_args` is passed to the skill separately after the task record is created.
+
+(Use `--scope framework` only when the user is on a framework-scoped task —
+otherwise omit and let the default `project` scope apply.)
+
+Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` /
+`worktree.branch` / `worktree.base_branch` from the result. Print the
+worktree banner when `worktree` is returned:
+
+```
+[APT] Working in isolated worktree: {worktree_path}
+[APT] Task branch: {branch} (from {base_branch})
+```
+
+Then invoke `apt:{skill}` with `skill_args` + the new task context
+(`task_id`, `task_dir`, `worktree_path`). When `spawn_agent` is true, spawn
+`agent` with the same context.
+
+### `task_context = require-existing`
+
+Resolve which active task this invocation refers to, then dispatch. Read
+`state.active_tasks` from `.aperant/state.json`.
+
+**Active-task resolution chain (first match wins):**
+
+1. `--task-id <id>` flag present in `skill_args` → use it. If `<id>` is not
+   in `state.active_tasks`, error and stop.
+2. `state.active_tasks` has exactly one entry AND that entry's
+   `lifecycle_phase` is non-terminal (`planning`, `executing`, `verifying`,
+   `reviewing`) → use it. If the single entry is in a terminal phase
+   (`shipped-pending-merge` or `rejected`), fall through to step 4.
+3. `state.active_tasks` has more than one entry with exactly one in a
+   non-terminal lifecycle phase (`planning`, `executing`, `verifying`,
+   `reviewing`) → use it.
+   (Terminal phases in `active_tasks` are `shipped-pending-merge` and
+   `rejected`. Note: `completed` tasks are removed from `active_tasks`
+   entirely at close and can never appear here.)
+4. Otherwise, print the numbered menu and STOP. Auto-mode (autonomy 2/3)
+   does NOT bypass this prompt — multi-task ambiguity is the user's call,
+   never the framework's guess:
+
+   ```
+   [APT] Multiple active tasks — pick one with `--task-id <id>`:
+     1. {task-id-1}  {description}  ({lifecycle_phase})
+     2. {task-id-2}  {description}  ({lifecycle_phase})
+     ...
+   ```
+
+Once resolved, print the worktree banner if the task has a `worktree_path`,
+then invoke `apt:{skill}` with `skill_args` + the resolved `task_id`. When
+`spawn_agent` is true, spawn `agent` with the same context.
 
 ---
 

package/dist/plugin/skills/apt-author-skill/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
 default_execution_mode: step
 execution_modes:
   - auto
@@ -129,6 +130,16 @@ the author sees the full checklist of gaps to fill. Group by section:
 The generated structural test only checks tags and numbered steps — the
 TODOs are the semantic gaps the author must close.
 
+**Required frontmatter field — `task_context`.** The scaffold ships with
+`task_context: create-new` as the safest default (the new skill will get a
+fresh task record + worktree via `apt-tools task create` when invoked as
+`/apt <slug>`). Verify this is correct for your skill before merging — the
+allowed values are `create-new | require-existing | self-managed | none`.
+See `packages/framework/docs/skill-passthrough.md` for the four-policy
+contract and the orchestrator dispatch behavior. Missing or wrong values
+are caught by the structural test in
+`packages/framework/src/__tests__/skill-frontmatter-task-context.test.ts`.
+
 ## 4. Show the Structural Test
 
 Read the generated structural test file and echo its contents so the

package/dist/plugin/skills/apt-bootstrap/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-classify/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: false
 internal: true
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-close-task/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-create-docs/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: apt-docs-author
+task_context: create-new
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-debug/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: DEBUG
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-design/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-discuss/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-docs/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-execute/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-executor"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-mockup/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-pause/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-personas/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-plan/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-planner"
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-pr-review/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: self-managed
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-quick/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: QUICK
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-resume/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-review/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-reviewer"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-roadmap/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: step
 execution_modes:
   - auto

package/dist/plugin/skills/apt-roundtable/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: DEEP
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-run/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: self-managed
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-scan/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/dist/plugin/skills/apt-setup/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: step
 execution_modes:
   - auto