docs(skills): teach CLI agent orchestration #168
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,167 +1,108 @@ | ||
| --- | ||
| name: dynamic-workflows | ||
| description: Run programmable multi-agent workflows through the DevSpace CLI. | ||
| --- | ||
|
|
||
| # DevSpace Dynamic Workflows | ||
|
|
||
| Use a workflow when the work benefits from a repeatable program: parallel | ||
| reviews, fan-out research, staged implementation, per-file pipelines, or a | ||
| review-and-fix loop. Use a direct subagent for one focused delegation. | ||
|
|
||
| This skill is CLI-only. A coding harness should create or select a workflow | ||
| script and invoke it with `devspace workflow`. | ||
|
|
||
| ## CLI | ||
|
|
||
| ```bash | ||
| devspace workflow run --file path/to/workflow.js [--arg key=value]... [--follow] | ||
| devspace workflow run --script-path path/to/workflow.js [--resume <run-id>] [--follow] | ||
| devspace workflow run --name <name> [--arg key=value]... [--follow] | ||
| devspace workflow status <run-id> [--follow] | ||
| devspace workflow cancel <run-id> | ||
| devspace workflow ls | ||
| devspace workflow calls <run-id> | ||
| devspace workflow call <run-id> <call-index> | ||
| ``` | ||
|
|
||
| Named scripts are stored in the project’s `.devspace/workflows/` directory. | ||
| Workflow commands are scoped to the current Git checkout (or the current | ||
| directory when it is not a Git project). Use `--follow` for a live terminal | ||
| handoff; otherwise poll with `status`. | ||
|
|
||
| `--arg key=value` passes JSON values when the value is valid JSON and otherwise | ||
| passes a string. A failed or cancelled run can be started again with | ||
| `workflow run --resume <run-id>` after reviewing its status and call results. | ||
|
|
||
| ## Script capabilities | ||
|
|
||
| Workflow scripts are JavaScript modules with a metadata export and an async | ||
| body. The orchestration API includes: | ||
|
|
||
| | Capability | Use | | ||
| | --- | --- | | ||
| | `agent(prompt, options?)` | Ask one configured profile or provider to perform a unit of work. | | ||
| | `parallel(thunks)` | Run independent units together and collect their results. | | ||
| | `pipeline(items, ...stages)` | Apply the same sequence of agent stages to each item. | | ||
| | `phase(title)` | Group later work under a named stage. | | ||
| | `log(message)` | Emit progress text for the supervising harness. | | ||
| | `args` | Read values passed with `--arg`. | | ||
| | `workflow(nameOrPath, args?)` | Compose a named or project workflow as a step. | | ||
|
|
||
| An `agent` can select `profile` or `provider`, and can set `label`, `phase`, | ||
| `schema`, `model`, `effort`, or `isolation: 'worktree'`. Use a profile when one | ||
| is configured; use `provider` only when the target is intentional. `profile` | ||
| and `provider` are alternatives, not a combination. | ||
|
|
||
| The optional `schema` describes a JSON result, which is useful when later | ||
| stages consume structured findings. Prompts should say whether a child may | ||
| change files and what it should return. | ||
|
|
||
| ## Basic script | ||
|
|
||
| ```js | ||
| export const meta = { | ||
| name: 'review-changes', | ||
| description: 'Independent correctness and security review', | ||
| } | ||
|
|
||
| phase('Review') | ||
| const [correctness, security] = await parallel([ | ||
| () => agent('Review the diff for correctness bugs. Return file paths and concrete findings.', { label: 'correctness' }), | ||
| () => agent('Review the diff for security issues. Return file paths, severity, and evidence.', { label: 'security' }), | ||
| ]) | ||
|
|
||
| return { correctness, security } | ||
| ``` | ||
|
|
||
| Run it with: | ||
|
|
||
| ```bash | ||
| devspace workflow run --file .devspace/workflows/review-changes.js --follow | ||
| ``` | ||
|
|
||
| ## Structured pipeline | ||
|
|
||
| ```js | ||
| export const meta = { name: 'test-plan', description: 'Find and prioritize test gaps' } | ||
|
|
||
| return await pipeline( | ||
| args.files, | ||
| (file) => agent(`Find test gaps in ${file}`, { | ||
| schema: { | ||
| type: 'object', | ||
| properties: { gaps: { type: 'array', items: { type: 'string' } } }, | ||
| required: ['gaps'], | ||
| }, | ||
| }), | ||
| (findings, file) => agent(`Prioritize these gaps for ${file}: ${JSON.stringify(findings)}`), | ||
| ) | ||
| ``` | ||
|
|
||
| ```bash | ||
| devspace workflow run --name test-plan --arg files='["src/parser.ts","src/parser.test.ts"]' --follow | ||
| ``` | ||
|
|
||
| For parallel writers, request `isolation: 'worktree'` and make the prompt | ||
| describe how the result should be handed back. For sequential edits that must | ||
| see one another’s files, keep the stages in a pipeline or ordinary sequence. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,87 @@ | ||
| --- | ||
| name: subagents | ||
| description: Delegate focused coding work to DevSpace subagents from a shell. | ||
| --- | ||
|
|
||
| # DevSpace subagents | ||
|
|
||
| Use a subagent for one focused piece of work: a second opinion, a narrow | ||
| investigation, a test plan, or an isolated implementation. Use a dynamic | ||
| workflow when the task needs several stages or programmable fan-out. | ||
|
|
||
| This skill uses the DevSpace CLI from any coding harness that can run shell | ||
| commands. | ||
|
|
||
| ## Discover available targets | ||
|
|
||
| Run this before choosing a profile or provider when the available targets are | ||
| not already known: | ||
|
|
||
| ```bash | ||
| devspace agents targets | ||
| devspace agents targets --json | ||
| ``` | ||
|
|
||
| Configured profiles are preferred because they provide a reusable description | ||
| and defaults. A raw provider is useful when the user names a specific harness | ||
| or no matching profile exists. Do not guess a profile name. | ||
|
|
||
| ## Start and inspect work | ||
|
|
||
| ```bash | ||
| devspace agents run <profile-or-provider> "<self-contained brief>" | ||
| devspace agents show <agent-id> | ||
| devspace agents ls | ||
| ``` | ||
|
|
||
| The `run` command returns an agent id immediately. Use `show` to wait for the | ||
| final response or to read a later update. `ls` lists sessions for the current | ||
| project scope. Running the command from a subdirectory uses the enclosing Git | ||
| checkout; a non-Git directory uses the current directory. | ||
|
|
||
| To continue the same session, use its id as the target: | ||
|
|
||
| ```bash | ||
| devspace agents run <agent-id> "Follow up by checking the failing test and report the cause." | ||
| ``` | ||
|
|
||
| ## Write a useful brief | ||
|
|
||
| Give the child everything it needs without relying on the parent conversation: | ||
|
|
||
| - the exact goal and expected output; | ||
| - relevant files, commands, or boundaries; | ||
| - whether it may modify files; | ||
| - the checks it should run before reporting back. | ||
|
|
||
| The child’s final response is the handoff. Ask for concise findings, paths, or | ||
| patch-ready changes rather than a broad narrative. | ||
|
|
||
| ## Optional model controls | ||
|
|
||
| Profiles normally supply model and effort defaults. When an exact override is | ||
| needed, pass: | ||
|
|
||
| ```bash | ||
| devspace agents run <target> --model <model> --effort <level> "<brief>" | ||
| ``` | ||
|
|
||
| Only use values supplied by the user, a configured profile, or the target | ||
| catalog. Omit overrides when the provider’s accepted values are unknown. | ||
|
|
||
| ## Common uses | ||
|
|
||
| ```bash | ||
| # Ask for an independent security review. | ||
| devspace agents run reviewer "Review the authentication changes for vulnerabilities. Return findings with file paths and severity." | ||
|
|
||
| # Delegate a small implementation and ask for verification. | ||
| devspace agents run implementer "Add a regression test for the parser bug. Run the focused test and report the result." | ||
|
|
||
| # Continue after the parent has inspected the first response. | ||
| devspace agents run agt_1234abcd "The test still fails on Windows. Investigate only the path handling and report a fix." | ||
| ``` | ||
|
Comment on lines
+74
to
+83
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
rg -n -C 3 \
'reviewer|implementer|default.*profile|profiles' \
--glob '*.json' --glob '*.yaml' --glob '*.yml' --glob '*.md' .Repository: Waishnav/devspace Length of output: 22297 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
printf '--- focused search for reviewer/implementer in src ---\n'
rg -n '\'?reviewer\'?|\'?implementer\'?|DEVSPACE_AGENT|agent profile|agents run|targets' src docs tools bin scripts --glob '*.ts' --glob '*.js' --glob '*.mjs' --glob '*.cjs' --glob '*.json' || true
printf '\n--- package scripts/package manager files ---\n'
cat package.json | sed -n '1,80p'
git ls-files | sed -n '1,120p'
printf '\n--- subagent skill relevant lines ---\n'
cat -n skills/subagents/SKILL.md | sed -n '1,110p'Repository: Waishnav/devspace Length of output: 246 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- focused search for reviewer/implementer in src ---'
rg -- \
'\'?reviewer\'?|\'?implementer\'?|DEVSPACE_AGEN|agent profile|agents run|targets' \
src docs tools bin scripts --glob '*.ts' --glob '*.js' --glob '*.mjs' --glob '*.cjs' --glob '*.json' || true
printf '%s\n' ''
printf '%s\n' '--- package scripts/package manager files ---'
sed -n '1,80p' package.json
git ls-files | sed -n '1,160p'
printf '%s\n' ''
printf '%s\n' '--- subagent skill relevant lines ---'
cat -n skills/subagents/SKILL.md | sed -n '1,110p'Repository: Waishnav/devspace Length of output: 271 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- focused search for reviewer/implementer in src ---'
rg -n -S -- \
"reviewer|implementer|DEVSPACE_AGEN|agent profile|agents run|targets" \
src docs tools bin scripts --glob '*.ts' --glob '*.js' --glob '*.mjs' --glob '*.cjs' --glob '*.json' || true
printf '%s\n' ''
printf '%s\n' '--- package scripts/package manager files ---'
sed -n '1,80p' package.json
git ls-files | sed -n '1,160p'
printf '%s\n' ''
printf '%s\n' '--- subagent skill relevant lines ---'
cat -n skills/subagents/SKILL.md | sed -n '1,110p'Repository: Waishnav/devspace Length of output: 27538 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- example agent profiles ---'
for f in examples/agents/*.md; do
echo "--- $f"
sed -n '1,8p' "$f"
done
printf '%s\n' ''
printf '%s\n' '--- subagent skill reference files names only ---'
git ls-files 'skills/subagents/references/*.md'
printf '%s\n' ''
printf '%s\n' '--- source resolution for unknown subagent ---'
sed -n '55,85p' src/local-agent-resolution.tsRepository: Waishnav/devspace Length of output: 3746 Use configured profile names in copy-paste examples.
🤖 Prompt for AI Agents |
||
|
|
||
| Keep direct delegation to one focused child at a time. For independent | ||
| reviewers, staged implementation, or repeatable fan-out, use the | ||
| `dynamic-workflows` skill. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,9 @@ | ||
| # Claude target options | ||
|
|
||
| Use the configured profile defaults whenever possible. Model and effort values | ||
| are installation- and model-dependent; pass an override only when the user or | ||
| the target catalog provides the exact value. | ||
|
|
||
| ```bash | ||
| devspace agents run claude --model <known-model> --effort <known-effort> "<brief>" | ||
| ``` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: Waishnav/devspace
Length of output: 50374
🏁 Script executed:
Repository: Waishnav/devspace
Length of output: 47212
Document how dirty worktrees exit the workflow.
isolation: 'worktree'creates a detached worktree, and DevSpace only returns the worktree path without merging changes into the parent checkout. Tell workflows to return the worktree path and handle checkout merging/error handling at the call site.🤖 Prompt for AI Agents
Source: Coding guidelines