diff --git a/AGENTS.md b/AGENTS.md index 8d580c3..a847f2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,7 @@ that correction durable in the relevant file under `docs/agents/`. - [Project Identity](docs/agents/project-identity.md) - [README Guidance](docs/agents/readme.md) - [Skill Behavior](docs/agents/skill-behavior.md) +- [Ownership Boundaries](docs/agents/ownership-boundaries.md) - [Eval Guidance](docs/agents/evals.md) - [Public Metadata And OSS Readiness](docs/agents/public-metadata.md) - [Maintaining Agent Docs](docs/agents/maintaining-agent-docs.md) diff --git a/README.md b/README.md index 76ab089..a61b390 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,16 @@ as a design choice rather than a default optimization. It also tells the agent to check the project Java version first. The right stream code for Java 8 may be different from the right code for Java 17, Java 21, or Java 24. +General lambda and callback style lives in the companion package +`martinfrancois/java-functional-style`; see [Ownership Boundaries](#ownership-boundaries). + ## Contents - [Getting Started](#getting-started) - [Why This Exists](#why-this-exists) - [Common Stream Mistakes](#common-stream-mistakes) - [What It Helps With](#what-it-helps-with) +- [Ownership Boundaries](#ownership-boundaries) - [How It's Evaluated](#how-its-evaluated) - [Origin](#origin) - [Contributing](#contributing) @@ -241,6 +245,23 @@ Poor fit: - large API redesigns or new dependencies without maintainer agreement; - changing business behavior just to make code look more functional. +## Ownership Boundaries + +`martinfrancois/java-streams` owns stream and collector semantics. General lambda and callback +style (identity functions, no-op stages, helper extraction, comparator composition, +method-reference pitfalls, supplier laziness, checked boundaries in callbacks) is owned by the +companion package `martinfrancois/java-functional-style` +([repository](https://github.com/martinfrancois/java-functional-style-skill)), and Optional +semantics by `martinfrancois/java-optionals` +([repository](https://github.com/martinfrancois/java-optionals-skill)). + +Each package works on its own. Install the companion next to this one when stream cleanup also +involves non-trivial callbacks: + +```bash +npx tessl i martinfrancois/java-functional-style +``` + ## How It's Evaluated The skill is tested on Java stream implementation, review, and cleanup tasks. Each task is run diff --git a/docs/agents/ownership-boundaries.md b/docs/agents/ownership-boundaries.md new file mode 100644 index 0000000..19de8df --- /dev/null +++ b/docs/agents/ownership-boundaries.md @@ -0,0 +1,47 @@ +# Ownership Boundaries + +## Scope + +Use this when changing runtime guidance, README wording, evals, or companion-package documentation +for Java Streams. This page holds the only full list of who owns what; other pages link here. + +## Rules + +- `java-streams` owns stream and collector semantics: terminal operation choice, collector choice, + duplicate-key and null behavior, encounter order, primitive streams, `findFirst` versus + `findAny`, `parallelStream`, `Gatherers.mapConcurrent`, stream Java-version compatibility, and + stream-specific behavior preservation. It also keeps its own short "lambdas as glue" rule and its + preference for method references, because the published stream evals measure them. +- `martinfrancois/java-functional-style` owns general Java lambda and functional-interface style: + identity functions, no-op functional stages, helper extraction from block callbacks, comparator + composition, method-reference pitfalls (receiver binding, overloads, boxing), supplier laziness, + checked-exception boundaries inside callbacks, and callback side-effect boundaries. +- `martinfrancois/java-optionals` owns Optional semantics. +- Each package works on its own. Don't make stream guidance depend on the companion being installed, + and don't remove stream guidance because the companion also covers it. +- Don't grow generic lambda guidance here. When a functional-style gap shows up in stream work, fix + it in the companion and add stream-side text only if hosted evidence proves the stream evals need + it. + +## Composition Check + +Adding the companion must not make this skill worse. The check runs this repository's evals, +unchanged, with both skills injected as context and requires 100% with-context for every scenario +in the run: + +```bash +# from a checkout of java-functional-style-skill, next to this repository +scripts/run_composed_eval.sh ../java-streams-skill main +``` + +The main suite is required whenever either package changes runtime text; run `reference` and +`regression` too when the change touches review wording or when budget allows. The companion +repository owns the runner and runs the check before its releases; this repository runs it when +its own runtime changes. Local validation alone doesn't satisfy this check. + +## References + +- [Skill Behavior](skill-behavior.md) +- [README Guidance](readme.md) +- [Eval Guidance](evals.md) +- [Workflow](workflow.md) diff --git a/docs/agents/skill-behavior.md b/docs/agents/skill-behavior.md index 7a101f7..6d33be0 100644 --- a/docs/agents/skill-behavior.md +++ b/docs/agents/skill-behavior.md @@ -42,6 +42,8 @@ guidance, or auto-selection wording. - Keep stream lambdas as short glue. Prefer method references or one-expression lambdas whose body stays on the same line as `->`, and extract named helpers for branching, loops, temporary variables, formatting, merge rules, or nested stream chains that would continue on later lines. + This rule stays here because the published stream evals measure it; deeper callback-style + guidance belongs to the companion package, see [Ownership Boundaries](ownership-boundaries.md). - Runtime guidance should keep internal workflow language out of ordinary user-facing reviews. Avoid terms such as "hard stop", "marker", "scan", "checklist", and skill names unless the user asked for an explicit skill workflow, audit, or scan command. @@ -52,3 +54,4 @@ guidance, or auto-selection wording. - [README Guidance](readme.md) - [Eval Guidance](evals.md) +- [Ownership Boundaries](ownership-boundaries.md) diff --git a/docs/agents/workflow.md b/docs/agents/workflow.md index fb6bd9e..76929e1 100644 --- a/docs/agents/workflow.md +++ b/docs/agents/workflow.md @@ -126,6 +126,9 @@ release-readiness. Follow the recommendation unless the pull request documents a maintainer-approved override. +- When runtime skill text changes, also run the composition check in + [Ownership Boundaries](ownership-boundaries.md) so the companion package still composes cleanly. + - Run the Tessl skill quality review at threshold 100 when changing runtime skill content: ```bash