SfSkills Domains Docs GitHub

Home / admin / configuration-workbook-authoring

configuration-workbook-authoring

Author the Salesforce Configuration Workbook — the structured, reviewable handoff document an admin uses to execute a feature across Objects/Fields, Page Layouts, Profiles/PSGs, Sharing, Validation, Automation, List Views, Reports, Integrations, and Data.

Open the skill folder on GitHub

Configuration Workbook Authoring

This skill activates when a Salesforce delivery team needs to convert approved user stories and fit-gap rows into the Configuration Workbook — the structured, reviewable handoff document that drives admin execution and routes each row to a single downstream runtime agent. The workbook is the canonical artifact between requirements (RTM) and metadata (deployment manifest).

It is NOT the object designer, NOT the permission-set designer, NOT the Flow builder, and NOT the deployment manifest. It is the handoff document those agents consume.

Before Starting

Gather this context before authoring or revising a workbook. Without all five, the rows you write cannot be reviewed or routed.

InputWhy the workbook cannot start without it
Approved user storiesEvery row carries source_story_id. A row without an upstream story is orphaned and cannot be reviewed.
Approved fit-gap rows, with their descope decisionsEvery row carries source_req_id (the RTM req_id) so the workbook traces back to the RTM — and the descope list tells you which requirements must produce no row.
Target org aliasAPI names, existing record types and existing PSGs must reflect the live org, not a wishlist. Probe before writing a target_value.
Sprint / release identifierThe workbook is version-locked at sprint commit; mid-sprint change requests open new rows rather than editing existing ones in place.
Downstream agent rosterEvery recommended_agent must resolve to a real agents/<id>/AGENT.md that is not deprecated (see agents/_shared/SKILL_MAP.md and agents/_shared/AGENT_DISAMBIGUATION.md).

Questions to Ask Before Configuring

Ask these before writing a single row. Each answer removes one failure mode from references/gotchas.md; a workbook written without them looks complete and routes to nobody.

AskWhy it mattersWhat a good answer adds
"Which requirements did the steering committee descope, defer or escalate?"A descoped story that reappears as a row is a refusal condition for config-workbook-author, not a nice-to-have; an escalated one needs an ADR before any row existsThe descope ledger — the record of the requirements that deliberately produced no row (Gotcha 4 in references/worked-examples.md Rule 7)
"Who, by name, is accountable for each section landing in the org?"owner is a person, not a team alias. A section owned by "the admin team" is a section nobody signs off, including the empty onesA named owner per section, including for not-in-scope-this-release rows
"Which agent executes this row, and is it still on the runtime roster?"The fourteen Wave-3b auditors still have AGENT.md files on disk, so an existence check passes them and routes the row to a stubOne live agent id per row, with --domain= arguments where audit-router replaced a retired auditor (Gotcha 8)
"For every automation and sharing row that picks a mechanism, which decision-tree branch resolved it?"An unrecorded choice cannot be disagreed with at review, and "it was obvious" is the decision that goes unrecordedA <tree>.md Q<n> citation plus one clause of reason on every Section 4 row and every Section 6 row whose artefact is an automation-engine choice; a Queue/Group/BusinessHours configuration row cites nothing because it picks no engine (Gotchas 12 and 13)
"Is access granted through permission sets, or is this org still profile-driven?"A profile row is unverifiable after deploy: a retrieved profile only carries FLS for what else was in the same manifest, and a profile deploy overlays rather than replacesSection 3 rows that name permission sets, with profiles reserved for the residue that has no PermissionSet equivalent (Gotcha 15)
"What is the org's current state for every target_value you are about to write?"API names, existing rules and existing PSGs collide silently; "we'll figure out the API name later" rows become reworkA probe date in notes beside each new component, so the reviewer knows the row was checked against reality and when
"What does version-lock mean here — who tags the file, and where does it live?"status: committed is a per-row label an in-place edit can rewrite; only the snapshot is the lockA path (docs/workbooks/<release>/cwb.md) and a tag, agreed before the sprint, not improvised at commit (Gotcha 14)

What a proper configuration adds over just writing a build sheet: every deployed component traces back to an approved requirement and forward to the agent that built it, every technology choice carries the branch that decided it, and the requirements that deliberately produced nothing are as visible as the ones that produced rows.

Core Concepts

Concept 1: One row per addressable change

The workbook's atomic unit is a row. A row describes a single configurable artifact (one field, one validation rule, one PSG composition step, one Flow trigger, one report folder permission, one named credential). Rows are never "epics" — if a row would require multiple agents to execute, it must be split.

