# 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. Triggers: 'salesforce configuration workbook', 'admin handoff document', 'implementation workbook'. NOT for object design itself (use admin/custom-field-creation, admin/lookup-and-relationship-design, agents/object-designer/AGENT.md), NOT for permission set design (use admin/permission-set-architecture, agents/permission-set-architect/AGENT.md), NOT for Flow construction (use skills/flow/* and agents/flow-builder/AGENT.md), and NOT for the deployment manifest (use skills/devops/metadata-api-retrieve-deploy). - Skill: `pranavnagrecha/configuration-workbook-authoring` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds add pranavnagrecha/configuration-workbook-authoring` - Raw SKILL.md: https://api.skillmd.com/api/skills/pranavnagrecha/configuration-workbook-authoring/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: PranavNagrecha (https://skillmd.com/u/pranavnagrecha) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/pranavnagrecha/configuration-workbook-authoring --- # 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: - **Approved user stories** — every workbook row must carry `source_story_id`. Rows without an upstream story are orphaned and cannot be reviewed. - **Approved fit-gap rows** — every workbook row must carry `source_req_id` so the workbook traces back to the RTM. - **Target org alias** — the workbook is grounded in the live org. API names, existing record types, and existing PSGs must reflect reality, not wishlist. - **Sprint / release identifier** — the workbook is version-locked at sprint commit. Mid-sprint change requests open *new* rows; they never edit existing rows in place. - **Downstream agent roster** — every row's `recommended_agent` must resolve to a real `agents//AGENT.md` from the runtime tier (see `agents/_shared/SKILL_MAP.md` for the authoritative list). --- ## 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: | Field | Required | Notes | |---|---|---| | `row_id` | yes | Stable, unique within the workbook (e.g. `CWB-FIELDS-014`). Survives section reorder. | | `section` | yes | One of the 10 canonical sections. Must match exactly. | | `target_value` | yes | The configurable value (API name, formula, picklist set, sharing rule criterion, etc.). | | `owner` | yes | The named human accountable for this row landing in the org. Not a team alias. | | `source_req_id` | yes | Fit-gap row id from the RTM. Orphan rows = REJECT. | | `source_story_id` | yes | User-story id (e.g. `US-2031`). | | `recommended_agent` | yes | Single downstream runtime agent (one of `object-designer`, `permission-set-architect`, `flow-builder`, `path-designer`, `lightning-record-page-auditor`, etc.). | | `recommended_skills[]` | yes (≥1) | Skill ids the executing agent should consult. | | `status` | yes | `proposed` \| `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`). | | `notes` | optional | Risks, 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. Allowed `recommended_agent` values (subset, see `agents/_shared/SKILL_MAP.md` for the full list): - `object-designer` — Objects + Fields rows - `permission-set-architect` — Profiles + Permission Sets + PSGs rows - `flow-builder` — Automation rows where the chosen tool is Flow - `path-designer` — Path + Guidance rows in the Lightning Pages section - `lightning-record-page-auditor` — Lightning Record Page rows - `validation-rule-auditor` (or `audit-router --domain validation_rule`) — Validation Rules rows - `report-and-dashboard-auditor` (or `audit-router --domain report_dashboard`) — Reports + Dashboards rows - `integration-catalog-builder` — Integrations rows - `data-loader-pre-flight` — Data + Migration rows - `csv-to-object-mapper` — Data + Migration rows when CSV-to-object mapping is the dominant work --- ## 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//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**: - `CWB-OBJ-007`, section Objects+Fields, recommended_agent `object-designer`. - `CWB-PSG-019`, section Profiles+Permission Sets+PSGs, recommended_agent `permission-set-architect`. - `CWB-AUT-031`, section Automation, recommended_agent `flow-builder`. 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 | Situation | Recommended Approach | Reason | |---|---|---| | Row touches 2+ sections | Split the row, one per section | Each row must be addressable by one agent | | Row has no `source_req_id` | Reject — open a fit-gap row first | Workbook traces back to RTM; orphans are forbidden | | Mid-sprint change request | Open a new row with `status: change-requested`, link to the superseded row in `notes` | Workbook is version-locked at sprint commit | | Row's downstream tool is Apex, not Flow | `recommended_agent: trigger-consolidator` or `apex-refactorer` (per `automation-selection.md`) | Cite the decision tree branch, do not freestyle | | Row's `target_value` references a credential | Use a Named Credential alias; never inline secrets | Secrets in workbook = leak | | Workbook has no Integrations section | Add it, even if empty | An empty section is information; a missing one is a gap | | Two reviewers disagree on a row | Promote disagreement to `notes`, leave `status: proposed`, escalate to architect | Workbook isn't the venue for un-resolved decisions | --- ## Recommended Workflow Step-by-step instructions for an AI agent or practitioner authoring this workbook: 1. **Intake** — pull approved user stories and fit-gap rows. Confirm every story has at least one fit-gap row and every gap row has at least one story; flag the others to the BA before writing any workbook content. 2. **Outline** — instantiate the 10 canonical sections (in order) using `templates/config-workbook.md`. Empty sections stay in the file with a one-line `not-in-scope-this-release` note. 3. **Populate** — for each in-scope change, author one or more rows per Pattern 1 + Pattern 3. Every row must have `source_req_id`, `source_story_id`, exactly one `recommended_agent`, at least one `recommended_skills[]` entry, and `status: proposed`. 4. **Review** — share with the admin team and BA. Reviewers reject any row that is missing canonical fields, references a `recommended_agent` that isn't in the runtime roster, or carries a placeholder status. 5. **Version-lock** — at sprint commit, run `python3 scripts/check_workbook.py --workbook docs/workbooks//cwb.md`, fix any errors, set every in-scope row's `status: committed`, and tag the file. From this point the file is immutable. 6. **Hand off** — for each row, hand `(row_id, recommended_agent, recommended_skills[], target_value, source_req_id)` to the downstream agent. The downstream agent reads the row, executes the change, and reports back with the metadata path it produced. 7. **Close out** — update each executed row's `status: executed` and link the deployed metadata path. Cross-link the row back to the RTM so the release report can show every gap row → workbook row → metadata file. --- ## Review Checklist Before declaring the workbook ready for sprint commit: - [ ] Every row has a unique `row_id` - [ ] Every row has both `source_req_id` and `source_story_id` - [ ] Every row has exactly one `recommended_agent` from the runtime roster - [ ] Every row has at least one entry in `recommended_skills[]` - [ ] No row has a placeholder `status` — `TBD`, `WIP`, `DOING`, `NEXT`, `?`, a bare to-do marker, or empty - [ ] All 10 canonical sections exist (empty sections carry a `not-in-scope-this-release` note) - [ ] No row carries an inline credential, password, or token - [ ] `python3 scripts/check_workbook.py --workbook ` exits 0 --- ## 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. --- ## Output Artifacts | Artifact | Description | |---|---| | `cwb.md` | The 10-section markdown workbook authored from `templates/config-workbook.md`. The committed sprint copy lives at `docs/workbooks//cwb.md`. | | `cwb.json` | Machine-readable JSON envelope of the rows for downstream agents. | | `cwb.csv` | Flat CSV export with one row per workbook row; useful for review in spreadsheets. | | RTM linkage block | A short markdown table mapping `row_id → source_req_id → source_story_id → recommended_agent → status`. Lives at the top of `cwb.md`. | --- ## Official Sources Used See `references/well-architected.md`. --- ## Related Skills - `admin/custom-field-creation` — what an Objects+Fields row references but does not duplicate. - `admin/permission-set-architecture` — what a Profiles+PSG row references. - `admin/sharing-and-visibility` — what a Sharing Settings row references. - `admin/validation-rules` — what a Validation Rules row references. - `admin/lightning-app-builder-advanced` — what a Lightning Pages row references. - `admin/reports-and-dashboards` — what a Reports+Dashboards row references. - `data-loader-pre-flight` agent — consumer for Data + Migration rows. - `agents/object-designer/AGENT.md` — primary consumer for Objects+Fields rows. - `agents/permission-set-architect/AGENT.md` — primary consumer for PSG rows. - `agents/flow-builder/AGENT.md` — primary consumer for Automation rows. - `standards/decision-trees/automation-selection.md` — cited by every Automation row. - `standards/decision-trees/sharing-selection.md` — cited by every Sharing Settings row.