Address dev-experience feedback: tone, durability, AIC naming, skill purpose by george-bafaloukas-forgerock · Pull Request #8 · pingidentity/agent-plugins

george-bafaloukas-forgerock · 2026-06-22T13:47:23Z

Summary

Implements the actionable items from Dave Ernsting's feedback in the #dev-experience channel about the agent-plugins skills. Each item was re-validated against the current code before implementing.

Changes

Tone — no negative framing about Ping docs/product (#3)

Rewrote the node-fundamentals.md intro to state what the file is and enables ("behavioural invariants… complements the per-node reference docs") instead of "not documented clearly in official docs and are common sources of bugs".
Neutralised the Okta/Auth0 migration note in common-starting-patterns.md.

Durability — no statements that go stale (#2)

Replaced dated/release-channel statements ("Rapid channel as of 2026-06-03", "Regular channel promotion planned", "not yet GA", "from Q3 2026") with capability + a link to the live release notes/docs.
Removed the dead "PingOne Recognize — not yet GA" routing line; de-temporalised one "Currently unused".

Naming — pingone-st prose → AIC (#1, safe part)

Corrected user/agent-facing prose to "PingOne Advanced Identity Cloud (AIC)" across platform-families.md, capability-map.md, service-map.md, and the authoring rules — including a real contradiction where platform-families.md defined pingone-st as "PingOne ST / ForgeRock lineage".
Kept the locked pingone-st schema enum / directory tag (renaming it is a separate, larger migration — see below).

Editorial guardrails (#6)

Added an "Editorial principles — accuracy, tone, durability" section + a pingone-st→AIC naming note to the authoring rules (kept in sync across both rules/authoring-rules.md and shared/templates/AUTHORING-RULES.md).

Skill purpose clarity (#4, direction C)

Added a "What this skill does for you" line to all six SKILL.md files stating whether each generates artifacts, guides through docs, or both.

Validation

scripts/validate_skills.py → OK (6 skills, 66 anchors, index.json)
evals.harness.validate_prompts → OK

Deferred (need PM alignment — tracked separately as TRIAGE/DevEx)

ID4AI scope (Update .cursor-plugin to match cursor/plugin-template spec #5): the new purpose line is worded as conceptual/non-executable to match product reality; final framing pending PM decision on whether to keep it as labelled architecture guidance or narrow it.
Full pingone-st → aic rename: schema enum + directory paths + ~130 frontmatter blocks + eval anchor paths. Self-contained migration for its own PR.

🤖 Generated with Claude Code

…y, AIC naming, skill purpose Implements actionable items from Dave Ernsting's dev-experience feedback. - Remove negative framing about Ping docs/product (node-fundamentals.md intro, Okta/Auth0 migration note) — state what content is and enables, not what docs lack - Remove temporal/release-channel statements that go stale (Rapid-channel dates, "not yet GA", "from Q3 2026") — replace with capability + link to live docs - Align pingone-st prose to "PingOne Advanced Identity Cloud (AIC)" across taxonomies and authoring rules; keep the locked pingone-st schema enum / directory tag - Add editorial-principles rule (accuracy, tone, durability) to authoring rules (both rules/authoring-rules.md and shared/templates/AUTHORING-RULES.md) - Add "What this skill does for you" line to all six SKILL.md files stating whether each generates artifacts, guides through docs, or both (direction C) ID4AI skill purpose line is worded as conceptual/non-executable to match the product reality; final framing pending PM decision (tracked separately). Validated: scripts/validate_skills.py OK (6 skills, 66 anchors); prompt validator OK. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ates Addresses gaps identified via Glean research sweep across all 6 skills. New curated anchors: - ping-foundation/cross-platform/ping-cli-basics.md — Ping CLI 1.0 unified configuration automation: install, profiles, CRUD, platform export for Terraform/CaC, CI/CD patterns, gotchas; boundaries vs MCP servers and Terraform providers - ping-foundation/cross-platform/config-promotion.md — cross-platform configuration promotion covering PingOne native promotion, AIC self-service promotions, and Ping CLI + Terraform GitOps; model selection table; hard limits and constraints (EA-framing follows editorial rule 1a — behavioural constraints only, no dated GA claims) - ping-orchestration/cross-platform/journey-and-flow-promotion.md — journey/ flow-specific promotion depth: ESV integrity checks, orphaned scripts, DaVinci flow versioning and promotion variables, environment lock impact, per-node considerations, rollback behaviour Skill routing: - ping-foundation/SKILL.md: new Cross-platform tooling section with Ping CLI and config-promotion routing rows; pingcli trigger added to description and When to use list - ping-orchestration/SKILL.md: config-promotion row added to Cross-platform orchestration patterns Eval coverage: - ping-foundation.yaml: T-80–T-82 (Ping CLI), T-83–T-85 (config promotion), N-07–N-08 - ping-orchestration.yaml: T-59–T-61 (journey/flow promotion) API docs link update (#7): - 5 legacy apidocs.pingidentity.com links replaced with verified developer.pingidentity.com/pingone-api/ canonical URLs across service-invocation-patterns.md, core-admin-patterns.md, and tenant-and-environment-setup.md - grep confirms zero remaining apidocs.pingidentity.com references All validators pass: 6 skills, 69 curated anchors, all prompt YAML valid. Layer 1 + Layer 2 evals: 100% pass rate across all 5 skills. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

brando-dill

Overall good, just left some minor comments.

brando-dill · 2026-06-23T13:16:08Z

+---
+title: "Promoting Journeys, Scripts, and DaVinci Flows Between Environments"
+product_family: cross-platform
+products: ["pingone", "pingone-st"]


Again, have we stuck with pingone and pingone-st or did we change nomenclature? Need to review every file for taxonomy.

pingone-st is correct — it's the stable internal routing tag for AIC, as established in the editorial changes on this branch (authoring-rules.md section 1a now explicitly documents: "pingone-st denotes PingOne Advanced Identity Cloud
(AIC) — never surface it as a product name in prose, but it is the correct enum value"). Every other AIC-scoped file in the repo uses pingone-st the same way.
We need to review as a bigger refactor if we want to alter that across the board

brando-dill · 2026-06-23T13:16:48Z

+- Flow policies
+- Connector configurations (connection IDs and settings)
+
+**Key gotcha:** Connector credentials (client IDs, secrets, API keys) are environment-specific. Use **promotion variables** to externalise them so the promoted flow references the target environment's credential values, not the source's.


Confirm this is accurate.

Updated this and more to be more accurate based on the docs
``

brando-dill · 2026-06-23T13:17:32Z

+
+### Flow versioning
+
+Each DaVinci flow has a **saved version** (draft) and a **published version** (live). Native PingOne promotion moves the published version. Ensure the correct version is published before triggering a promotion.


Confirm this, not as familiar with DaVinci here.

- config-promotion.md: add pingaccess, pingdirectory to products array - config-promotion.md + ping-cli-basics.md: replace hardcoded pingcli/1.0/ URLs with pingcli/latest/ to stay current across version changes (7 replacements) - am-services.md: clarify AIC email configuration — Email Provider and Email Templates under Tenant Settings, not IDM Notifications; note standalone PingIDM and PingAM behaviours separately (per Brando's correction) - common-starting-patterns.md: remove Okta/Auth0 migration section entirely (per Brando's request) Deferred for Patrick's review (comments 3, 4, 5, 8, 9 in PR #8): - pingcli accuracy in config-promotion.md (GitOps section) - recommended model selection table in config-promotion.md - ping-cli-basics.md overall accuracy - DaVinci flow versioning and promotion variables in journey-and-flow-promotion.md Taxonomy comment (comment 7): products array uses pingone-st which is the stable internal routing tag for AIC — correct per the taxonomy changes on this branch. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

/pingcli/latest/ returns 404 — the site does not implement a /latest/ alias. The unversioned /pingcli/ root correctly redirects to the current version (1.0) and is already used in the slug: field. Deep-linked subpages (/product-compatibility, /install/*, /command_reference/*) require an explicit version in the path and correctly stay at 1.0. Pattern: top-level overview link uses the unversioned /pingcli/ redirect (durable); subpage links pin to /pingcli/1.0/ (the only valid path). Labels updated to include (1.0) so version pinning is transparent to future authors. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…to factual Addresses Brando's PR #8 comment on the 'Recommended model' column — the table entries were inferred rather than sourced from Ping's own guidance. - Replace 'Recommended model' with 'Typical fit' in config-promotion.md - Replace 'Recommendation' with 'Typical fit' in journey-and-flow-promotion.md - Add 'Why' column to each table explaining the factual suitability basis (platform constraints, scope, toolchain requirements) rather than prescribing - Add pointer to developer.pingidentity.com/config-automation-promotion/ for Ping's own guidance on model selection Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…ables Verified each 'Why' claim against docs.pingidentity.com and Glean. Four fixes: 1. AIC row (both tables): remove 'only natively supported path' — docs don't use this phrasing and Terraform/community tooling are valid alternatives; replace with 'platform-provided self-service path' 2. Multi-product row (both tables): Ping CLI CRUD for PingFederate is still rolling out (compatibility matrix shows it as 'coming soon'); PingAccess and PingDirectory are absent from the Ping CLI matrix entirely. Terraform providers cover all three — the two are now distinguished; link to the live compatibility matrix so agents check current state rather than relying on frozen prose Confirmed accurate (no change needed): - Same-org constraint on PingOne native promotion - Automatic dependency management for DaVinci flows - Sequential-pairs enforcement on AIC - PingFederate server profiles / no in-console promotion UI - Terraform drift detection claim Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…haviour Connector config structure moves in PingOne native promotion, but sensitive attributes (client secrets, API keys) are blocked by the platform and cannot transfer directly. Sensitive promotion variables must be pre-created in the target environment before promotion. Verified against: - docs.pingidentity.com/pingone/early-access-features/ea-p1_configuration_management_special_handling.html - docs.pingidentity.com/pingone/early-access-features/ea-p1_promotion_key_concepts.html Also adds the dependency-inclusion note for flow policies (dependent flow versions are auto-included when a policy is promoted directly). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…motion text Verified against docs.pingidentity.com/pingone/early-access-features/: 1. 'client IDs' removed from list of sensitive attributes — client IDs are non-sensitive and do move as structural config; client secrets, API keys, and passwords are the sensitive attributes the platform gates on 2. Variable creation location corrected — variables are created in the SOURCE environment (specifying the target-environment value), not in the target. The previous text inverted the correct mental model. Now reads: 'Variables are created in the source environment with the target-specific value specified at that point' 3. 'blocks' → 'gates' — the platform issues a mandatory prompt/gate; the promotion completes once the sensitive variable exists (not a flat block on the resource itself) All other claims confirmed accurate by doc verification. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…on section Re-verified all claims against docs.pingidentity.com/pingone/early-access-features/. 1. 'Flow definitions (all versions)' → only the most recently deployed version is promoted. If version 3 is the most recently deployed of 4 versions, only version 3 moves. Official doc: 'Only the most recent deployed version of the flow is promoted to the target environment.' 2. 'moves the published version' → 'most recently deployed version'; doc uses 'deployed' not 'published' 3. Flow-policy dependency direction inverted: the correct action is to promote the FLOW POLICY (which auto-includes referenced flow versions as dependencies), not to promote the flow and separately also promote the policy. Inverting this leaves the policy out of sync. 4. Promotion variable step 2 placed assignment in the TARGET environment — official doc states: 'Variables are always created and configured in the source environment.' Target values are specified at creation time in the source. Step 2 now correctly says 'In the source environment, create a sensitive promotion variable...' Also removes 'client IDs' which reappeared in the promotion variables section — client IDs are non-sensitive structural config, not a sensitive attribute requiring a variable. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…ion section Re-verified all claims exhaustively with doc quotes. Two remaining issues: 1. 'will fail at authentication time' — this consequence is not stated in any of the four official docs pages; it was an inference presented as a documented fact. Softened to: 'the policy in the target environment may reference a different version than the one you promoted.' 2. Missing LDAP gateway carve-out: the special_handling doc explicitly states 'Gateway credentials can't be promoted or managed using promotion variables' — added as an inline exception on the connector config bullet. All other claims now confirmed with verbatim doc quotes. Section is fully backed by docs.pingidentity.com/pingone/early-access-features/ sources. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

/pingcli/latest/ URLs now resolve (confirmed 200 on all 5 paths as of 2026-06-24). Replaces all pingcli/1.0/ deep-link references in ping-cli-basics.md, config-promotion.md, and journey-and-flow-promotion.md with pingcli/latest/, matching Brando's original intent. Removes (1.0) version labels from the Source section of ping-cli-basics.md since URLs are now version-agnostic. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

patrickcping

Will need some changes RE the CLI

…ntradiction Addresses Patrick's PR #8 review comments. ping-cli-basics.md: - Remove pingcli platform export section (0.8 feature, not in 1.x) - Remove Custom API requests / pingcli request section (0.8 feature) - Remove 0.8 version note and 0.8 command-name gotcha row - Remove Terraformer plugin references throughout - Remove Terraform GitOps variant row and Terraform HCL from Prerequisites - Reframe intro/Scope to 'why Ping CLI' over 'how' per Patrick's direction - Explicitly call out platform export and pingcli request as out-of-scope with a pointer to the compatibility matrix for current 1.x feature state config-promotion.md: - Remove entire GitOps/pingcli platform export section (steps 1-6) - Replace 'exportable via pingcli platform export' with Terraform providers - Replace platform-export-specific gotcha row with Terraform provider gap row - Remove pingcli-general/exporting source link - Update related-references description to remove export mention journey-and-flow-promotion.md: - Fix Scope contradiction: 'Does NOT cover: general promotion model' was inconsistent with the DaVinci native promotion content below it; rewrite Scope to explicitly state what IS covered (AIC self-service + PingOne native promotion for DaVinci flows) vs what is not (Terraform/CaC, general model choice) - Replace 'Export with pingcli platform export' in Terraform variant row Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…verification Verified against developer.pingidentity.com/pingcli/latest/ and terraform.pingidentity.com. ping-cli-basics.md: - pingcli config view-profile → pingcli config profiles show (correct 1.x path) - Region strings com/eu/asia/sg/ca → NA/EU/AP/AU/CA/SG (1.x regionCode enum values; old strings were root domain suffixes from 0.8 config model; also adds AU which was missing entirely) - pingcli davinci flows list --application-id → -e / --environment-id (correct flag) - pingcli mfa device-policies replace → pingcli mfa mfa-device-policies replace (subcommand has mfa- prefix in 1.x) config-promotion.md: - Remove PingAccess from Terraform provider claim in two places — PingAccess has no Terraform provider; correct: PingFederate and PingDirectory only (source: developer.pingidentity.com/terraform/) - Replace 'Ping CLI export' hard limits row with 'Terraform provider coverage' row — platform export is 0.8-only; the constraint in 1.x is Terraform provider resource coverage, not CLI export scope Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

patrickcping

Couple of general comments and corrections

ping-cli-basics.md: - Scope: apply Patrick's exact suggestion — remove 0.8-specific callout, clean to 'Does NOT cover: Features below 1.x...' - Connecting Ping services: remove detailed credentials table — agent should not be responsible for connection config; replaced with pointer to official docs and a profile verification command - CI/CD: remove secret env var examples — agent should not handle secrets; kept JSON output and exit code examples, added docs pointer - Prerequisites: remove detailed credential fields; defer to official setup guide config-promotion.md: - Terraform provider row: apply Patrick's exact suggestion — 'Resource and data source support varies by provider' with pointer to terraform.pingidentity.com for available resources and data sources - Terraform rollback row: apply Patrick's exact suggestion — 'Revert to prior state file or prior apply' (remove terraform destroy) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…verification All four fixes backed by verbatim doc quotes from docs.pingidentity.com. 1. config-promotion.md (×2): PingOne native promotion excludes four services, not three — PingOne Recognize was missing. Added to both the three-models table and the 'What promotes vs what does not' table. Source: ea-p1_promote.html lists exactly four excluded services. 2. journey-and-flow-promotion.md: Terraform Typical fit row incorrectly listed PingAccess as covered by a Terraform provider. PingAccess has no provider. Consistent with config-promotion.md which already stated this correctly. Source: developer.pingidentity.com/terraform/ — PingAccess not listed. 3. config-promotion.md: Promotion variables row said target values are 'assigned in the target before applying' — incorrect. Target values are specified at variable creation time in the source environment. Source: ea-p1_create_promotion_variable.html: 'Variables are always created and configured in the source environment.' 4. journey-and-flow-promotion.md: ESV lock row said 'Blocked in the development environment during lock' — incomplete. AIC locks both source AND target. Source: AIC promotions page: 'ESV API access in both locked environments.' Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

patrickcping

LGTM

george-bafaloukas-forgerock requested review from brando-dill and patrickcping June 22, 2026 13:47

brando-dill reviewed Jun 23, 2026

View reviewed changes

george-bafaloukas-forgerock and others added 9 commits June 23, 2026 14:30

patrickcping requested changes Jun 24, 2026

View reviewed changes

george-bafaloukas-forgerock and others added 2 commits June 24, 2026 11:39

patrickcping reviewed Jun 24, 2026

View reviewed changes

george-bafaloukas-forgerock and others added 2 commits June 24, 2026 12:17

patrickcping approved these changes Jun 24, 2026

View reviewed changes


		### Flow versioning

		Each DaVinci flow has a saved version (draft) and a published version (live). Native PingOne promotion moves the published version. Ensure the correct version is published before triggering a promotion.

Conversation

george-bafaloukas-forgerock commented Jun 22, 2026

Summary

Changes

Validation

Deferred (need PM alignment — tracked separately as TRIAGE/DevEx)

Uh oh!

brando-dill left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brando-dill Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

george-bafaloukas-forgerock Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

brando-dill Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

george-bafaloukas-forgerock Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

brando-dill Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

patrickcping left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

patrickcping left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

patrickcping left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants