AI Agent Skill: docktree-init
Relevant source files
The following files were used as context for generating this wiki page:
The docktree-init skill is an agent-installable capability designed to automate the onboarding of repositories to the Docktree ecosystem. It facilitates the generation of a docktree.yml configuration file by scanning existing Docker Compose files, detecting shareable services (such as databases), and guiding the user through necessary configuration decisions. This skill bridges the gap between raw infrastructure definitions and Docktree's isolated worktree project management.
Sources: skills/docktree-init/SKILL.md:1-6, README.md:65-67
Core Initialization Logic
The initialization process is primarily driven by the docktree init command. It involves scanning the repository for docker-compose.yml files, identifying potential "shareable" services, and building a proposal for the docktree.yml configuration.
Scanning and Detection
The system identifies three main categories of project elements during the scan:
- Compose Files: Automatically locates valid Compose files within the repository root.
- Environment Files: Detects
.envfiles that are currently ignored by Git usinggit check-ignore. - Symlinkable Directories: Identifies common dependency or build directories like
node_modules,vendor, or.venv.
Sources: internal/cli/init.go:78-98, internal/cli/init.go:277-313
Shareable Service Analysis
A critical component of docktree-init is the detection of services that can be shared across worktrees (e.g., PostgreSQL, MySQL, MongoDB). The skill evaluates these candidates and generates "Todos" for the user to determine the appropriate tenancy model (full_share vs per_database).
Sources: internal/cli/init.go:207-227, internal/config/config.go:193-200
The diagram shows the logical flow from the initial repository scan to the final generation of the configuration file, highlighting the branch where user interaction is required for shared services.
Sources: skills/docktree-init/SKILL.md:11-53, internal/cli/init.go:68-129
Data Structures
The interaction between the CLI and the AI agent is governed by specific JSON structures designed for machine readability.
InitResult Structure
When run with the --json flag, the init command returns an InitResult containing path information and pending decisions.
| Field | Type | Description |
|---|---|---|
written | string | The file path where the proposed or final config was written. |
todos | []InitTodo | A list of decisions the agent must walk the user through. |
warnings | []InitWarning | Non-blocking concerns, such as the detection of secrets wrappers. |
Sources: internal/cli/types.go:217-227
InitTodo Details
Each InitTodo represents a specific configuration point that requires human input.
| Field | Type | Description |
|---|---|---|
path | string | The YAML path in the config (e.g., shared.services.db.tenancy). |
question | string | A human-readable prompt for the user. |
kind | string | Data type: enum (selection) or string_list (array of strings). |
options | []string | Valid choices for enum types or suggested values for string_list. |
Sources: internal/cli/types.go:209-215
Operational Workflow for Agents
Agents are instructed to follow a strict 5-step procedure to ensure configuration accuracy and validity.
1. Initial Scan
The agent must execute docktree init --json --dry-run to retrieve the list of todos and warnings without modifying the filesystem.
Sources: skills/docktree-init/SKILL.md:13-15
2. User Consultation
For each item in todos, the agent asks exactly one question.
- Enums: Present the list and ask for a selection.
- String Lists: Show detected values (like environment variables) and ask for confirmation or modification.
Sources: skills/docktree-init/SKILL.md:31-41
3. Application of Decisions
Once all answers are collected, the agent pipes a JSON object of answers to the CLI using the --apply flag.
Sources: skills/docktree-init/SKILL.md:47-53
This sequence diagram illustrates the interactive loop between the Agent, the CLI, and the User to resolve configuration decisions.
Sources: skills/docktree-init/SKILL.md:11-60
Configuration Validation
The final step in the skill procedure is validating the generated docktree.yml. The agent runs docktree --json prepare --dry-run to ensure the configuration is syntactically correct and compatible with the project environment.
Sources: skills/docktree-init/SKILL.md:55-60, internal/cli/help_doc.go:198-206
Detected Secrets Wrappers
The initialization logic includes a specific check for "secrets wrappers" (e.g., Infisical, Doppler, Vault). If a service command contains these keywords, the system issues an InitWarning because Docktree may be unable to see or rewrite environment variables injected by these wrappers.
Sources: internal/cli/init.go:318-340, README.md:88-92
Command Reference
| Flag | Description |
|---|---|
--dry-run | Prints the proposed configuration to stdout without writing files. |
--force | Overwrites an existing docktree.yml (default behavior writes .proposed). |
--apply | Reads JSON answers from stdin to generate the final config. |
--json | Global flag to output machine-readable data structures. |
Sources: internal/cli/init.go:346-351, internal/cli/help_doc.go:136-138
The docktree-init skill ensures that repositories are onboarded with minimal friction, offloading the complexity of detecting shared resources and project structure to the CLI while maintaining human control over critical isolation decisions.