Skip to main content

ADR-001: Project Structure and OSS Standards

Status: Accepted 2026-01-03 Date: 2026-01-03 Decision Makers: @amiable-dev/maintainers Council Review: 2026-01-03 (Tier: High, Models: GPT-5.2, Claude Opus 4.5, Gemini 3 Pro, Grok 4.1)

Context​

The amiable-templates repository is being established as an open source documentation site that aggregates Railway deployment templates from multiple repositories. To maximize community engagement and ensure sustainable maintenance, we need to establish a consistent project structure that:

  1. Lowers the barrier to contribution
  2. Provides clear governance and communication channels
  3. Ensures quality through automated workflows
  4. Protects both contributors and maintainers with proper policies
  5. Aligns with the amiable-dev organization's existing OSS patterns

Current State​

The repository currently contains:

  • CLAUDE.md for AI assistant guidance
  • .agent/rules/snyk_rules.md for security scanning rules

Goals​

  1. Establish community standards that encourage contribution
  2. Implement governance that scales with community growth
  3. Create a consistent experience across amiable-dev repositories
  4. Protect the project from common OSS pitfalls (legal, security, maintainer burnout)

Non-Goals​

This ADR explicitly does NOT cover:

  • MkDocs site architecture (see ADR-002)
  • Template configuration system (see ADR-003)
  • CI/CD and deployment (see ADR-004)
  • Security scanning implementation (see ADR-005)
  • Documentation aggregation (see ADR-006)

Considered Options​

Adopt the proven structure from llm-council and litellm-langfuse-railway with adaptations for a documentation site.

Pros:

  • Consistency across amiable-dev organization
  • Proven patterns that have been LLM Council reviewed
  • Comprehensive coverage of OSS requirements
  • Clear implementation path with existing examples

Cons:

  • Some overhead for a primarily documentation project
  • Initial setup effort

Option 2: Minimal OSS Structure​

Only include LICENSE and README, add other files as needed.

Pros:

  • Fast initial setup
  • Low maintenance overhead

Cons:

  • Missing professional signals (GitHub Community Profile)
  • No contribution guidelines leads to inconsistent PRs
  • No security policy delays vulnerability handling
  • Must retrofit structure later

Decision​

Adopt the llm-council OSS structure with the following adaptations for this documentation-focused repository:

1. Community Standards Files (Root Level)​

FilePurposeAdaptation
LICENSEMIT LicenseStandard MIT
CODE_OF_CONDUCT.mdContributor Covenant v2.1No changes
CONTRIBUTING.mdContribution guidelinesFocus on docs contributions, template additions
GOVERNANCE.mdDecision-making processDefine maintainer roles, ADR process
SECURITY.mdVulnerability reportingFocus on supply chain (dependencies, CI)
SUPPORT.mdHelp channelsGitHub Discussions + issue templates
.gitignorePrevent accidental commitsPython/MkDocs patterns, cache directories
.editorconfigConsistent formattingMarkdown, YAML, Python settings

2. GitHub Configuration (.github/)​

.github/
├── CODEOWNERS              # Maintainer review requirements
├── FUNDING.yml             # Sponsorship links
├── dependabot.yml          # Dependency updates (Python, GitHub Actions)
├── ISSUE_TEMPLATE/
│   ├── config.yml          # Template chooser + discussion links
│   ├── bug_report.md       # Site issues, broken links
│   └── feature_request.md  # New template requests
├── PULL_REQUEST_TEMPLATE.md
└── workflows/
    ├── deploy.yml          # Build and deploy to GitHub Pages
    └── security.yml        # Gitleaks secret scanning

3. CODEOWNERS Configuration​

# Default owners
* @amiable-dev/maintainers

# Template configuration (critical)
templates.yaml @amiable-dev/maintainers
templates.schema.yaml @amiable-dev/maintainers

# CI/CD workflows
.github/ @amiable-dev/maintainers

# ADRs require review
docs/adrs/ @amiable-dev/maintainers

