New Coding Agent Contribution Guide

Traceability

• Spec ID: new-coding-agent-contribution-guide
• Status: Implemented

Intent

Give contributors one evidence-first route for adding a Coding Agent host to Better Harness. The guide should turn the lessons visible in the Qwen Code and GitHub Copilot contributions into a reusable contract without making either pull request the source of truth.

Acceptance Scenarios

• NCAG-AC-1 (discoverable route): A contributor starting from the root AGENTS.md, root README, CONTRIBUTING.md, community extension map, canonical host matrix, or published Hosts documentation can reach the new guide.
• NCAG-AC-2 (complete host slices): The guide distinguishes native host research, thin shell metadata, configured-asset collection, session evidence, shared registration, documentation, packaging, and output routing, while allowing unsupported slices to remain explicitly unavailable.
• NCAG-AC-3 (evidence and safety): The guide requires native-contract evidence, workspace qualification, privacy-safe normalization, deterministic fixtures, real-host smoke evidence or an explicit unavailable note, and Windows/macOS/Linux validation proportional to the changed behavior.
• NCAG-AC-4 (traceable workflow): The guide routes contributors through a spec, stable acceptance ids, scoped commits, Review Readiness Check evidence, and the repository's pull request template without inventing Story, AI, CI, or host-support claims.
• NCAG-AC-5 (worked examples): The guide links PR #6 and PR #22 as contrasting worked examples and states what lesson to inspect in each, without treating their descriptions or current states as timeless contracts.
• NCAG-AC-6 (publication integrity): English canonical guidance and the English/zh-Hans curated site pages remain consistent, all relative Markdown links resolve, and the Docusaurus site builds with zero broken links.

Non-goals

• Adding, repairing, approving, merging, or otherwise changing PR #6 or PR #22.
• Adding a new host adapter, provider enum, manifest, session parser, report mode, or packaging target.
• Declaring every host capable of session evidence or every shell publishable.
• Replacing AGENTS.md, docs/ARCHITECTURE.md, docs/community.md, or the canonical host matrix as their respective sources of truth.
• Freezing third-party host internals in this guide; contributors must cite the host version and primary source they actually verified.

Plan and Tasks

1. Add docs/adapters/contributing-new-coding-agent.md as the canonical contribution workflow beside the host matrix.
2. Structure it as a sequence from research and support-scope decisions through implementation slices, evidence, packaging, documentation, and review.
3. Link the two pull requests in a bounded worked-examples section and link the repository instructions and architecture owners throughout the route.
4. Add an English curated page under docs/docs/hosts/, a matching zh-Hans translation, and sidebar routing without duplicating canonical judgment.
5. Add navigation from AGENTS.md, CONTRIBUTING.md, README.md, README.zh-CN.md, docs/community.md, docs/adapters/README.md, and the published adapter matrix pages.
6. Run the link graph, site build, focused tests, full repository tests, and a final diff/readiness review; update this status only when evidence supports it.

Test and Review Evidence

• NCAG-AC-1/5: inspect the final diff and follow every guide/PR/instruction link from each named entry page.
• NCAG-AC-6: regenerate the Better Harness Markdown graph with node scripts/doc-link-graph/cli.mjs skills/better-harness, then run node --test test/doc-link-graph.test.mjs test/docs-site.test.mjs.
• NCAG-AC-6: run npm ci && npm run build from docs/; both locales must build with zero broken links.
• NCAG-AC-2/3/4: run npm test because repository tests enforce some provider and documentation contracts; no runtime behavior should change.
• All ACs: run git diff --check, inspect staged/unstaged scope separately, and apply the Change Traceability Review Readiness Check before handoff.

Observed on 2026-07-30:

• node scripts/doc-link-graph/cli.mjs skills/better-harness regenerated the 34-file / 50-link graph with no tracked drift.
• node --test test/doc-link-graph.test.mjs test/docs-site.test.mjs passed 7/7.
• npm ci && npm run build from docs/ built English and zh-Hans with zero broken links.
• npm test passed 867/867 after preserving the tested canonical-owner phrase in the community intake matrix.
• npm run pack:verify passed with 311 npm entries and 337 runtime ZIP entries.
• git diff --check passed; the final readiness review found documentation and site-source changes only, with no staged files or generated graph drift.

Risks

• Guide drift: concrete path lists can become stale as new hosts arrive. Mitigation: point to registry/search commands and canonical owners, and use the PRs only as examples.
• False parity: contributors may copy another adapter and overclaim support. Mitigation: require a per-slice support decision, source-backed host contract, and explicit unavailable/partial states.
• Credential or transcript exposure: real-host validation can leak private data. Mitigation: require sanitized fixtures, bounded smoke output, and no raw transcripts or secrets in commits or PR text.
• Published-doc duplication: the curated website can diverge from repository guidance. Mitigation: keep the repository guide canonical and make the site page a concise route back to it.