Skip to content

docs(project): add operational playbooks to stackctl CLI skill #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wax911 merged 1 commit into from
Jul 30, 2026
Merged

docs(project): add operational playbooks to stackctl CLI skill #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions skills/stackctl-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: stackctl-cli
description: Use this skill when helping agents answer stackctl CLI usage questions, choose source-valid stackctl commands, or avoid stale documented examples.
description: Use this skill when a task involves the stackctl CLI, including managing Docker Swarm stacks, choosing source-valid commands, running operational workflows, answering usage questions, or avoiding stale documented examples.
---

# stackctl CLI
Expand Down Expand Up @@ -37,5 +37,28 @@ command behavior, flags, examples, or agent-facing guidance.
- Env files: `env list`, `create`, `diff`, `materialize`, `audit`.
- Shell integration: `completions`.

For full command facts, read `references/commands.md`. For source hierarchy, runtime facts, and
known stale docs, read `references/truth-model.md`.
## Operational model

stackctl manages Docker Swarm stacks through a four-stage pipeline: discover Compose files, generate
canonical stack YAML, render `${VAR}` placeholders, and deploy via `docker stack deploy`. Different
commands run different stages:

- `up` runs all four stages in memory and deploys from a temp file.
- `reload` runs all four stages, writes to disk, and deploys without teardown.
- `generate` and `render` run early stages without deploying.
- `sync` validates drift by comparing in-memory generation to committed files.
- `plan <operation>` previews any operation without executing.

## Task playbooks

For task-oriented workflows (deploy, update, drift check, teardown, secrets, env scaffolding,
diagnostics, previewing), read `references/playbooks.md`. It provides command chains, prerequisites,
output interpretation, exit code guidance, and a decision tree mapping agent intents to commands.

## References

- `references/commands.md`: Full command, subcommand, option, argument, and caveat reference tables.
- `references/playbooks.md`: Task-oriented operational workflows, decision tree, and exit code
interpretation.
- `references/truth-model.md`: Source hierarchy, runtime facts, config resolution, exit codes, and
anti-hallucination controls.
Loading