SKILL.md
---
name: treeseed
description: Operate a TreeSeed control plane through its current MCP capabilities for project, knowledge, governance, and execution work. Use when a task targets TreeSeed records or governed project-agent chat; do not use it as authority to run agents or mutate repositories.
metadata:
protocol: "2026-07-28"
catalog-receipt: "catalog-receipt.json"
categories: "knowledge,governance,projects,execution,mcp"
---
# TreeSeed
Treat the connected TreeSeed server as the authority for identity, access, governance, scheduling, and receipts. Discover its current MCP tools, resources, templates, prompts, schemas, and capability annotations before choosing an operation. Do not rely on a remembered tool list or construct REST paths.
## Operating boundary
- Act as the authenticated external principal. Do not claim project-agent identity unless an explicit, authorized project-agent chat operation returns that delegation.
- Read current state before a consequential mutation. Follow returned blockers, concurrency tokens, confirmation requests, resource links, and next actions.
- Use server-provided structured input and output schemas. Never place credentials, session material, private keys, or bearer tokens in tool arguments or model-visible content.
- Treat `input_required` as a signed, exact-argument confirmation checkpoint. Ask the human when required; never alter, reuse, or synthesize confirmation state.
- Follow durable `treeseed://` resource links for asynchronous work. Use progress, cancellation, completion, and subscriptions when advertised instead of polling invented endpoints.
- Do not invoke or emulate `save`, `stage`, or `release` until the server advertises their accepted governed operations.
- For repository-backed project knowledge, use the `trsd library` workflow in `references/knowledge.md`; never assume an unbound virtual repository or a `src/content` library root.
## Choose the relevant guidance
- For questions, research, knowledge, or TreeDX projections, read [references/knowledge.md](references/knowledge.md).
- For proposals, decisions, estimates, reviews, or discussions, read [references/governance.md](references/governance.md).
- For teams, projects, repositories, or provider bindings, read [references/projects.md](references/projects.md).
- For agents, providers, capacity, plans, workdays, assignments, or explicit project-agent chat, read [references/execution.md](references/execution.md).
- For connection discovery, protocol behavior, errors, subscriptions, or confirmations, read [references/mcp.md](references/mcp.md).
## Distribution
Install and update the project-scoped skill with the pinned Vercel Labs Skills CLI version recorded by the consuming project:
```text
npx skills@1.5.23 add treeseed-ai/skill --skill treeseed --agent codex --yes
npx skills@1.5.23 update treeseed --project --yes
```
The receipt pins published SDK and API evidence for this copy. Runtime discovery remains authoritative when a connected server advertises a newer compatible catalog. Installed files and `skills-lock.json` belong to the consuming project; this repository remains the source of releases.
references/governance.md
# Governance work
Use the server's current semantic resources for questions, objectives, proposals, decisions, discussions, estimates, reviews, and findings. Do not infer approval from comments, labels, reactions, or an external host's state.
- Read the proposal, its evidence, current revision, and decision state before commenting or reviewing.
- Keep plans, estimates, findings, and summaries attached to the returned governed lineage.
- Acting work requires the API's accepted decision and execution evidence. Planning or research may be admitted under a workday profile, but it does not mint acting authority.
- Treat a merge, provider receipt, or external PR as observed evidence until TreeSeed adopts it through an authoritative operation.
- For high-risk decisions, pass the server's exact confirmation request back to the accountable human without rewriting its arguments.
references/execution.md
# Execution work
Use execution resources to understand agents, provider connections, capacity, API-derived plans, time-based workdays, assignments, and durable operation status. External assistants remain external principals.
- Inspect capacity and plan explanations; do not author derived capacity plans, reservations, leases, or settlements.
- Plan a workday from high-level intent. Start only the exact fresh preflight receipt returned by the API, and accept stale-plan rejection rather than silently recalculating.
- Follow assignment and workday resource links for progress, cancellation, interruption, return, and settlement.
- Invoke project-agent chat only through the explicit governed chat capability. The returned actor chain and invocation record determine whether delegation occurred.
- Never pass provider credentials, GitHub credentials, host authority, repository write credentials, or TreeDX secrets into an agent workspace.
- If the server does not advertise an operation, it is unavailable. Do not emulate it with raw REST, Git, database, or provider calls.
LICENSE
Copyright 2026 Fractal Synapse Labs LCA PBC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.github/workflows/verify.yml
name: Verify
on:
pull_request:
push:
branches:
- main
- staging
permissions:
contents: read
jobs:
skill:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
- uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.13"
- name: Validate skill and published catalog evidence
run: |
python -m unittest discover -s tests -v
python scripts/verify.py --check-remote
- name: Verify project-scoped Vercel Skills installation
run: |
test "$(npx --yes skills@1.5.23 --version)" = "1.5.23"
workspace="$(mktemp -d)"
cd "$workspace"
git init --quiet
npx --yes skills@1.5.23 add "$GITHUB_WORKSPACE" --skill treeseed --agent codex --yes --copy
test -f .agents/skills/treeseed/SKILL.md
test -f skills-lock.json
- name: Verify published update and lock restoration
if: github.ref == 'refs/heads/main'
run: |
workspace="$(mktemp -d)"
cd "$workspace"
git init --quiet
npx --yes skills@1.5.23 add treeseed-ai/skill --skill treeseed --agent codex --yes --copy
cp .agents/skills/treeseed/SKILL.md expected.md
printf '\nmodified\n' >> .agents/skills/treeseed/SKILL.md
npx --yes skills@1.5.23 update treeseed --project --yes
cmp expected.md .agents/skills/treeseed/SKILL.md
mv .agents installed-backup
npx --yes skills@1.5.23 experimental_install
cmp expected.md .agents/skills/treeseed/SKILL.md
AGENTS.md
# TreeSeed skill workspace guidance
GitHub Issues are the planning and status authority. GitHub Actions are the verification authority. Do not post routine progress comments on issues or pull requests; update issue bodies and pull-request descriptions instead.
Optimize agent and CI usage for completed, verified outcomes. Read exact targeted context, batch related changes and checks, reuse immutable release evidence, inspect only failed jobs, and do not rebuild unchanged artifacts. Stop at genuine authority boundaries.
This repository owns the TreeSeed skill, its references, catalog compatibility receipt, tests, Actions, tags, and releases. Never commit credentials, runtime state, host identities, personal paths, or installed project copies of this skill.
.gitignore
__pycache__/
*.py[cod]
catalog-receipt.json
{
"schemaVersion": "treeseed.skill-catalog-receipt/v2",
"protocolVersion": "2026-07-28",
"skillsCliVersion": "1.5.23",
"categories": ["knowledge", "governance", "projects", "execution", "mcp"],
"sdk": {
"version": "0.13.0-rc.61",
"sourceCommit": "0f0c04c99143da43d69a13ad6363d3d7265a9b77",
"contractBundle": {
"url": "https://github.com/treeseed-ai/sdk/releases/download/0.13.0-rc.61/contract-bundle.json",
"digest": "sha256:074aa15ef46cfca3949f0fd69a91561edd42f396b56c8670b2ee4b4ef75bbd3b"
},
"packageDigest": "sha256:2b19f0fa66a03bf43c7dfd45b09607fcced9564a18cf1df9f07b0997df0e652a",
"operationCatalogDigest": "sha256:28060eedb6b49b5169cbfa9ce055cb380c68ac27f9b25c58a0e1a9cc3cdb1be0",
"mcpInputDigest": "sha256:e277ad6aee473be430c2ded1efe9a511cb283a3741a6da716c7c9d89b9145f0f",
"openApiDigest": "sha256:20982482c701cde2d824d0aab5bd350284ad0203a4d6819f1389f79734ddee97"
},
"api": {
"version": "0.8.0-rc.60",
"sourceCommit": "d275d8f4079db6ee965a78f3617e17022c26f53c",
"componentManifest": {
"url": "https://github.com/treeseed-ai/api/releases/download/0.8.0-rc.60/component-release.json",
"digest": "sha256:78353fa375658c8a3617db891b8fc6eb234bff1132fd02aeefbef0ecbcd0ccbf"
},
"imageDigest": "sha256:3b2a56b701c7afba40bad7c111320947ede0c55a93c4fe0bfabb45b1c0b5ef53"
}
}
agents/openai.yaml
interface:
display_name: "TreeSeed"
short_description: "Operate governed TreeSeed platform capabilities"
default_prompt: "Use $treeseed to perform this work through the current governed TreeSeed capabilities."
policy:
allow_implicit_invocation: true
references/knowledge.md
# Knowledge work
Start by discovering the connected server's current knowledge and question resources. Prefer resource reads and search over broad mutation tools, and preserve project/team scope in every request.
- Questions drive research; knowledge records and TreeDX projections hold the durable result.
- Fetch the current record and its revision before updating it. Preserve citations, provenance, project scope, and returned concurrency evidence.
- Use subscriptions for changing discussions or knowledge projections when advertised.
- TreeDX remains canonical for content. A control-plane projection or receipt is not permission to bypass TreeDX custody or write directly to its storage.
- If research should become governed work, hand it into the proposal/decision lifecycle described in [governance.md](governance.md).
## Query a project library with `trsd`
Resolve the project binding before relying on results:
```sh
trsd library show <project> --json
trsd library status <project> --json
```
`<project>` may be an unambiguous project slug or UUID. Status must report a bound repository and healthy search index. Treat missing bindings, unavailable indexes, moved refs, and empty error responses as failures.
Discover and read repository-root collections:
```sh
trsd library paths <project> --prefix agents --ref <commit-or-protected-ref> --json
trsd library search <project> "release policy" --path knowledge --ref <exact-commit> --json
trsd library read <project> agents/engineer.mdx --ref <exact-commit> --json
trsd library query <project> "active agents" --model agent --ref <exact-commit> --json
trsd library context <project> "what governs this change?" --ref <exact-commit> --max-items 20 --max-tokens 8000 --json
```
Prefer the exact `resolvedRef` returned by TreeDX for subsequent calls. Libraries use top-level paths such as `agents/`, `books/`, `knowledge/`, `notes/`, and `questions/`; never prepend `src/content`.
## Organize and save knowledge
All changes use governed TreeDX workspaces:
```sh
trsd library workspace create <project> --json
trsd library workspace read <workspace> <path> --json
trsd library workspace write <workspace> --input draft.yaml --json
trsd library workspace diff <workspace> --json
trsd library workspace submit <workspace> --version <version> --message "Describe the knowledge change" --json
trsd library reviews list --team <team> --json
trsd library reviews decide <review> --input decision.yaml --json
trsd library reviews publish <review> --input publication.yaml --json
```
Use `workspace abandon <workspace> --version <version>` only for an unsubmitted draft. Mutation input belongs in files or stdin-capable clients, never in arguments when it contains document bodies or sensitive material. Publication must verify the reviewed commit at the upstream exact ref.
## Local diagnosis
Development state is mounted beneath the Platform workspace at `.treeseed/data`. It is visible for diagnostics only. Use TreeDX, control-plane, MCP, or `trsd` APIs for every read that informs work and every mutation; never repair repositories, refs, indexes, databases, or credentials by editing mounted files.
references/mcp.md
# MCP connection behavior
The accepted server speaks stateless Streamable HTTP MCP `2026-07-28`. Begin with server discovery, then list the capabilities relevant to the task. Runtime discovery is authoritative over the pinned receipt when the server presents a newer compatible catalog.
- Use advertised input/output schemas, semantic annotations, and OAuth scope challenges.
- Follow `treeseed://` resources and templates instead of inventing REST paths. Use completion for resource or prompt arguments when available.
- Use resource subscriptions/listen for durable changes and honor cancellation and progress notifications.
- An `input_required` response contains signed, expiring, single-use state bound to the principal, OAuth client, operation, and exact arguments. Never decode it into authority, replay it, or transplant it between clients.
- Treat RFC 9457 problems and TreeSeed blockers as typed outcomes. Preserve request and trace identifiers when reporting failures.
- Do not request legacy initialization, session, roots, sampling, or MCP logging behavior. Do not expose credentials in prompts, content, resources, logs, or tool results.
tests/test_verify.py
import json
import tempfile
import unittest
from pathlib import Path
from scripts.verify import verify
ROOT = Path(__file__).resolve().parents[1]
class VerifySkillTest(unittest.TestCase):
def copy_fixture(self) -> Path:
temporary = tempfile.TemporaryDirectory()
self.addCleanup(temporary.cleanup)
target = Path(temporary.name)
for name in ("SKILL.md", "catalog-receipt.json"):
(target / name).write_bytes((ROOT / name).read_bytes())
(target / "references").mkdir()
for source in (ROOT / "references").iterdir():
(target / "references" / source.name).write_bytes(source.read_bytes())
return target
def test_repository_passes(self) -> None:
verify(ROOT)
def test_stale_receipt_fails(self) -> None:
target = self.copy_fixture()
receipt_path = target / "catalog-receipt.json"
receipt = json.loads(receipt_path.read_text())
receipt["schemaVersion"] = "treeseed.skill-catalog-receipt/v1"
receipt_path.write_text(json.dumps(receipt))
with self.assertRaisesRegex(ValueError, "stale"):
verify(target)
def test_invalid_catalog_digest_fails(self) -> None:
target = self.copy_fixture()
receipt_path = target / "catalog-receipt.json"
receipt = json.loads(receipt_path.read_text())
receipt["sdk"]["contractBundle"]["digest"] = "sha256:not-a-digest"
receipt_path.write_text(json.dumps(receipt))
with self.assertRaisesRegex(ValueError, "digest is invalid"):
verify(target)
if __name__ == "__main__":
unittest.main()
scripts/verify.py
#!/usr/bin/env python3
"""Verify the TreeSeed skill and its immutable catalog evidence."""
from __future__ import annotations
import argparse
import hashlib
import json
import re
import sys
import urllib.request
from pathlib import Path
DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
COMMIT = re.compile(r"^[0-9a-f]{40}$")
LINK = re.compile(r"\[[^]]+\]\(([^)]+)\)")
def fail(message: str) -> None:
raise ValueError(message)
def verify(root: Path, check_remote: bool = False) -> None:
skill = root / "SKILL.md"
receipt_path = root / "catalog-receipt.json"
if not skill.is_file() or not receipt_path.is_file():
fail("SKILL.md and catalog-receipt.json are required")
text = skill.read_text(encoding="utf-8")
if not text.startswith("---\n") or "\nname: treeseed\n" not in text:
fail("SKILL.md must declare the treeseed frontmatter name")
for target in LINK.findall(text):
if "://" not in target and not (root / target).is_file():
fail(f"broken local link: {target}")
receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
if receipt.get("schemaVersion") != "treeseed.skill-catalog-receipt/v2":
fail("unsupported or stale catalog receipt schema")
if receipt.get("skillsCliVersion") != "1.5.23":
fail("unexpected Vercel Labs Skills CLI version")
for owner in ("sdk", "api"):
source_commit = receipt.get(owner, {}).get("sourceCommit", "")
if not COMMIT.fullmatch(source_commit):
fail(f"{owner}.sourceCommit must be an exact commit")
for owner, artifact_name in (("sdk", "contractBundle"), ("api", "componentManifest")):
artifact = receipt[owner][artifact_name]
if not DIGEST.fullmatch(artifact.get("digest", "")):
fail(f"{owner}.{artifact_name}.digest is invalid")
if check_remote:
with urllib.request.urlopen(artifact["url"], timeout=30) as response:
actual = "sha256:" + hashlib.sha256(response.read()).hexdigest()
if actual != artifact["digest"]:
fail(f"{owner}.{artifact_name} digest mismatch")
forbidden_home_prefix = "/" + "home/"
for path in root.rglob("*"):
if path.is_file() and not {".git", "__pycache__"}.intersection(path.parts):
try:
content = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
continue
if forbidden_home_prefix in content:
fail(f"personal home path in {path.relative_to(root)}")
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("root", nargs="?", default=".")
parser.add_argument("--check-remote", action="store_true")
args = parser.parse_args()
try:
verify(Path(args.root).resolve(), args.check_remote)
except (OSError, ValueError, json.JSONDecodeError) as error:
print(f"skill verification failed: {error}", file=sys.stderr)
return 1
print("TreeSeed skill verification passed")
return 0
if __name__ == "__main__":
raise SystemExit(main())
references/projects.md
# Project and repository work
Resolve team and project context from visible resources rather than guessing identifiers. When names are ambiguous, fetch the candidates and ask the user to choose.
- Read project access, current revision, repository topology, and provider status before mutation.
- Use catalogued provider and repository operations. Never construct GitHub API calls, raw control-plane URLs, commit-authority fields, or integration receipts on TreeSeed's behalf.
- Git commits remain native Git objects. Issues and pull requests are provider projections bound to governed work; they do not independently grant TreeSeed authority.
- Archive, withdraw, or supersede when the server offers those lifecycle operations. Treat deletion, credential changes, authority expansion, and production changes as confirmation-bearing work.
- Market and Market API are external projects and never Platform-custodied repositories or deployment resources.