Skip to main content

Story 004 – README Template Based on Best-README-Template

Status: TODO
Priority: MEDIUM
Estimated Effort: [TBD]
Created: 2025-01-27
Last updated: 2025-01-27 (v0.7.4.1+1 – Story created)
Version: v0.7.4.1+1
Code: E7S04

Task Checklist​

  • E7:S04:T01 – Create README template based on Best-README-Template - TODO
  • E7:S04:T02 – Add ai-dev-kit integration and acknowledgments to template - TODO
  • E7:S04:T03 – Create customization guide for adopting projects - TODO
  • E7:S04:T04 – Create dependency tracking guidance for adopting projects - TODO (reframed from FR-003)
  • E7:S04:T05 – Provide example tooling for dependency tracking in adopting projects - TODO (reframed from FR-003)
  • E7:S04:T06 – Document PR generation patterns for adopting projects - TODO (reframed from FR-003)
  • E7:S04:T07 – Create comprehensive dependency tracking guide for adopting projects - TODO (new from FR-003)

Overview​

Create a README template based on the excellent Best-README-Template, with ai-dev-kit integration and proper acknowledgments. Then provide guidance on how adopting projects can customize it further for their specific needs.

Goals​

  • Build on Best-README-Template as the foundation
  • Create a ready-to-use README template with ai-dev-kit integration
  • Include proper acknowledgments for all dependencies and resources
  • Provide customization guidance for adopting projects to adapt the template
  • Provide guidance and tooling for adopting projects to track external dependencies directly (Best-README-Template, Keep a Changelog, Shields.io)
  • Eliminate ai-dev-kit as unnecessary middleman for dependency tracking

Tasks​

E7:S04:T01 – Create README template based on Best-README-Template​

Input:

  • Best-README-Template structure and content
  • ai-dev-kit framework information
  • Common README sections and best practices

Deliverable:

  • Complete README template file based on Best-README-Template
  • All standard sections included with placeholder content
  • Proper markdown structure and formatting

Dependencies: None
Blocker: None
Parallel Development Candidacy: Safe

Approach:

  1. Review Best-README-Template structure and content
  2. Create README template file using Best-README-Template as foundation
  3. Include all standard sections (About, Getting Started, Usage, Roadmap, Contributing, License, Contact, Acknowledgments)
  4. Add placeholder content that can be customized
  5. Ensure proper markdown formatting and structure
  6. Maintain Best-README-Template's excellent structure and organization

E7:S04:T02 – Add ai-dev-kit integration and acknowledgments to template​

Input:

  • README template from E7:S04:T01
  • ai-dev-kit framework information
  • List of resources to acknowledge

Deliverable:

  • README template with ai-dev-kit framework integration

  • Complete Acknowledgments section with proper attributions:

    • Best-README-Template
    • Keep a Changelog
    • Shields.io
    • ai-dev-kit

  • Framework-specific sections and references

Dependencies: E7:S04:T01
Blocker: None
Parallel Development Candidacy: Blocked (requires T01)

Approach:

  1. Add ai-dev-kit framework references to appropriate sections
  2. Integrate framework installation and usage information
  3. Add complete Acknowledgments section with proper formatting
  4. Acknowledge Best-README-Template for README structure
  5. Acknowledge Keep a Changelog for changelog format
  6. Acknowledge Shields.io for badge/shield usage
  7. Acknowledge ai-dev-kit for framework adoption
  8. Ensure all links are correct and properly formatted

E7:S04:T03 – Create customization guide for adopting projects​

Input:

  • Complete README template from E7:S04:T02
  • ai-dev-kit framework information
  • Customization best practices

Deliverable:

  • README customization guide document
  • Step-by-step instructions for customizing the template
  • Examples of common customizations
  • Guidance on replacing placeholder content

Dependencies: E7:S04:T02
Blocker: None
Parallel Development Candidacy: Blocked (requires T02)

