stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/task-packs/authoring-guide.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

7.3 KiB
Raw Blame History

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Task Pack Authoring Guide

This guide teaches engineers how to design, validate, and publish Task Packs that align with the Sprint 43 specification. Follow these steps to ensure deterministic behaviour, secure approvals, and smooth hand-off to operators.

1 · Prerequisites

  • StellaOps CLI >= 2025.10.0 with pack commands enabled.
  • Authority client configured with Packs.Write (publish) and Packs.Run (local testing) scopes.
  • Access to Task Runner staging environment for validation runs.
  • Familiarity with the Task Pack Specification and Packs Registry.
  • Optional: connection to DevOps staging registry or Offline Kit mirror for publishing.

2 · Design Checklist

  1. Define objective. Document the operational need, inputs, expected outputs, and rollback strategy.
  2. Identify approvals. Determine which scopes/roles must sign off (Packs.Approve assignments).
  3. Plan security posture. Limit secrets usage, set tenant visibility, and note network constraints (sealed mode).
  4. Model observability. Decide which metrics, logs, and evidence artifacts are critical for post-run audits.
  5. Reuse libraries. Prefer built-in modules or shared pack fragments to reduce drift.

Capture the above in docs/summary.md (optional but recommended) for future maintainers.

3 · Authoring Workflow

3.1 Scaffold project

mkdir my-pack
cd my-pack
stella pack init --name sbom-remediation

stella pack init creates baseline files:

  • pack.yaml with metadata placeholders.
  • schemas/inputs.schema.json (sample).
  • docs/usage.md (template for human instructions).
  • .packignore to exclude build artifacts.

3.2 Define inputs & schemas

  • Use JSON Schema (draft-2020-12) for input validation.
  • Avoid optional inputs unless there is a deterministic default.
  • Store schemas under schemas/ and reference via relative paths.

3.3 Compose steps

  • Break workflow into small deterministic steps.
  • Name each step with stable id.
  • Wrap scripts/tools using built-in modules; copy scripts to assets/ if necessary.
  • Use when expressions for branch logic; ensure expressions rely solely on inputs or previous outputs.
  • For loops, adopt map with capped iteration count; avoid data-dependent randomness.

3.4 Configure approvals

  • Add spec.approvals entries for each required review.
  • Provide informative reasonTemplate with placeholders.
  • Set expiresAfter to match operational policy (e.g., 4 h for security reviews).
  • Document fallback contacts in docs/runbook.md.

3.5 Manage secrets

  • Declare secrets under spec.secrets.
  • Reference secrets via expressions (e.g., {{ secrets.jiraToken.value }}) inside modules that support secure injection.
  • Never bake secrets or tokens into pack assets.
  • If secret optional, set optional: true and handle absence in step logic.

3.6 Document outputs

  • List expected artifacts under spec.outputs.
  • Include human-friendly docs (Markdown) describing each output and how to access it through CLI or Console.

4 · Validation

4.1 Static validation

stella pack validate

Checks performed:

  • Schema compliance (YAML, JSON Schema).
  • Determinism guard (forbidden functions, clock usage, network allowlist).
  • Reference integrity (assets, schemas, documentation).
  • Approval/secret scope availability.

4.2 Simulation & plan hash

stella pack plan --inputs samples/inputs.json --output .artifacts/plan.json
stella pack simulate --inputs samples/inputs.json --output .artifacts/sim.json
  • Review plan graph to ensure step ordering and gating align with expectations.
  • Store simulation output with pack metadata for future audits.

4.3 Local rehearsal

stella pack run \
  --inputs samples/inputs.json \
  --secrets jiraToken=@secrets/jira.txt \
  --dry-run
  • Use --dry-run to verify approvals and outputs without side effects.
  • Real runs require Packs.Run and all approval gates satisfied (e.g., via CLI prompts or Console).

4.4 Unit tests (optional but encouraged)

  • Create a tests/ folder with CLI-driven regression scripts (e.g., using stella pack plan + jq assertions).
  • Integrate into CI pipelines; ensure tests run offline using cached assets.

5 · Publishing

5.1 Build bundle

stella pack build \
  --output dist/sbom-remediation-1.3.0.stella-pack.tgz \
  --manifest pack.yaml

5.2 Sign bundle

cosign sign-blob \
  --yes \
  --output-signature dist/sbom-remediation-1.3.0.sig \
  dist/sbom-remediation-1.3.0.stella-pack.tgz

Store signature alongside bundle; DSSE optional but recommended (see security guidance).

5.3 Publish to registry

stella pack push \
  registry.stella-ops.org/packs/sbom-remediation:1.3.0 \
  --bundle dist/sbom-remediation-1.3.0.stella-pack.tgz \
  --signature dist/sbom-remediation-1.3.0.sig

Registry verifies signature, stores provenance, and updates index.

5.4 Offline distribution

  • Export bundle + signature + provenance into Offline Kit using stella pack bundle export.
  • Update mirror manifest (manifest/offline-manifest.json) with new pack entries.

6 · Versioning & Compatibility

  • Follow SemVer (increment major when breaking schema/behaviour).
  • Document compatibility in docs/compatibility.md (recommended).
  • Registry retains immutable history; use metadata.deprecated: true to indicate retirement.

7 · Best Practices

  • Keep steps idempotent. Support manual retries without side effects.
  • Surface evidence early. Export intermediate artifacts (plans, logs) for operators.
  • Localize messages. Provide locales/en-US.json for CLI/Console strings (Sprint 43 requirement).
  • Avoid long-running commands. Split heavy tasks into smaller steps with progress telemetry.
  • Guard network usage. Use when: "{{ env.isSealed }}" to block disallowed network operations or provide offline instructions.
  • Document fallbacks. Include manual recovery instructions in docs/runbook.md.

8 · Hand-off & Review

  • Submit PR including pack bundle metadata, docs, and validation evidence.
  • Request review from Task Runner + Security + DevOps stakeholders.
  • Attach stella pack plan output and signature digest to review notes.
  • After approval, update change log (docs/CHANGELOG.md) and notify Task Runner operations.

9 · Compliance Checklist

  • Metadata, inputs, steps, approvals, secrets, and outputs defined per spec.
  • Schemas provided for all object inputs and outputs.
  • Determinism validation (stella pack validate) executed with evidence stored.
  • Plan + simulation artifacts committed in .artifacts/ or CI evidence store.
  • Bundle signed (cosign/DSSE) and signature recorded.
  • Runbook and troubleshooting notes documented.
  • Offline distribution steps prepared (bundle export + manifest update).
  • Imposed rule reminder retained at top.

Last updated: 2025-10-27 (Sprint 43).