feat: add yazi terminal file manager and update APS skill to v1.2.1

.github/agents/aps-v1.1.16.agent.md → .github/agents/aps-v1.2.1.agent.md

@@ -1,6 +1,6 @@
 ---
-name: APS v1.1.16 Agent
-description: "Generate APS v1.1.16 .agent.md or .prompt.md files: detect artifact type from user intent, load APS+VS Code adapter, extract intent, then generate+write+lint. Author: Christopher Buckley. Co-authors: Juan Burckhardt, Anastasiya Smirnova. URL: https://github.com/chris-buckley/agnostic-prompt-standard"
+name: APS v1.2.1 Agent
+description: "Generate APS v1.2.1 .agent.md or .prompt.md files: detect artifact type from user intent, load APS+VS Code adapter, extract intent, then generate+write+lint. Author: Christopher Buckley. Co-authors: Juan Burckhardt, Anastasiya Smirnova. URL: https://github.com/chris-buckley/agnostic-prompt-standard"
 tools:
   - execute/runInTerminal
   - read/readFile

.github/agents/new-feature.agent.md

@@ -34,12 +34,16 @@ You MUST include the check_packages helper for apt dependencies in generated ins
 You MUST verify installation with the binary's version command in install.sh.
 You MUST use the dev-container-features-test-lib pattern in generated test files.
 You MUST use conventional commit format for any commits.
+You MUST create a feature branch from main before making any changes.
+You MUST NOT commit feature files until the user explicitly approves them.
+You MUST present generated files for user review using format:SCAFFOLD_SUMMARY before committing.
+You MUST run the feature-specific test after committing as the completion gate.
+You MUST offer to create a PR after tests pass.
 You MUST NOT modify unrelated files or make drive-by refactors.
 You MUST NOT remove or reorder existing README content beyond adding the new entry.
-You MUST NOT run devcontainer features test automatically.
+You MUST NOT commit or push changes to files the user did not ask for in the current step.
 You SHOULD read an existing feature's install.sh as a reference before generating a new one.
 You SHOULD provide graceful fallback logic when GitHub API calls fail during version resolution.
-You SHOULD suggest test commands to the user after scaffolding using format:SCAFFOLD_SUMMARY.
 You MAY implement checksum verification if the user requests it and upstream provides checksums.
 You MAY add extra options to devcontainer-feature.json if the user specifies them.
 </instructions>
@@ -170,6 +174,7 @@ BINARY_NAME: ""
 REQUESTED_VERSION: "latest"
 SUPPORT_CHECKSUM: false
 RELEASE_ASSET_PATTERN: ""
+TEST_RESULT: ""
 </runtime>
 
 <triggers>
@@ -179,10 +184,15 @@ RELEASE_ASSET_PATTERN: ""
 <processes>
 <process id="main" name="Main Workflow">
 RUN `parse-input`
+RUN `create-branch`
 RUN `inspect-upstream`
 RUN `scaffold`
 RUN `integrate`
 RETURN: format="SCAFFOLD_SUMMARY"
+WAIT for user approval
+RUN `commit-feature`
+RUN `test-feature`
+RUN `create-pr`
 </process>
 
 <process id="parse-input" name="Parse User Input">
@@ -196,6 +206,10 @@ IF INP contains "checksum=true":
   SET SUPPORT_CHECKSUM := true (from "Agent Inference")
 </process>
 
+<process id="create-branch" name="Create Feature Branch">
+USE `execute/runInTerminal` where: command="git checkout -b feat/{FEATURE_ID}"
+</process>
+
 <process id="inspect-upstream" name="Inspect Upstream Releases">
 USE `web/githubRepo` where: query="latest release assets", repo=SOURCE_REPO
 CAPTURE RELEASE_ASSET_PATTERN from result
@@ -226,6 +240,22 @@ USE `edit/editFiles` where: filePath=".github/workflows/test.yaml"
 USE `read/readFile` where: filePath="README.md"
 USE `edit/editFiles` where: filePath="README.md"
 </process>
+
+<process id="commit-feature" name="Commit Feature">
+USE `execute/runInTerminal` where: command="git add -A && git commit -m 'feat: add {FEATURE_ID} dev container feature'"
+</process>
+
+<process id="test-feature" name="Test Feature">
+USE `execute/runInTerminal` where: command="devcontainer features test -f {FEATURE_ID} -i ubuntu:latest ."
+CAPTURE TEST_RESULT from result
+IF TEST_RESULT contains "FAILED":
+  TELL "Test failed. Review output and fix install.sh." level=error
+</process>
+
+<process id="create-pr" name="Create Pull Request">
+USE `execute/runInTerminal` where: command="git push origin feat/{FEATURE_ID}"
+USE `execute/runInTerminal` where: command="gh pr create --base main --head feat/{FEATURE_ID} --title 'feat: add {FEATURE_DISPLAY_NAME} dev container feature' --fill"
+</process>
 </processes>
 
 <input>

