From e1c8853748bf430b145c1095c3d33e2babddb9d0 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 20 Nov 2025 19:24:17 -0500 Subject: [PATCH] feat: Add .beads/README.md generation during bd init (bd-m7ge) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Automatically creates a promotional README.md in the .beads directory when bd init is run. The README explains what Beads is, provides essential commands, highlights key benefits for AI-assisted workflows, and encourages developers to try Beads in their own projects. Changes: - Added createReadme() function to generate compelling README content - Integrated README creation in both regular and --no-db init modes - README creation is idempotent (skips if already exists) - Non-fatal warnings if README creation fails The README is designed to get open source contributors excited about using Beads for their AI-assisted development workflows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- cmd/bd/init.go | 113 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/cmd/bd/init.go b/cmd/bd/init.go index ecf9e4b3..345ff658 100644 --- a/cmd/bd/init.go +++ b/cmd/bd/init.go @@ -162,6 +162,12 @@ With --no-db: creates .beads/ directory and issues.jsonl file instead of SQLite // Non-fatal - continue anyway } + // Create README.md + if err := createReadme(localBeadsDir); err != nil { + fmt.Fprintf(os.Stderr, "Warning: failed to create README.md: %v\n", err) + // Non-fatal - continue anyway + } + if !quiet { green := color.New(color.FgGreen).SprintFunc() cyan := color.New(color.FgCyan).SprintFunc() @@ -263,6 +269,12 @@ With --no-db: creates .beads/ directory and issues.jsonl file instead of SQLite fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err) // Non-fatal - continue anyway } + + // Create README.md + if err := createReadme(localBeadsDir); err != nil { + fmt.Fprintf(os.Stderr, "Warning: failed to create README.md: %v\n", err) + // Non-fatal - continue anyway + } } // Check if git has existing issues to import (fresh clone scenario) @@ -963,6 +975,107 @@ func createConfigYaml(beadsDir string, noDbMode bool) error { return nil } +// createReadme creates the README.md file in the .beads directory +func createReadme(beadsDir string) error { + readmePath := filepath.Join(beadsDir, "README.md") + + // Skip if already exists + if _, err := os.Stat(readmePath); err == nil { + return nil + } + + readmeTemplate := `# Beads - AI-Native Issue Tracking + +Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code. + +## What is Beads? + +Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git. + +**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads) + +## Quick Start + +### Essential Commands + +` + "```bash" + ` +# Create new issues +bd create "Add user authentication" + +# View all issues +bd list + +# View issue details +bd show + +# Update issue status +bd update --status in-progress +bd update --status done + +# Sync with git remote +bd sync +` + "```" + ` + +### Working with Issues + +Issues in Beads are: +- **Git-native**: Stored in ` + "`.beads/issues.jsonl`" + ` and synced like code +- **AI-friendly**: CLI-first design works perfectly with AI coding agents +- **Branch-aware**: Issues can follow your branch workflow +- **Always in sync**: Auto-syncs with your commits + +## Why Beads? + +✨ **AI-Native Design** +- Built specifically for AI-assisted development workflows +- CLI-first interface works seamlessly with AI coding agents +- No context switching to web UIs + +🚀 **Developer Focused** +- Issues live in your repo, right next to your code +- Works offline, syncs when you push +- Fast, lightweight, and stays out of your way + +🔧 **Git Integration** +- Automatic sync with git commits +- Branch-aware issue tracking +- Intelligent JSONL merge resolution + +## Get Started with Beads + +Try Beads in your own projects: + +` + "```bash" + ` +# Install Beads +curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + +# Initialize in your repo +bd init + +# Create your first issue +bd create "Try out Beads" +` + "```" + ` + +## Learn More + +- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs) +- **Quick Start Guide**: Run ` + "`bd quickstart`" + ` +- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples) + +--- + +*Beads: Issue tracking that moves at the speed of thought* ⚡ +` + + // Write README.md (0644 is standard for markdown files) + // #nosec G306 - README needs to be readable + if err := os.WriteFile(readmePath, []byte(readmeTemplate), 0644); err != nil { + return fmt.Errorf("failed to write README.md: %w", err) + } + + return nil +} + // readFirstIssueFromJSONL reads the first issue from a JSONL file func readFirstIssueFromJSONL(path string) (*types.Issue, error) { // #nosec G304 -- helper reads JSONL file chosen by current bd command