sorrel/docs/workflows

Workflows, Vault, Slices

Execution and context: portable job bundles that travel with the work, secrets that exist only as references, and slice manifests that give an agent exactly the files it needs — all gated by Core policy decisions.

Portable workflows (sorrel-runners)

Workflows are declared in sorrel.workflow.yml: named workflows, jobs with commands, dependencies (needs), inputs, platforms, and environment. The parser converts a workflow into a portable JobBundle in deterministic topological order.

version: 1
workflows:
  validate:
    jobs:
      lint:
        command: npm run lint
      test:
        command: npm test
        needs: [lint]
        env:
          NPM_TOKEN:
            secretRef: secret_npm_token_dev

Bundles declare the capabilities they need (runner.use, workflow.run) and are authorized through Core's policy path before a single process starts. Local process execution and Docker/Podman container execution both work experimentally today. A forged bundle that skips the policy gate is rejected — that path is covered by conformance tests. The CLI also accepts the single-workflow form with top-level id and jobs fields.

Secrets as references (sorrel-vault)

Secret values never enter history, diffs, logs, or proposals. Workflows reference SecretRef handles; resolution happens at execution time through a backend, guarded by Core grant decisions (secret.read, secret.inject), and runner output is redacted against resolved values.

$ npm run vault -- import .env      # keys only — values are never persisted
$ npm run vault -- list             # SecretRef declarations + environments
$ npm run vault -- grant ...        # allow / deny / needs_grant decision
$ npm run vault -- redact run.log   # scrub resolved secrets from text

A local YAML file cannot bypass policy: vault operations evaluate the same Core decisions as everything else, and that equivalence is enforced by the shared conformance manifest.

CLI SecretSpec integration

The standalone runner and Node Vault packages never resolve values on their own. The sorrel CLI adds the integration layer: it resolves declared handles from keyring, dotenv, or environment SecretSpec providers after Core grant checks, injects them into a local workflow process, redacts output, and records structured results under .sorrel/runs/. It prefers devenv when available and reports a local-fallback backend otherwise.

Slices (sorrel-slices)

Agents rarely need a whole monorepo. A slice manifest describes a focused subproject: entry points, the files in its dependency closure, and what it exports. The current generator walks TS/JS projects; the CLI can also record generic slice manifests for other stacks. Slices become shareable, reviewable context units — "here is exactly what this agent saw."