task/9478-add-contribution-and-other-markdown-files-to-allow-human-and-ai-contributions

[briemla]

OP#9478

[Sebastian-Gerken]

I like the direction of making contribution guidance local to the repo, but I think the current structure is doing too much in passive context.

The main issue is that AGENTS.md has become a second full handbook, while CONTRIBUTING.md and .junie/guidelines.md already cover much of the same material. That creates duplication, drift risk, and can steer agents too broadly.

I’d suggest tightening the hierarchy:

1. Keep AGENTS.md short and agent-specific: hard constraints, exact commands, and links to deeper docs.
2. Keep CONTRIBUTING.md as the source of truth for human workflow and repository policy.
3. Move detailed coding style, testing patterns, and review checklists into linked docs instead of keeping them in passive context.

I also noticed contradictions already creeping in, like the branch naming example vs the required issue-number format, which is a sign the overlap will be hard to maintain.

If this direction makes sense, I have a proposal patch ready that applies the tiered structure directly.

[briemla]

I like the direction of making contribution guidance local to the repo, but I think the current structure is doing too much in passive context.

The main issue is that AGENTS.md has become a second full handbook, while CONTRIBUTING.md and .junie/guidelines.md already cover much of the same material. That creates duplication, drift risk, and can steer agents too broadly.

I’d suggest tightening the hierarchy:

1. Keep AGENTS.md short and agent-specific: hard constraints, exact commands, and links to deeper docs.
2. Keep CONTRIBUTING.md as the source of truth for human workflow and repository policy.
3. Move detailed coding style, testing patterns, and review checklists into linked docs instead of keeping them in passive context.

I also noticed contradictions already creeping in, like the branch naming example vs the required issue-number format, which is a sign the overlap will be hard to maintain.

If this direction makes sense, I have a proposal patch ready that applies the tiered structure directly.

Your direction makes sense. I would add that the .junie/guidelines.md is a relict and can be removed from the repository. Junie should use Agents.md like all other agents.

[Sebastian-Gerken]

I've pushed a proposal commit (bb0ff82) that applies the tiered structure we discussed and removes .junie/guidelines.md entirely per @briemla's suggestion.

The change slims AGENTS.md from ~493 to ~75 lines and CONTRIBUTING.md from ~380 to ~122 lines. Detailed coding style, testing patterns (including Stage Play), and review checklists now live in docs/development/. Both top-level files link there instead of carrying the content inline.

While reviewing the result I spotted a few issues we should fix before merging:

1. The precedence sections contradict each other. AGENTS.md currently says "AGENTS > CONTRIBUTING > docs/development", CONTRIBUTING.md says the reverse, and docs/development/README.md sides with CONTRIBUTING.md. Each file claims to be the authority. We probably want an audience-scoped model instead: AGENTS.md governs agent runtime behavior, CONTRIBUTING.md governs human contribution policy, and shared rules (branch naming, commit format) stay identical in both.

2. The 90% coverage target only appears in CONTRIBUTING.md but not in docs/development/testing.md, which is supposed to be the detailed testing reference. Agents following retrieval pointers will miss it.

3. Type annotation scope is inconsistent. CONTRIBUTING.md says "new functions and methods", code-style.md says "all function signatures, including private helpers." These are different scopes.

4. uv run mypy is mentioned in CONTRIBUTING.md's command table but nowhere in docs/development/. Agents reading only the detail files won't know about it.

5. Test categories (unit/acceptance/benchmark/regression) are listed as commands in testing.md but never explained. A short section on what goes where would help.

None of these are blockers for the direction — the structure is right, these are just consistency gaps to close in a follow-up commit.