.github/skills/agnostic-prompt-standard/SKILL.md

@@ -7,8 +7,8 @@ metadata:
   author: "Christopher Buckley"
   co_authors: "Juan Burckhardt; Anastasiya Smirnova"
   spec_version: "1.0"
-  framework_revision: "1.1.16"
-  last_updated: "2026-02-18"
+  framework_revision: "1.2.1"
+  last_updated: "2026-03-12"
 ---
 
 # Agnostic Prompt Standard (APS) v1.0 — Skill Entry
@@ -38,6 +38,9 @@ This `SKILL.md` is the **entrypoint** for the Agnostic Prompt Standard (APS) v1.
     - `constants-json-block-v1.0.0.example.md`
     - `constants-text-block-v1.0.0.example.md`
     - `constants-csv-block-v1.0.0.example.md`
+  - `composites/` — combined reference examples.
+    - `gui-component-spec-v1.0.0.example.md`
+    - `mcp-tool-bridge-v1.0.0.example.md`
   - `formats/` — example format blocks.
     - `format-code-changes-full-v1.0.0.example.md`
     - `format-code-map-v1.0.0.example.md`
@@ -56,12 +59,16 @@ This `SKILL.md` is the **entrypoint** for the Agnostic Prompt Standard (APS) v1.
   - `build-skill.md` — process for building new APS-compliant skills.
 - `guides/` — reference documents for humans and agents.
   - `skill-authoring-v1.0.0.guide.md` — skill authoring reference.
+  - `mcp-tool-bridge-v1.0.0.guide.md` — MCP tool bridge integration guide.
+  - `subagent-architecture-v1.0.0.guide.md` — cross-platform subagent architecture and interface mapping guide.
 - `platforms/` — **non-normative** platform adapters. Each platform has a single `adaptor.md` file.
   - `README.md` — platforms overview and contract.
   - `_template/` — skeleton for new platform adapters.
     - `adaptor.md`
   - `claude-code/` — Claude Code CLI adapter.
     - `adaptor.md` — platform constants, tool registry, and format contracts.
+  - `generic/` — generic / external tools adapter.
+    - `adaptor.md` — neutral tool mapping guidance for MCP or other external tool layers.
   - `opencode/` — OpenCode adapter.
     - `adaptor.md` — platform constants.
   - `vscode-copilot/` — VS Code + GitHub Copilot adapter.
@@ -72,10 +79,12 @@ This `SKILL.md` is the **entrypoint** for the Agnostic Prompt Standard (APS) v1.
 
 ## Platform adapters
 
-Platform-specific details (file discovery, frontmatter dialects, tool naming) are documented in `platforms/`.
+Platform-specific details (file discovery, frontmatter dialects, tool naming, and coordinator/worker orchestration) are documented in `platforms/`.
 
 → See [platforms/README.md](platforms/README.md) for overview and how to add new adapters.
 
+→ See [guides/subagent-architecture-v1.0.0.guide.md](guides/subagent-architecture-v1.0.0.guide.md) for portable coordinator/worker authoring guidance.
+
 ### VS Code + GitHub Copilot
 
 The initial adapter for VS Code + GitHub Copilot is at `platforms/vscode-copilot/`.

.github/skills/agnostic-prompt-standard/assets/composites/mcp-tool-bridge-v1.0.0.example.md

