agent-trellis 0.20.0 → 0.22.0

package/dist/pi-bridge/index.js

@@ -24,7 +24,7 @@ import { toParametersSchema, toPiContent } from "./schemaTranslate.js";
  * extraction changed nothing it could observe. */
 export { withTimeout };
 const CLIENT_INFO = { name: "trellis-mcp-bridge", version: "0.0.0" };
-function listServerTools(client, timeoutMs) {
+async function listServerTools(client, timeoutMs) {
     return withTimeout(client.listTools(), timeoutMs, `listTools timed out after ${timeoutMs}ms`).then((result) => result.tools);
 }
 /**
@@ -43,7 +43,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     // independent of whether `trellis onboard` was ever run to add pi to
     // managed.yaml. managedAgents governs static config-file writes; this
     // is pi reading canonical directly at its own runtime, P4's own concern.
-    const { desired } = resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
+    const { desired } = await resolveMcpPlan("pi", canonical.mcp, ALL_AGENTS, canonical.secretsPolicy);
     const clients = new Set();
     const registry = new McpToolRegistry();
     const closeClient = async (client) => {

package/docs/architecture.md

@@ -43,7 +43,7 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 ├── mcp/servers.yaml          # single MCP source, values are var-name
 │                             # references only, never literals
 ├── memories/*.md             # shared memory entries (server-memory backed)
-├── scope.yaml                 # exceptions to "shared with all agents" —
+├── scope.yaml                 # skill compatibility registry; agent/memory scope
 │                             # see "Private / agent-specific capabilities"
 └── secrets.policy.yaml       # which var names are allowed, nothing else
 
@@ -132,12 +132,14 @@ one `trellis rollback` restores originals and removes generated
 
 Not everything belongs to all six agents. A skill built around Claude
 Code's Task-based subagent delegation has no equivalent to delegate to on
-Codex; an MCP server might only make sense for one agent's workflow. Every
-scopable item — skill, subagent profile, memory entry, MCP server —
-defaults to "shared with all managed agents," and can be restricted with an explicit
-`scope` (skills/agents/memories) or inline `agents:` (MCP servers, see
-below). Restriction is the exception you declare, not something you
-configure for the common case.
+Codex; an MCP server might only make sense for one agent's workflow.
+Every custom skill must register applicable agents in `scope.yaml`.
+Missing, empty or invalid skill scope pauses Trellis distribution and Runtime
+access; sync removes only Trellis-owned links. `skill scope --all` records
+the current managed set, so adding another agent never silently expands
+compatibility. Package-owned built-ins retain their package-defined policy.
+Subagent profiles, memory entries and MCP servers retain their existing
+all-managed default and explicit restrictions.
 
 **Skills, subagent profiles, and memory entries declare scope in
 `.trellis/scope.yaml`, never inside the artifact file itself.** This
@@ -150,6 +152,18 @@ portable file exactly as its target agent's own spec expects; Trellis's
 own bookkeeping lives next to it, not inside it. See
 `schema/scope.example.yaml`.
 
+Compatibility is explicit: Claude-specific workflows list `claude-code`,
+Codex-specific workflows list `codex`, and portable workflows list each
+reviewed agent. Publisher provenance does not prove compatibility. Hermes
+skills belong to Hermes's own curator/review/archive lifecycle; Trellis
+never manages or writes its skill directory.
+
+Workspace skills use `.agents/scope.yaml` for Trellis-managed delivery and
+Runtime access. Agents that discover `.agents/skills` natively can still
+read that shared source directly; per-agent Trellis registration does not
+override a native agent's own discovery. Keep agent-specific skills in the
+global canonical store when native discovery must be isolated.
+
 **MCP servers are the one exception** — `agents:` is declared inline per
 server in `mcp/servers.yaml` (see `schema/servers.example.yaml`), because
 that file is Trellis's own format and is never handed to an agent
@@ -629,6 +643,12 @@ acceptance criteria already describes this shape ("point at a scratch
 section exists to make it a project-wide rule that every later phase's
 acceptance criteria must follow, not a detail specific to P1.
 
+CLI fixtures must isolate the working directory as well as HOME. Running
+from the real checkout with only HOME changed can make ancestor discovery
+mistake the developer's `~/.agents/` for a workspace. Run the CLI by absolute
+path from the scratch directory; otherwise read-only parity checks can
+compare different layers and write tests can reach real project artifacts.
+
 This is also why P0 needing to resolve pi's actual skill-discovery path
 (§D5 in `openspec/changes/trellis-doctor-p0/design.md`) is investigated
 directly against a real pi installation *as a read-only observation*, and

package/docs/getting-started.md

@@ -465,9 +465,10 @@ $ trellis migrate --from codex --only instructions
 | `skip-case-broken` | Found as `skill.md` instead of `SKILL.md` — fix the case on the source agent first. |
 | `skip-unsupported` | The source capability can't be safely represented (including native memory without a supported adapter); nothing was written for it. |
 
-Migrate never overwrites a genuine conflict, and never scopes a migrated
-skill (or MCP server) to just the source agent — once in canonical, it's
-visible to every agent by default (see `sync`, below). If migrate reports
+Migrate never overwrites a genuine conflict. A newly migrated skill is
+registered only for its source agent; review its compatibility before
+sharing it through `trellis skill scope <name> --agents <ids>`.
+MCP servers retain their existing scope behavior. If migrate reports
 a `conflict`, open the two files/entries it names and decide by hand
 which content should actually be canonical, then re-run.
 
@@ -663,10 +664,10 @@ remains the command for a local directory:
 npx trellis add mattpocock/skills --list
 
 # Fetch and inspect the exact plan without writing canonical or Agent files.
-npx trellis add mattpocock/skills --skill loop-me --dry-run
+npx trellis add mattpocock/skills --skill loop-me --agent codex --dry-run
 
 # Import to the user-level canonical store, then sync to every managed Agent.
-npx trellis add mattpocock/skills --skill loop-me --yes
+npx trellis add mattpocock/skills --skill loop-me --agent '*' --yes
 ```
 
 The source may be `owner/repository` or a credential-free HTTPS
@@ -678,10 +679,11 @@ dependencies, or write into `.agents/skills`, `~/.agents/skills`, or any
 Agent-specific Skill directory during import. Review the imported
 `SKILL.md` before relying on it in an Agent session.
 
-By default the imported Skill is unscoped, which means every Agent currently
-listed in `~/.trellis/managed.yaml` receives it on sync. Restrict delivery to
-managed Agents with `--agent`; comma-separated values and repeated flags are
-accepted. `--agent '*'` writes the current managed set as an explicit scope.
+Imports require an explicit choice of applicable agents. Interactive terminals
+offer a selection with no agents preselected; noninteractive/JSON calls must
+supply `--agent`. Comma-separated values and repeated flags are accepted.
+`--agent '*'` records the current managed set; `--agent none` imports a paused
+skill. A newly managed agent does not receive existing skills automatically.
 An Agent that is installed but unmanaged is refused before any canonical or
 native write. Add it to Trellis's managed boundary first:
 
@@ -785,6 +787,24 @@ the first place (see `mcp sync`'s own explanation of `env` vs.
 All four of `skill add`/`skill remove`/`mcp add`/`mcp remove` support
 `--dry-run` and `--json`, same convention as every other command.
 
+Local imports use the same compatibility rule:
+
+```sh
+trellis skill add review --from ./skills/review --agents claude-code,codex
+trellis skill add pending --from ./skills/pending --none
+trellis skill list --agent codex --json
+trellis skill scope review --all
+```
+
+Every custom skill needs a `skills.<name>: [agent ids]` entry in
+`~/.trellis/scope.yaml` (or `.agents/scope.yaml` for workspace delivery).
+Unregistered skills pause until reviewed; sync removes only their
+Trellis-owned links and leaves independent files untouched. `skill list
+--agent` shows scoped skills with `linked`, `missing`, `conflict` or `runtime`
+delivery status. Codex's global delivery root is `~/.agents/skills`.
+Use `trellis sync skills --dry-run` before converging an older installation.
+Hermes maintains its own skills; Trellis never writes its skill store.
+
 ## `trellis sync`
 
 Distributes canonical skills and instructions to every **managed** agent

package/docs/research.md

@@ -221,7 +221,23 @@ real incidents during development (a GitLab PAT stored under the wrong
 variable name, and three divergent values of the same router token, one of
 which was silently invalid). Trellis's contribution here is `trellis secrets
 audit` — a linter that fails a build if any adapter output contains a raw
-credential — not a new secret store.
+credential — not a new secret store. The concrete reference form is
+`mxenv://<profile>/<KEY>` (mx-env-secret-source): written in `servers.yaml`
+`env`/`envAliases`, or inline in a header template such as
+`Authorization: Bearer ${mxenv://legacy/SERVICE_TOKEN}`, resolved from the
+mxenv profile at consumption time. Env references are delivered under the
+`KEY` segment; header references are substituted in memory and retain their
+profile identity even when two profiles use the same key. Missing keys,
+unknown profiles and malformed header references fail explicitly, without
+printing provider output or substituting an empty credential. Bare `${VAR}`
+headers retain their existing env-file/process-env behavior.
+
+Header references require Trellis gateway/runtime delivery (or pi's bridge),
+which resolves them independently of the GUI or shell's inherited environment.
+Native clients do not understand `mxenv://`; direct native sync reports a
+conflict with instructions to enable gateway/runtime, rather than writing an
+unusable reference or persisting its resolved value. The canonical server
+still uses `transport: http`/`sse`; no third-party stdio shim is needed.
 
 A third real incident during migrate-in: a source config's `${VAR}`
 reference doesn't always name itself (`OPENAPI_MCP_HEADERS:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -69,6 +69,7 @@
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@modelcontextprotocol/server": "^2.3.1",
+    "@morphixai/mxenv-core": "^0.12.2",
     "smol-toml": "^1.9.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"

package/schema/scope.example.yaml

@@ -1,6 +1,8 @@
-# .trellis/scope.yaml — exceptions only. Anything NOT listed here is
-# shared with all managed agents — that's the default Trellis exists for.
-# Only write an entry when a capability should NOT go everywhere.
+# .trellis/scope.yaml — every custom skill must register applicable agents.
+# Missing/invalid skill entries are PAUSED. [] explicitly pauses a skill.
+# Lists name known compatible agents; managing another agent does not expand
+# an existing skill's list. `skill scope <name> --all` records today's set.
+# Subagent profiles and memories retain their all-managed default.
 #
 # Why this lives in its own file instead of inside each SKILL.md/agent.md:
 # Codex validates SKILL.md frontmatter against an allow-list of known keys
@@ -15,11 +17,21 @@
 # instead of here — see schema/servers.example.yaml.
 
 skills:
+  shared-workflow: [claude-code, codex, kiro, pi]
+  codex-workflow: [codex]
+  pending-review: []
   # This skill only makes sense for Claude Code's tool surface (e.g. it
   # references the Task tool for subagent delegation, which the other
   # three agents don't have an equivalent of).
   claude-subagent-dispatch: [claude-code]
 
+# Keep publisher provenance separate from compatibility: a Claude-only or
+# Codex-only upstream skill still needs the matching list above. Portable
+# skills list every reviewed target. Never add a Trellis-only `agents`
+# field to upstream SKILL.md files.
+# Hermes skills are autonomous (curator/review/archive); Trellis does not
+# deliver, overwrite, link, or manage ~/.hermes/skills.
+
 agents:
   # Subagent profiles are implicitly Claude-Code-only today — Codex has no
   # persistent subagent concept, Kiro/pi unconfirmed (see docs/research.md).

package/schema/secrets.policy.example.yaml

@@ -12,6 +12,11 @@
 # whose own native MCP client resolves `${VAR}` in its own process), so it
 # already has to read a value into memory to hand to that subprocess.
 #
+# Prefer `mxenv://<profile>/<KEY>` references in servers.yaml `env` /
+# `envAliases` entries where possible: they resolve from the encrypted
+# mxenv store at consumption time and need neither ambient env nor a
+# plaintext env_file (mx-env-secret-source).
+#
 # env_file (optional) narrows *where* the bridge reads those values from —
 # a dotenv-format file (KEY=VALUE per line, no quoting/interpolation), never
 # merged with ambient process env once set: a name absent from it resolves

package/schema/servers.example.yaml

@@ -1,7 +1,17 @@
 # .trellis/mcp/servers.yaml — canonical MCP server definitions.
 #
 # Rules (see docs/architecture.md and docs/research.md §"Secrets"):
-#   - `env` values are variable NAMES only. Never a literal secret.
+#   - `env` values are variable NAMES only, or `mxenv://<profile>/<KEY>`
+#     references resolved from the mxenv store at consumption time and
+#     delivered under the `KEY` segment (mx-env-secret-source). A
+#     reference gives this file value-free, machine-independent
+#     provenance; prefer it over relying on ambient process env.
+#   - HTTP/SSE headers accept inline references, e.g.
+#       Authorization: "Bearer ${mxenv://legacy/SERVICE_TOKEN}"
+#     Use Trellis gateway/runtime delivery (or pi's bridge) for these:
+#     values resolve in memory without depending on the launching shell.
+#     Missing/invalid references fail explicitly. Native direct sync
+#     refuses these references because native clients cannot resolve them.
 #   - Real values come from whatever already populates process env
 #     (a plain `.env`-style file, 1Password's `op run`, etc.) — Trellis
 #     does not store or transport secret values itself.