agentsclimarketplace

Trestle authoring workflow

Skill oscal-compass-lab/compliance-trestle-skills/skills/trestle-authoring-workflow

Use this skill for the Compliance Trestle authoring workflow. The workflow is the generate-edit-assemble cycle that converts OSCAL documents to markdown and back. Use it for authoring catalogs, profiles, SSPs, or component definitions. Use it for editing control markdown, YAML headers, or the roundtrip workflow between JSON and markdown.From its SKILL.md

Install
npx -y skills add oscal-compass-lab/compliance-trestle-skills --skill trestle-authoring-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.2 KB, as published. Nobody here has run it

Trestle Authoring Workflow

The Generate-Edit-Assemble Cycle

Trestle authoring tools convert OSCAL JSON to markdown for human editing. Then they convert markdown back to JSON:

JSON (OSCAL) → generate → Markdown (edit) → assemble → JSON (OSCAL)

This cycle continues. After the first generate, edit markdown and assemble again.

Author Commands by Model Type

Catalog Authoring

  • trestle author catalog-generate --name <catalog> --output <md_dir> → markdown per control
  • trestle author catalog-assemble --markdown <md_dir> --output <catalog> → JSON catalog

Profile Authoring

  • trestle author profile-generate --name <profile> --output <md_dir> → markdown with profile additions
  • trestle author profile-assemble --markdown <md_dir> --output <profile> → JSON profile
  • trestle author profile-resolve --name <profile> --output <resolved> → resolved profile catalog

Component Definition Authoring

  • trestle author component-generate --name <compdef> --output <md_dir> → markdown per component/control
  • trestle author component-assemble --markdown <md_dir> --output <compdef> → JSON component-definition

SSP Authoring

  • trestle author ssp-generate --profile <profile> --compdefs <comp1,comp2> --output <md_dir> → markdown per control
  • trestle author ssp-assemble --markdown <md_dir> --output <ssp> → JSON SSP
  • trestle author ssp-filter --name <ssp> --profile <profile> --output <filtered> → filtered SSP

Markdown Structure

Control Markdown File

Each control gets its own .md file with:

  1. YAML header: metadata, parameters, properties
  2. Control title: # control-id - [Group Title] Control Title
  3. Control Statement: ## Control Statement with labeled parts
  4. Control guidance: ## Control guidance
  5. Additional sections: Implementation responses, component sections

YAML Header Tags (x-trestle-*)

TagPurpose
x-trestle-set-paramsParameter values for the control
x-trestle-globalGlobal metadata (sort-id, profile title)
x-trestle-sectionsMap of section short names to display names
x-trestle-add-propsProperties to add to the control
x-trestle-comp-def-rulesRules from component definitions
x-trestle-comp-def-rules-param-valsRule parameter values
x-trestle-inherited-propsProperties inherited from upstream
x-trestle-leveraging-compLeveraged component information
x-trestle-statementStatement-level metadata

Parameter Handling

In catalog markdown (x-trestle-set-params):

x-trestle-set-params:
  ac-1_prm_1:
    values:
      - organization-defined value
    label: descriptive label

In profile markdown (adds profile-values):

x-trestle-set-params:
  ac-1_prm_1:
    values:
      - catalog value
    profile-values:
      - profile-specific value

In SSP markdown (adds ssp-values):

x-trestle-set-params:
  ac-1_prm_1:
    values:
      - resolved value
    ssp-values:
      - ssp-specific value

Key Options

OptionCommandsPurpose
--set-parameterscatalog-assemble, profile-assembleApply parameter changes from YAML header
--overwrite-header-valuesall -generateOverwrite existing header values with provided YAML
--force-overwriteall -generateErase existing markdown before regenerating
--yaml / -yall -generateProvide external YAML header to merge
--versionall -assembleSet version in assembled model
--regenerateall -assembleGenerate new UUIDs
--sectionsprofile-assembleDefine allowed sections
--required-sectionsprofile-assembleSections that must be present
--compdefsssp-generateComma-separated component definitions

Implementation Status Values

Controls track implementation status with these values:

  • implemented: Fully implemented
  • partial: Partially implemented
  • planned: Implementation is planned
  • alternative: Alternative implementation
  • not-applicable: Control is not applicable

Control Origination Values

  • organization: Organization-level
  • system-specific: System-specific
  • customer-configured: Customer configured
  • customer-provided: Customer provided
  • inherited: Inherited from another system

CI/CD Integration

Use the authoring tools in CI/CD pipelines:

  • Assemble commands write output only if content changed. This prevents extra triggers.
  • --set-parameters limits what can change during automated assembly.
  • --required-sections and --allowed-sections check document structure.
  • Individual control markdown files support fine-grained git tracking.

Multi-Repository Coordination

Large organizations split OSCAL artifacts across multiple Git repositories. The split follows ownership boundaries. Trestle authoring tools support this through CI/CD-driven propagation.

Repository Topology

catalog-repo (Regulators)
    |
    v  imports
profile-repo (Compliance Officers)
    |
    v  references
compdef-repo (Vendors / Control Providers)
    |
    v  combined into
ssp-repo (System Owners)

Each repository contains its own trestle workspace (.trestle/ directory). Each repository manages artifacts independently with its own CI/CD pipeline.

Change Propagation Pattern

When an upstream artifact changes:

  1. Upstream repo merges markdown edits to main.
  2. CI/CD runs trestle author *-assemble to rebuild OSCAL JSON.
  3. If JSON changed, CI/CD creates a PR in each downstream repository.
  4. Downstream owners review the PR, which pulls the updated upstream artifact.
  5. On merge, the downstream CI/CD assembles its own artifacts with the new input.

This pattern uses repository_dispatch events (GitHub Actions) or cross-project triggers (GitLab CI) to connect repositories.

When to Use Multi-Repo vs Single-Repo

FactorSingle RepoMulti-Repo
Team sizeSmall (1-5 people)Multiple teams or organizations
OwnershipSame team owns all artifactsDifferent teams own different artifacts
Release cadenceArtifacts change togetherIndependent versioning needed
Access controlSame permissions for allDifferent access per artifact type
ComplexitySimpler setup and maintenanceClearer ownership split

Start with a single repo. Split when ownership boundaries emerge or when independent versioning is required.

Two-Phase Component Definition Authoring

Component definitions combine structured rule data with narrative prose. Trestle supports a two-phase authoring pattern. Use the best tool for each type of content.

Phase 1: Rules with CSV Spreadsheet

# CSV contains structured mappings: rules, parameters, control associations
trestle task csv-to-oscal-cd

The CSV captures:

  • Rule_Id, Rule_Description: the technical rule
  • Control_Id_List: which regulation controls this rule implements
  • Parameter_Id, Parameter_Value_Alternatives: configurable parameters
  • Component_Type: Service (control-to-rule) or Validation (rule-to-check)

Vendors manage this CSV in spreadsheet tools. It is committed to Git. The csv-to-oscal-cd task converts it to OSCAL JSON.

Phase 2: Responses with Markdown

# Generate markdown from the Phase 1 component definition
trestle author component-generate --name my-service --output md_compdefs/my-service

# Markdown shows rules (read-only) + editable prose sections
# Edit: write implementation descriptions per control per component
# Then reassemble
trestle author component-assemble --markdown md_compdefs/my-service --output my-service

The markdown includes:

  • Read-only rules section (from Phase 1 CSV data)
  • Read-only control description and guidance (from catalog/profile)
  • Editable implementation response sections (prose describing HOW the control is met)
  • Implementation status (implemented, partial, planned, and related values)

Why Two Phases?

  • Structured data (rules, parameters, mappings) is best managed in spreadsheets.
  • Narrative prose (implementation descriptions) is best edited as markdown.
  • Different personas can own each phase. Security engineers write rules. Product owners write prose.
  • Phase 1 can be automated from tooling. Phase 2 needs human judgment.

Git-Based Authoring Workflow

Trestle authoring tools support Git-based collaboration with CI/CD automation.

PR-Based Review Cycle

  1. Author edits markdown on a feature branch.
  2. Opens a PR for peer review.
  3. CI/CD runs trestle validate on the PR to catch errors early.
  4. Reviewers approve. The PR is merged to main.
  5. CI/CD on main runs trestle author *-assemble to rebuild OSCAL JSON.
  6. If JSON changed, CI/CD commits the updated JSON. It can also trigger downstream repos.

Conditional Write Behavior

Assemble commands write output only if content changed. This prevents:

  • Extra git commits (no-op JSON changes)
  • Infinite CI/CD trigger loops between repositories
  • Misleading git history with empty diffs

Branch Protection Recommendations

BranchProtectionWho Can Merge
mainRequire PR review + CI/CD passArtifact owner (per persona)
Feature branchesNo protectionAny contributor

Individual control markdown files support fine-grained git tracking. Reviewers can see which controls changed in a PR diff.

Models Without Author Commands

Not all OSCAL models have trestle author generate or assemble commands. The following models use a JSON-based workflow instead:

Modeltrestle author SupportWorkflow
Catalogcatalog-generate / catalog-assembleMarkdown roundtrip
Profileprofile-generate / profile-assembleMarkdown roundtrip
Component Definitioncomponent-generate / component-assembleMarkdown roundtrip
SSPssp-generate / ssp-assembleMarkdown roundtrip
Assessment PlanNonecreate → split → edit → merge → validate
Assessment ResultsNonecreate → split → edit → merge → validate
POA&MNonecreate → split → edit → merge → validate

JSON-Based Workflow

For assessment plans, assessment results, and POA&M:

# 1. Create a new model with placeholder fields
trestle create -t <model-type> -o <name>

# 2. Split into editable sections
trestle split -f <model-file>.json -e '<model-type>.<element1>,<model-type>.<element2>'

# 3. Edit the resulting JSON files directly

# 4. Merge sections back together
trestle merge -e '<model-type>.<element1>,<model-type>.<element2>'

# 5. Validate the final model
trestle validate -t <model-type> -n <name>

For detailed workflows, see the trestle-assessment skill (assessment plans and results) and the trestle-poam skill (plan of action and milestones).

Keep looking

Skills are one crate of 611,178. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.