[pull] main from PaulDuvall:main

README.md

@@ -676,7 +676,7 @@ Generated issues must include:
 - **Dependency Validation**: Automated checking for circular dependencies
 - **Status Propagation**: Subissue changes update epic progress
 
-**Implementation Examples**: See [examples/issue-generation/](examples/issue-generation/) for detailed AI prompts, epic breakdown workflows, CI integration patterns, and traceability implementations.
+**Implementation Examples**: See [examples/issue-generation/](examples/issue-generation/) for detailed AI prompts, epic breakdown workflows, CI integration patterns, and traceability implementations. For AI-first workflows, see [Beads guide](examples/issue-generation/beads-guide.md) - a git-native issue tracker with CLI access and persistent agent memory.
 
 > "If a task takes more than one day, split it."
 > – Kanban Guide, Lean Kanban University

examples/issue-generation/.beads/.gitignore

@@ -0,0 +1,29 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Keep JSONL exports and config (source of truth for git)
+!issues.jsonl
+!metadata.json
+!config.json

examples/issue-generation/.beads/.local_version

@@ -0,0 +1 @@
+0.29.0

examples/issue-generation/.beads/README.md

@@ -0,0 +1,81 @@
+# 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 <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --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* ⚡

examples/issue-generation/.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

examples/issue-generation/.beads/issues.jsonl

