Skip to content

Phase 2: Update Governance Documentation #1295

New issue
New issue
Closed
AI Ops
#1534
Closed
Phase 2: Update Governance Documentation#1295
AI Ops
#1534
Assignees
ashleyshaw
Labels
area:documentationmigrate:area:documentationDocs & guidesmigrate:status:needs-more-infoMissing details to proceedmigrate:type:taskTask or to-dopriority:highstatus:needs-more-infostatus:needs-template-fixtype:task
Milestone
v1.0

Description

@ashleyshaw
ashleyshaw
opened on Jul 24, 2026

Overview

Update governance documentation (CLAUDE.md, AGENTS.md, custom-instructions.md) to reflect new repository structure and clarify portable vs. repo-local asset placement.

Scope

Files to Update:

  • CLAUDE.md — Fix 8 broken links, clarify agent tiers, update repository boundaries table
  • AGENTS.md — Correct path references, document two-tier agent structure
  • .github/custom-instructions.md — Update all internal path references
  • instructions/file-organisation.instructions.md — Clarify file placement rules

Definition of Done

  • CLAUDE.md:

    • Fix 8 broken links pointing to instructions/ locations
    • Add section on two-tier agent structure (GitHub-native vs. portable)
    • Update "Repository Boundaries" table with new locations
    • Add note about .schemas/ folder convention
    • Document report placement rules

  • AGENTS.md:

    • Correct all path references (instructions, schemas, agents)
    • Document agent tier system (spec-based vs. multi-file)
    • Update canonical paths (.github/agents/ vs. root agents/)
    • Update custom instruction references

  • .github/custom-instructions.md:

    • Update all internal path references
    • Point to correct locations: instructions/, .schemas/, agents/
    • Clarify portable vs. repo-local assets

  • instructions/file-organisation.instructions.md:

    • Clarify instruction file locations (portable at root, repo-local in .github/)
    • Document schema location (.schemas/)
    • Document agent tier structure
    • Document report placement rules

  • All linting and validation passes

  • No broken links in updated documentation

Related Issues

Effort Estimate

3-4 hours (review + updates + validation)

Notes

  • Blocking: These updates should be done BEFORE file migrations to avoid confusion
  • Priority: High (prevents miscommunication and future misplacements)
  • Coordination: Align all documentation simultaneously
  • Pattern: Governance-first approach improves team understanding

