docs(spec): add devcontainer integration and resource type inheritance #492

2026-03-01T19:33:34Z

freemo commented

2026-03-01 19:33:34 +00:00

Summary

Add comprehensive devcontainer support, resource type inheritance, and execution environment routing to the CleverAgents specification, expressed through two new ADRs and 20+ specification section updates.

Closes #491

New ADRs

ADR-042: Resource Type Inheritance — Single-inheritance inherits field enabling resource type subtypes with polymorphic tool binding, auto-discovery child matching, and DAG query matching. Max chain depth 5. Collection fields merge additively by default with explicit replace option.
ADR-043: Devcontainer Integration — devcontainer-instance subtype of container-instance with lazy activation (detected → building → running), devcontainer.json parsing, three container-project association patterns, and a 6-level execution environment routing precedence chain.

Specification Changes

Glossary: Added Resource Type Inheritance, Devcontainer, Execution Environment definitions
Resource type schema: Added inherits field to YAML schema and structure reference table
Tables: Updated handler, sandbox strategy, and coherence tables with devcontainer-instance entries
Auto-discovery: Added devcontainer detection subsection with WBS diagram showing lazy activation
Tool metadata: Expanded environment field from simple enum to structured required/preferred/specific
Technology stack: Added devcontainer CLI row
Project model: Added execution environment subsection with priority: fallback|override semantics
CLI agents resource add: Added --mount (resource ref + host path) and --clone-into flags with 4 new Rich/Plain examples (container-instance with mount, clone-into, git-checkout with devcontainer auto-detection)
CLI agents plan use: Added --execution-environment and --execution-env-priority flags
CLI agents project context set: Added same execution environment flags
Command synopsis: Updated top-level synopsis block for both commands
Execution model: New Execution Environment Routing section with 6-level precedence table and pseudocode routing algorithm
Resource type examples: Added Example 6 (Devcontainer Instance inherited type definition)
End-to-end examples: Added Examples 16 (Devcontainer-Driven Development), 17 (Explicit Container with Directory Mount), 18 (Container with Remote Repo Clone)

Ancillary Fixes

Added previously missing ADR-036 through ADR-040 to the ADR index
Updated next ADR number in index to 044
Added cross-references from ADR-039 to ADR-042 and ADR-043

## Summary Add comprehensive devcontainer support, resource type inheritance, and execution environment routing to the CleverAgents specification, expressed through two new ADRs and 20+ specification section updates. Closes #491 ### New ADRs - **ADR-042: Resource Type Inheritance** — Single-inheritance `inherits` field enabling resource type subtypes with polymorphic tool binding, auto-discovery child matching, and DAG query matching. Max chain depth 5. Collection fields merge additively by default with explicit replace option. - **ADR-043: Devcontainer Integration** — `devcontainer-instance` subtype of `container-instance` with lazy activation (detected → building → running), devcontainer.json parsing, three container-project association patterns, and a 6-level execution environment routing precedence chain. ### Specification Changes - **Glossary**: Added Resource Type Inheritance, Devcontainer, Execution Environment definitions - **Resource type schema**: Added `inherits` field to YAML schema and structure reference table - **Tables**: Updated handler, sandbox strategy, and coherence tables with `devcontainer-instance` entries - **Auto-discovery**: Added devcontainer detection subsection with WBS diagram showing lazy activation - **Tool metadata**: Expanded `environment` field from simple enum to structured `required/preferred/specific` - **Technology stack**: Added `devcontainer CLI` row - **Project model**: Added execution environment subsection with `priority: fallback|override` semantics - **CLI `agents resource add`**: Added `--mount` (resource ref + host path) and `--clone-into` flags with 4 new Rich/Plain examples (container-instance with mount, clone-into, git-checkout with devcontainer auto-detection) - **CLI `agents plan use`**: Added `--execution-environment` and `--execution-env-priority` flags - **CLI `agents project context set`**: Added same execution environment flags - **Command synopsis**: Updated top-level synopsis block for both commands - **Execution model**: New `Execution Environment Routing` section with 6-level precedence table and pseudocode routing algorithm - **Resource type examples**: Added Example 6 (Devcontainer Instance inherited type definition) - **End-to-end examples**: Added Examples 16 (Devcontainer-Driven Development), 17 (Explicit Container with Directory Mount), 18 (Container with Remote Repo Clone) ### Ancillary Fixes - Added previously missing ADR-036 through ADR-040 to the ADR index - Updated next ADR number in index to 044 - Added cross-references from ADR-039 to ADR-042 and ADR-043

freemo added the

Type

Task

label 2026-03-01 19:33:42 +00:00

freemo force-pushed docs/update-and-fix-container from 775cb949ec to 300c7cbc3f

2026-03-01 19:37:51 +00:00

Compare

freemo force-pushed docs/update-and-fix-container from 300c7cbc3f to 05310391c1

2026-03-01 20:04:14 +00:00

Compare

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-01 20:06:14 +00:00

freemo merged commit 05310391c1 into master

2026-03-01 20:53:28 +00:00

freemo deleted branch docs/update-and-fix-container

2026-03-01 20:53:28 +00:00

freemo added the

State

Completed

label 2026-03-04 00:41:46 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: cleveragents/cleveragents-core#492