afv-library/rules/a4v-expert-global-rule.md

Rule: Salesforce Metadata Generation

Objective

Enforce: skill load -> API context -> file generation for all Salesforce metadata.

Constraints

1. Never write without a loaded metadata type skill for that type.
2. One type at a time - complete the full cycle for the current type before moving to the next type.
3. Always attempt salesforce-api-context MCP for each type before writing; if it is unavailable after a real attempt, proceed with the loaded skill only.
4. Child types need their own API context response - if adding child metadata inside a parent metadata file, load the child metadata skill and use salesforce-api-context MCP for each child type separately; do not rely on the parent's schema or API context response for child metadata creation. The same fallback in constraint 3 applies.
5. Max one clarifying question before starting.
6. Do not call execute_metadata_action unless a skill instructs you to do so.

Skill Selection

• Search available skills and load the best-matching app-level skill first when the request asks for a Lightning app, end-to-end solution, or a business app spanning multiple metadata types.
• Search available skills and load the best-matching per-type metadata skill first when the request targets individual metadata components.

Initial Gate

Never create files or generate metadata before completing skill selection.

1. Determine whether the request is app-level or metadata-type-level.
2. Search available skills for the request and identify the best-matching candidate skill.
3. If the request is app-level, load the best-matching app-level skill by reading its contents and use it to identify metadata types and dependency order.
4. If the request is metadata-type-level, identify the target metadata type and the best-matching per-type metadata skill for that type. Do not treat skill selection as the per-type skill-load step.
5. Confirm skill selection with: intent=<app|type> selected_skill=<exact-skill-name|none> skill_selection=complete|pending
6. Set skill_selection=complete only after the exact selected skill name has been identified and recorded.
7. Print this exact skill-selection status line in the chat before proceeding.

Do not continue until skill_selection=complete and selected_skill=<exact-skill-name|none> are recorded.

Per-Type Loop (a-e)

For each metadata type in scope, whether identified by an app-level skill or requested directly, execute steps a through e below one metadata type at a time. Do not create or modify files for the current metadata type, and do not move to the next metadata type, until steps a through e are complete.

a. Load Skill

• Search available skills for the best-matching skill for the current metadata type and load it by reading its SKILL.md.
• Record selected_skill=<exact-skill-name|none> for the current metadata type before proceeding.
• Load once per type, not per record.
• If no skill exists after a real search, stop and ask for guidance instead of writing without a skill.

b. Use salesforce-api-context MCP

• Use one or more of these tools as required:
  • get_metadata_type_sections
  • get_metadata_type_context
  • get_metadata_type_fields
  • get_metadata_type_fields_properties
  • search_metadata_types
• Attempt API context for every type before writing.
• Record which tools were called for the current metadata type before proceeding.
• If API context is unavailable after a real attempt, record that state and continue with the loaded skill only.
• Treat templates, generators, pipelines, and CLI bootstraps as implementation aids, not as replacements for this gate.

c. Pre-Write Gate

• Before EVERY write: confirm selected_skill=<exact-skill-name> is recorded and that skill is loaded for this type.
• Before EVERY write: confirm mcp_tools=<tool-list> is recorded for this type, or confirm mcp=unavailable after a real attempt.
• If selected_skill=none or the skill is missing -> stop.
• If mcp_tools=none and mcp is not unavailable -> stop and call MCP now.

d. Generate Files

• Use skill constraints + API context when available.
• Use skill constraints only when API context was unavailable after a real attempt.
• Generate all records for this type now.

e. Checkpoint

• Record: type=<metadata-type> selected_skill=<exact-skill-name|none> skill=complete|pending mcp=complete|pending|unavailable mcp_tools=<tool-list|none>
• Skill loaded? API context called or unavailable after a real attempt? All files written?
• Only proceed to the next type when all are true.

Anti-Patterns

Don't	Why	Do
Never write without loading the metadata skill	Missing platform constraints	Search for and load the skill before any write
Never mark skill_selection=complete without `selected_skill=<exact-skill-name	none>`	Fake gate completion
Never treat skill selection as skill loading	Fake gate completion	Perform the actual per-type skill load in step a
Never skip the Initial Gate	Sequence breach	Complete skill selection before any generation
Never reload a skill per record	Wastes tokens	Load once per type
Never skip the API context attempt for any type	No schema for those types	Attempt API context for EVERY type
Never write using API context alone without a loaded skill	Missing platform constraints	Stop and ask for guidance when no skill exists
Never write without recorded mcp_tools or mcp=unavailable	No evidence of MCP gate completion	Record MCP tool usage before any write
Never ask more than 1 clarifying question	Token waste	Max 1 question
Never skip any gate in the loop (skill load, API context, pre-write, checkpoint)	Wrong artifacts	Follow all mandatory gates in the loop (a-e)
Never write with a missing checkpoint	Aware violation	Stop and complete missing step