# Aggregation scripts
scripts/ @amiable-dev/maintainers

4. Issue Labels​

LabelDescriptionColor
bugSite issues, broken links#d73a4a
enhancementSite improvements#a2eeef
documentationDocumentation updates#0075ca
good-first-issueBeginner-friendly#7057ff
help-wantedNeeds community help#008672
template-requestRequest for new template#fbca04
aggregationDoc aggregation issues#c5def5
upstreamIssue in source template repo#e4e669

5. Versioning Strategy​

Use semantic versioning for site releases via Git tags:

  • MAJOR: Breaking nav structure changes, deprecated pages removed
  • MINOR: New templates added, new sections
  • PATCH: Content updates, fixes

6. Branch Protection​

Enable on main branch:

  • Require pull request reviews (1 approval)
  • Require status checks to pass
  • Require signed commits (recommended, not required)
  • No force pushes

Consequences​

Positive​

  1. Professional appearance: GitHub Community Profile shows 100% completion
  2. Lower contribution barrier: Clear guidelines reduce friction
  3. Consistent governance: Aligned with other amiable-dev projects
  4. Security posture: Clear vulnerability reporting process
  5. Discoverability: Standard files improve SEO

Negative​

  1. Maintenance overhead: More files to keep updated
  2. Initial setup effort: One-time cost to create all files
  3. Review burden: CODEOWNERS requires maintainer approval

Neutral​

  1. Documentation site has different needs than code projects
  2. Some OSS patterns (DCO, CITATION.cff) may be overkill initially

Implementation Phases​

Phase 1: Foundation (P0)​

  • LICENSE (MIT)
  • .gitignore (Python/MkDocs patterns)
  • .editorconfig
  • CODE_OF_CONDUCT.md (Contributor Covenant v2.1)
  • SECURITY.md

Phase 2: Contribution Experience (P0)​

  • CONTRIBUTING.md
  • .github/CODEOWNERS
  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/ISSUE_TEMPLATE/feature_request.md
  • .github/ISSUE_TEMPLATE/config.yml
  • .github/PULL_REQUEST_TEMPLATE.md

Phase 3: Governance & Sustainability (P1)​

  • GOVERNANCE.md
  • SUPPORT.md
  • .github/FUNDING.yml
  • .github/dependabot.yml

Phase 4: GitHub Features (P2)​

  • Enable GitHub Discussions (Q&A, Ideas, Announcements)
  • Configure issue labels
  • Enable branch protection rules
  • Set repository topics for discoverability

Compliance / Validation​

  • All community standards files created and linked from README
  • GitHub "Community Standards" checklist shows 100% completion
  • Issue templates function correctly (manual test)
  • CODEOWNERS properly routes review requests
  • Branch protection rules enabled

LLM Council Review Summary​

Reviewed: 2026-01-03 Tier: High (4 models: GPT-5.2, Claude Opus 4.5, Gemini 3 Pro, Grok 4.1)

Verdict: Accepted with Modifications​

The council unanimously agreed that the community health files are robust but identified gaps in technical automation.

Key Findings Incorporated​

FindingResolution
Missing CI/CD workflowsAdded to ADR-004 scope; deploy.yml and security.yml created
Missing README.mdWill create during implementation
templates.yaml validation neededAdded schema validation in CI workflow
GOVERNANCE.md may be prematureKept but simplified; will expand when 3+ maintainers
Semantic versioning may be overkillChanged to continuous deployment; tags for milestones only
Link checking for upstream templatesAdded to ADR-006 aggregation scope
Template intake policy neededAdded to CONTRIBUTING.md
Upstream template health monitoringAdded weekly link checking workflow

Dissenting Views​

  • Claude Opus 4.5: Suggested deferring GOVERNANCE.md entirely until 3+ contributors. Kept but simplified.
  • GPT-5.2: Recommended explicit template intake criteria. Added to CONTRIBUTING.md.
  • All models: Agreed branch protection should only be enabled after CI is working.

References​