Approach:

  1. Create customization guide document structure
  2. Document how to use the README template
  3. Provide step-by-step instructions for customization:
    • Replacing placeholder project information
    • Customizing sections for specific project needs
    • Adding project-specific features and capabilities
    • Updating installation and usage instructions
  4. Include examples of common customizations
  5. Document how to maintain acknowledgments when customizing
  6. Provide guidance on optional sections and when to include/remove them

E7:S04:T04 – Create dependency tracking guidance for adopting projects​

Status: TODO (reframed from FR-003)
Note: This task was reframed based on FR-003. Instead of ai-dev-kit tracking dependencies, adopting projects should track them directly.

Input:

  • List of external dependencies (Best-README-Template, Keep a Changelog, Shields.io)
  • Framework principle: "Copy, don't reference"
  • Dependency tracking best practices

Deliverable:

  • Dependency tracking guide for adopting projects
  • Example dependency tracking configuration files
  • Documentation explaining why projects should track dependencies directly
  • Guidance on setting up dependency tracking in adopting projects

Dependencies: E7:S04:T02
Blocker: None
Parallel Development Candidacy: Blocked (requires T02)

Approach:

  1. Create dependency tracking guide document
  2. Explain rationale: Why adopting projects should track dependencies directly (eliminates middleman, aligns with "copy, don't reference" principle)
  3. Document tracked dependencies:
    • Best-README-Template (GitHub repository)
    • Keep a Changelog (website/documentation)
    • Shields.io (service/API)
  4. Provide example dependency tracking configuration (e.g., .dependencies.yaml or dependencies.json)
  5. Document how to track versions/commit hashes for each dependency
  6. Provide metadata examples (repo URL, release/tag tracking, update detection method)
  7. Include integration guidance with common CI/CD platforms

E7:S04:T05 – Provide example tooling for dependency tracking in adopting projects​

Status: TODO (reframed from FR-003)
Note: This task was reframed based on FR-003. Provide example tooling that adopting projects can use, rather than implementing in ai-dev-kit.

Input:

  • Dependency tracking guide from E7:S04:T04
  • Update detection requirements
  • CI/CD or automation platform capabilities

Deliverable:

  • Example automated update detection scripts (Python/Shell)
  • Example GitHub Actions workflows for dependency tracking
  • Example update detection configuration files
  • Documentation on how to use the example tooling

Dependencies: E7:S04:T04
Blocker: None
Parallel Development Candidacy: Blocked (requires T04)

Approach:

  1. Create example update detection scripts:
    • For GitHub repos (Best-README-Template): Check latest release/tag
    • For Keep a Changelog: Check website for updates or version changes
    • For Shields.io: Check for API changes or documentation updates
  2. Provide example scripts (Python/Shell):
    • Query GitHub API for latest releases/tags
    • Check for changes in tracked resources
    • Compare current tracked version with latest available
  3. Create example GitHub Actions workflows:
    • Scheduled execution (daily or weekly checks)
    • Update detection and notification
    • Store last check timestamp
  4. Provide example output formats:
    • JSON/YAML with detected updates
    • Version comparison results
  5. Document how adopting projects can customize and use the example tooling
  6. Include testing guidance for update detection

E7:S04:T06 – Document PR generation patterns for adopting projects​

Status: TODO (reframed from FR-003)
Note: This task was reframed based on FR-003. Document patterns that adopting projects can use, rather than implementing in ai-dev-kit.

Input:

  • Example tooling from E7:S04:T05
  • PR generation requirements
  • Git workflow and branch strategy patterns

Deliverable:

  • PR generation pattern documentation
  • Example PR generation scripts/workflows
  • PR template examples for dependency updates
  • Documentation on PR generation patterns and best practices

Dependencies: E7:S04:T05
Blocker: None
Parallel Development Candidacy: Blocked (requires T05)