@@ -0,0 +1,112 @@
+<!-- APS v1.0 — MCP tool bridge example
+     This composite asset shows one MCP Tool object, one canonical
+     predefinedTools.json entry, one config.json ALIAS mapping, and one APS
+     process excerpt that uses the canonical tool id. -->
+
+# MCP tool bridge example
+
+This example shows how to bridge one MCP tool into APS without putting host config in the prompt.
+
+## 1. Raw MCP Tool (`tools/list` result)
+
+```json
+{
+  "name": "search_docs",
+  "title": "Search Docs",
+  "description": "Search the documentation site.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Search text"
+      }
+    },
+    "required": ["query"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "matches": {
+        "type": "array"
+      }
+    }
+  },
+  "annotations": {
+    "readOnlyHint": true,
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": true
+  }
+}
+```
+
+## 2. Canonical `predefinedTools.json` entry
+
+```json
+[
+  {
+    "name": "search_docs",
+    "displayName": "Search Docs",
+    "description": "Search the documentation site.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search text"
+        }
+      },
+      "required": ["query"]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "matches": {
+          "type": "array"
+        }
+      }
+    },
+    "hints": {
+      "readOnly": true,
+      "destructive": false,
+      "idempotent": true,
+      "openWorld": true
+    },
+    "source": {
+      "kind": "mcp",
+      "server": "docs",
+      "toolName": "search_docs"
+    }
+  }
+]
+```
+
+## 3. Host alias in `config.json`
+
+Use `config.json` only when the host exposes a decorated runtime name.
+
+```json
+{
+  "alias": {
+    "mcp__docs__search_docs": "search_docs"
+  }
+}
+```
+
+## 4. APS process excerpt
+
+```text
+<process id="lookup_docs" name="Look up docs" args="QUERY: String">
+USE `search_docs` where: query=QUERY
+CAPTURE RESULTS from `search_docs`
+RETURN: RESULTS
+</process>
+```
+
+## Notes
+
+- `search_docs` is the canonical APS tool id.
+- The prompt stays neutral. It does not include transport or host config.
+- The host-specific runtime name stays in external config.
+- The engine can resolve the alias before tool execution.

.github/skills/agnostic-prompt-standard/guides/subagent-architecture-v1.0.0.guide.md

