feat: add yazi terminal file manager and update APS skill to v1.2.1 (#86)

* feat: update Agnostic Prompt Standard skill to v1.2.1

Updates APS agent from v1.1.16 to v1.2.1, adds generic platform adapter,
MCP tool bridge composite example, and subagent architecture guide.
Refreshes all platform adapters and references.

Co-authored-by: Copilot <[email protected]>

* feat: add yazi terminal file manager dev container feature

Adds yazi (https://github.com/sxyazi/yazi) as a new dev container feature.
Installs both yazi and ya binaries from GitHub releases with
multi-architecture support (x86_64, aarch64, i686).

Co-authored-by: Copilot <[email protected]>

* fix: update new-feature agent with git workflow and test gates

Adds branching, user review checkpoint, feature test execution,
and PR creation steps. Removes contradictory 'MUST NOT run tests'
instruction.

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: jsburckhardt

.github/agents/aps-v1.1.16.agent.md .github/agents/aps-v1.2.1.agent.md.github/agents/aps-v1.1.16.agent.md renamed to .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>