209 lines
7.3 KiB
Markdown
209 lines
7.3 KiB
Markdown
> **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](spec.md) and [Packs Registry](registry.md).
|
||
- 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
stella pack build \
|
||
--output dist/sbom-remediation-1.3.0.stella-pack.tgz \
|
||
--manifest pack.yaml
|
||
```
|
||
|
||
### 5.2 Sign bundle
|
||
|
||
```bash
|
||
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](../security/pack-signing-and-rbac.md)).
|
||
|
||
### 5.3 Publish to registry
|
||
|
||
```bash
|
||
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).*
|
||
|