@@ -0,0 +1,146 @@
+<instructions>
+You MUST load this guide before you author coordinator and worker agents.
+You MUST model portable multi-agent systems as one coordinator and one or more leaf workers.
+You MUST define the worker <input> block as the public request contract into the worker.
+You MUST mirror each worker <input> field in the caller dispatch process arguments.
+You MUST define a worker response contract in <formats> and capture it in the caller.
+You MUST keep platform-specific invocation syntax inside the caller dispatch layer only.
+You MUST use explicit allowlists for worker selection and tool access.
+You MUST keep worker results task-bounded, typed, and brief.
+You SHOULD use handoffs instead of nested worker spawning when a platform supports handoffs.
+You SHOULD treat undocumented nested delegation as unsupported for portable APS authoring.
+You MUST treat Claude Code workers as leaf workers.
+You SHOULD treat VS Code Copilot and OpenCode workers as leaf workers for portable APS authoring.
+</instructions>
+
+<constants>
+GUIDE_VERSION: "1.0.0"
+
+PLATFORM_CAPABILITY_MATRIX: CSV<<
+platform,coordinator_role,worker_role,documented_depth_policy,invocation_surface,notes
+claude-code,main-thread agent only,markdown subagent,depth-1-only,Agent,"Workers cannot spawn workers."
+vscode-copilot,main chat agent or prompt,subagent or custom agent worker,portable-depth-1,agent/runSubagent,"Custom-agent subagents are experimental and nested delegation is not documented."
+opencode,primary agent,mode=subagent worker,portable-depth-1,Task,"Primary/subagent roles are documented and nested delegation is not documented."
+generic,host-defined or manual APS coordinator,host-defined or external worker,host-defined,host-defined,"Use explicit APS dispatch processes when host behavior is unclear."
+>>
+
+REQUEST_INTERFACE_RULES: TEXT<<
+1. The worker <input> block is the public interface into the worker.
+2. The caller dispatch process MUST accept the same fields, names, and meanings.
+3. If a platform needs renamed fields, keep the rename in the dispatch layer only.
+4. Do not hide required worker inputs inside free-form prompt text.
+5. Keep request types stable across platforms.
+>>
+
+RESPONSE_INTERFACE_RULES: TEXT<<
+1. The worker MUST return a typed result that matches a <format> contract.
+2. The caller MUST capture the worker result before the next step starts.
+3. Keep summaries brief and task-bounded.
+4. Do not leak platform-only metadata unless the caller explicitly asks for it.
+>>
+
+PORTABLE_PATTERNS: JSON<<
+{
+  "coordinator_worker": {
+    "description": "One coordinator dispatches one worker and integrates the worker result.",
+    "best_for": ["single specialty task", "strong contract boundaries"]
+  },
+  "fan_out_review": {
+    "description": "One coordinator dispatches multiple leaf workers in parallel and then compares typed results.",
+    "best_for": ["research", "review", "verification"]
+  },
+  "sequential_handoff": {
+    "description": "One worker finishes, returns a typed result, and the coordinator hands off the next step to a different worker.",
+    "best_for": ["plan -> implement", "implement -> review"]
+  }
+}
+>>
+
+ANTI_PATTERNS: TEXT<<
+- Worker-to-worker recursion without a documented host contract.
+- Free-form worker prompts with hidden required fields.
+- Caller processes that rename or reshape worker inputs in multiple places.
+- Worker outputs that mix summary text, hidden state, and untyped data.
+- Broad tool access for narrow workers.
+>>
+
+APS_INTERFACE_EXAMPLE: TEXT<<
+Worker contract:
+<input>
+TICKET_ID: String
+TARGET_PATHS: String[]
+</input>
+
+Caller dispatch process:
+<process id="dispatch-review" name="Dispatch review" args="TICKET_ID: String, TARGET_PATHS: String[]">
+USE `Agent` where: description="Review the requested files", prompt="Review the requested files", worker="reviewer"
+SET WORKER_REQUEST := { TICKET_ID: TICKET_ID, TARGET_PATHS: TARGET_PATHS }
+CAPTURE REVIEW_RESULT from `reviewer`
+RETURN: REVIEW_RESULT
+</process>
+
+Rule:
+- The caller args are the same interface as the worker input.
+- The caller is responsible for the platform-specific call surface.
+- The worker returns a typed result that the caller captures.
+>>
+
+BIDIRECTIONAL_CONTRACT_RULE: TEXT<<
+Request flow: caller process args -> worker <input>.
+Response flow: worker <format> result -> caller capture variables.
+The contract is bidirectional only when the caller defines both mappings explicitly.
+>>
+</constants>
+
+<formats>
+<format id="SUBAGENT_ARCHITECTURE_SPEC_V1" name="Subagent Architecture Spec" purpose="Describe a coordinator plus worker architecture with explicit request and response contracts.">
+# Subagent Architecture Spec: <ARCHITECTURE_NAME>
+
+## Coordinator
+- Role: <COORDINATOR_ROLE>
+- Dispatch surface: <DISPATCH_SURFACE>
+- Depth policy: <DEPTH_POLICY>
+
+## Workers
+| Worker | Role | Input contract | Output contract | Allowed tools | Notes |
+|--------|------|----------------|-----------------|---------------|-------|
+| <WORKER_NAME> | <WORKER_ROLE> | <INPUT_CONTRACT_ID> | <OUTPUT_CONTRACT_ID> | <ALLOWED_TOOLS> | <WORKER_NOTES> |
+
+## Request and response mapping
+<REQUEST_RESPONSE_MAP>
+
+## Failure policy
+<FAILURE_POLICY>
+
+WHERE:
+- <ALLOWED_TOOLS> is String; comma-separated logical or host tool ids allowed for the worker.
+- <ARCHITECTURE_NAME> is String; descriptive name for the coordinator/worker design.
+- <COORDINATOR_ROLE> is String; the coordinator responsibility statement.
+- <DEPTH_POLICY> is String; one of depth-1-only, portable-depth-1, host-defined.
+- <DISPATCH_SURFACE> is String; host invocation surface such as Agent, agent/runSubagent, Task, or manual APS process.
+- <FAILURE_POLICY> is Markdown; what the coordinator does when a worker fails, times out, or returns invalid data.
+- <INPUT_CONTRACT_ID> is String; id or label of the worker request contract.
+- <OUTPUT_CONTRACT_ID> is String; id or label of the worker response contract.
+- <REQUEST_RESPONSE_MAP> is Markdown; explicit mapping from caller args to worker input and from worker result to caller capture.
+- <WORKER_NAME> is String; worker identifier.
+- <WORKER_NOTES> is String; short notes about visibility, allowlists, or platform limits.
+- <WORKER_ROLE> is String; worker responsibility statement.
+</format>
+
+<format id="SUBAGENT_CONTRACT_CHECKLIST_V1" name="Subagent Contract Checklist" purpose="Review checklist for portable coordinator/worker authoring.">
+# Subagent Contract Checklist
+
+- [ ] The coordinator is the single dispatch owner.
+- [ ] Each worker has an explicit APS <input> contract.
+- [ ] Each caller dispatch process mirrors the worker input fields one-for-one.
+- [ ] Each worker returns a typed <format> result.
+- [ ] The caller captures the worker result before the next step starts.
+- [ ] Nested delegation is either documented by the host or avoided.
+- [ ] Worker tool access uses least privilege.
+- [ ] Worker visibility and allowlists are explicit.
+- [ ] Platform-only routing details stay outside the portable contract.
+
+WHERE:
+- This checklist is a fixed review format with no placeholders.
+</format>
+</formats>