Approach:

  1. Document PR generation workflow patterns:
    • When update detected, create branch
    • Update README template with latest changes from upstream
    • Generate PR with update details
  2. Provide example PR generation scripts:
    • Checkout new branch (e.g., update/best-readme-template-vX.Y.Z)
    • Fetch latest version from upstream
    • Merge/apply changes to README template
    • Update dependency tracking file with new version
    • Commit changes
    • Create PR via GitHub API or CLI
  3. Create example PR templates:
    • Title format: "Update [dependency] to v[version]"
    • Description with:
      • What changed in upstream
      • Changes applied to README template
      • Version comparison
      • Testing notes
  4. Provide example GitHub Actions workflows:
    • Trigger on update detection
    • Run PR generation script
    • Handle PR creation and management
  5. Document different update type patterns:
    • Best-README-Template: Merge latest template changes
    • Keep a Changelog: Update changelog format references
    • Shields.io: Update badge/shield examples if API changes
  6. Document PR generation best practices and manual override procedures
  7. Include customization guidance for adopting projects

E7:S04:T07 – Create comprehensive dependency tracking guide for adopting projects​

Status: TODO (new from FR-003)
Note: This task consolidates dependency tracking guidance into a comprehensive guide for adopting projects.

Input:

  • Dependency tracking guidance from E7:S04:T04
  • Example tooling from E7:S04:T05
  • PR generation patterns from E7:S04:T06
  • Framework principles and best practices

Deliverable:

  • Comprehensive dependency tracking guide for adopting projects
  • Complete documentation covering all aspects of dependency tracking
  • Quick start guide for setting up dependency tracking
  • Troubleshooting and FAQ sections

Dependencies: E7:S04:T04, T05, T06
Blocker: None
Parallel Development Candidacy: Blocked (requires T04, T05, T06)

Approach:

  1. Consolidate all dependency tracking guidance into single comprehensive guide
  2. Create guide structure:
    • Introduction and rationale (why track dependencies directly)
    • Quick start guide
    • Detailed configuration instructions
    • Example tooling and workflows
    • PR generation patterns
    • Best practices and recommendations
    • Troubleshooting section
    • FAQ
  3. Include all three dependencies:
    • Best-README-Template tracking
    • Keep a Changelog tracking
    • Shields.io tracking
  4. Provide complete examples that adopting projects can copy and customize
  5. Document integration with common CI/CD platforms
  6. Include decision trees for when to update dependencies
  7. Add links to related documentation and resources
  8. Ensure guide is self-contained and actionable

Acceptance Criteria​

  • README template is based on Best-README-Template structure

  • Template includes all standard sections with placeholder content

  • Template includes ai-dev-kit framework integration

  • Acknowledgments section includes all required resources:

    • Best-README-Template
    • Keep a Changelog
    • Shields.io
    • ai-dev-kit

  • Customization guide provides clear instructions for adopting projects

  • Template is ready to use and can be customized for any project

  • Dependency tracking guide explains why adopting projects should track dependencies directly

  • Example tooling provided for dependency tracking in adopting projects

  • PR generation patterns documented for adopting projects

  • Comprehensive dependency tracking guide consolidates all guidance

  • All guidance is actionable and can be copied/customized by adopting projects

Dependencies​

Blocks:

  • Real-world adoption examples documentation
  • User onboarding materials

Blocked By:

  • None

Coordinates With:

  • Epic 5 (Documentation Management) - Documentation quality standards
  • Epic 7:S01 (Real-World Adoption Examples) - Case study documentation
  • Epic 7:S03 (User Onboarding Materials) - Onboarding resources

References​

Notes​

This story creates a concrete README template based on Best-README-Template, building on their excellent foundation. The template includes ai-dev-kit integration and proper acknowledgments, then provides guidance on how adopting projects can customize it further for their specific needs.

Dependency Tracking (Reframed per FR-003): Instead of ai-dev-kit tracking dependencies and propagating updates, adopting projects should track external dependencies (Best-README-Template, Keep a Changelog, Shields.io) directly. This eliminates ai-dev-kit as an unnecessary middleman and aligns with the "copy, don't reference" framework principle. The story provides guidance, example tooling, and patterns that adopting projects can use to set up their own dependency tracking.

Update Strategy (for adopting projects):

  • Best-README-Template: Track GitHub releases/tags, merge template changes when updated
  • Keep a Changelog: Track documentation/format updates
  • Shields.io: Track API changes or new badge options