Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
60 changes: 56 additions & 4 deletions agent-skills/skills/atmos-hooks/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: atmos-hooks
description: "Atmos hooks: lifecycle events, hook kinds, command/store/git/security hooks, step/steps hooks, when: conditions, scoping and overrides, toolchain integration, --skip-hooks, and Atmos Pro/local output"
description: "Atmos hooks: lifecycle events, hook kinds, command/store/git/security hooks, step/steps hooks, when: conditions, scoping and overrides, toolchain integration, --skip-hooks, docs generate hooks, and Atmos Pro/local output"
metadata:
copyright: Copyright Cloud Posse, LLC 2026
version: "1.0.0"
Expand All @@ -10,7 +10,8 @@ metadata:
# Atmos Hooks

Use this skill for lifecycle hooks that run before or after component operations,
or for generation hooks declared in a scaffold template.
for generation hooks declared in a scaffold template, or for repo-level hooks declared under
`docs.generate` in `atmos.yaml`.

Hooks can run scanners, policy checks, store writes, Git actions, custom commands, or other
toolchain-aware automation around Terraform, Helm, Kubernetes, and other component commands.
Expand Down Expand Up @@ -77,6 +78,9 @@ Scaffold templates use the separate `before.scaffold.generate` and
`after.scaffold.generate` events. They reuse the condition vocabulary but can run only
`kind: step` and `kind: steps`; do not configure stack-only kinds in `spec.hooks`.

