Train plugin API knowledge base & v2 separation-of-concerns analysis

[clintoncwolfe]

Reference/design docs (with rendered UML/architecture diagrams) analyzing how Train's transport & plugin system works and is consumed across the ecosystem, as groundwork for a Train Plugin API v2.

• context/local/design/plugins-v1.md — factual reference for the current (V1) Train plugin API: anatomy, registration/loading, transport & connection classes, data contracts, options/URIs/credentials, runtime flow, testing, and real-world transport variances.
• context/local/design/plugins-v2-separation-of-concerns.md — inventory of ~29 areas of concern across four actors (Core / Transport / Client / Ecosystem), each as current locus → tension → recommended v2 locus, plus cross-cutting meta-problems and open questions.
• context/local/integrations/inspec.md — critical assessment of InSpec's usage of Train (backend construction, target/credential resolution, resource→primitive dispatch, the two plugin systems, mock-as-core).
• context/local/integrations/chef-infra-client-agentless.md — how Chef Infra Client "Target Mode" (Agentless) relies on Train.
• Diagrams authored in PlantUML (img/src/*.puml) and rendered to PNG under each img/ dir.
• Dev-environment scaffolding: start-development/search-context skills, reference-repo list, bundle-install wrapper.

Docs only — no changes to Train library code.

[Copilot]

Pull request overview

Adds a local documentation “knowledge base” describing Train’s current (v1) plugin/transport API and an initial separation-of-concerns inventory to inform a future plugin API v2, plus supporting UML diagrams and minimal dev-environment scaffolding (reference repo list, env defaults, bundler wrapper, skills, MCP config).

Changes:

• Add design/reference docs for Train plugin API v1 and a v2 separation-of-concerns analysis, plus ecosystem integration studies (InSpec, Chef Target Mode).
• Add PlantUML diagram sources and rendered PNGs to support the docs.
• Add dev scaffolding for AI-assisted work (skills docs, reference repo list, env defaults, bundler wrapper, MCP server config) and ignore local clones/artifacts in .gitignore.

Reviewed changes

Copilot reviewed 23 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
etc/reference-repo-list.txt	Lists external reference repos to clone into context/reference-repos for research.
etc/env.default.sh	Default environment variables for shared context repo selection and Chef license acceptance.
context/local/integrations/inspec.md	Integration study documenting how InSpec consumes Train primitives and plugin system.
context/local/integrations/chef-infra-client-agentless.md	Integration study documenting Chef Infra Client Target Mode’s reliance on Train.
context/local/integrations/img/src/agentless-architecture.puml	Diagram source for Chef Target Mode architecture over Train.
context/local/integrations/img/src/agentless-connection-sequence.puml	Diagram source for Chef Target Mode connection/setup sequence.
context/local/integrations/img/src/targetio-dispatch.puml	Diagram source for TargetIO shim dispatch and Train primitives.
context/local/integrations/img/src/inspec-train-architecture.puml	Diagram source for InSpec-over-Train architecture and plugin boundary.
context/local/integrations/img/src/inspec-train-connect-sequence.puml	Diagram source for InSpec target resolution/backend construction flow.
context/local/integrations/img/src/inspec-train-resource-dispatch.puml	Diagram source for InSpec resource-to-Train primitive dispatch.
context/local/integrations/img/agentless-architecture.png	Rendered diagram image used by the Chef integration doc.
context/local/integrations/img/agentless-connection-sequence.png	Rendered diagram image used by the Chef integration doc.
context/local/integrations/img/targetio-dispatch.png	Rendered diagram image used by the Chef integration doc.
context/local/integrations/img/inspec-train-architecture.png	Rendered diagram image used by the InSpec integration doc.
context/local/integrations/img/inspec-train-connect-sequence.png	Rendered diagram image used by the InSpec integration doc.
context/local/integrations/img/inspec-train-resource-dispatch.png	Rendered diagram image used by the InSpec integration doc.
context/local/design/plugins-v1.md	Factual reference for Train’s current (v1) plugin API, grounded in repo evidence.
context/local/design/plugins-v2-separation-of-concerns.md	Separation-of-concerns inventory and recommended ownership shifts for v2.
context/local/design/img/src/architecture.puml	Diagram source for v1 component architecture.
context/local/design/img/src/class-diagram.puml	Diagram source for v1 class model.
context/local/design/img/src/sequence-load-connect.puml	Diagram source for v1 load/connect lifecycle.
context/local/design/img/src/sequence-run-command.puml	Diagram source for v1 run_command/file runtime flow.
context/local/design/img/src/archetypes.puml	Diagram source comparing real-world transport archetypes.
context/local/design/img/src/v2-actor-boundaries.puml	Diagram source for actor boundaries and contract seams in v2 framing.
context/local/design/img/src/v2-locus-shift.puml	Diagram source for recommended responsibility shifts (v1 → v2).
context/local/design/img/*.png	Rendered diagram images used by the design docs.
.github/skills/start-development/SKILL.md	Adds the start-development skill documentation.
.github/skills/search-context/SKILL.md	Adds the search-context skill documentation.
.github/scripts/bundle-install.sh	Adds a wrapper for bundle install that clears problematic VS Code git env overrides.
.vscode/mcp.json	Adds Atlassian MCP server configuration for VS Code.
.gitignore	Ignores local env and cloned context/reference directories created by the scaffolding.

Suppressed comments (1)

.github/skills/search-context/SKILL.md:69

• Typo: "brough" should be "brought".

3. Any confusion or unresolved issues should be brough to the user's attention for a decision.