The row schema is:

FieldRequiredNotes
row_idyesStable, unique within the workbook (e.g. CWB-FIELDS-014). Survives section reorder.
sectionyesOne of the 10 canonical sections. Must match exactly.
target_valueyesThe configurable value (API name, formula, picklist set, sharing rule criterion, etc.).
owneryesThe named human accountable for this row landing in the org. Not a team alias.
source_req_idyesThe RTM req_id — REQ-XXX, immutable and never reused, per admin/requirements-traceability-matrix § ID Conventions. Orphan rows = REJECT.
source_story_idyesUser-story id (e.g. US-2031).
recommended_agentyesExactly ONE runtime agent id, optionally followed by --flag arguments (audit-router --domain=sharing). Must resolve to agents/<id>/AGENT.md and carry a frontmatter status that is not deprecated.
recommended_skills[]yes (≥1)Skill ids the executing agent must consult, ;-delimited. Every entry resolves on disk: <domain>/<slug> → skills/<domain>/<slug>/SKILL.md, <domain>/<slug> → references/<file>.md, or a repo-relative templates/… / standards/… path.
statusyesproposed | committed | in-progress | executed | verified | change-requested. Never a placeholder — check_workbook.py rejects TBD, WIP, DOING, NEXT, ?, a bare to-do marker, and empty (see PLACEHOLDER_STATUS_TOKENS).
notesoptionalRisks, decisions, links to ADRs.

Concept 2: Ten canonical sections

The workbook is fixed at ten sections. Authors do not invent new sections; if a configurable artifact does not fit into one of these, it is not within the workbook's scope:

  1. Objects + Fields — new objects, custom fields, field-type changes,

    formula fields, external IDs.

  2. Page Layouts + Lightning Pages — record-type-keyed layout assignments,

    Dynamic Forms regions, Lightning Record Page components.

  3. Profiles + Permission Sets + PSGs — every PS and PSG composition; the

    muting strategy.

  4. Sharing Settings — OWD, role hierarchy adjustments, sharing rules,

    manual share, restriction rules. Cite the sharing decision tree.

  5. Validation Rules — VR formula, error location, error message, bypass

    reference (Custom Permission + Custom Setting).

  6. Automation (Flow / Apex / Approvals) — every Flow, every Apex trigger

    handler hook, every approval process. Cite the automation decision tree.

  7. List Views + Search — list view filter criteria, default list view per

    profile, search layouts, lookup filters.

  8. Reports + Dashboards — folder structure, folder sharing, key reports

    and dashboards, scheduled subscriptions.

  9. Integrations — named credentials, connected apps, remote site settings,

    external services, Platform Event channels, CDC subscriptions. Sensitive credentials are referenced by alias, never inline.

  10. Data + Migration — required data loads, dedup rules, External Id

    upsert keys, sandbox seed data, cutover order.

Concept 3: Every row is addressable by exactly one downstream agent

The workbook is not just documentation — it is a routing instrument. The recommended_agent field assigns each row to a single agent that will execute it. If a single configuration step requires two agents (e.g. a new object and its PSG), it must be split into two rows, each addressable on its own.

The default recommended_agent per section. agents/_shared/SKILL_MAP.md is the authoritative roster; a row may name a different live agent when the artefact warrants it, but never one that is absent from disk or deprecated.

Sectionrecommended_agent
1 — Objects + Fieldsobject-designer
2 — Page Layouts + Lightning Pagesaudit-router --domain=lightning_record_page; path-designer for Path + Guidance rows
3 — Profiles + Permission Sets + PSGspermission-set-architect; profile-to-permset-migrator when the row decomposes a profile
4 — Sharing Settingsaudit-router --domain=sharing
5 — Validation Rulesaudit-router --domain=validation_rule
6 — Automationflow-builder (net-new Flow), apex-builder (net-new Apex), apex-refactorer (existing class), flow-analyzer (object already carries automation), assignment-and-auto-response-rules-designer (Lead/Case ownership routing)
7 — List Views + Searchaudit-router --domain=list_view_search_layout
8 — Reports + Dashboardsaudit-router --domain=report_dashboard
9 — Integrationsintegration-catalog-builder
10 — Data + Migrationdata-loader-pre-flight; csv-to-object-mapper when CSV-to-object mapping is the dominant work; duplicate-rule-designer for dup-rule rows

