From f3948e1bdf849297c5cec1d92b58c8c047e4cf6e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 25 Aug 2026 00:40:17 +0000 Subject: [PATCH] Add consumer-side Pickleball guidance pointers for Copilot and README. Keep the nested AGENTS.md exporter one-liner, add the same bootstrap for IntelliJ Copilot Chat, and point the consumer README at AGENTS.md without copying the full guide or snapshotting those bridges. Co-authored-by: ds-code-t --- docs/agent/README.md | 4 +- docs/agent/feature-map.md | 2 +- docs/agent/repository-index.md | 1 + docs/consumer-project.md | 2 +- .../.github/copilot-instructions.md | 1 + maven-consumer-project/README.md | 2 + .../diagnostic/PickleballGuidanceChecks.java | 1 + scripts/refresh_agent_index.py | 1 + scripts/verify_agent_contract.py | 84 ++++++++++++------- .../pickleball/guidance/docs/agent/README.md | 4 +- .../guidance/docs/agent/feature-map.md | 2 +- .../guidance/docs/agent/repository-index.md | 1 + .../guidance/docs/consumer-project.md | 2 +- 13 files changed, 69 insertions(+), 38 deletions(-) create mode 100644 maven-consumer-project/.github/copilot-instructions.md diff --git a/docs/agent/README.md b/docs/agent/README.md index b3324a47..efb17fb1 100644 --- a/docs/agent/README.md +++ b/docs/agent/README.md @@ -20,7 +20,9 @@ Agent adapters should remain small and point back to the canonical contract rath The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. -The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation and should not duplicate the AI guidance lifecycle. +The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. + +The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation. It may point humans and agents at `AGENTS.md` for guidance export, but should not duplicate the AI guidance lifecycle. `export-guidance .pickleball` is deliberately unconditional before Pickleball work. A successful export writes `.pickleball/GUIDANCE-MANIFEST.json` last, removes obsolete previously managed files, and refreshes current dependency guidance. Git-ignore handling is best effort. If export fails, existing `.pickleball` content is potentially stale. diff --git a/docs/agent/feature-map.md b/docs/agent/feature-map.md index 3a2226af..8fcff1d1 100644 --- a/docs/agent/feature-map.md +++ b/docs/agent/feature-map.md @@ -19,7 +19,7 @@ This file maps consumer-visible capabilities to implementation anchors, executab | Custom element definitions/catalog context | `ExecutionDictionary.java`; `ElementMatch.java`; consumer `PickleballTests.java`; search `category(`, `inheritsFrom` | `catalog-context.feature`; `forms-dynamic-steps.feature`; `site/catalog.html` | `docs/custom-element-definitions.md`; `docs/config-files-and-resource-mapping.md` | | Mapping, ParsingMap/NodeMap, templates/directives | `MappingSteps.java`; `FileAndDataParsing.java`; `MappingProcessor.java`; `NodeMap.java`; `ParsingMap.java`; `ValueFormatting.java`; `common/dataelements` | `mapping-and-resources.feature`; `mapping-value-type-preservation.feature`; `scenario-data-references.feature`; Data Element features; internal Java checks | `docs/mapping-and-templating.md`; `docs/data-values-and-elements.md`; `docs/data-element-query-runtime.md`; `docs/config-files-and-resource-mapping.md` | | Configuration/profiles/RunVars | `PKB_props.java`; `PickleballProfiles.java`; `PkbPropertyValueNormalizer.java`; runner/config classes; search `pkb_profile`, `pkb_runvars`, `pkb_run_profile`, `pkb_configpath` | `configuration-system-properties.feature`; `ProfileConfigurationChecks.java`; consumer properties/profile examples | `docs/configuration.md`; `docs/getting-started.md`; `docs/ai-run-configuration.md`; `docs/consumer-project.md` | -| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` | +| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; `maven-consumer-project/AGENTS.md`; `maven-consumer-project/.github/copilot-instructions.md`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` | | Diagnostic reporting and controlled reruns | `src/main/java/tools/dscode/common/reporting/diagnostic`; diagnostic aspects; `DiagnosticCli.java`; `VisualFingerprintComparator.java`; `DiagnosticRunComparator.java` | `DiagnosticReportingChecks.java`; `Diagnostic213CompletionChecks.java`; diagnostic features | `docs/diagnostic-reporting.md`; `docs/ai-diagnostic-reporting-plan.md`; `docs/ai-run-configuration.md`; root `AGENTS.md` | | Nested steps/block conditionals | search `Nested`, `Conditional`, `Block`, `Condition` in core implementation | `nested-and-block-conditionals.feature` | `docs/nested-steps.md`; `docs/block-conditionals.md` | | Component scenarios/reusable RUN/selectors/markers | `ModularScenarios.java`; `ScenarioStep.java`; `ScenarioStepData.java`; `StepBase.java`; `StepExtension.java`; `CurrentScenarioState.java`; `CucumberScanUtil.java`; search `finalizerSteps`, `RunSelection` | `component-scenarios.feature`; `reusable-scenario-selection.feature`; `run-step-parameter-variations.feature`; marker features | `docs/component-scenarios.md`; `docs/service-call-scenarios.md`; `docs/data-values-and-elements.md` | diff --git a/docs/agent/repository-index.md b/docs/agent/repository-index.md index 6d0e3fea..163dbf16 100644 --- a/docs/agent/repository-index.md +++ b/docs/agent/repository-index.md @@ -9,6 +9,7 @@ This inventory helps coding agents discover relevant files. It does not replace - `build.gradle` - `gradlew` - `gradlew.bat` +- `maven-consumer-project/.github/copilot-instructions.md` - `maven-consumer-project/.mvn/wrapper/maven-wrapper.properties` - `maven-consumer-project/AGENTS.md` - `maven-consumer-project/mvnw` diff --git a/docs/consumer-project.md b/docs/consumer-project.md index c4954679..4633e07b 100644 --- a/docs/consumer-project.md +++ b/docs/consumer-project.md @@ -42,7 +42,7 @@ The snapshot includes: - static local test-site resources; and - the committed shared/local `profiles*.yaml` and `pickleball*.properties` examples. -It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` bridge, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot. +It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` and `.github/copilot-instructions.md` bridges, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot. ## Purpose diff --git a/maven-consumer-project/.github/copilot-instructions.md b/maven-consumer-project/.github/copilot-instructions.md new file mode 100644 index 00000000..e303a3a3 --- /dev/null +++ b/maven-consumer-project/.github/copilot-instructions.md @@ -0,0 +1 @@ +Before any Pickleball work, run `mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.common.reporting.diagnostic.DiagnosticCli" "-Dexec.classpathScope=test" "-Dexec.args=export-guidance .pickleball"` and, after a successful export, follow `.pickleball/AGENT-GUIDE.md`. diff --git a/maven-consumer-project/README.md b/maven-consumer-project/README.md index 1046cff6..f0fd1bfb 100644 --- a/maven-consumer-project/README.md +++ b/maven-consumer-project/README.md @@ -2,6 +2,8 @@ This is a standalone Maven example project that consumes Pickleball as a test-scoped dependency and exercises browser and service behavior against its local test site. +Before Pickleball work, export guidance and see `AGENTS.md`. + ## Run ```bash diff --git a/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java b/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java index c0bc3c08..be4a697d 100644 --- a/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java +++ b/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java @@ -112,6 +112,7 @@ void dependencyExportsVersionMatchedGuidanceAndManifest() throws Exception { )); assertTrue(managedFiles.stream().noneMatch(path -> path.contains("_local2"))); assertFalse(managedFiles.contains("maven-consumer-project/AGENTS.md")); + assertFalse(managedFiles.contains("maven-consumer-project/.github/copilot-instructions.md")); assertFalse(managedFiles.contains("maven-consumer-project/mvnw")); assertFalse(managedFiles.contains( "maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java" diff --git a/scripts/refresh_agent_index.py b/scripts/refresh_agent_index.py index d498019f..b70dc42a 100644 --- a/scripts/refresh_agent_index.py +++ b/scripts/refresh_agent_index.py @@ -31,6 +31,7 @@ "gradlew", "gradlew.bat", "maven-consumer-project/AGENTS.md", + "maven-consumer-project/.github/copilot-instructions.md", "maven-consumer-project/pom.xml", "maven-consumer-project/README.md", "maven-consumer-project/mvnw", diff --git a/scripts/verify_agent_contract.py b/scripts/verify_agent_contract.py index 7ce81450..4ef92196 100644 --- a/scripts/verify_agent_contract.py +++ b/scripts/verify_agent_contract.py @@ -47,6 +47,7 @@ "scripts/agent_validate.sh", "scripts/agent_validate.ps1", "maven-consumer-project/AGENTS.md", + "maven-consumer-project/.github/copilot-instructions.md", "maven-consumer-project/README.md", "maven-consumer-project/.gitignore", "maven-consumer-project/mvnw", @@ -79,7 +80,6 @@ "maven-consumer-project/GEMINI.md", "maven-consumer-project/REVIEW.md", "maven-consumer-project/.clinerules", - "maven-consumer-project/.github/copilot-instructions.md", } ADAPTER_FILES = ( "CLAUDE.md", @@ -136,6 +136,7 @@ "pickleball-workbench/AGENTS.md", "maven-consumer-project/README.md", "maven-consumer-project/AGENTS.md", + "maven-consumer-project/.github/copilot-instructions.md", } WORKBENCH_CONTRACT_FILES = ( @@ -278,43 +279,57 @@ def starts_with_any(path: str, prefixes: tuple[str, ...]) -> bool: return any(path.startswith(prefix) for prefix in prefixes) -def validate_consumer_bridge(errors: list[str]) -> None: - bridge = ROOT / "maven-consumer-project" / "AGENTS.md" - if not bridge.is_file(): - return +CONSUMER_BRIDGE_FILES = ( + "maven-consumer-project/AGENTS.md", + "maven-consumer-project/.github/copilot-instructions.md", +) - text = bridge.read_text(encoding="utf-8").strip() - nonblank_lines = [line for line in text.splitlines() if line.strip()] - if len(nonblank_lines) != 1: - errors.append( - "Consumer AGENTS bridge must stay a single nonblank bootstrap line: " - "maven-consumer-project/AGENTS.md" - ) - for required in ( - "DiagnosticCli", - "export-guidance", - ".pickleball/AGENT-GUIDE.md", - ): - if required not in text: - errors.append( - f"Consumer AGENTS bridge must reference {required}: " - "maven-consumer-project/AGENTS.md" - ) +def validate_consumer_bridge(errors: list[str]) -> None: + texts: list[str] = [] + for relative in CONSUMER_BRIDGE_FILES: + path = ROOT / relative + if not path.is_file(): + continue - for forbidden in ( - "GUIDANCE-MANIFEST.json", - ".git/info/exclude", - "pkb_changed_variables", - "runProfileFingerprint", - "Diagnostic investigation protocol", - ): - if forbidden in text: + text = path.read_text(encoding="utf-8").strip() + texts.append(text) + nonblank_lines = [line for line in text.splitlines() if line.strip()] + if len(nonblank_lines) != 1: errors.append( - f"Consumer AGENTS bridge contains dependency-owned guidance ({forbidden}); " - "keep only the bootstrap command and generated-guide pointer." + "Consumer guidance bridge must stay a single nonblank bootstrap line: " + + relative ) + for required in ( + "DiagnosticCli", + "export-guidance", + ".pickleball/AGENT-GUIDE.md", + ): + if required not in text: + errors.append( + f"Consumer guidance bridge must reference {required}: {relative}" + ) + + for forbidden in ( + "GUIDANCE-MANIFEST.json", + ".git/info/exclude", + "pkb_changed_variables", + "runProfileFingerprint", + "Diagnostic investigation protocol", + ): + if forbidden in text: + errors.append( + f"Consumer guidance bridge contains dependency-owned guidance ({forbidden}); " + "keep only the bootstrap command and generated-guide pointer: " + + relative + ) + + if len(texts) == len(CONSUMER_BRIDGE_FILES) and len(set(texts)) != 1: + errors.append( + "Consumer AGENTS.md and .github/copilot-instructions.md bridges must be identical." + ) + def validate_consumer_readme(errors: list[str]) -> None: readme = ROOT / "maven-consumer-project" / "README.md" @@ -322,6 +337,11 @@ def validate_consumer_readme(errors: list[str]) -> None: return text = readme.read_text(encoding="utf-8") + if "AGENTS.md" not in text: + errors.append( + "Consumer README must point to AGENTS.md for guidance export: " + "maven-consumer-project/README.md" + ) for forbidden in ( "export-guidance", ".pickleball/", diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md b/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md index b3324a47..efb17fb1 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md @@ -20,7 +20,9 @@ Agent adapters should remain small and point back to the canonical contract rath The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. -The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation and should not duplicate the AI guidance lifecycle. +The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. + +The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation. It may point humans and agents at `AGENTS.md` for guidance export, but should not duplicate the AI guidance lifecycle. `export-guidance .pickleball` is deliberately unconditional before Pickleball work. A successful export writes `.pickleball/GUIDANCE-MANIFEST.json` last, removes obsolete previously managed files, and refreshes current dependency guidance. Git-ignore handling is best effort. If export fails, existing `.pickleball` content is potentially stale. diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md b/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md index 3a2226af..8fcff1d1 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md @@ -19,7 +19,7 @@ This file maps consumer-visible capabilities to implementation anchors, executab | Custom element definitions/catalog context | `ExecutionDictionary.java`; `ElementMatch.java`; consumer `PickleballTests.java`; search `category(`, `inheritsFrom` | `catalog-context.feature`; `forms-dynamic-steps.feature`; `site/catalog.html` | `docs/custom-element-definitions.md`; `docs/config-files-and-resource-mapping.md` | | Mapping, ParsingMap/NodeMap, templates/directives | `MappingSteps.java`; `FileAndDataParsing.java`; `MappingProcessor.java`; `NodeMap.java`; `ParsingMap.java`; `ValueFormatting.java`; `common/dataelements` | `mapping-and-resources.feature`; `mapping-value-type-preservation.feature`; `scenario-data-references.feature`; Data Element features; internal Java checks | `docs/mapping-and-templating.md`; `docs/data-values-and-elements.md`; `docs/data-element-query-runtime.md`; `docs/config-files-and-resource-mapping.md` | | Configuration/profiles/RunVars | `PKB_props.java`; `PickleballProfiles.java`; `PkbPropertyValueNormalizer.java`; runner/config classes; search `pkb_profile`, `pkb_runvars`, `pkb_run_profile`, `pkb_configpath` | `configuration-system-properties.feature`; `ProfileConfigurationChecks.java`; consumer properties/profile examples | `docs/configuration.md`; `docs/getting-started.md`; `docs/ai-run-configuration.md`; `docs/consumer-project.md` | -| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` | +| Consumer guidance export/reference snapshot | `DiagnosticCli.java`; `gradle/consumer-guidance.gradle`; `scripts/sync_consumer_guidance.py`; `maven-consumer-project/AGENTS.md`; `maven-consumer-project/.github/copilot-instructions.md`; search `export-guidance`, `GUIDANCE-MANIFEST.json` | `PickleballGuidanceChecks.java`; consumer guidance contract checks | `docs/consumer-agent-guide.md`; `docs/consumer-project.md` | | Diagnostic reporting and controlled reruns | `src/main/java/tools/dscode/common/reporting/diagnostic`; diagnostic aspects; `DiagnosticCli.java`; `VisualFingerprintComparator.java`; `DiagnosticRunComparator.java` | `DiagnosticReportingChecks.java`; `Diagnostic213CompletionChecks.java`; diagnostic features | `docs/diagnostic-reporting.md`; `docs/ai-diagnostic-reporting-plan.md`; `docs/ai-run-configuration.md`; root `AGENTS.md` | | Nested steps/block conditionals | search `Nested`, `Conditional`, `Block`, `Condition` in core implementation | `nested-and-block-conditionals.feature` | `docs/nested-steps.md`; `docs/block-conditionals.md` | | Component scenarios/reusable RUN/selectors/markers | `ModularScenarios.java`; `ScenarioStep.java`; `ScenarioStepData.java`; `StepBase.java`; `StepExtension.java`; `CurrentScenarioState.java`; `CucumberScanUtil.java`; search `finalizerSteps`, `RunSelection` | `component-scenarios.feature`; `reusable-scenario-selection.feature`; `run-step-parameter-variations.feature`; marker features | `docs/component-scenarios.md`; `docs/service-call-scenarios.md`; `docs/data-values-and-elements.md` | diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/agent/repository-index.md b/src/main/resources/META-INF/pickleball/guidance/docs/agent/repository-index.md index 6d0e3fea..163dbf16 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/agent/repository-index.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/agent/repository-index.md @@ -9,6 +9,7 @@ This inventory helps coding agents discover relevant files. It does not replace - `build.gradle` - `gradlew` - `gradlew.bat` +- `maven-consumer-project/.github/copilot-instructions.md` - `maven-consumer-project/.mvn/wrapper/maven-wrapper.properties` - `maven-consumer-project/AGENTS.md` - `maven-consumer-project/mvnw` diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md index c4954679..4633e07b 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md @@ -42,7 +42,7 @@ The snapshot includes: - static local test-site resources; and - the committed shared/local `profiles*.yaml` and `pickleball*.properties` examples. -It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` bridge, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot. +It intentionally excludes Maven wrappers, Git/IDE/generated artifacts, the consumer `AGENTS.md` and `.github/copilot-instructions.md` bridges, internal Java verification classes, and maintainer-only `_local2` files. It is reference material, not another consumer project to edit or run. Make changes in the real consumer project; a future guidance export may replace every managed file in this snapshot. ## Purpose