feat(init): onboard CLI agent tooling - #169
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📝 WalkthroughWalkthroughThe change adds independent Subagents and Dynamic Workflows configuration, managed CLI skill installation, expanded diagnostics, and CLI-only workflow execution guidance. Documentation updates describe provider discovery, profile filtering, capability-specific skills, and shell-based workflow invocation. ChangesConfiguration and managed skills
CLI integration
CLI workflow contract
Capability and profile documentation
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Operator
participant DevSpaceCLI
participant Config
participant SkillInstaller
participant WorkflowCLI
Operator->>DevSpaceCLI: enable Subagents or Dynamic Workflows
DevSpaceCLI->>Config: resolve persisted and environment settings
DevSpaceCLI->>SkillInstaller: install enabled managed skills
Operator->>WorkflowCLI: run or list workflow
WorkflowCLI-->>Operator: return CLI workflow output and status
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThe PR adds independent onboarding controls for CLI Subagents and Dynamic Workflows and installs enabled bundled skills into the user configuration directory. It also persists the workflow flag and updates the related documentation and tests.
Confidence Score: 4/5The skill installer’s failed-copy recovery should be fixed before merging because a transient filesystem error can leave onboarding permanently unable to repair the managed skill. The installer writes its ownership marker only after copying, yet treats any existing unmarked directory as user-owned, so a partial first copy becomes unrecoverable; managed updates also merge rather than synchronize directory contents. Files Needing Attention: src/skill-installer.ts
|
| Filename | Overview |
|---|---|
| src/skill-installer.ts | Adds managed skill copying, but interrupted copies cannot be repaired automatically and overlay updates retain removed files. |
| src/cli.ts | Adds separate onboarding prompts, persists both capability choices, and installs enabled skills after writing configuration. |
| src/user-config.ts | Adds a backward-compatible workflow flag resolver that honors environment overrides. |
| src/config.ts | Uses the shared workflow flag resolver when constructing runtime configuration. |
| src/skill-installer.test.ts | Covers install, update, and preservation behavior but not interrupted-copy recovery or stale-file cleanup. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[devspace init] --> B[Prompt for Subagents]
B --> C[Prompt for Dynamic Workflows]
C --> D[Write config and auth]
D --> E[Install enabled managed skills]
E --> F{Destination exists?}
F -- No --> G[Copy bundled skill]
F -- Yes, managed --> G
F -- Yes, unmarked --> H[Preserve user directory]
G --> I[Write managed marker]
I --> J[Setup complete]
Reviews (1): Last reviewed commit: "docs: document CLI-only agent workflows" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| await cp(source, destination, { recursive: true, force: true }); | ||
| await writeFile(marker, "Managed by DevSpace.\n", { encoding: "utf8", mode: 0o600 }); |
There was a problem hiding this comment.
When the initial cp fails after creating or partially populating the destination, the marker is never written, so the next initialization treats the partial directory as user-owned and preserves it instead of repairing the skill. This leaves onboarding permanently unable to complete without manually deleting the directory.
| return { name, status: "preserved", path: destination }; | ||
| } | ||
|
|
||
| await cp(source, destination, { recursive: true, force: true }); |
There was a problem hiding this comment.
Recursive cp overlays an existing managed skill without removing files absent from the new bundle. When a bundled reference is removed or renamed in a later release, its obsolete installed copy remains readable and can provide outdated or conflicting instructions.
ef3fba7 to
d8b457f
Compare
d8b457f to
76495f9
Compare
|
|
|
@coderabbitai full review |
✅ Action performedFull review finished. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/chatgpt-coding-workflow.md`:
- Around line 128-132: Update the workflow documentation around the DevSpace CLI
guidance to distinguish tool usage by mode: instruct standard modes and MCP
hosts to invoke commands with bash, while instructing codex mode users to use
exec_command because bash is hidden there. Keep the existing CLI and
skill-availability explanation intact.
In `@docs/configuration.md`:
- Around line 108-137: Update the DEVSPACE_WIDGETS=full documentation near the
workflow widget description to remove references to attaching UI to workflow
execution tools and live workflow dashboards. Ensure the description matches the
current MCP tool surface, which does not expose separate workflow execution
tools, while preserving any still-supported widget behavior.
In `@docs/dynamic-workflow/devspace/primitives-spec.md`:
- Around line 241-242: Remove the `--script-path` entry from the file-source
table in the workflow primitives specification, since the documented `workflow
run` contract only supports `--file`, `--name`, and `--resume`; do not add an
implementation unless the CLI contract, help output, parser, tests, and tool
surfaces are updated consistently.
In `@docs/setup.md`:
- Around line 25-28: Update the setup-flow documentation near the CLI Subagents
and Dynamic Workflows prompts to qualify skill installation: state that enabled
skills are copied only when the destination is new or previously marked as
DevSpace-managed, while preserving user-owned skill directories with the same
name.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 043b99a6-6f6d-4d01-b0ed-34ea76c7d158
📒 Files selected for processing (15)
docs/agent-profile-schema.mddocs/chatgpt-coding-workflow.mddocs/configuration.mddocs/dynamic-workflow/devspace/plan.mddocs/dynamic-workflow/devspace/primitives-spec.mddocs/gotchas.mddocs/setup.mdpackage.jsonsrc/cli.tssrc/config.test.tssrc/config.tssrc/server.tssrc/skill-installer.test.tssrc/skill-installer.tssrc/user-config.ts
| Subagents and Dynamic Workflows execute through the DevSpace CLI. The bundled | ||
| skills installed by `devspace init` describe the commands and are available to | ||
| ChatGPT, Claude, and coding harnesses that can run shell commands. MCP does not | ||
| register separate agent or workflow execution tools; use its ordinary `bash` | ||
| tool when the host needs to invoke a CLI command. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the shell tool for codex mode.
The text requires the ordinary bash tool, but Lines 159-162 state that codex mode hides bash and exposes exec_command. Tell users to use bash in the standard modes and exec_command in codex mode.
As per coding guidelines: “Verify the actual user-consumption path, including ... real MCP hosts ... tool surfaces, widgets, and rendered artifacts.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/chatgpt-coding-workflow.md` around lines 128 - 132, Update the workflow
documentation around the DevSpace CLI guidance to distinguish tool usage by
mode: instruct standard modes and MCP hosts to invoke commands with bash, while
instructing codex mode users to use exec_command because bash is hidden there.
Keep the existing CLI and skill-availability explanation intact.
Source: Coding guidelines
| - the bundled `subagents` skill when the Subagents capability is enabled | ||
| - the bundled `dynamic-workflows` skill when the Dynamic Workflows capability is enabled | ||
| - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills` | ||
| - additional paths from `DEVSPACE_SKILL_PATHS` | ||
|
|
||
| User and project skills with the same name take precedence over bundled skills. | ||
| DevSpace does not copy bundled skills into `~/.devspace/skills` during setup. | ||
| `devspace init` asks about Subagents and Dynamic Workflows separately and | ||
| installs enabled skills into `~/.devspace/skills` (or the configured | ||
| `DEVSPACE_CONFIG_DIR/skills`). A user-owned directory is preserved; only a | ||
| directory previously marked as DevSpace-managed is updated. | ||
|
|
||
| When Subagents are enabled, DevSpace discovers agent profiles | ||
| When Subagents or Dynamic Workflows are enabled, DevSpace discovers agent profiles | ||
| from: | ||
|
|
||
| - `~/.devspace/agents/*.md` | ||
| - project `.devspace/agents/*.md` | ||
|
|
||
| `open_workspace` returns a compact catalog containing profile names, | ||
| descriptions, providers, and optional models/effort levels so the host model can choose an | ||
| agent without reading provider-specific launch details. `devspace agents ls` | ||
| descriptions, and optional model/effort defaults so the host model can choose an | ||
| agent without reading provider-specific launch details. Provider entries contain | ||
| only their names. `devspace agents ls` | ||
| lists existing subagent sessions for the current workspace, scoped by the | ||
| workspace environment injected into shell commands. The `subagents` | ||
| skill teaches the model to discover targets with `devspace agents targets`, | ||
| then use the minimal `devspace agents run`, `devspace agents show`, and | ||
| `devspace agents ls` workflow. | ||
|
|
||
| Provider availability is detected at runtime. DevSpace does not persist probe | ||
| timestamps, availability snapshots, or an experimental provider enable-list in | ||
| `config.json`. Final provider policy and onboarding are deferred until the | ||
| Subagents and Dynamic Workflows features are finalized. | ||
| Provider availability is detected at runtime. Unavailable providers and profiles | ||
| that depend on them are omitted from `open_workspace` and `devspace agents | ||
| targets`. The enabled feature switches are persisted in `config.json`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove the stale workflow-widget contract.
The current documentation says that MCP does not expose separate workflow execution tools, but Line 86 still says that DEVSPACE_WIDGETS=full attaches UI to workflow tools and live workflow dashboards. Update that widget description so users do not expect tools that are no longer registered.
As per coding guidelines: “Verify the actual user-consumption path, including ... tool surfaces, widgets, and rendered artifacts.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/configuration.md` around lines 108 - 137, Update the
DEVSPACE_WIDGETS=full documentation near the workflow widget description to
remove references to attaching UI to workflow execution tools and live workflow
dashboards. Ensure the description matches the current MCP tool surface, which
does not expose separate workflow execution tools, while preserving any
still-supported widget behavior.
Source: Coding guidelines
| | File (`--file` / `--script-path`) | Persist to `<stateDir>/workflows/runs/<runId>.js` | | ||
| | Named (`--name`) | (1) `<workspace>/.devspace/workflows/<name>.js` (2) `~/.devspace/workflows/<name>.js` | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Remove or implement --script-path.
Section 4.1 defines workflow run with --file, --name, and --resume only. This table tells users that --script-path is valid. Remove --script-path here, or add the flag to the CLI contract, help output, parser, and tests.
As per coding guidelines, verify the actual user-consumption path, including tool surfaces.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/dynamic-workflow/devspace/primitives-spec.md` around lines 241 - 242,
Remove the `--script-path` entry from the file-source table in the workflow
primitives specification, since the documented `workflow run` contract only
supports `--file`, `--name`, and `--resume`; do not add an implementation unless
the CLI contract, help output, parser, tests, and tool surfaces are updated
consistently.
Source: Coding guidelines
| The setup flow asks one question at a time, including separate prompts for CLI | ||
| Subagents and Dynamic Workflows. Enabled skills are copied to | ||
| `~/.devspace/skills` (or the configured `DEVSPACE_CONFIG_DIR/skills`) so coding | ||
| harnesses can use them through their shell tools. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Qualify the skill installation statement.
The setup flow preserves user-owned skill directories with the same name and updates only directories previously marked as DevSpace-managed. Replace “Enabled skills are copied” with wording that states this behavior explicitly.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/setup.md` around lines 25 - 28, Update the setup-flow documentation near
the CLI Subagents and Dynamic Workflows prompts to qualify skill installation:
state that enabled skills are copied only when the destination is new or
previously marked as DevSpace-managed, while preserving user-owned skill
directories with the same name.
|
Closing in favor of #144. The Sol implementation is more complete architecturally: remote MCP is optional, provider selection is explicit, and managed skill installation uses replacement/rollback semantics rather than an overlay copy. Review also found lifecycle issues here around partial installs and stale files that the replacement avoids. |
1 participant
Users should be able to enable the two CLI capabilities without hand-installing guidance. Setup now asks separately about Subagents and Dynamic Workflows, persists both switches, and installs enabled skills into ~/.devspace/skills (or the configured DevSpace directory). DevSpace-managed copies can be updated while user-owned skill directories are preserved; the documentation describes the CLI-only contract and compact workspace response.
Summary by CodeRabbit
New Features
Documentation
Tests