The five audit-router --domain=… entries are not stylistic. The single-mode auditors they replaced (sharing-audit-agent, validation-rule-auditor, lightning-record-page-auditor, list-view-and-search-layout-auditor, report-and-dashboard-auditor) still have AGENT.md files on disk carrying status: deprecated and deprecated_in_favor_of: audit-router, so a row that names one passes an existence check and routes to a stub. agents/_shared/AGENT_DISAMBIGUATION.md holds the full old-name → --domain= mapping; scripts/check_workbook.py reads the frontmatter and reports the row.

Common Patterns

Pattern 1: Source-grounded row authoring

When to use: Every time a new row is added to the workbook.

How it works:

  1. Pick the source — a source_req_id from the RTM, a source_story_id, or

    both. Both are required.

  2. Restate the change in target_value using API names already in the org or

    names that conform to templates/admin/naming-conventions.md.

  3. Pick exactly one recommended_agent. If the row "needs" two agents,

    split the row.

  4. Pick recommended_skills[] — at least one skill id from the executing

    agent's Mandatory Reads list.

  5. Set status: proposed. Promotion to committed happens only at sprint

    commit (Step 5 of the workflow).

Why not the alternative: Free-text "build sheets" that lack row_id, source_req_id, or recommended_agent cannot be reviewed for completeness, cannot be routed to agents, and silently drift from the RTM.

Pattern 2: Version-locking at sprint commit

When to use: When the team commits a workbook to a sprint or release.

How it works: Set status: committed on every in-scope row, snapshot the file (commit a tagged copy under docs/workbooks/<release>/cwb.md), and from that point treat the file as immutable. Mid-sprint change requests open new rows with status: change-requested and a notes field linking back to the row(s) they supersede. Old rows stay; their target_value is preserved as historical record.

Why not the alternative: Editing rows in place destroys the audit trail and lets reviewers approve a workbook that no longer matches what was deployed.

Pattern 3: One row, one agent, one section

When to use: Whenever the temptation arises to have a single row "stand in" for a multi-section change.

How it works: A "new Account Plan object with a PSG and a record-trigger Flow" is three rows:

Each row carries the same source_story_id and the same source_req_id. Cross-row dependencies live in notes, not in row content.

Why not the alternative: A row that touches three sections cannot be routed to a single agent and degrades the workbook into a wiki.

Decision Guidance

SituationRecommended ApproachReason
Row touches 2+ sectionsSplit the row, one per sectionEach row must be addressable by one agent
Row has no source_req_idReject — open a fit-gap row firstWorkbook traces back to RTM; orphans are forbidden
Mid-sprint change requestOpen a new row with status: change-requested, link to the superseded row in notesWorkbook is version-locked at sprint commit
Row's downstream tool is Apex, not Flowrecommended_agent: trigger-consolidator or apex-refactorer (per automation-selection.md)Cite the decision tree branch, do not freestyle
Row's target_value references a credentialUse a Named Credential alias; never inline secretsSecrets in workbook = leak
Workbook has no Integrations sectionAdd it, even if emptyAn empty section is information; a missing one is a gap
Two reviewers disagree on a rowPromote disagreement to notes, leave status: proposed, escalate to architectWorkbook isn't the venue for un-resolved decisions
  1. Intake and the descope ledger. Pull the approved stories and the

    fit-gap rows including their descope decisions. Confirm every story maps to a req_id and vice versa. Write the descope / defer / escalate ledger first (references/worked-examples.md Rule 7) — before any row exists, so a descoped requirement cannot quietly acquire one.

  2. Outline. Copy templates/config-workbook.md to

    docs/workbooks/<release>/cwb.md. All ten sections, in canonical order, numbered — the checker verifies the numbering, because Sections 4 and 6 are cited by number. Empty sections keep a not-in-scope-this-release row with a named owner.

  3. Populate. One row per configurable artefact, per Patterns 1 and 3.

    Copy the shape from references/worked-examples.md Rules 1–6: target_value names a metadata component (never a Setup path), exactly one live recommended_agent, at least one recommended_skills entry you have opened, status: proposed, and — on every Section 4 and Section 6 row — the <tree>.md Q<n> branch that resolved the tool choice.

  4. Check. `python3 scripts/check_workbook.py --workbook

    docs/workbooks/<release>/cwb.md. It resolves every agent (includingstatus: deprecated), resolves every skill path against disk, enforcesrow_iduniqueness, the status enum, the tree citations, one-agent-per-row and the Section 3 profile rule. Exit code 1 fails a hook or CI step. Do **not** pass--allow-empty-section` from here on.

  5. Review. Walk ## Review Checklist with the admin team and the BA. The

    checker proves the schema; the review is where target_value is checked against the org probe and the tree citation is argued with.

  6. Version-lock. Set every in-scope row to committed, snapshot the file

    at docs/workbooks/<release>/cwb.md, and tag it. Both actions, or it is not locked (references/gotchas.md Gotcha 14). From here the file is append-only.

  7. Hand off and close out. Give each downstream agent

    (row_id, recommended_agent, recommended_skills, target_value, source_req_id). Assemble the deployment manifest from the committed rows (references/worked-examples.md Rule 8), then set each row to executed with the metadata path it produced, so the release report can show every req_id → row_id → metadata file.

Review Checklist

Before declaring the workbook ready for sprint commit:

Salesforce-Specific Gotchas

  1. API-name reality check — the workbook's target_value for an object or

    field must use API names that don't already exist (or that you intend to extend). Probe the org first; "we'll figure out the API name later" rows become rework.

  2. Section discipline drift — teams under deadline pressure invent

    sections like "Misc" or "Other" to absorb rows that don't fit. Reject these — if it doesn't fit one of the 10 sections, it isn't a workbook row.

  3. PSG rows that pretend to be field rows — a row that says "add the field

    and grant the SDR PSG access" is two rows. Pretending otherwise hides the permission change from the permission-set-architect agent.

  4. Section-boundary confusion between OWD and sharing rules — the org-wide

    default is the sharingModel element on the object file (Section 1); the SharingRules container is a different file (Section 4).

  5. Deprecated agents that still exist on disk — a row naming

    sharing-audit-agent or validation-rule-auditor passes an existence check and routes to a stub; route to audit-router --domain=<x>.

  6. Profile rows that cannot be verified after deploy — a retrieved profile

    only carries FLS for what else was in the same manifest, and a profile deploy overlays rather than replaces.

All fifteen, with the platform behaviour behind each, are in references/gotchas.md.

Output Artifacts

ArtifactDescription
cwb.mdThe 10-section markdown workbook authored from templates/config-workbook.md. The committed sprint copy lives at docs/workbooks/<release>/cwb.md.
cwb.jsonMachine-readable JSON envelope of the rows for downstream agents.
cwb.csvFlat CSV export with one row per workbook row; useful for review in spreadsheets.
RTM linkage blockA short markdown table mapping row_id → source_req_id → source_story_id → recommended_agent → status. Lives at the top of cwb.md.
Descope / defer / escalate ledgerThe requirements that deliberately produced no row, with the decision, the rationale, who decided and when. Sits after Section 10. Without it a missing row is invisible.
package.xmlThe deployment manifest assembled from the committed rows at hand-off. Shape and worked example in references/worked-examples.md Rule 8; the deploy itself belongs to devops/metadata-api-retrieve-deploy.

Official Sources Used

Canonical list, with the claim each source supports: references/well-architected.md § Official Sources Used.

Reference Files

FileRead it when
references/worked-examples.mdYou are about to write rows. Carries the nine format rules applied end to end to one small feature: the per-row schema, agent + skill resolution, the RTM linkage block, decision-tree citation, empty sections, the descope ledger, the package.xml the committed rows produce, and a real checker run.
references/gotchas.mdA row looks fine and something downstream refuses it, or you are reviewing someone else's workbook. Fifteen failure modes with the platform behaviour behind each.
references/examples.mdYou want short excerpts of the row schema for a different domain (greenfield objects, PSG composition, multi-Flow automation) rather than the full format walk-through.
references/llm-anti-patterns.mdAn assistant produced the workbook. Seven ways LLMs break the schema, with a detection hint for each.
references/well-architected.mdYou need the pillar mapping, the tradeoffs behind the schema rigour, or the sources every platform claim in this package rests on (## Official Sources Used is canonical here).
templates/config-workbook.mdYou are starting a workbook. The canonical ten-section skeleton, JSON envelope, CSV schema and hand-off block.
templates/configuration-workbook-authoring-template.mdYou are planning the authoring task itself — scope, context gathered, which pattern applies, the authoring checklist.
scripts/check_workbook.pyBefore sprint commit, and in CI on every PR touching a workbook.
skills/admin/case-management-setup/references/worked-example-case-intake.mdYou want a full ten-section workbook for a real solution, not a format walk-through.

Upstream — what the workbook consumes:

Downstream — what a workbook row hands off to:

Routing authorities every row is bound to:

Package files