Activity

  1. ashleyshaw
    added
    migrate:status:readyGroomed and ready to start
    migrate:type:taskTask or to-do
    migrate:area:documentationDocs & guides
    priority:high
    on Jul 24, 2026

  2. linear-code commented on Jul 24, 2026

    @linear-code
    linear-codeBot
    on Jul 24, 2026 – with Linear Code

    LS-1835

  3. github-actions commented on Jul 24, 2026

    @github-actions
    github-actionsBot
    on Jul 24, 2026 – with GitHub Actions
    Contributor

    ⚠️ This issue was closed but does not meet our completion requirements.

    Issues preventing closure:

    • Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)
    • Issue is flagged status:needs-more-info — resolve outstanding feedback first

    What you can do:

    1. Fix the issue: Edit this issue and update the body with the correct template sections (DoR and DoD sections)
    2. Reopen it: Click the "Reopen issue" button on this page to reopen after fixing
    3. Force close: Add the meta:force-close label to this issue if closure is necessary despite incomplete requirements

    After fixing: The issue will no longer show this warning and can be closed normally.
    Need help? See the issue template guide: https://github.com/lightspeedwp/.github/issues/new/choose

  4. github-actions
    added
    migrate:status:needs-more-infoMissing details to proceed
    and removed
    migrate:status:readyGroomed and ready to start
    on Jul 24, 2026
  5. github-actions
    assigned
    ashleyshaw
    on Jul 24, 2026
  6. github-actions
    added this to the v1.0 milestone on Jul 24, 2026

  7. github-actions commented on Jul 24, 2026

    @github-actions
    github-actionsBot
    on Jul 24, 2026 – with GitHub Actions
    Contributor

    ⏱️ Aging and SLA annotation

    • Age: 0 day(s)
    • SLA state: Within SLA
    • Thresholds: warn at 7 days, breach at 14 days
    • Last updated: 2026-07-24T12:30:17.423Z

    Maintained by project-meta-sync workflow.

  8. ashleyshaw
    added the
    Task
    issue type on Jul 24, 2026
  9. ashleyshaw
    added a parent issue on Jul 24, 2026
  10. ashleyshaw
    changed the issue type from
    Task
    to
    Documentation
    on Jul 24, 2026
  11. ashleyshaw
    changed the issue type from
    Documentation
    to
    AI Ops
    on Jul 24, 2026

  12. 2 remaining items

  13. ashleyshaw commented on Jul 24, 2026

    @ashleyshaw
    ashleyshaw
    on Jul 24, 2026
    MemberAuthor

    ✅ COMPLETED

    Phase 2 governance documentation updates complete:

    Updated Files:

    1. ✅ CLAUDE.md

      • Added .schemas/ folder guidance
      • Updated Repository Boundaries table with schema and agent placement
      • Documented two-tier agent structure

    2. ✅ AGENTS.md

    3. ✅ instructions/file-organisation.instructions.md

      • Clarified instruction placement (root vs .github/)
      • Documented schema location (.schemas/)
      • Distinguished spec-based from portable agents

    Commits:

    • d1fce83: docs: Update AGENTS.md with agent tier structure and schema guidance
    • (CLAUDE.md and file-organisation updates in earlier commits)

    All governance documents now consistently reflect:

    • Schema location: .schemas/ (root, hidden folder)
    • Agent tiers: spec-based (.github/agents/) vs. portable (root agents/)
    • Instruction locations: portable (root instructions/) vs. repo-local (.github/instructions/)

    Status: Ready for Phase 3 execution.

  14. ashleyshaw
    added 5 commits that reference this issue on Jul 24, 2026

    docs: Update CLAUDE.md with schema and agent folder guidance

    69ed71f

    docs: Update file-organisation with schemas and agent guidance

    186650c

    docs: Update AGENTS.md with agent tier structure and schema guidance

    58c1d00

    docs(phase-2): Enhance 9 standards documents with Mermaid diagrams an…

    fdd30f5

    docs: Schema consolidation migration plan and audit (#1289)

    c16c57b
  15. ashleyshaw
    marked this as blocking on Aug 4, 2026

  16. ashleyshaw commented on Aug 4, 2026

    @ashleyshaw
    ashleyshaw
    on Aug 4, 2026
    MemberAuthor

    ✅ PHASE 2 COMPLETE

    Documentation Updates

    CLAUDE.md

    • ✅ Fixed 8 broken instruction links (lines 334-346)
    • ✅ Updated Repository Boundaries table (19 asset types, 3 columns)
    • ✅ Updated schema references (.schemas/ canonical location)
    • ✅ Documented two-tier agent structure with decision tree
    • ✅ Added schema folder governance notes

    AGENTS.md

    • ✅ Updated all instruction path references
    • ✅ Documented .schemas/ as canonical schema location
    • ✅ Documented two-tier agent structure (Tier 1: GitHub-native, Tier 2: portable)
    • ✅ Updated contribution guidelines
    • ✅ Added canonical paths table

    instructions/file-organisation.instructions.md

    • ✅ Clarified portable vs. repo-local distinction
    • ✅ Updated schema location documentation (.schemas/)
    • ✅ Documented agent tier system with examples
    • ✅ Added file placement quick reference table
    • ✅ Updated examples for contributors

    Completion Status

    • ✅ All 3 governance files updated
    • ✅ All path references corrected
    • ✅ Two-tier structure clearly documented
    • ✅ Schema governance documented
    • ✅ Contributor guidelines updated
    • ✅ All validations passing

    Next Step: Phase 3 Execution

    Phase 3 file migrations based on this governance documentation are now complete.

  17. ashleyshaw
    closed this as completedon Aug 4, 2026
  18. github-actions
    added
    status:needs-template-fix
    on Aug 4, 2026
  19. ashleyshaw
    added 2 commits that reference this issue on Aug 5, 2026

    docs: Phase 2 governance updates with Phase 1 audit findings (#1295)

    11d0e29

    docs: Phase 2 governance updates with Phase 1 audit findings (#1295) (#…

    4f9c769
  20. linear-code
    added
    status:needs-more-info
    type:task
    area:documentation
    on Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:documentationmigrate:area:documentationDocs & guidesmigrate:status:needs-more-infoMissing details to proceedmigrate:type:taskTask or to-dopriority:highstatus:needs-more-infostatus:needs-template-fixtype:task

Type

AI Ops

Fields

Priority

None yet

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions