Skip to content

Phase 3B: Schema consolidation completion & path consistency #1542

Open

Description

@ashleyshaw

Phase 3B: Schema Consolidation Completion & Path Consistency

Epic: Repository Restructuring Initiative
Depends on: #1534 (Phase 2: Update Governance Documentation) ✅ MERGED
Type: Phase 3 sub-task (schema consolidation)
Priority: Medium

Overview

Phase 1B audited schema consolidation and identified a 2-file gap in the .schemas/ target folder. Phase 3B completes this work with minor documentation/completeness fixes.

Status: Ready to execute
Estimated effort: 30–45 minutes
Timeline: Part of Phase 3 execution (weeks 3–4 of restructuring sprint)


Remaining Tasks (2 items)

Task 1: Complete .schemas/ with Missing Files [REQUIRED]

Files to copy/create:

  1. agent-config.example.md (6.6 KB)

    • Source: schemas/agent-config.example.md
    • Destination: .schemas/agent-config.example.md
    • Action: Copy file, verify content identical
  2. examples/ directory (2 files, ~2–5 KB combined)

    • Files:
      • agent-capability-manifest.example.json
      • agent-plugin-binding.example.json
    • Source: schemas/examples/
    • Destination: .schemas/examples/
    • Action: Create directory, copy files, verify content identical

Verification:
```bash

Check file counts match

ls -la schemas/ | wc -l
ls -la .schemas/ | wc -l

Should both be 25 files + README

Verify md5 checksums match

md5sum schemas/.json .schemas/.json
md5sum schemas/examples/* .schemas/examples/*
```

PR template: Use `refactor/` or `chore/` prefix
Commit message: "refactor: complete .schemas/ with agent-config.example.md and examples/"


Task 2: Verify Script Path Consistency [OPTIONAL - Can skip]

File: `.github/projects/active/repo-restructuring-2026-07-25/SCHEMA_AUDIT_REPORT.md`
Lines: 154–173 (script reference table)

Issue: One path uses `./.github/scripts/agents/` format; others use different convention

Action: Review all script path references in audit report and ensure consistent formatting

Impact: Minor documentation clarity (non-blocking, can defer beyond Phase 3B if needed)


Success Criteria (DoD)

  • Issue created with detailed implementation notes
  • Task 1: `.schemas/` folder contains all 25 core schema files
  • Task 1: Verify file checksums match between `schemas/` and `.schemas/`
  • Task 2 (if taken): Script paths verified consistent
  • All files pass markdown linting
  • PR created, reviewed, merged to develop
  • Link this issue in commit/PR for traceability

Implementation Notes

Option A: Direct Copy (Recommended)

```bash
cp schemas/agent-config.example.md .schemas/
cp -r schemas/examples/ .schemas/
git add .schemas/
```

Option B: Create as Phase 3B Dedicated PR

  1. Create branch: `refactor/schema-consolidation-complete`
  2. Copy files from `schemas/` to `.schemas/`
  3. Create PR, request CodeRabbit review
  4. Merge when cleared

Option C: Defer to Phase 3C

If time-constrained, this can roll into Phase 3C (final validation) since:

  • Files already exist in `schemas/`
  • Documentation already updated in Phase 2
  • Non-blocking for feature work

Related Issues


Notes from CodeRabbit Review

Original feedback items (Batch 2):

  1. ✅ [COMPLETED] Migration matrix Test expectations row consistency (Batch 1)
  2. ⏳ [THIS ISSUE] Complete .schemas/ with missing 2 files
  3. ⏳ [THIS ISSUE] Verify script path consistency in audit report
  4. ✅ [COMPLETED] Schema ownership clarification in CLAUDE.md (Batch 1)

Phase Timeline Context

Phase 1 (Audit) ✅ Complete — 1A: Instructions, 1B: Schemas, 1C: Agents

Phase 2 (Governance) ✅ Complete — Update docs #1534 MERGED

Phase 3 (Migration) ⏳ In progress — 3A: Instructions, 3B: Schemas (THIS), 3C: Agents, 3D: Reports

Phase 4–5 ⏳ Planned


Issue created: 2026-08-05
Tracked in: Phase 3B Schema Consolidation


Definition of Ready (DoR)

  • Clear problem statement and expected outcome
  • Acceptance criteria defined
  • Related issues/dependencies identified
  • Required resources/approvals listed

Definition of Done (DoD)

  • All acceptance criteria met
  • Changes tested and validated
  • Documentation updated
  • Changes merged and deployed
  • Stakeholders notified

Activity

  1. linear-code commented on Aug 5, 2026

    @linear-code
  2. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

    ✅ Template check passed after update. Thanks for fixing the issue body.

  3. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

    ⏱️ Aging and SLA annotation

    • Age: 7 day(s)
    • SLA state: SLA risk
    • Thresholds: warn at 7 days, breach at 14 days
    • Last updated: 2026-08-12T22:42:04.221Z

    Maintained by project-meta-sync workflow.

  4. self-assigned this
    on Aug 7, 2026
  5. added this to the v1.1 milestone on Aug 29, 2026
  6. github-actions commented on Sep 8, 2026

    @github-actions
    Contributor

    ⚠️ Bare Labels Detected

    This issue has labels that are not in the canonical taxonomy:

    • migrate:area:infrastructure
    • migrate:type:task
    • priority:medium

    Valid Canonical Labels

    Please use labels with a prefix from the canonical taxonomy:

    • Type: type:bug, type:feature, type:task, type:documentation, etc.
    • Status: status:needs-triage, status:in-progress, status:done, etc.
    • Priority: priority:critical, priority:high, priority:normal, priority:low
    • Area: area:ci, area:docs, area:labels, area:security, etc.
    • Meta: meta:needs-changelog, meta:duplicate, meta:blocked, etc.

    For the complete list, see .github/labels.yml.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Fields

Priority

None yet

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions