cleveragents-core/.opencode/skills/cleveragents-spec/references/resources

Resources — Detailed Reference

Resource Type Hierarchy

Physical Types — Git Layer

Type	User Addable	Sandbox	Description
git	yes	none	A git repository (object DB, refs, full history). May be local or remote.
git-remote	no	(none)	A remote URL configured on a git repo. Auto-discovered child of git.
git-branch	no	(inherits)	A named branch ref. Auto-discovered child of git.
git-tag	no	(inherits)	A tag ref. Auto-discovered child of git.
git-commit	no	(inherits)	A specific commit object. Auto-discovered child of git-branch.
git-tree	no	(inherits)	A tree object (directory listing at a commit). Auto-discovered child of git-commit.
git-tree-entry	no	(inherits)	A blob entry in a tree (specific file at specific path). Auto-discovered child of git-tree.
git-stash	no	(inherits)	A stash entry. Auto-discovered child of git.
git-submodule	no	(inherits)	A submodule reference. Auto-discovered child of git.

Physical Types — Git Checkout

Type	User Addable	Sandbox	Description
git-checkout	yes	git_worktree	A locally checked-out git repo. Composition type — auto-discovers git child and fs-directory child. Most users register this type.

Physical Types — Filesystem Layer

Type	User Addable	Sandbox	Description
fs-mount	yes	copy_on_write	A physical mount point. Root directory auto-discovered as fs-directory child.
fs-directory	yes	copy_on_write	A directory. Can be standalone, root of fs-mount, worktree root of git-checkout, or subdirectory.
fs-file	no	(inherits)	A regular file. Auto-discovered child of fs-directory.
fs-symlink	no	(inherits)	A symbolic link. Auto-discovered child of fs-directory.
fs-hardlink	no	(inherits)	A hard link (link count > 1). Auto-discovered child of fs-directory.

Virtual Types (abstract identity; never user-addable; no sandbox)

Type	Links	Answers
file	fs-file ↔ git-tree-entry	"This file on disk and this blob in git are the same file"
directory	fs-directory ↔ git-tree	"This directory on disk matches this tree object in git"
symlink	fs-symlink ↔ git-tree-entry (mode 120000)	"This symlink on disk and this git entry are the same symlink"
commit	git-commit (cross-repo)	"This commit exists in both repos"
branch	git-branch (cross-repo)	"These repos share a branch at the same HEAD"
tag	git-tag (cross-repo)	"These repos share a tag"
remote	git-remote (cross-repo)	"These repos share the same upstream"
submodule	git-submodule (cross-repo)	"These repos reference the same submodule"
tree	git-tree (cross-commit/cross-repo)	"These tree objects have identical content"

---

Sandbox Strategies

Strategy	Resource Types	Rollback
git_worktree	git-checkout	git reset --hard <commit_sha>
copy_on_write	fs-mount, fs-directory	Restore from snapshot
overlay	Custom	Discard overlay writes since checkpoint
transaction_rollback	Database types	ROLLBACK TO SAVEPOINT <name>
none	git, APIs, cloud services	No rollback; user proceeds at own risk

---

Resource Type Inheritance

# Example: devcontainer-instance inherits container-instance
name: devcontainer-instance
inherits: container-instance
description: "A container provisioned from a devcontainer.json"

cli_args:
  - name: config-path
    type: path
    required: false
    description: "Path to .devcontainer/devcontainer.json"

handler:
  class: DevcontainerHandler
  module: cleveragents.resource.handlers.devcontainer

Inheritance rules:

1. Single inheritance only (no diamond)
2. Maximum chain depth: 5 levels
3. No circular inheritance (validated at registration)
4. Built-in types may not inherit from custom (namespaced) types
5. Removing a parent type is prohibited while subtypes exist

Field resolution: Walk inheritance chain from most specific to root. Subtype value wins (override). If omitted, parent's value is inherited.

Collection field merging: cli_args, child_types, parent_types use additive merging by default. Use <field>_replace: true to replace entirely.

Polymorphism: Tools bound to a parent type automatically work with all subtypes.

---

Execution Environment Routing (6-Level Precedence)

When a plan enters Execute, the runtime determines WHERE each tool runs:

Priority	Source	Condition
1 (highest)	Plan-level execution_environment with priority: override	agents plan use --execution-environment R --execution-env-priority override
2	Project-level execution_environment with priority: override	agents project context set --execution-environment R --execution-env-priority override
3	Nearest-ancestor devcontainer (auto-detected)	Lazy-built on first access
4	Plan-level execution_environment with priority: fallback	Used only when no devcontainer detected
5	Project-level execution_environment with priority: fallback	Used only when no closer-scoped environment
6 (default)	Host	The local operating system

Tool-level environment preferences:

• environment.required: container → tool MUST run in container; error if router resolves to host
• environment.preferred: container → hint only; runs wherever router places it
• environment.specific: local/api-dev → route to specific named resource regardless of chain

---

Devcontainer Integration

Auto-discovered when a git-checkout or fs-directory resource contains a .devcontainer/ directory.

Lifecycle:

1. During auto-discovery: created in detected (not built) state
2. First time execution environment router selects it: built and started (lazy activation)
3. Remains available for subsequent plan executions until explicitly stopped or removed

Resource type: devcontainer-instance (inherits container-instance)

CLI:

# Devcontainer discovered automatically on git-checkout registration
agents resource add git-checkout local/my-repo --path /path/to/repo

# View discovered devcontainer
agents resource tree local/my-repo

# Stop the running container
agents resource stop local/my-repo-devcontainer

# Rebuild the container (e.g. after devcontainer.json changes)
agents resource rebuild local/my-repo-devcontainer

---

Working with Resources

# Register a git checkout (auto-discovers git + fs-directory children)
agents resource add git-checkout local/api-repo \
  --path /repos/api-service \
  --branch main

# Register a standalone directory
agents resource add fs-directory local/config-dir \
  --path /etc/myapp

# List all resources
agents resource list

# Filter by type
agents resource list --type git-checkout

# Explore resource structure
agents resource show local/api-repo
agents resource inspect local/api-repo
agents resource tree --depth 3 local/api-repo

# Inspect a specific file within a resource
agents resource inspect --file src/main.py local/api-repo

# Link a child resource to a parent
agents resource link-child local/api-repo local/some-subdir

# Remove a resource
agents resource remove local/api-repo

# Custom resource type
agents resource type add --config ./types/my-db-type.yaml
agents resource type list
agents resource type show local/my-db-type