@@ -0,0 +1,11 @@
+{"id":"issue-generation-7c9","title":"Epic: Restructure issue-generation examples for MECE, AI-first workflow","description":"Complete restructure of examples/issue-generation directory:\n- Fix task sizing (4-8 hours → \u003c1 hour for AI development)\n- Consolidate duplicate content (MECE compliance)\n- Create numbered learning path\n- Slim down README as navigation hub\n- Rename files with clear structure","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:15:44.932916-05:00","updated_at":"2025-12-10T11:10:01.863134-05:00","closed_at":"2025-12-10T11:10:01.863137-05:00"}
+{"id":"issue-generation-7c9.1","title":"Update task sizing: 4-8 hours → \u003c1 hour in all files","description":"Update all references to '4-8 hours' to '\u003c1 hour' across:\n- README.md\n- ai-prompts-for-epic-management.md\n- detailed-kanban-workflow.md\n- ci-integration-examples.md\n- beads-example.md\nTarget: \u003c30 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:15:54.341478-05:00","updated_at":"2025-12-10T11:10:01.224491-05:00","closed_at":"2025-12-10T11:10:01.224493-05:00","dependencies":[{"issue_id":"issue-generation-7c9.1","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:15:54.341959-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.10","title":"Validate links and test navigation flow","description":"Final validation:\n- Check all internal links resolve\n- Test learning path flow (01 → 02 → 03...)\n- Verify no orphaned content\n- Confirm MECE compliance\nTarget: \u003c20 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:42.825114-05:00","updated_at":"2025-12-10T11:10:01.796202-05:00","closed_at":"2025-12-10T11:10:01.796204-05:00","dependencies":[{"issue_id":"issue-generation-7c9.10","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:42.82554-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.2","title":"Create 01-getting-started.md with AI-first concepts","description":"Create new getting started guide covering:\n- What are Kanban-optimized issues for AI development\n- Why \u003c1 hour tasks (not 4-8)\n- Core principles (flow, RED/GREEN/REFACTOR, CI/CD)\n- Next steps navigation\nTarget: \u003c45 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:11.959822-05:00","updated_at":"2025-12-10T11:10:01.287875-05:00","closed_at":"2025-12-10T11:10:01.287878-05:00","dependencies":[{"issue_id":"issue-generation-7c9.2","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:11.960319-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.3","title":"Create 02-choosing-tools.md from README content","description":"Extract tool comparison from README:\n- Decision tree (Beads vs traditional)\n- Comparison table (already exists in README)\n- When to use each tool\n- Hybrid approach guidance\nTarget: \u003c30 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:12.054233-05:00","updated_at":"2025-12-10T11:10:01.34896-05:00","closed_at":"2025-12-10T11:10:01.348962-05:00","dependencies":[{"issue_id":"issue-generation-7c9.3","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:12.05472-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.4","title":"Consolidate to 03-ai-prompts.md (rename ai-prompts-for-epic-management.md)","description":"Consolidate all AI prompt content:\n- Rename ai-prompts-for-epic-management.md → 03-ai-prompts.md\n- Remove duplicate prompts from detailed-kanban-workflow.md\n- Update task sizing in examples\n- Add cross-references\nTarget: \u003c45 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:12.145198-05:00","updated_at":"2025-12-10T11:10:01.407851-05:00","closed_at":"2025-12-10T11:10:01.407853-05:00","dependencies":[{"issue_id":"issue-generation-7c9.4","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:12.14562-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.5","title":"Rename to 04-workflow-examples.md and remove duplicates","description":"Rename detailed-kanban-workflow.md → 04-workflow-examples.md:\n- Remove duplicate AI prompts (already in 03-ai-prompts.md)\n- Keep JSON output examples\n- Update task sizing to \u003c1 hour\n- Add cross-references\nTarget: \u003c45 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:24.689343-05:00","updated_at":"2025-12-10T11:10:01.46827-05:00","closed_at":"2025-12-10T11:10:01.468273-05:00","dependencies":[{"issue_id":"issue-generation-7c9.5","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:24.689803-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.6","title":"Rename ci-integration-examples.md to 05-ci-integration.md","description":"Simple rename with updates:\n- Rename ci-integration-examples.md → 05-ci-integration.md\n- Update task sizing references\n- No content consolidation needed (well-scoped)\nTarget: \u003c15 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:24.788249-05:00","updated_at":"2025-12-10T11:10:01.533171-05:00","closed_at":"2025-12-10T11:10:01.533174-05:00","dependencies":[{"issue_id":"issue-generation-7c9.6","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:24.788712-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.7","title":"Rename beads-example.md to beads-guide.md","description":"Rename and update:\n- Rename beads-example.md → beads-guide.md\n- Update task sizing (4-8 hours → \u003c1 hour)\n- Parallel track for Beads users\nTarget: \u003c15 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:24.882337-05:00","updated_at":"2025-12-10T11:10:01.598146-05:00","closed_at":"2025-12-10T11:10:01.598149-05:00","dependencies":[{"issue_id":"issue-generation-7c9.7","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:24.882787-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.8","title":"Restructure README.md as navigation hub","description":"Transform README from content dump to navigation:\n- Remove detailed examples (keep quick start only)\n- Add learning path guide (01 → 02 → 03...)\n- Update directory structure listing\n- Keep comparison table for quick reference\n- Update task sizing to \u003c1 hour\nTarget: \u003c45 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:42.628954-05:00","updated_at":"2025-12-10T11:10:01.664111-05:00","closed_at":"2025-12-10T11:10:01.664113-05:00","dependencies":[{"issue_id":"issue-generation-7c9.8","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:42.629442-05:00","created_by":"daemon"}]}
+{"id":"issue-generation-7c9.9","title":"Update all internal references and links","description":"Update cross-references after renames:\n- Main repo README.md references\n- Internal links within issue-generation files\n- Directory structure in README.md\n- Ensure all markdown links work\nTarget: \u003c30 minutes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:16:42.72715-05:00","updated_at":"2025-12-10T11:10:01.730105-05:00","closed_at":"2025-12-10T11:10:01.730107-05:00","dependencies":[{"issue_id":"issue-generation-7c9.9","depends_on_id":"issue-generation-7c9","type":"parent-child","created_at":"2025-12-10T10:16:42.72761-05:00","created_by":"daemon"}]}

examples/issue-generation/.beads/metadata.json

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

examples/issue-generation/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads