# Ethanolivertroy Compliance Trestle Claude Plugin Trestle Authoring Workflow > Trestle Authoring Workflow - Skill: `tomevault-io/ethanolivertroy-compliance-trestle-claude-plugin-trestle-aut` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ethanolivertroy-compliance-trestle-claude-plugin-trestle-aut` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ethanolivertroy-compliance-trestle-claude-plugin-trestle-aut/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ethanolivertroy-compliance-trestle-claude-plugin-trestle-aut --- # Trestle Authoring Workflow ## The Generate-Edit-Assemble Cycle Trestle's authoring tools convert OSCAL JSON to markdown for human editing, then back to JSON: ``` JSON (OSCAL) → generate → Markdown (edit) → assemble → JSON (OSCAL) ``` This cycle is continuous: after initial generation, you repeatedly edit markdown and reassemble. ## Author Commands by Model Type ### Catalog Authoring - `trestle author catalog-generate --name --output ` → markdown per control - `trestle author catalog-assemble --markdown --output ` → JSON catalog ### Profile Authoring - `trestle author profile-generate --name --output ` → markdown with profile additions - `trestle author profile-assemble --markdown --output ` → JSON profile - `trestle author profile-resolve --name --output ` → resolved profile catalog ### Component Definition Authoring - `trestle author component-generate --name --output ` → markdown per component/control - `trestle author component-assemble --markdown --output ` → JSON component-definition ### SSP Authoring - `trestle author ssp-generate --profile --compdefs --output ` → markdown per control - `trestle author ssp-assemble --markdown --output ` → JSON SSP - `trestle author ssp-filter --name --profile --output ` → 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-*) | Tag | Purpose | |-----|---------| | `x-trestle-set-params` | Parameter values for the control | | `x-trestle-global` | Global metadata (sort-id, profile title) | | `x-trestle-sections` | Map of section short names to display names | | `x-trestle-add-props` | Properties to add to the control | | `x-trestle-comp-def-rules` | Rules from component definitions | | `x-trestle-comp-def-rules-param-vals` | Rule parameter values | | `x-trestle-inherited-props` | Properties inherited from upstream | | `x-trestle-leveraging-comp` | Leveraged component information | | `x-trestle-statement` | Statement-level metadata | ### Parameter Handling **In catalog markdown** (`x-trestle-set-params`): ```yaml x-trestle-set-params: ac-1_prm_1: values: - organization-defined value label: descriptive label ``` **In profile markdown** (adds `profile-values`): ```yaml x-trestle-set-params: ac-1_prm_1: values: - catalog value profile-values: - profile-specific value ``` **In SSP markdown** (adds `ssp-values`): ```yaml x-trestle-set-params: ac-1_prm_1: values: - resolved value ssp-values: - ssp-specific value ``` ## Key Options | Option | Commands | Purpose | |--------|----------|---------| | `--set-parameters` | catalog-assemble, profile-assemble | Apply parameter changes from YAML header | | `--overwrite-header-values` | all -generate | Overwrite existing header values with provided YAML | | `--force-overwrite` | all -generate | Erase existing markdown before regenerating | | `--yaml` / `-y` | all -generate | Provide external YAML header to merge | | `--version` | all -assemble | Set version in assembled model | | `--regenerate` | all -assemble | Generate new UUIDs | | `--sections` | profile-assemble | Define allowed sections | | `--required-sections` | profile-assemble | Sections that must be present | | `--compdefs` | ssp-generate | Comma-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 The authoring tools are designed for CI/CD pipelines: - Assemble commands only write output if content changed (prevents unnecessary triggers) - `--set-parameters` limits what can change during automated assembly - `--required-sections` and `--allowed-sections` enforce document structure - Individual control markdown files enable fine-grained git tracking ## Multi-Repository Coordination Large organizations split OSCAL artifacts across multiple Git repositories aligned to ownership boundaries. Trestle's 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) and 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 | Factor | Single Repo | Multi-Repo | |--------|-------------|------------| | Team size | Small (1-5 people) | Multiple teams or organizations | | Ownership | Same team owns all artifacts | Different teams own different artifacts | | Release cadence | Artifacts change together | Independent versioning needed | | Access control | Same permissions for all | Different access per artifact type | | Complexity | Simpler setup and maintenance | Better separation of concerns | **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 that uses the best tool for each type of content. ### Phase 1: Rules via CSV Spreadsheet ```bash # 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 and converted to OSCAL JSON via the `csv-to-oscal-cd` task. ### Phase 2: Responses via Markdown ```bash # 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`, etc.) ### Why Two Phases? - **Structured data** (rules, parameters, mappings) is best managed in spreadsheets - **Narrative prose** (implementation descriptions) is best edited as markdown - Different personas may own each phase (security engineers write rules; product owners write prose) - Phase 1 can be automated from tooling; Phase 2 requires human judgment ## Git-Based Authoring Workflow Trestle's authoring tools are designed for 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; 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 and (optionally) triggers downstream repos ### Conditional Write Behavior Assemble commands **only write output if content changed**. This prevents: - Unnecessary git commits (no-op changes to JSON) - Infinite CI/CD trigger loops between repositories - Misleading git history with empty diffs ### Branch Protection Recommendations | Branch | Protection | Who Can Merge | |--------|-----------|---------------| | `main` | Require PR review + CI/CD pass | Artifact owner (per persona) | | Feature branches | No protection | Any contributor | Individual control markdown files enable fine-grained git tracking — reviewers can see exactly which controls were modified in a PR diff. ## Models Without Author Commands Not all OSCAL models have `trestle author` generate/assemble commands. The following models use a **JSON-based workflow** instead: | Model | `trestle author` Support | Workflow | |-------|--------------------------|----------| | Catalog | `catalog-generate` / `catalog-assemble` | Markdown roundtrip | | Profile | `profile-generate` / `profile-assemble` | Markdown roundtrip | | Component Definition | `component-generate` / `component-assemble` | Markdown roundtrip | | SSP | `ssp-generate` / `ssp-assemble` | Markdown roundtrip | | **Assessment Plan** | **None** | `create → split → edit → merge → validate` | | **Assessment Results** | **None** | `create → split → edit → merge → validate` | | **POA&M** | **None** | `create → split → edit → merge → validate` | ### JSON-Based Workflow For assessment plans, assessment results, and POA&M: ```bash # 1. Create a new model with placeholder fields trestle create -t -o # 2. Split into editable sections trestle split -f .json -e '.,.' # 3. Edit the resulting JSON files directly # 4. Merge sections back together trestle merge -e '.,.' # 5. Validate the final model trestle validate -t -n ``` For detailed workflows, see the `trestle-assessment` skill (assessment plans and results) and the `trestle-poam` skill (plan of action and milestones). --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ethanolivertroy) — claim your Tome and manage your conversions.