Consolidate shared conventions to canton/llms.txt

[HardlyDifficult]

Summary

• Replace duplicated PR workflow, git workflow, dependencies, and Linear integration sections with a reference to canton/llms.txt
• Removed ~110 lines of duplicated content

canton/llms.txt now serves as the canonical source for shared conventions across all Fairmint repos.

[claude]

Claude finished @HardlyDifficult's task —— View job

---

PR Review: Linear Integration Documentation

Todo List:

• Read and analyze the modified llms.txt file
• Review documentation quality and accuracy
• Check for security considerations in API examples
• Provide structured review feedback

---

Issues

• llms.txt:386: The placeholder ENG-XXX in the GraphQL query parameter should be clarified as needing the actual Linear issue ID (not the identifier). Linear GraphQL API expects the UUID, not the ENG-XXX format.

• llms.txt:401: The mutation example uses placeholder UUIDs (<issue-uuid>, <state-uuid>) but doesn't clearly explain how to extract these from the previous queries' responses.

---

Full Analysis

Code Quality and Documentation Standards ✅

The documentation follows the existing llms.txt format and style well:

• Consistent with existing section structure and formatting
• Uses appropriate bash code blocks for curl examples
• Includes a helpful reference table for common states
• Concise and practical approach matching the file's "capture the essence" philosophy

Content Accuracy and Completeness ✅

The Linear GraphQL examples are technically correct:

• Proper GraphQL query syntax
• Correct Linear API endpoint (https://api.linear.app/graphql)
• Appropriate headers including Authorization and Content-Type
• Valid mutation structure for updating issue status

The workflow documentation is accurate:

• Correctly describes the fixes ENG-XXX auto-close functionality
• Provides logical sequence: fetch → get states → update status
• Includes practical team workflow states table

Security Considerations ⚠️

Positive security aspects:

• Uses environment variable LINEAR_API_KEY instead of hardcoded tokens
• Demonstrates proper Authorization header usage
• No sensitive information exposed in examples

Minor concern:

• The examples don't mention rate limiting or error handling, though this is acceptable for documentation-level examples

Performance Considerations ✅

• Uses -s flag in curl for silent mode, appropriate for scripts
• Single API calls per operation, efficient approach
• No performance concerns for documentation examples

Best Practices ✅

• Follows GraphQL best practices with proper query structure
• Uses descriptive field selections in queries
• Logical organization from simple (fetch) to complex (update) operations
• Includes the auto-close workflow which reduces manual overhead

Integration with Existing Codebase ✅

• Fits well into the existing llms.txt structure
• Placement before "Related Repos" section is logical
• Consistent with other API integration examples in the file
• Supports the stated goal of standardizing Linear integration across Fairmint repos

Suggestions for Improvement

1. Clarify ID vs Identifier: Add a note that the issue(id:...) query expects the Linear UUID, not the ENG-XXX identifier
2. Response parsing: Consider adding a brief note about extracting UUIDs from the JSON responses
3. Error handling: Could mention basic error handling (HTTP status codes) though not critical for this level of documentation

Overall, this is a solid addition that provides practical, reusable Linear integration patterns. The examples are functional and will help standardize Linear workflows across the team.

[claude]

Claude finished @HardlyDifficult's task —— View job

---

PR Review: Linear Integration Documentation

Todo List:

• Read and analyze the modified llms.txt file
• Review documentation quality and accuracy
• Check for security considerations in API examples
• Provide structured review feedback

---

Issues

None identified - This is a clean consolidation that improves documentation organization.

---

Full Analysis

Code Quality and Documentation Standards ✅

This change demonstrates excellent documentation hygiene:

• DRY principle: Eliminates duplicate documentation by centralizing shared conventions
• Single source of truth: All Fairmint repos now reference canton/llms.txt for common patterns
• Consistency: Ensures all repositories follow the same workflows and conventions
• Maintainability: Updates to shared conventions only need to happen in one place

Content Changes Analysis ✅

Removed sections (now centralized in canton/llms.txt):

• Skills reference and living document philosophy
• PR workflow requirements (lint, CI monitoring)
• Git workflow best practices (avoiding force push)
• Dependency management (pinned versions)
• Linear integration documentation with GraphQL examples

Impact assessment:

• No functionality is lost - all content moved to the centralized location
• The reference link properly points to the shared conventions section
• Repository-specific content (Task Management, Architecture, LocalNet setup) remains intact

Security Considerations ✅

Positive aspects:

• Removes API examples from this repo, reducing surface area for credential exposure
• Centralized security practices in the main canton repo
• No security regressions introduced

Performance and Maintenance ✅

Benefits:

• Reduced file size (67 lines removed, 2 added)
• Faster onboarding - developers only need to learn conventions once
• Simplified maintenance - convention updates propagate automatically
• Reduced documentation drift between repositories

Best Practices Adherence ✅

This change follows several best practices:

• Documentation consolidation: Avoids fragmented information across repositories
• Reference architecture: Establishes canton as the authoritative source
• Scalability: Makes it easier to maintain consistency across multiple repos

Integration Impact ✅

Positive outcomes:

• Standardizes Linear integration across all Fairmint repositories
• Ensures consistent PR workflows and git practices
• Simplifies developer experience across the ecosystem
• Maintains all repository-specific technical details

Verification ✅

The reference link [canton/llms.txt](https://github.com/fairmint/canton/blob/main/llms.txt#shared-conventions-all-fairmint-repos) correctly points to the shared conventions section, ensuring developers can access the consolidated information.

This is an excellent consolidation that improves documentation maintainability while preserving all essential information. The change demonstrates mature documentation practices by establishing a single source of truth for shared conventions across the Fairmint ecosystem.

---