@salesforce/afv-skills 1.63.0 → 1.64.0

package/skills/nonprofit-volunteer-management-records-create/scripts/tests/test_render_review_table.py

@@ -0,0 +1,421 @@
+"""Tests for render-review-table.py — the fixed-column review table.
+
+Run from the skill's scripts/tests directory:
+    cd contributed-skills/npc-titan/nonprofit-volunteer-management-records-create/scripts/tests
+    python3 -m unittest test_render_review_table
+
+Covers: one column order for every row regardless of the order fields arrive in, label
+headers, lookups last, required fields shown as needs-input, optional fields with no value
+omitted, only reuse and needs-input tags printed, the Name column dropped when the row label shows it, same-on-every-row columns moved
+above the table, identical-row grouping (and --expand), and the spec errors the agent can hit.
+"""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SCRIPT = os.path.join(os.path.dirname(HERE), "render-review-table.py")
+
+_spec = importlib.util.spec_from_file_location("render_review_table", SCRIPT)
+rrt = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(rrt)
+GUIDE = rrt.parse_field_guide(rrt.DEFAULT_FIELD_GUIDE)
+
+
+def f(value, origin="given"):
+    return {"value": value, "origin": origin}
+
+
+def render(spec, expand=False):
+    return rrt.build_table(spec, GUIDE, expand=expand)
+
+
+def run_cli(spec, *args):
+    return subprocess.run([sys.executable, SCRIPT, *args], input=json.dumps(spec),
+                          capture_output=True, text=True)
+
+
+def header_row(table):
+    return [line for line in table.splitlines() if line.startswith("| Record")][0]
+
+
+def body_rows(table):
+    lines = table.splitlines()
+    start = lines.index(header_row(table)) + 2
+    rows = []
+    for line in lines[start:]:
+        if not line.startswith("|"):
+            break
+        rows.append([c.strip() for c in line.strip().strip("|").split("|")])
+    return rows
+
+
+def headers(table):
+    return [c.strip() for c in header_row(table).strip().strip("|").split("|")]
+
+
+class FieldGuideParsing(unittest.TestCase):
+    def test_every_creatable_entity_is_parsed(self):
+        for entity in ("VolunteerInitiative", "Location", "Address", "OperatingHours",
+                       "TimeSlot", "Position", "PositionQualification", "JobPosition",
+                       "JobPositionQualification", "JobPositionShift", "Competency",
+                       "Examination"):
+            self.assertIn(entity, GUIDE, entity)
+            self.assertTrue(GUIDE[entity], entity)
+
+    def test_relationship_rows_map_to_api_names(self):
+        apis = {fld["api"]: fld for fld in GUIDE["JobPosition"]}
+        self.assertIn("VolunteerInitiativeId", apis)
+        self.assertTrue(apis["VolunteerInitiativeId"]["lookup"])
+        self.assertFalse(apis["Title"]["lookup"])
+        self.assertTrue(apis["Title"]["schema_required"])
+
+
+class MixedKeyOrder(unittest.TestCase):
+    """The defect this script exists for: fields arriving in a different order per record."""
+
+    def spec(self):
+        return {"entity": "JobPositionShift", "records": [
+            {"label": "Sat 3 Oct", "fields": {
+                "JobPositionId": f("Greeter — Eastside", "reuse"),
+                "StartDate": f("2026-10-03"), "EndDate": f("2026-10-03"),
+                "StartTime": f("09:00"), "EndTime": f("12:00"),
+                "TimeZone": f("America/Chicago", "default"),
+                "Status": f("Upcoming", "default"), "MaximumAttendeesCount": f(8)}},
+            {"label": "Sun 4 Oct", "fields": {
+                "MaximumAttendeesCount": f(6), "Status": f("Draft"),
+                "EndTime": f("16:00"), "TimeZone": f("America/Denver"),
+                "StartTime": f("13:00"), "EndDate": f("2026-10-04"),
+                "StartDate": f("2026-10-04"),
+                "JobPositionId": f("Greeter — Westside", "reuse")}},
+            {"label": "Sat 10 Oct", "fields": {
+                "Status": f("Upcoming", "default"), "StartTime": f("09:00"),
+                "JobPositionId": f("Greeter — Eastside", "reuse"),
+                "TimeZone": f("America/Chicago", "default"), "EndDate": f("2026-10-10"),
+                "MaximumAttendeesCount": f(8), "EndTime": f("12:00"),
+                "StartDate": f("2026-10-10")}},
+        ]}
+
+    def test_every_value_lands_under_its_own_header(self):
+        table = render(self.spec())
+        cols = headers(table)
+        rows = body_rows(table)
+        self.assertEqual(len(rows), 3)
+        expected = [
+            {"Start Date": "2026-10-03", "Start Time": "09:00", "End Time": "12:00",
+             "Maximum Attendees Count": "8", "Status": "Upcoming",
+             "Time Zone": "America/Chicago", "Job Position": "Greeter — Eastside `reuse`"},
+            {"Start Date": "2026-10-04", "Start Time": "13:00", "End Time": "16:00",
+             "Maximum Attendees Count": "6", "Status": "Draft",
+             "Time Zone": "America/Denver", "Job Position": "Greeter — Westside `reuse`"},
+            {"Start Date": "2026-10-10", "Start Time": "09:00", "End Time": "12:00",
+             "Maximum Attendees Count": "8", "Status": "Upcoming",
+             "Time Zone": "America/Chicago", "Job Position": "Greeter — Eastside `reuse`"},
+        ]
+        for row, want in zip(rows, expected):
+            cells = dict(zip(cols, row))
+            for header, value in want.items():
+                self.assertEqual(cells[header], value, header)
+
+    def test_column_order_is_tier_order_then_lookups(self):
+        cols = headers(render(self.spec()))
+        self.assertEqual(cols, [
+            "Record", "Start Date", "End Date", "Start Time", "End Time", "Time Zone",
+            "Status", "Maximum Attendees Count", "Job Position"])
+
+    def test_order_does_not_depend_on_the_first_record(self):
+        spec = self.spec()
+        reversed_spec = {"entity": spec["entity"], "records": list(reversed(spec["records"]))}
+        self.assertEqual(headers(render(spec)), headers(render(reversed_spec)))
+
+    def test_relationship_name_and_api_name_are_one_column(self):
+        spec = {"entity": "JobPosition", "records": [
+            {"fields": {"Name": f("A"), "Title": f("A"),
+                        "VolunteerInitiative": f("Food Pantry", "reuse")}},
+            {"fields": {"Name": f("B"), "Title": f("B"),
+                        "VolunteerInitiativeId": f("Food Drive", "reuse")}},
+        ]}
+        cols = headers(render(spec))
+        self.assertEqual(cols.count("Volunteer Initiative"), 1)
+        self.assertEqual(cols[-1], "Volunteer Initiative")
+
+
+class Headers(unittest.TestCase):
+    def test_labels_not_api_names(self):
+        spec = {"entity": "VolunteerInitiative", "records": [
+            {"fields": {"Name": f("Child"), "ParentVolunteerInitiative":
+                        f("Parent Program", "reuse")}}]}
+        cols = headers(render(spec))
+        self.assertIn("Parent Volunteer Initiative", cols)
+        self.assertNotIn("ParentVolunteerInitiativeId", cols)
+
+    def test_describe_label_overrides(self):
+        spec = {"entity": "JobPosition",
+                "labels": {"VolunteerInitiativeId": "Related Volunteer Initiative"},
+                "records": [{"fields": {"Name": f("A"), "Title": f("A"),
+                                        "VolunteerInitiativeId": f("P", "new")}}]}
+        self.assertIn("Related Volunteer Initiative", headers(render(spec)))
+
+    def test_custom_fields_after_standard_before_lookups(self):
+        spec = {"entity": "JobPosition", "records": [{"fields": {
+            "Name": f("A"), "Title": f("A"), "Region__c": f("North"),
+            "LocationId": f("Eastside Hall", "reuse")}}]}
+        cols = headers(render(spec))
+        self.assertEqual(cols, ["Record", "Title", "Region", "Location"])
+
+
+class MissingFields(unittest.TestCase):
+    def test_optional_field_with_no_value_is_omitted(self):
+        spec = {"entity": "VolunteerInitiative", "records": [
+            {"fields": {"Name": f("A"), "Status": f("Upcoming", "default")}},
+            {"fields": {"Name": f("B"), "Status": f("Upcoming", "default")}}]}
+        cols = headers(render(spec))
+        self.assertNotIn("Start Date", cols)
+        self.assertNotIn("Description", cols)
+
+    def test_optional_field_set_on_one_row_shows_dash_elsewhere(self):
+        spec = {"entity": "VolunteerInitiative", "records": [
+            {"fields": {"Name": f("A"), "Description": f("Weekly pantry", "generated")}},
+            {"fields": {"Name": f("B")}}]}
+        table = render(spec)
+        cells = dict(zip(headers(table), body_rows(table)[1]))
+        self.assertEqual(cells["Description"], "—")
+
+    def test_required_field_missing_shows_needs_input(self):
+        spec = {"entity": "JobPosition", "records": [{"fields": {"Name": f("Greeter")}}]}
+        table = render(spec)
+        cells = dict(zip(headers(table), body_rows(table)[0]))
+        self.assertEqual(cells["Title"], "`needs-input`")
+        self.assertIn("Still needed before this can be written: Title (row 1)", table)
+
+    def test_explicit_needs_input_origin(self):
+        spec = {"entity": "Location", "records": [
+            {"fields": {"Name": f("Eastside Hall"),
+                        "LocationType": f(None, "needs-input")}},
+            {"fields": {"Name": f("Westside Hall"),
+                        "LocationType": f(None, "needs-input")}}]}
+        table = render(spec)
+        self.assertIn("Location Type (rows 1, 2)", table)
+
+    def test_schema_required_blank_value_is_needs_input(self):
+        spec = {"entity": "JobPosition", "records": [
+            {"fields": {"Name": f("A"), "Title": f("", "given")}}]}
+        self.assertIn("Title (row 1)", render(spec))
+
+    def test_always_set_but_not_schema_required_can_be_left_blank(self):
+        spec = {"entity": "Address", "records": [{"fields": {
+            "ParentId": f("Eastside Hall", "new"), "LocationType": f("Business Site"),
+            "Street": f("12 Main St"), "City": f("Austin"), "State": f("TX"),
+            "PostalCode": f("78701"), "Country": f("", "given")}}]}
+        table = render(spec)
+        cells = dict(zip(headers(table), body_rows(table)[0]))
+        self.assertEqual(cells["Country"], "—")
+        self.assertNotIn("Still needed", table)
+
+    def test_required_custom_field(self):
+        spec = {"entity": "JobPosition", "requiredCustomFields": ["Region__c"],
+                "records": [{"fields": {"Name": f("A"), "Title": f("A")}}]}
+        table = render(spec)
+        self.assertIn("Region", headers(table))
+        self.assertIn("Region (row 1)", table)
+
+
+class Grouping(unittest.TestCase):
+    def spec(self):
+        same = {"JobPositionId": f("Sorter", "reuse"), "StartDate": f("2026-10-03"),
+                "EndDate": f("2026-10-03"), "StartTime": f("09:00"), "EndTime": f("12:00"),
+                "TimeZone": f("America/Chicago", "default")}
+        other = dict(same, StartTime=f("13:00"), EndTime=f("16:00"))
+        return {"entity": "JobPositionShift", "records": [
+            {"fields": dict(same)}, {"fields": dict(same)}, {"fields": dict(same)},
+            {"fields": other}]}
+
+    def test_identical_rows_collapse(self):
+        rows = body_rows(render(self.spec()))
+        self.assertEqual(len(rows), 2)
+        self.assertTrue(rows[0][0].startswith("Rows 1–3"))
+        self.assertIn('say "show all 3"', rows[0][0])
+        self.assertEqual(rows[1][0], "4")
+
+    def test_expand_lists_every_row(self):
+        rows = body_rows(render(self.spec(), expand=True))
+        self.assertEqual([r[0] for r in rows], ["1", "2", "3", "4"])
+
+    def test_only_consecutive_rows_group(self):
+        spec = self.spec()
+        spec["records"] = [spec["records"][0], spec["records"][3], spec["records"][1]]
+        self.assertEqual(len(body_rows(render(spec))), 3)
+
+    def test_different_names_do_not_group(self):
+        spec = {"entity": "Competency", "records": [
+            {"fields": {"Name": f("Forklift")}}, {"fields": {"Name": f("First Aid")}}]}
+        self.assertEqual(len(body_rows(render(spec))), 2)
+
+
+class NameColumn(unittest.TestCase):
+    def test_name_matching_label_is_not_repeated(self):
+        spec = {"entity": "Position", "records": [
+            {"fields": {"Name": f("Planter"), "Description": f("Plants trees", "generated")}},
+            {"fields": {"Name": f("Site Lead", "generated"),
+                        "Description": f("Leads the crew", "generated")}}]}
+        table = render(spec)
+        self.assertNotIn("Name", headers(table))
+        self.assertEqual([r[0] for r in body_rows(table)],
+                         ["1 · Planter", "2 · Site Lead"])
+
+    def test_name_kept_when_a_label_differs(self):
+        spec = {"entity": "Position", "records": [
+            {"label": "Role A", "fields": {"Name": f("Planter")}},
+            {"fields": {"Name": f("Site Lead")}}]}
+        self.assertIn("Name", headers(render(spec)))
+
+    def test_missing_name_keeps_the_column(self):
+        spec = {"entity": "JobPosition", "records": [
+            {"fields": {"Name": f(None, "needs-input"), "Title": f("A")}}]}
+        table = render(spec)
+        self.assertIn("Name", headers(table))
+        self.assertIn("Name (row 1)", table)
+
+    def test_same_fields_different_names_still_two_rows(self):
+        spec = {"entity": "Position", "records": [
+            {"fields": {"Name": f("Planter"), "Status": f("Upcoming", "default")}},
+            {"fields": {"Name": f("Waterer"), "Status": f("Upcoming", "default")}}]}
+        self.assertEqual(len(body_rows(render(spec))), 2)
+
+
+class SharedColumns(unittest.TestCase):
+    def spec(self):
+        return {"entity": "JobPosition", "records": [
+            {"fields": {"Name": f("Planter – LA"), "Title": f("Planter", "default"),
+                        "Status": f("Upcoming", "default"),
+                        "LocationId": f("Los Angeles", "new")}},
+            {"fields": {"Name": f("Planter – NY"), "Title": f("Planter", "default"),
+                        "Status": f("Upcoming", "default"),
+                        "LocationId": f("New York", "new")}}]}
+
+    def test_same_value_on_every_row_moves_above_the_table(self):
+        table = render(self.spec())
+        self.assertIn("Same on every row: Title Planter · Status Upcoming", table)
+        self.assertEqual(headers(table), ["Record", "Location"])
+
+    def test_a_single_row_keeps_every_column(self):
+        spec = self.spec()
+        spec["records"] = spec["records"][:1]
+        table = render(spec)
+        self.assertNotIn("Same on every row", table)
+        self.assertIn("Status", headers(table))
+
+    def test_needs_input_column_stays_in_the_table(self):
+        spec = {"entity": "Location", "records": [
+            {"fields": {"Name": f("A"), "LocationType": f(None, "needs-input")}},
+            {"fields": {"Name": f("B"), "LocationType": f(None, "needs-input")}}]}
+        table = render(spec)
+        self.assertIn("Location Type", headers(table))
+        self.assertNotIn("Same on every row", table)
+
+    def test_rows_that_differ_only_in_shared_columns_still_group(self):
+        spec = {"entity": "JobPositionShift", "records": [
+            {"fields": {"JobPositionId": f("Sorter", "reuse"), "StartDate": f("2026-10-03"),
+                        "StartTime": f("09:00")}}] * 3}
+        rows = body_rows(render(spec))
+        self.assertEqual(len(rows), 1)
+        self.assertTrue(rows[0][0].startswith("Rows 1–3"))
+
+
+class OriginTags(unittest.TestCase):
+    def spec(self):
+        return {"entity": "JobPosition", "records": [{"fields": {
+            "Name": f("Planter – LA"), "Title": f("Planter", "default"),
+            "Description": f("Plant trees", "generated"),
+            "LocationId": f("Los Angeles", "new"),
+            "VolunteerInitiativeId": f("Tree Planting – LA", "reuse")}}]}
+
+    def test_only_reuse_is_tagged(self):
+        table = render(self.spec())
+        cells = dict(zip(headers(table), body_rows(table)[0]))
+        self.assertEqual(cells["Title"], "Planter")
+        self.assertEqual(cells["Description"], "Plant trees")
+        self.assertEqual(cells["Location"], "Los Angeles")
+        self.assertEqual(cells["Volunteer Initiative"], "Tree Planting – LA `reuse`")
+        for tag in ("`given`", "`default`", "`generated`", "`new`"):
+            self.assertNotIn(tag, table)
+
+    def test_reuse_note_only_when_a_cell_is_reused(self):
+        self.assertIn("`reuse` = links to a record already in your org", render(self.spec()))
+        spec = self.spec()
+        spec["records"][0]["fields"]["VolunteerInitiativeId"] = f("Tree Planting – LA", "new")
+        self.assertNotIn("`reuse` =", render(spec))
+
+    def test_needs_input_note_when_something_is_missing(self):
+        spec = {"entity": "JobPosition", "records": [{"fields": {"Name": f("Greeter")}}]}
+        self.assertIn("`needs-input` = required, still missing", render(spec))
+
+
+class Title(unittest.TestCase):
+    def test_default_title_counts_rows(self):
+        spec = {"entity": "Competency", "records": [
+            {"fields": {"Name": f("A")}}, {"fields": {"Name": f("B")}}]}
+        self.assertTrue(render(spec).startswith("Records to insert — 2 Competencies"))
+
+    def test_series_title_override(self):
+        spec = {"entity": "JobPositionShift",
+                "title": "Records to insert — 12 Job Position Shifts (1 series)",
+                "records": [{"label": "Saturdays 9:00–12:00", "fields": {
+                    "JobPositionId": f("Driver", "new"),
+                    "StartDate": f("every Saturday from 3 Oct 2026"),
+                    "EndDate": f("same day"), "StartTime": f("09:00"), "EndTime": f("12:00"),
+                    "TimeZone": f("America/Chicago", "default")}}]}
+        table = render(spec)
+        self.assertTrue(table.startswith("Records to insert — 12 Job Position Shifts (1 series)"))
+        self.assertNotIn("Still needed", table)
+
+
+class Errors(unittest.TestCase):
+    def assert_fails(self, spec, fragment):
+        result = run_cli(spec)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn(fragment, result.stderr)
+
+    def test_unknown_entity(self):
+        self.assert_fails({"entity": "JobPositionAssignment",
+                           "records": [{"fields": {"Name": f("x")}}]}, "unknown entity")
+
+    def test_undocumented_field(self):
+        self.assert_fails({"entity": "Position", "records": [
+            {"fields": {"Name": f("x"), "Category": f("y")}}]}, "not in field-guide.md")
+
+    def test_system_managed_field(self):
+        self.assert_fails({"entity": "JobPositionShift", "records": [
+            {"fields": {"RemainingCapacity": f(3)}}]}, "system-managed")
+
+    def test_bad_origin(self):
+        self.assert_fails({"entity": "Competency", "records": [
+            {"fields": {"Name": f("x", "seeded")}}]}, "origin")
+
+    def test_lookup_needs_reuse_or_new(self):
+        self.assert_fails({"entity": "JobPosition", "records": [{"fields": {
+            "Name": f("x"), "Title": f("x"), "LocationId": f("Hall", "given")}}]},
+            "is a lookup")
+
+    def test_lookup_shows_name_not_id(self):
+        self.assert_fails({"entity": "JobPosition", "records": [{"fields": {
+            "Name": f("x"), "Title": f("x"),
+            "LocationId": f("131Hs000000Abc1IAC", "reuse")}}]}, "looks like a record Id")
+
+    def test_empty_records(self):
+        self.assert_fails({"entity": "Competency", "records": []}, "non-empty list")
+
+    def test_cli_happy_path(self):
+        result = run_cli({"entity": "Competency", "records": [
+            {"fields": {"Name": f("Forklift Operation")}}]})
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("Records to insert — 1 Competency", result.stdout)
+        self.assertIn("| 1 · Forklift Operation |", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/nonprofit-volunteer-management-structure-generate/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: nonprofit-volunteer-management-structure-generate
+description: "Use this skill to plan a Salesforce Nonprofit Cloud Volunteer Management (VM) program before anything is created: it interviews the user about their programs, sites, volunteer roles, requirements, and shift schedules, checks the org read-only for records to reuse, and presents a plan of the records the program needs. It never writes; on the user's yes it hands the plan to nonprofit-volunteer-management-records-create. TRIGGER when a user wants to plan, design, or structure a VM program, or asks \"what records do we need\" or \"how should we model this program\". DO NOT TRIGGER to explain what a VM object or field is for (use nonprofit-volunteer-management-model-get), to write records (use nonprofit-volunteer-management-records-create), to enable Volunteer Management in an org, for per-person records (JobPositionAssignment, PersonLocationAvailability, PersonCompetency / PersonExamination, ConstituentRole), or for NPSP / Volunteers for Salesforce (V4S), which is unsupported."
+metadata:
+  version: "1.2"
+  domains: ["Nonprofit"]
+  relatedSkills:
+    - "nonprofit-volunteer-management-model-get"
+    - "nonprofit-volunteer-management-records-create"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck: "(OrgPermissions.VolunteerManagement) && (OrgPreferences.VolunteerManagementEnabled)"
+---
+
+# Nonprofit Cloud Volunteer Management — Structure Planning
+
+This skill turns a description of a volunteer program ("I run a weekly food pantry with team leads and general volunteers") into a plan of Volunteer Management records: the Volunteer Initiatives, Locations, Competencies, Examinations, Positions, Job Positions, their qualifications, and Job Position Shift series the program needs. It asks the discovery questions, walks through each configuration decision, checks the org for records it can reuse, and presents the plan. It adds only the structure the program needs.
+
+## Hard rules
+
+- **Never delete records.** No delete, rollback or cleanup of any kind. If a write fails part-way, report what was created and what wasn't; never undo it.
+- **Never act on NPSP or Volunteers for Salesforce (V4S).** That legacy package is unsupported here. Say so and stop.
+- **No acronyms or internal labels in what the user sees.** Write out Volunteer Initiative, Job Position, Job Position Shift, Job Position Assignment, Position Qualification, Job Position Qualification, Data Processing Engine, and "out of the box". Never show internal step or section labels, or a record's Id: name a reused record by its name; its Id goes only in the handoff.
+- **Never create records.** This skill plans. It hands the plan to `nonprofit-volunteer-management-records-create` only after the user answers yes to "Do you want to create the records from the plan?".
+
+## Mechanism
+
+Org calls go through the connection the session has: the headless-360 tools (`dispatch_readonly` only; this skill never writes) or an authenticated Salesforce CLI. Both return the same results at API v67.0. Tell the user which one is in use. If neither is connected, stop and ask the user to connect one; never guess an org result. The exact call for each step, in both forms, is in `references/mcp-invocation.md`.
+
+This skill only reads. With no org connection, planning still completes; see step 1.
+
+## Scope
+
+- **In scope:** the discovery interview, the configuration decisions, reuse checks against the org, the plan summary, and handing a confirmed plan to `nonprofit-volunteer-management-records-create`.
+- **Out of scope:** writing records (records-create), setting field values (records-create's `field-guide.md`), explaining what an entity or field means (`nonprofit-volunteer-management-model-get`), turning Volunteer Management on, and day-to-day operations such as matching, assignments, or a volunteer's own availability and qualifications. Operating Hours and Time Slots are not planned here; records-create creates them only when the user asks for them.
+
+## Required Inputs
+
+- **The user's description of the program.** The interview fills in the rest.
+- **An org connection (optional).** Used only for reads, and only after the user agrees.
+
+**Defaults (Start Simple).** Recommend these unless the interview shows a clear need for more:
+
+- One Volunteer Initiative, with no parent.
+- No Position template; qualifications go on the Job Position unless the role is reused.
+- One Job Position for the tasks the same volunteers do at one place ("greet guests and help set up" is one Job Position). Split it only when the user wants separate sign-up or tracking per task.
+- No shifts unless volunteers sign up for set times.
+
+A default is a recommendation. It is decided only when the user picks it.
+
+When the user arrives with the decisions already made, still read `references/configuration-decisions.md` and `references/plan-output.md` before writing the plan; they hold the platform behaviors the plan has to state correctly.
+
+## Workflow
+
+1. **Ask for read consent.** Before the first org read, say what you'll read (the Volunteer Management check and the reuse checks) and why, and get a yes. Warn that declining means existing records can't be checked, so duplicates may be created. If the user declines, or no org is connected, skip steps 2 and 5 and keep planning; the plan is stamped `Reuse-check: DECLINED`. If the user agrees to some reads but not others, the plan is also stamped `DECLINED`. Without the read, a record the user says already exists stays New in the table; its Reason says the user named it and records-create finds and reuses it before writing.
+2. **Check that Volunteer Management is on**, once, after the user agrees to the org read (calls in `references/mcp-invocation.md`):
+   1. Read the org preference `VolunteerManagementEnabled`. `true` → on. `false` or 404 → off: stop and tell the user an admin turns it on in Setup → Volunteer Management Settings. 403 → the user has no access to org settings: stop and say so.
+   2. Describe `VolunteerInitiative`. 200 → the user can see the Volunteer Management objects. Any error → stop and tell the user they need the Manage Volunteer Data permission set. Don't look up permission-set assignments beforehand.
+3. **Run the discovery interview** (`references/discovery-interview.md`). Ask about these topics in this order, whatever the program's complexity: programs and how they relate, locations, roles, delivery format (onsite, virtual, hybrid), qualifications, scheduling, capacity. Stay on one topic at a time. Note anything the user says early about a later topic, but don't jump ahead. Finish every topic before deciding anything, then summarize what you heard and ask the user to correct it.
+4. **Walk the configuration decisions** (`references/configuration-decisions.md`), one per turn: Locations, parent Volunteer Initiative, Position template, shifts or no shifts, recurrence, and qualifications (including whether a requirement belongs on the role or on the person). For each, say what you heard, give the options, recommend one with the reason, name the platform behavior that matters, and ask. Wait for an explicit answer before the next decision.
+5. **Check for existing records** before planning anything as New. Run each check when its decision comes up, so the user decides with the org in view. The Volunteer Initiative check runs before the parent Volunteer Initiative decision. Check every planned record by its natural key:
+
+   | Record | Natural key |
+   |---|---|
+   | Volunteer Initiative, Location, Position, Competency, Examination | Name |
+   | Job Position | Name + Volunteer Initiative |
+
+   Filter each query to the names in the plan, never the whole object. Escape apostrophes in names with a backslash. Locations, Competencies, Examinations and Positions are meant to be shared across programs, so look for them by the distinctive word stems too, and run the query again with a shorter stem when a near-match could be worded differently. When a match turns up, show it and ask whether it's the record the user means. Job Positions always get the check: if the Volunteer Initiative is New, check by name only; a match belongs to another initiative, so the Job Position is still New and records-create checks again before writing.
+6. **Present the plan (message 1).** Read `references/plan-output.md` and use its template: the summary table, then one or two lines each, only where they apply, for what was left out on purpose, the schedule, what these records don't do on their own, and outstanding inputs, then the `Reuse-check:` line. Check that the plan is complete first. Don't restate the table or add other sections. End the message with exactly one question: "Do you want to see the additional configuration and extensions you can set up beyond these records?"
+7. **Offer the additional configuration (message 2).** Send this only after the user answers, and never in the same response as the plan. On yes, show the Additional Configuration Considerations checklist and the Extensions table from `references/plan-output.md`, both in full and both informational, then ask "Do you want to create the records from the plan?" as the last line. On no ("no", "skip that"), the answer covers only the additional configuration, not the records: reply with only "Do you want to create the records from the plan?" and wait. Never treat it as a no to creating the records. If the user asks for changes instead, update the plan and repeat step 6.
+8. **Act on the create answer.** On yes, hand the plan to `nonprofit-volunteer-management-records-create`. On no, or if the user wanted only the plan, stop. If the user asks for changes instead, update the plan and repeat step 6.
+
+**Reuse-check line.** Every plan carries exactly one of these:
+
+- `Reuse-check: RESOLVED — org read; the Reuse/New mapping is authoritative`
+- `Reuse-check: DECLINED — org not read (or read only in part); every unchecked record planned as New; records-create checks before writing`
+
+If the line is missing or unrecognized, records-create runs its own reuse checks.
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| One read consent before any org read; declining doesn't stop planning | The user controls access to their org. Without the read, duplicates are possible, so the plan says so |
+| Ask the discovery topics in order and finish them all before deciding anything | Later answers often change earlier decisions |
+| One configuration decision per turn: recommend, then ask | These are the user's decisions: how many volunteers is too many, which qualifications matter, whether a program needs its own initiative |
+| Never plan a record as New without checking the org first (unless the read was declined) | Orgs collect Volunteer Management records over time; a duplicate splits the data |
+| Filter every reuse query to the planned names; never read a whole object | A reuse check looks for matches. It is not an inventory of the org |
+| Presenting the plan isn't consent; an earlier "go ahead" isn't consent | Only a yes to "Do you want to create the records from the plan?" lets records-create write |
+| Offer the checklist and Extensions after the plan and before the create question; on yes, show them in full, as information only. Don't offer to build them or suggest they'll be done later | The user owns that work. Shown with the plan it buries the question; shown after the create answer it scrolls away under the records step |
+| Every limit that applies to a planned record goes in the plan itself, under "What these records don't do on their own" | A user who skips the additional configuration still needs to know a maximum isn't enforced or an approval flag does nothing on its own |
+| A shift's maximum is counted, never enforced: nothing blocks a sign-up to a full shift until the customer adds a validation rule. Never say the platform stops sign-ups on its own | Saying the cap stops sign-ups leaves the user with overbooked shifts |
+| Volunteer matching uses only Competency qualifications with a required level. A requirement a volunteer must meet before being matched (a background check, a training) is a Competency; an Examination is for manual checks and compliance tracking only | An Examination never affects who is matched |
+| Every Position Qualification or Job Position Qualification has a row for the Competency or Examination it points at, Reuse or New | A qualification can't be created without the record it references |
+| The plan records decisions, not fields. Never write a field name or "TBD" in it | records-create sets field values from its field guide and asks for anything missing |
+| Hand schedule details to records-create; don't plan Operating Hours, Time Slots or individual shifts for an existing Job Position | records-create builds the shift series and checks for shifts that already exist |
+| Don't change existing records, org settings, users or permissions. Point out a misconfigured record, but leave it as it is | This skill only reads |
+
+## Output Expectations
+
+- **Message 1:** the plan summary table (Record · Name · Reuse or New · Belongs to · Decision); then, each in a line or two and only when it applies, what was left out on purpose, one line per shift series, what these records don't do on their own, and the outstanding inputs; the `Reuse-check:` line; and "Do you want to see the additional configuration and extensions you can set up beyond these records?" as the last line. Nothing in the message repeats the table.
+- **Message 2:** on yes, the Additional Configuration Considerations checklist and the Extensions table in full; either way, "Do you want to create the records from the plan?" as the last line.
+- **Handoff (only on yes):** the plan table, the Id of each reused record, the schedule details, the outstanding inputs and the `Reuse-check:` line, passed to `nonprofit-volunteer-management-records-create`.
+
+## Cross-Skill Integration
+
+- **`nonprofit-volunteer-management-model-get`**: what an entity, field or feature means. Use it when the user asks "what is…" during planning.
+- **`nonprofit-volunteer-management-records-create`**: writes the confirmed plan. It owns field values, the write order, the existing-shift check, and Operating Hours and Time Slots.
+
+## Reference File Index
+
+| File | Used in |
+|---|---|
+| `references/mcp-invocation.md` | Steps 2 and 5 — the exact calls for the Volunteer Management check and each reuse check, for headless-360 and the Salesforce CLI |
+| `references/discovery-interview.md` | Step 3 — the discovery questions, probing prompts and summary |
+| `references/configuration-decisions.md` | Step 4 — each configuration decision, its options, default and platform behaviors |
+| `references/plan-output.md` | Steps 6–8 — the plan template, schedule details, platform limits, completeness check, checklist, Extensions table and handoff |
+| `references/edge-cases.md` | Any step — hybrid programs, existing records, contradictions, several programs |