Issue #129 Keep templates user-focused; AGENTS for contributors

Author: simbo1905

.github/ISSUE_TEMPLATE.md

@@ -9,7 +9,9 @@ assignees: ""
 
 (Optional) When submitting an Issue, please consider using a "deep research" tool to sanity check your proposal. Then **before** submission, run your draft through a strong model with a prompt such as:
 
-> "Please review the AGENTS.md and README.md along with this draft Issue and check that it does not have any gaps — why it might be insufficient, incomplete, lacking a concrete example, duplicating prior issues or PRs, or not be aligned with the project goals or non‑goals."
+> "Please review README.md along with this draft Issue and check that it does not have any gaps — why it might be insufficient, incomplete, lacking a concrete example, duplicating prior issues or PRs, or not be aligned with the project goals or non‑goals."
+
+If you used an AI assistant while preparing this Issue, ensure it followed the contributor/agent workflow rules in `AGENTS.md`.
 
 (Optional)  Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review". 
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,7 +9,9 @@ assignees: ''
 
 (Optional) When submitting a bug report, please consider using an AI assistant to help create a minimal test case that demonstrates the issue. Then **before** submission, run your bug description through a strong model with a prompt such as:
 
-> "Please review the AGENTS.md and README.md along with this bug report and check that it includes: a clear description of the problem, steps to reproduce, expected vs actual behavior, and a minimal test case that demonstrates the bug."
+> "Please review README.md along with this bug report and check that it includes: a clear description of the problem, steps to reproduce, expected vs actual behavior, and a minimal test case that demonstrates the bug."
+
+If you used an AI assistant while preparing this report, ensure it followed the contributor/agent workflow rules in `AGENTS.md`.
 
 (Optional) Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review".
 

.github/ISSUE_TEMPLATE/custom.md

@@ -9,8 +9,9 @@ assignees: ''
 
 (Optional) When submitting this issue, please consider using an AI assistant to help analyze and articulate the problem. Then **before** submission, run your issue description through a strong model with a prompt such as:
 
-> "Please review the AGENTS.md and README.md along with this issue description and check that it: clearly explains the problem or request, provides sufficient context, includes relevant details, and aligns with project standards."
+> "Please review README.md along with this issue description and check that it: clearly explains the problem or request, provides sufficient context, includes relevant details, and aligns with project standards."
 
-(Optional) Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review".
+If you used an AI assistant while preparing this issue, ensure it followed the contributor/agent workflow rules in `AGENTS.md`.
 
+(Optional) Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review".
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -9,7 +9,9 @@ assignees: ''
 
 (Optional) When submitting a feature request, please consider using an AI assistant to validate your implementation approach. Then **before** submission, run your feature description through a strong model with a prompt such as:
 
-> "Please review the AGENTS.md and README.md along with this feature request and check that it: aligns with project goals, doesn't duplicate existing functionality, includes concrete use cases, and suggests a reasonable implementation approach."
+> "Please review README.md along with this feature request and check that it: aligns with project goals, doesn't duplicate existing functionality, includes concrete use cases, and suggests a reasonable implementation approach."
+
+If you used an AI assistant while preparing this request, ensure it followed the contributor/agent workflow rules in `AGENTS.md`.
 
 (Optional) Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review".
 

.github/pull_request_template.md

@@ -1,7 +1,9 @@
 
-(Optional) When submitting an PR, please consider using a "deep research" tool to sanity check your proposal. Then **before** submission, run your draft through a strong model with a prompt such as:
+(Optional) When submitting a PR, please consider using a "deep research" tool to sanity check your proposal. Then **before** submission, run your draft through a strong model with a prompt such as:
 