Documentation generation uses `before.docs.generate` and `after.docs.generate`; see
[Repo-Level Hooks: docs generate](#repo-level-hooks-docs-generate).

Multi-component DAG runs (e.g. `--affected`, `--query`, or workflows that fan out across several
components) also fire aggregate events once for the whole run, in addition to the per-component
events fired for each individual component: `after.terraform.plan.aggregate`,
Expand Down Expand Up @@ -210,14 +214,62 @@ to opt back into running the hook in the directory Atmos was launched from. This
against the directory Atmos was launched from, so it keeps the ambient cwd unless
`working_directory:` is set explicitly.

## Repo-Level Hooks: docs generate

`atmos docs generate <type>` has no stack or component, so its hooks are declared in `atmos.yaml`
as a **map** of named hooks (not a list) under `docs.generate.<type>.hooks`. They use the same
kinds and fields as component hooks (`kind: command`/`step`/`steps`, `type`, `events`, `when`,
`on_failure`, `retry`, `with`, `env`). Hooks belong to one generator: hooks under `readme` do not
run for another type.

```yaml
docs:
generate:
readme:
input: ["./README.yaml"]
template: "./README.md.gotmpl"
output: "./README.md"
hooks:
publish-wiki:
kind: step
type: http
events: [after.docs.generate]
when: success
on_failure: fail
with:
url: "https://wiki.example.com/rest/api/content/123456"
method: PUT
headers:
Authorization: "Bearer {{ .env.WIKI_TOKEN }}"
expect:
status: [200]
```

- Publishing to a wiki or portal is a generic `http` step, or a `kind: command` hook that reads
`ATMOS_DOCS_OUTPUT_PATH`. Atmos has no wiki-specific integration.
- `events:` omitted means the hook fires on both events. Hooks run in name order, in the process working directory where `atmos docs generate` starts (or the `--chdir` target), not `base-dir`.
- A `before.docs.generate` hook with `on_failure: fail`, or a policy denial, aborts before any file
is written. With the default `on_failure: warn`, or with `ignore`, generation continues, so set
`on_failure: fail` on any hook that must block generation. `after.docs.generate` hooks run on
success and on failure, filtered by `when:` (default is success only; use `failure` or `always`
to react to failures). A failing after-hook fails the command only with `on_failure: fail`.
- Hook context: env vars `ATMOS_DOCS_TYPE`, `ATMOS_DOCS_OUTPUT_PATH`, `ATMOS_DOCS_BASE_DIR`, and
template values `{{ .docs.type }}`, `{{ .docs.output_path }}`, `{{ .docs.base_dir }}`. There is
no infrastructure component or stack: the stack is empty, and `ATMOS_COMPONENT` holds the
generator name (for example `readme`).
- `atmos docs generate --skip-hooks` skips all hooks, `--skip-hooks=name1,name2` skips named
hooks, and `ATMOS_SKIP_HOOKS` is honored.
- Governing policies with `on: operation` and `action: hooks` also apply; see
[atmos-policy](../atmos-policy/SKILL.md).

## Operational Guidance

- Use hooks for repeatable lifecycle behavior, not one-off local scripts.
- Scope hooks as narrowly as possible: component hooks for component-specific behavior, shared
mixins/defaults for organization-wide checks.
- Use `--skip-hooks` to bypass all hooks for a diagnostic run, or `--skip-hooks=name1,name2` to skip
specific hooks by name. This flag is registered on the `terraform` command only today; there is no
helmfile or packer equivalent yet.
specific hooks by name. This flag is registered on the `terraform` and `docs generate` commands
today; there is no helmfile or packer equivalent yet. `ATMOS_SKIP_HOOKS` sets it from the environment.
- Treat hook output as part of CI evidence. When Atmos Pro is connected and the hook kind supports
upload, prefer structured upload; otherwise rely on local/CI summaries.
- Keep destructive hooks opt-in and visible in stack config.
7 changes: 5 additions & 2 deletions agent-skills/skills/atmos-policy/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,11 @@ Distinguish input kind, component type, and CI provider:
successful plan, including no-change plans, and again before applying the evaluated private copy.
Implicit apply/deploy and direct destroy are rejected when plan policies are enabled.
- `operation`: lifecycle event, component type/name, stack, command, status, exit code, dry-run.
Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks. Do not claim
enforcement for Packer, Ansible, containers, emulators, or custom components yet.
Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks, plus
`atmos docs generate` (`before.docs.generate`/`after.docs.generate`): `component_type: docs`,
`command: generate`, `component` is the doc type (for example `readme`), and `stack` is empty.
`action: hooks` rules dispatch hooks there too. Do not claim enforcement for Packer, Ansible,
containers, emulators, or custom components yet.
- `plugin` (`on: plugin`): native plugin registries, packages, and local builds (`origin`, `path`, `profiles`, `operation`)
checked before install, activation, test, publish, and sign. See `atmos-plugins` for inputs and recipes.
- GitHub Actions context: `ci.provider == 'github-actions'`, `ci.schema == 'github-actions/v1'`.
Expand Down
2 changes: 1 addition & 1 deletion agent-skills/skills/atmos-settings/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Use this skill for global `atmos.yaml` options that are not owned by a narrower
| `logs` | Log level, log file path, log color, debug output behavior |
| `errors` | Error output formatting and error reporting options |
| `env` | Environment variables applied to Atmos operations |
| `docs` | Documentation generation defaults |
| `docs` | Documentation generation defaults, including `docs.generate.<type>.hooks` (`before.docs.generate`/`after.docs.generate`; see `atmos-hooks`) |
| `metadata` | Project-level metadata such as name, tags, and version |
| `version` | Minimum or maximum Atmos version constraints |

Expand Down
4 changes: 3 additions & 1 deletion cmd/command_discovery.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import (
"github.com/cloudposse/atmos/cmd/internal"
errUtils "github.com/cloudposse/atmos/errors"
tuiutils "github.com/cloudposse/atmos/internal/tui/utils"
"github.com/cloudposse/atmos/pkg/browser"
iolib "github.com/cloudposse/atmos/pkg/io"
"github.com/cloudposse/atmos/pkg/perf"
"github.com/cloudposse/atmos/pkg/reexec"
Expand All @@ -28,8 +29,9 @@ import (
)

// Dependencies are replaceable so discovery tests never open a browser, prompt,
// or fetch an example. The browser helper is shared with the existing docs command.
// or fetch an example.
var (
openDocsURL = func(url string) error { return browser.New().Open(url) }
discoverySelect = selectCommandExample
discoveryConfirm = confirmCommandExample
discoveryInit = initializeCommandExample
Expand Down
124 changes: 118 additions & 6 deletions cmd/docs.go → cmd/docs/docs.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
package cmd
package docs

import (
"fmt"
"os"
"path/filepath"
"strings"

"github.com/charmbracelet/glamour"
"github.com/charmbracelet/lipgloss"
Expand All @@ -12,17 +13,26 @@ import (
"golang.org/x/term"

"github.com/cloudposse/atmos/cmd/internal"
"github.com/cloudposse/atmos/internal/exec"
termUtils "github.com/cloudposse/atmos/internal/tui/templates/term"
"github.com/cloudposse/atmos/pkg/browser"
cfg "github.com/cloudposse/atmos/pkg/config"
"github.com/cloudposse/atmos/pkg/flags"
"github.com/cloudposse/atmos/pkg/flags/compat"
l "github.com/cloudposse/atmos/pkg/list"
log "github.com/cloudposse/atmos/pkg/logger"
"github.com/cloudposse/atmos/pkg/schema"
"github.com/cloudposse/atmos/pkg/ui"
"github.com/cloudposse/atmos/pkg/ui/markdown"
u "github.com/cloudposse/atmos/pkg/utils"
)

const atmosDocsURL = "https://atmos.tools"
const (
atmosDocsURL = "https://atmos.tools"

// Prefix of a long flag in shell completion input.
longFlagPrefix = "--"
)

var openDocsURL = func(url string) error {
return browser.New().Open(url)
Expand All @@ -36,7 +46,7 @@ var docsCmd = &cobra.Command{
Example: "atmos docs vpc",
Args: cobra.MaximumNArgs(1),
FParseErrWhitelist: struct{ UnknownFlags bool }{UnknownFlags: false},
ValidArgsFunction: ComponentsArgCompletion,
ValidArgsFunction: componentsArgCompletion,
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) == 1 {
info := schema.ConfigAndStacksInfo{
Expand Down Expand Up @@ -145,10 +155,112 @@ var docsCmd = &cobra.Command{
},
}

// componentsArgCompletion provides shell completion for the component positional argument.
// It mirrors the root command's component completion: directory completion for path-like input,
// otherwise component names from the stack configurations.
func componentsArgCompletion(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
if len(args) == 0 {
// Enable directory completion for paths (platform-specific separator and forward slash).
if toComplete == "." || strings.Contains(toComplete, string(filepath.Separator)) || strings.Contains(toComplete, "/") {
log.Trace("Enabling directory completion for path input", "toComplete", toComplete)
return nil, cobra.ShellCompDirectiveFilterDirs
}

// Otherwise, suggest component names from stack configurations.
output, err := listComponents(cmd)
if err != nil {
return nil, cobra.ShellCompDirectiveNoFileComp
}
return output, cobra.ShellCompDirectiveNoFileComp
}

flagName := args[len(args)-1]
if strings.HasPrefix(flagName, longFlagPrefix) {
flagName = strings.ReplaceAll(flagName, longFlagPrefix, "")
}
if strings.HasPrefix(toComplete, longFlagPrefix) {
flagName = strings.ReplaceAll(toComplete, longFlagPrefix, "")
}
flagName = strings.ReplaceAll(flagName, "=", "")
if option, ok := cmd.GetFlagCompletionFunc(flagName); ok {
return option(cmd, args, toComplete)
}
return nil, cobra.ShellCompDirectiveNoFileComp
}

// listComponents returns the component names found in the stack configurations,
// filtered by the --stack flag when the command defines one.
func listComponents(cmd *cobra.Command) ([]string, error) {
stackFlag, err := cmd.Flags().GetString("stack")
if err != nil {
stackFlag = ""
}

atmosConfig, err := cfg.InitCliConfig(schema.ConfigAndStacksInfo{}, true)
if err != nil {
return nil, fmt.Errorf("error initializing CLI config: %w", err)
}

stacksMap, err := exec.ExecuteDescribeStacks(&atmosConfig, "", nil, nil, nil, false, false, false, false, nil, nil)
if err != nil {
return nil, fmt.Errorf("error describing stacks: %w", err)
}

return l.FilterAndListComponents(stackFlag, stacksMap)
}

func init() {
RootCmd.AddCommand(docsCmd)
internal.RegisterCommandMetadata(
docsCmd,
// Register this command with the registry.
// This happens during package initialization via blank import in cmd/root.go.
internal.Register(
&DocsCommandProvider{},
internal.WithDocumentationURL("https://atmos.tools/cli/commands/docs/usage"),
)
}

// DocsCommandProvider implements the CommandProvider interface.
type DocsCommandProvider struct{}

// GetCommand returns the docs command.
func (d *DocsCommandProvider) GetCommand() *cobra.Command {
return docsCmd
}

// GetName returns the command name.
func (d *DocsCommandProvider) GetName() string {
return "docs"
}

// GetGroup returns the command group for help organization.
func (d *DocsCommandProvider) GetGroup() string {
return "Configuration Management"
}

// GetFlagsBuilder returns the flags builder for this command.
// The docs command has no flags of its own; docs generate registers its own via its parser.
func (d *DocsCommandProvider) GetFlagsBuilder() flags.Builder {
return nil
}

// GetPositionalArgsBuilder returns the positional args builder for this command.
// The docs command validates its optional component argument via cobra.MaximumNArgs(1).
func (d *DocsCommandProvider) GetPositionalArgsBuilder() *flags.PositionalArgsBuilder {
return nil
}

// GetCompatibilityFlags returns compatibility flags for this command.
// The docs command has no compatibility flags.
func (d *DocsCommandProvider) GetCompatibilityFlags() map[string]compat.CompatibilityFlag {
return nil
}

// GetAliases returns command aliases.
// The docs command has no aliases.
func (d *DocsCommandProvider) GetAliases() []internal.CommandAlias {
return nil
}

// IsExperimental returns whether this command is experimental.
func (d *DocsCommandProvider) IsExperimental() bool {
return false
}
75 changes: 75 additions & 0 deletions cmd/docs/docs_generate.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
package docs

import (
"github.com/spf13/cobra"
"github.com/spf13/viper"

"github.com/cloudposse/atmos/cmd/internal"
pkgdocs "github.com/cloudposse/atmos/pkg/docs"
"github.com/cloudposse/atmos/pkg/flags"
log "github.com/cloudposse/atmos/pkg/logger"
)

// skipHooksFlag is the flag (and Viper key suffix) that skips lifecycle hooks for one run.
const (
skipHooksFlag = "skip-hooks"
skipHooksViperPrefix = "docs_generate_flags"
)

// docsGenerateParser registers and binds the docs generate flags.
var docsGenerateParser = flags.NewStandardParser(
// Bare --skip-hooks skips all hooks; --skip-hooks=a,b skips the named hooks.
flags.WithStringFlag(skipHooksFlag, "", "", "Skip lifecycle hooks for this invocation. Use --skip-hooks (no value) to skip all, or --skip-hooks=name1,name2 to skip specific hooks by name"),
flags.WithNoOptDefVal(skipHooksFlag, "*"),
flags.WithEnvVars(skipHooksFlag, "ATMOS_SKIP_HOOKS"),
// The prefix avoids colliding with the docs.generate section of atmos.yaml in Viper.
flags.WithViperPrefix(skipHooksViperPrefix),
)

// applySkipHooksEnv resolves --skip-hooks precedence (flag, then ATMOS_SKIP_HOOKS) and records the
// result on the flag, which is where the hook engine reads it.
func applySkipHooksEnv(cmd *cobra.Command) error {
v := viper.GetViper()
if err := docsGenerateParser.BindFlagsToViper(cmd, v); err != nil {
return err
}
flag := cmd.Flags().Lookup(skipHooksFlag)
if flag == nil || flag.Changed {
return nil
}
if value := v.GetString(skipHooksViperPrefix + "." + skipHooksFlag); value != "" {
return cmd.Flags().Set(skipHooksFlag, value)
}
return nil
}

// docsGenerateCmd is the subcommand under docs that groups generation operations.
var docsGenerateCmd = &cobra.Command{
Use: "generate",
Short: "Generate documentation artifacts",
Long: `Generate documentation by merging YAML data sources and applying templates.
Supports native terraform-docs injection.`,
Example: `Generate the README.md in the current directory:
atmos docs generate readme`,
Args: cobra.ExactArgs(1),
ValidArgs: []string{"readme"},
RunE: func(cmd *cobra.Command, args []string) error {
// cobra.ExactArgs(1) already validates argument count.
if err := applySkipHooksEnv(cmd); err != nil {
return err
}
return pkgdocs.ExecuteGenerate(cmd, args)
},
}

func init() {
docsGenerateParser.RegisterFlags(docsGenerateCmd)
if err := docsGenerateParser.BindToViper(viper.GetViper()); err != nil {
log.Debug("Failed to bind docs generate flags to Viper", "error", err)
}
docsCmd.AddCommand(docsGenerateCmd)
internal.RegisterCommandMetadata(
docsGenerateCmd,
internal.WithDocumentationURL("https://atmos.tools/cli/commands/docs/generate"),
)
}
Loading
Loading