docs: add spec reference guidance to PR template by type (#87)

* Initial plan

* docs: add spec reference guidance to PR template and CONTRIBUTING.md

- Add "Spec Requirement Guidelines" table to PR template showing when specs are required/optional by PR type
- Update AI spec validation workflow warning message with PR type requirements
- Add "Spec Reference Best Practices" section to CONTRIBUTING.md
- Clarify that feature PRs require specs, others are optional
- Remove "REQUIRED" from spec section comment to reflect nuanced guidance

Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com>

* docs: expand conventional commit examples in spec guidance

- Add scope syntax examples (feat(scope):, fix(scope):) to PR template
- Add conventional commit prefixes to all PR types in workflow warning
- Include ci:, build:, chore: prefixes for Infrastructure row
- Ensure consistency with repo's conventional commit usage

Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com>

* docs: add Infrastructure guidance and conventional commit prefixes for consistency

Addresses Copilot review feedback for documentation consistency across files.

Changes:
- Add Infrastructure (`ci:`, `build:`, `chore:`) row to workflow table
- Add Infrastructure bullet to CONTRIBUTING.md spec guidance
- Add conventional commit prefixes to all bullet points in CONTRIBUTING.md

This ensures PR template, workflow message, and CONTRIBUTING.md all use
consistent terminology and cover all five PR types.

Comment-IDs: 2636845208, 2636845210, 2636845212

Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com>
Co-authored-by: rjmurillo-bot <rjmurillo-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 4 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,7 +6,7 @@
 
 ## Specification References
 
-<!-- REQUIRED: Enable AI spec-to-implementation traceability -->
+<!-- Enable AI spec-to-implementation traceability -->
 <!-- The ai-spec-validation workflow checks for these references -->
 
 | Type | Reference | Description |
@@ -15,13 +15,24 @@
 | **Spec** | `.agents/planning/...` | <!-- Planning document --> |
 | **Spec** | `.agents/specs/...` | <!-- Spec document (if applicable) --> |
 
+### Spec Requirement Guidelines
+
+| PR Type | Spec Required? | Guidance |
+|---------|----------------|----------|
+| **Feature** (`feat:`, `feat(scope):`) | ✅ Required | Link issue, REQ-*, or spec file in `.agents/planning/` |
+| **Bug fix** (`fix:`, `fix(scope):`) | Optional | Link issue if exists; explain root cause if complex |
+| **Refactor** (`refactor:`, `refactor(scope):`) | Optional | Explain rationale and scope in PR description |
+| **Documentation** (`docs:`) | Not required | N/A |
+| **Infrastructure** (`ci:`, `build:`, `chore:`) | Optional | Link ADR or design doc if architecture impacted |
+
 <!--
 Supported reference formats:
 - Issues: "Closes #123", "Fixes #456", "Implements #789"
 - Requirements: "REQ-001", "DESIGN-002", "TASK-003"
 - Spec files: ".agents/specs/requirements/...", ".agents/planning/..."
 
-If no specs exist, create one in .agents/planning/ before submitting.
+For feature PRs: Create spec in .agents/planning/ before submitting if none exists.
+For other PRs: Add references when traceability adds value.
 -->
 
 ## Changes

.github/workflows/ai-spec-validation.yml

@@ -1,7 +1,9 @@
 name: Spec-to-Implementation Validation
 
 # AI-powered requirements traceability using GitHub Copilot CLI
+
 # Verifies that PR changes implement requirements from linked specs
+
 # Warns if requirements are not covered by the implementation
 
 on:
@@ -14,7 +16,7 @@ on:
       - 'scripts/**'
       - 'build/**'
       - '.claude/skills/**'
-      
+
 permissions:
   contents: read
   pull-requests: write
@@ -224,6 +226,18 @@ jobs:
           | Link issues | ``Closes #123`` |
           | Reference spec files | ``.agents/specs/requirements/...`` |
 
+          **Spec Requirement by PR Type:**
+
+          | PR Type | Required? |
+          |:--------|:----------|
+          | Feature (``feat:``) | ✅ Required |
+          | Bug fix (``fix:``) | Optional |
+          | Refactor (``refactor:``) | Optional |
+          | Documentation (``docs:``) | Not required |
+          | Infrastructure (``ci:``, ``build:``, ``chore:``) | Optional |
+
+          See PR template for full guidance.
+
           </details>
 
           ---

AGENTS.md

@@ -1083,6 +1083,7 @@ Agents violating these standards produce inconsistent, unprofessional output. Re
 - Unresolved review threads (most common)
 - Failing CI checks
 - Missing required approvals
+
 ---
 
 ## Putting It All Together

CONTRIBUTING.md

@@ -283,11 +283,30 @@ pwsh build/scripts/Invoke-PesterTests.ps1 -TestPath "./build/tests/Generate-Agen
 
 ## Pull Request Guidelines
 
-1. **Template changes**: Always include both template and generated files
-2. **Validation**: Run `pwsh build/Generate-Agents.ps1 -Validate` before submitting
-3. **Tests**: Ensure all tests pass
-4. **Documentation**: Update relevant docs if adding new agents
-5. **Commit messages**: Use conventional commit format (e.g., `feat(agent):`, `fix(template):`)
+1. **Spec references**: Feature PRs (`feat:`) require spec references (issue, REQ-*, or `.agents/planning/` files)
+2. **Template changes**: Always include both template and generated files
+3. **Validation**: Run `pwsh build/Generate-Agents.ps1 -Validate` before submitting
+4. **Tests**: Ensure all tests pass
+5. **Documentation**: Update relevant docs if adding new agents
+6. **Commit messages**: Use conventional commit format (e.g., `feat(agent):`, `fix(template):`)
+
+### Spec Reference Best Practices
+
+For traceability and AI-assisted validation:
+
+- **Features (`feat:`)**: Always link to an issue or create a planning document in `.agents/planning/` before submitting
+- **Bug fixes (`fix:`)**: Link to issue if it exists; for complex bugs, explain root cause
+- **Refactors (`refactor:`)**: Explain rationale and scope in PR description
+- **Documentation (`docs:`)**: Spec references not required
+- **Infrastructure (`ci:`, `build:`, `chore:`)**: Link to related infra/CI/tooling issue or spec; call out operational risk and rollback plan if applicable
+
+Supported reference formats:
+
+- Issue links: `Closes #123`, `Fixes #456`, `Implements #789`
+- Requirement IDs: `REQ-001`, `DESIGN-002`, `TASK-003`
+- Spec files: `.agents/specs/requirements/...`, `.agents/planning/...`
+
+The AI Spec Validation workflow will check for these references on all PRs.
 
 ## Questions?