This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00
..

OSS Contributor Workflow Example

This example demonstrates how to use beads' contributor workflow to keep your planning issues separate from upstream PRs when contributing to open-source projects.

Problem

When contributing to OSS projects, you want to:

  • Track your planning, todos, and design notes
  • Keep experimental work organized
  • NOT pollute upstream PRs with your personal planning issues

Solution

Use bd init --contributor to set up a separate planning repository that never gets committed to the upstream project.

Setup

Step 1: Fork and Clone

# Fork the project on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/project.git
cd project

# Add upstream remote (important for fork detection!)
git remote add upstream https://github.com/ORIGINAL_OWNER/project.git

Step 2: Initialize Beads with Contributor Wizard

# Run the contributor setup wizard
bd init --contributor

The wizard will:

  1. ✅ Detect that you're in a fork (checks for 'upstream' remote)
  2. ✅ Prompt you to create a planning repo (~/.beads-planning by default)
  3. ✅ Configure auto-routing so your planning stays separate
  4. ✅ Initialize the planning repo with git

Step 3: Start Working

# Create a planning issue
bd create "Plan how to fix bug X" -p 2

# This issue goes to ~/.beads-planning automatically!

How It Works

Auto-Routing

When you create issues as a contributor:

bd create "Fix authentication bug" -p 1

Beads automatically routes this to your planning repo (~/.beads-planning/.beads/), not the current repo.

Viewing Issues

# See all issues (from both repos)
bd list

# See only current repo issues
bd list --source-repo .

# See only planning issues
bd list --source-repo ~/.beads-planning

Discovered Work

When you discover work while implementing:

# The new issue inherits source_repo from parent
bd create "Found edge case in auth" -p 1 --deps discovered-from:bd-42

Committing Code (Not Planning)

Your code changes get committed to the fork, but planning issues stay separate:

# Only commits to fork (not planning repo)
git add src/auth.go
git commit -m "Fix: authentication bug"
git push origin my-feature-branch

Your planning issues in ~/.beads-planning never appear in PRs.

Example Workflow

# 1. Create fork and clone
git clone https://github.com/you/upstream-project.git
cd upstream-project
git remote add upstream https://github.com/upstream/upstream-project.git

# 2. Run contributor setup
bd init --contributor
# Wizard detects fork ✓
# Creates ~/.beads-planning ✓
# Configures auto-routing ✓

# 3. Plan your work (routes to planning repo)
bd create "Research how auth module works" -p 2
bd create "Design fix for bug #123" -p 1
bd ready  # Shows planning issues

# 4. Implement (commit code only)
git checkout -b fix-auth-bug
# ... make changes ...
git add . && git commit -m "Fix: auth bug"

# 5. Track discovered work (stays in planning repo)
bd create "Found related issue in logout" -p 2 --deps discovered-from:bd-abc

# 6. Push code (planning never included)
git push origin fix-auth-bug
# Create PR on GitHub - zero planning pollution!

# 7. Clean up after PR merges
bd close bd-abc --reason "PR merged"

Configuration

The wizard configures these settings in .beads/beads.db:

routing:
  mode: auto
  contributor: ~/.beads-planning
  maintainer: .

Manual Configuration

If you prefer manual setup:

# Initialize beads normally
bd init

# Configure routing
bd config set routing.mode auto
bd config set routing.contributor ~/.beads-planning
bd config set routing.maintainer .

Legacy Configuration (Deprecated)

Older versions used contributor.* keys. These still work for backward compatibility:

# Old keys (deprecated but functional)
bd config set contributor.planning_repo ~/.beads-planning
bd config set contributor.auto_route true

# New keys (preferred)
bd config set routing.mode auto
bd config set routing.contributor ~/.beads-planning

Multi-Repository View

Beads aggregates issues from multiple repos:

# List issues from all configured repos
bd list

# Filter by source repository
bd list --source-repo .                    # Current repo only
bd list --source-repo ~/.beads-planning    # Planning repo only

Benefits

✅ Clean PRs - No personal todos in upstream contributions ✅ Private planning - Experimental work stays local ✅ Git ledger - Everything is version controlled ✅ Unified view - See all issues with bd list ✅ Auto-routing - No manual sorting needed

Common Questions

Q: What if I want some issues in the upstream repo?

A: Override auto-routing with --repo flag:

bd create "Document new API" -p 2 --repo .

Q: Can I change the planning repo location?

A: Yes, configure it:

bd config set routing.contributor /path/to/my-planning

Q: What if I have push access to upstream?

A: The wizard will ask if you want a planning repo anyway. You can say "no" to store everything in the current repo.

Q: How do I disable auto-routing?

A: Change routing mode to explicit:

bd config set routing.mode explicit
bd config set routing.default .  # Default to current repo

See Also