Summary

The root CONTRIBUTING.md and the docs/contributing/ folder serve complementary but disconnected audiences. CONTRIBUTING.md targets general contributors (bug reporters, code submitters, documentation editors) while docs/contributing/ targets AI artifact authors (agents, prompts, instructions, skills) and provides repo operations references (branch protection, release process, copyright headers, roadmap). Neither ecosystem adequately cross-references the other, creating a fragmented contributor experience where newcomers miss relevant guidance depending on which entry point they discover first.

This issue tracks the work to map, reconcile, and cross-link these two contributing documentation surfaces so that every contributor — regardless of entry point — can navigate the full contribution landscape.

Content Mapping Analysis

Current Structure

Surface	Purpose	Audience
CONTRIBUTING.md	General contribution guide: bugs, enhancements, code, docs, style, testing, releases	All contributors
docs/contributing/README.md	AI artifact contribution hub: agents, prompts, instructions, skills	AI artifact authors
docs/contributing/*.md (9 files)	Specialized guides for artifact types, repo operations, and project direction	Artifact authors, maintainers

Cross-Reference Inventory

From	To	Type
docs/contributing/README.md	../../CONTRIBUTING.md	Back-link to general guide
CONTRIBUTING.md	docs/contributing/copyright-headers.md	Forward link (only one)
CONTRIBUTING.md	.github/instructions/commit-message.instructions.md	Forward link to instructions

One forward link from CONTRIBUTING.md into docs/contributing/ is the only bridge between these two documentation surfaces.

Identified Gaps

1. Missing Cross-References from CONTRIBUTING.md

CONTRIBUTING.md has an "Improving The Documentation" section that says to "follow the your first code contribution guidance" but never points contributors to the extensive specialized guides in docs/contributing/ for:

• Agent contributions (custom-agents.md)
• Instruction contributions (instructions.md)
• Prompt contributions (prompts.md)
• Skill contributions (skills.md)
• Common AI artifact standards (ai-artifacts-common.md)

A contributor wanting to improve documentation — the most common external contribution type — has no path from CONTRIBUTING.md to these guides.

2. No Unified Contributor Navigation

There is no documentation that presents the complete contributor journey spanning both surfaces. A first-time contributor who lands on CONTRIBUTING.md discovers bug reporting, enhancement suggestions, code contribution, and basic documentation guidance — but never learns about the AI artifact ecosystem. Conversely, a contributor who lands on docs/contributing/README.md gets linked back to CONTRIBUTING.md for "general contribution guidelines" but may not realize that release process details, testing requirements, and coding conventions live there.

3. Content Overlap Without Reconciliation

Three topics appear in both surfaces with different levels of detail and no reconciliation:

Topic	CONTRIBUTING.md	docs/contributing/	Divergence
Release Process	Brief section: conventional commits, release-please basics	release-process.md: comprehensive — extension publishing, channels, maturity lifecycle, version calculation table, mermaid diagrams	CONTRIBUTING.md subset is potentially stale relative to the detailed guide
Validation Commands	npm run lint:md, spell-check, format:tables	ai-artifacts-common.md: lint:frontmatter, lint:md, spell-check, lint:md-links, lint:ps	Different command sets with partial overlap; no single authoritative list
Copyright Headers	Mentions headers, links to copyright-headers.md	copyright-headers.md: SPDX format, placement rules, PSScriptAnalyzer integration	This is the one topic with a proper delegation link

4. Missing General Contribution Guidance in docs/contributing/

docs/contributing/ has no coverage of:

• Bug reporting process and expectations
• Enhancement suggestion workflow
• General code contribution guidelines (non-AI-artifact code)
• Testing requirements (Pester 5.x patterns and conventions)

These only exist in CONTRIBUTING.md, leaving docs/contributing/ incomplete as a standalone reference.

5. Stale Content in CONTRIBUTING.md

CONTRIBUTING.md is dated 2025-11-05, while several docs/contributing/ files are significantly newer:

File	Date
CONTRIBUTING.md	2025-11-05
skills.md	2026-01-18
release-process.md	2026-01-08
ROADMAP.md	2026-01-21

The root guide may not reflect current project processes, especially around the expanded AI artifact types and validation tooling.

Deliverables

D1: Cross-Reference Links in CONTRIBUTING.md

Add a dedicated section or expand "Improving The Documentation" to include navigation links to all docs/contributing/ guides, organized by contribution type:

• AI artifact contributions → link to docs/contributing/README.md as the hub
• Release process details → delegate to docs/contributing/release-process.md
• Branch protection / CI context → link to docs/contributing/branch-protection.md
• Project roadmap → link to docs/contributing/ROADMAP.md

D2: Reconcile Overlapping Content

For each overlapping topic (release process, validation commands, copyright headers):

• Designate one surface as the source of truth
• Replace the duplicate content in the other surface with a summary + link
• Ensure both surfaces agree on current tooling and processes

Recommended ownership:

Topic	Source of Truth	Summary + Link
Release Process	docs/contributing/release-process.md	CONTRIBUTING.md
Validation Commands	docs/contributing/ai-artifacts-common.md	CONTRIBUTING.md
Copyright Headers	docs/contributing/copyright-headers.md	CONTRIBUTING.md (already linked)

D3: Contributor Journey Navigation

Add a "How to Use These Guides" section to docs/contributing/README.md that maps contributor intents to the right starting point:

• "I found a bug" → CONTRIBUTING.md § Reporting Bugs
• "I have an idea" → CONTRIBUTING.md § Suggesting Enhancements
• "I want to write code" → CONTRIBUTING.md § Your First Code Contribution
• "I want to create an agent/prompt/instruction/skill" → respective docs/contributing/ guide
• "I want to improve docs" → combination of both surfaces depending on the target

D4: Content Freshness Audit

Review and update CONTRIBUTING.md to reflect current-state processes, including:

• Updated validation command list consistent with ai-artifacts-common.md
• Current project structure references
• Any process changes since 2025-11-05

Acceptance Criteria

• CONTRIBUTING.md contains cross-reference links to all relevant docs/contributing/ guides
• Each overlapping topic has a designated source of truth with the other surface delegating via summary + link
• docs/contributing/README.md includes contributor intent-based navigation covering both general and AI artifact contribution paths
• Validation command lists are consistent across both surfaces or properly delegated
• Release process content is reconciled with a single authoritative source
• CONTRIBUTING.md date and content reflect current project state
• No dead links between the two documentation surfaces

Implementation Notes

• This work is documentation-only and does not affect code, scripts, or CI.
• The copyright headers topic already follows the recommended pattern (summary in CONTRIBUTING.md + link to docs/contributing/copyright-headers.md) — use this as the model for reconciling the other overlapping topics.
• Consider whether CONTRIBUTING.md should become thinner (hub with links) or remain comprehensive (self-contained with delegation for advanced topics). Either approach works if navigation is clear.
• Related issue feat: Documentation Updates for Persona Distribution #435 touches docs/contributing/ files for persona distribution documentation but does not address the cross-referencing problem scoped here.

Files in Scope

• CONTRIBUTING.md
• docs/contributing/README.md
• docs/contributing/ai-artifacts-common.md (validation commands reconciliation)
• docs/contributing/release-process.md (release process reconciliation)

Related Issues

• feat: Documentation Updates for Persona Distribution #435 — Documentation Updates for Persona Distribution (touches docs/contributing/ files, complementary scope)
• feat(docs): define inactivity closure policy for pull requests #443 — Inactivity closure policy (adds content to CONTRIBUTING.md, should follow patterns established by this issue)
• feat(docs): define inactivity closure policy for issues and discussions #442 — Inactivity closure policy for issues (same consideration)