-> "Please review the AGENTS.md and README.md along with this draft PR and check that it does not have any gaps — why it might be insufficient, incomplete, lacking a concrete example, duplicating prior issues or PRs, or not be aligned with the project goals or non‑goals."
+> "Please review README.md along with this draft PR and check that it does not have any gaps — why it might be insufficient, incomplete, lacking a concrete example, duplicating prior issues or PRs, or not be aligned with the project goals or non‑goals."
+
+If you used an AI assistant while preparing this PR, ensure it followed the contributor/agent workflow rules in `AGENTS.md`.
 
 (Optional)  Please then attach both the prompt and the model's review to the bottom of this template under "Augmented Intelligence Review". 
 
@@ -28,4 +30,3 @@
 
 **(Optional) Augmented Intelligence Review**: 
 *Both prompt and model out, asking a strong model to double-check your submission, from the perspective of a maintainer of this repo* 
-

AGENTS.md

@@ -3,6 +3,8 @@
 ## Purpose & Scope
 - Operational guidance for human and AI agents working in this repository. This revision preserves all existing expectations while improving structure and wording in line with agents.md best practices.
 
+User-facing documentation lives in `README.md`. Keep this file focused on contributor/agent workflow, debugging, and coding standards.
+
 ## Operating Principles
 - Follow the sequence plan → implement → verify; do not pivot without restating the plan.
 - Stop immediately on unexpected failures and ask before changing approach.
@@ -138,14 +140,8 @@ throw new IllegalArgumentException("bad value"); // No specifics
 Use `Json.toDisplayString(value, depth)` to render JSON fragments in error messages, and include relevant context like schema paths, actual vs expected values, and specific constraint violations.
 
 ## JSON Compatibility Suite
-```bash
-# Build and run compatibility report
-mvn clean compile generate-test-resources -pl json-compatibility-suite
-mvn exec:java -pl json-compatibility-suite
 
-# Run JSON output (dogfoods the API)
-mvn exec:java -pl json-compatibility-suite -Dexec.args="--json"
-```
+See `README.md` for user-facing commands. When running locally as an agent, use the Maven wrapper described in this file.
 
 ## Architecture Overview
 
@@ -202,35 +198,7 @@ IMPORTANT: Bugs in the main logic this code cannot be fixed in this repo they **
 
 ## Common Workflows
 
-### API Compatibility Testing
-1. Run the compatibility suite: `mvn exec:java -pl json-compatibility-suite`.
-2. Inspect reports for regressions relative to upstream expectations.
-3. Validate outcomes against the official JSON Test Suite.
-
-## Module Reference
-
-### json-java21
-- Main library delivering the core JSON API.
-- Maven coordinates: `io.github.simbo1905.json:json-java21:0.X.Y`.
-- Requires Java 21 or newer.
-
-### json-compatibility-suite
-- Automatically downloads the JSON Test Suite from GitHub.
-- Surfaces known vulnerabilities (for example, StackOverflowError under deep nesting).
-- Intended for education and testing, not production deployment.
-
-### json-java21-api-tracker
-- Tracks API evolution and compatibility changes.
-- Uses Java 24 preview features (`--enable-preview`).
-- Runner: `io.github.simbo1905.tracker.ApiTrackerRunner` compares the public JSON API (`jdk.sandbox.java.util.json`) with upstream `java.util.json`.
-- Workflow fetches upstream sources, parses both codebases with the Java compiler API, and reports matching/different/missing elements across modifiers, inheritance, methods, fields, and constructors.
-- Continuous integration prints the report daily. It does not fail or open issues on differences; to trigger notifications, either make the runner exit non-zero when `differentApi > 0` or parse the report and call `core.setFailed()` within CI.
-
-### json-java21-jtd (JTD Validator)
-- JSON Type Definition validator implementing RFC 8927 specification.
-- Provides eight mutually-exclusive schema forms for simple, predictable validation.
-- Uses stack-based validation with comprehensive error reporting.
-- Includes full RFC 8927 compliance test suite.
+Prefer linking to `README.md` for stable, user-facing workflows and module descriptions. Keep this file focused on agent execution details.
 
 #### Debugging Exhaustive Property Tests