@htooayelwinict/appv23 2.3.0 → 2.3.1

package/README.md

@@ -23,7 +23,7 @@ The launcher pulls and runs:
 ghcr.io/htooayelwinict/appv23:production
 ```
 
-It mounts only the selected `--cwd` as `/workspace`, stores sandbox state in `~/.appv23/sandbox-home`, and copies host `~/.agents/skills` into the sandbox.
+It mounts only the selected `--cwd` as `/workspace`, stores sandbox state in `~/.appv23/sandbox-home`, copies host `~/.agents/AGENTS.md` into the sandbox agent context, and copies host `~/.agents/skills` into the sandbox.
 
 ## Options
 

package/bin/appv23.js

@@ -11,6 +11,7 @@ const DEFAULT_IMAGE =
 const PUBLIC_APPV23_IMAGE_PREFIX = "ghcr.io/htooayelwinict/appv23:";
 const CONTAINER_WORKSPACE = "/workspace";
 const CONTAINER_AGENT_HOME = "/agent-home";
+const IMPORTED_AGENTS_MARKER = "<!-- appv23-sandbox-imported-agents -->";
 const SKIP_IMPORT_NAMES = new Set([
   ".DS_Store",
   ".git",
@@ -222,24 +223,27 @@ function buildPullEnv(config, dockerConfig, env = process.env) {
 
 function prepareSandboxImports(config, runtime = {}) {
   const homeDir = runtime.homeDir || os.homedir();
+  const packageRoot = runtime.packageRoot || path.resolve(__dirname, "..");
   fs.mkdirSync(config.agentHome, { recursive: true, mode: 0o700 });
-  prepareAgentsFiles(config);
-  prepareSkills(config, homeDir);
+  prepareAgentsFiles(config, homeDir);
+  prepareSkills(config, homeDir, packageRoot);
 }
 
-function prepareAgentsFiles(config) {
-  if (!config.agentsFiles.length) {
+function prepareAgentsFiles(config, homeDir = os.homedir()) {
+  const sources = collectAgentsFiles(config, homeDir);
+  const target = path.join(config.agentHome, "agent", "AGENTS.md");
+  if (!sources.length) {
+    removeImportedAgentsFile(target);
     return;
   }
-  const target = path.join(config.agentHome, "agent", "AGENTS.md");
   const parts = [
-    "<!-- appv23-sandbox-imported-agents -->",
+    IMPORTED_AGENTS_MARKER,
     "# Imported appv23 sandbox instructions",
     "",
-    "These instructions were copied into the sandbox from explicit --agents-file arguments.",
+    "These instructions were copied into the sandbox from host ~/.agents/AGENTS.md and explicit --agents-file arguments.",
     "",
   ];
-  for (const source of config.agentsFiles) {
+  for (const source of sources) {
     const stat = fs.statSync(source);
     if (!stat.isFile()) {
       throw new Error(`agents file is not a file: ${source}`);
@@ -250,8 +254,42 @@ function prepareAgentsFiles(config) {
   fs.writeFileSync(target, parts.join("\n"), { mode: 0o600 });
 }
 
-function prepareSkills(config, homeDir) {
+function collectAgentsFiles(config, homeDir) {
+  const sources = [];
+  const userAgentsFile = path.join(homeDir, ".agents", "AGENTS.md");
+  if (fs.existsSync(userAgentsFile)) {
+    sources.push(userAgentsFile);
+  }
+  sources.push(...config.agentsFiles);
+  const deduped = [];
+  const seen = new Set();
+  for (const source of sources) {
+    const key = path.resolve(source);
+    if (seen.has(key)) {
+      continue;
+    }
+    deduped.push(key);
+    seen.add(key);
+  }
+  return deduped;
+}
+
+function removeImportedAgentsFile(target) {
+  if (!fs.existsSync(target)) {
+    return;
+  }
+  const text = fs.readFileSync(target, "utf8");
+  if (text.startsWith(IMPORTED_AGENTS_MARKER)) {
+    fs.unlinkSync(target);
+  }
+}
+
+function prepareSkills(config, homeDir, packageRoot) {
   const sources = [];
+  const bundledSkills = path.join(packageRoot, "skills");
+  if (fs.existsSync(bundledSkills)) {
+    sources.push(bundledSkills);
+  }
   const userSkills = path.join(homeDir, ".agents", "skills");
   if (config.importUserSkills && fs.existsSync(userSkills)) {
     sources.push(userSkills);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htooayelwinict/appv23",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "npx-friendly Docker launcher for the appv23 coding-agent sandbox.",
   "license": "MIT",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/appv23.js",
+    "skills/**/*.md",
     "README.md",
     "package.json"
   ],

package/skills/subagent-delegation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: subagent-delegation
+description: Use only when the user explicitly asks to spawn, delegate to, hand off to, or verify work through subagents, child agents, reviewer agents, explorer agents, research agents, web-search agents, or agent-to-agent workflows.
+---
+
+# Subagent Delegation
+
+Use this skill only when the user explicitly asks for subagents, delegation, handoff, reviewer/explorer/research child agents, `/delegate`, or `/subagents`.
+
+## Default behavior
+
+- Keep the parent agent normal unless this skill is explicitly triggered.
+- This skill is active for the current user request only. After the parent reports child results, return to normal main-agent behavior.
+- Do not use this skill on a later user request unless that later request explicitly asks for subagents, delegation, handoff, reviewer/explorer/research child agents, `/delegate`, or `/subagents`.
+- Use one delegation wave by default, with at most 3 child agents.
+- Do not launch a second wave unless the user explicitly asks for it after seeing the first child summaries.
+- Do not describe or plan "Wave 2", "Wave 3", or future waves in the same answer.
+- If the task is larger than 3 children can cover, process only the first bounded slice and ask the user whether to continue.
+- Do not let children spawn more subagents.
+- Do not write files unless the user explicitly asks for written artifacts.
+
+## Scope control
+
+- If the requested scope is vague, ask one concise clarification instead of broadening it.
+- For phrases like "those files" or "those md files", use only exact files already named in the current conversation or visible parent output.
+- If no exact file list is available, ask which files or directory to use.
+- Never convert a vague request into a whole-repo or whole-workspace sweep.
+- Never run whole-workspace file-count or whole-workspace discovery commands such as `find /workspace -type f`.
+- Avoid unbounded discovery commands. Prefer a named directory and a capped listing, for example `find docs -maxdepth 1 -name '*.md' | head -20`.
+- If there are more than 12 candidate files, ask the user to narrow scope before spawning children.
+
+## Child task contract
+
+Before spawning, the parent must give each child:
+
+- A role.
+- Exact paths or one narrow directory.
+- A clear stop condition.
+- A small output budget.
+- A requirement to report status, blockers, and a concise summary.
+
+Child instructions must say:
+
+- Make one diagnostic attempt after a missing path or failed tool call, then stop and report the blocker.
+- Do not retry the same tool call with the same arguments.
+- Do not call a `glob` tool. This runtime does not provide one; use `ls`, `find`, `read`, or a bounded `bash` command when needed.
+- Do not scan parent directories outside the assigned scope.
+- Do not include full tool traces in the final answer.
+
+## Parent reporting
+
+After children finish, report only:
+
+- Child task id.
+- Child role.
+- Child status.
+- Concise child summary.
+- Any blocker or guardrail status.
+
+If a child hits a guardrail or cancellation, report it and stop. Do not retry automatically.
+
+Do not compensate for child failure by directly scanning the remaining parent scope. Report the child status and ask the user for the next step.
+
+Do not carry this workflow into the next user message. A completed child result is not permission to call more subagent tools later.