Imported from lambda-curry/devagent (.devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/AGENTS.md). Install upstream with npx skills add lambda-curry/devagent --skill 2026-01-19_repeatable-beads-setup-instructions. Copyright stays with the author.

Document Repeatable Beads Setup Instructions [DERIVED] Progress Tracker

Owner: Jake Ruesink
Last Updated: 2026-01-20
Status: Complete
Task Hub: .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/

Summary

To set this up with easy to replicate instructions for new setups.

This task will produce clear, copy/paste-friendly setup instructions for new environments so Beads can be configured cleanly and consistently (including options like keeping Beads state in a separate “sister” repo via BEADS_DIR, and/or using multi-repo routing/hydration where appropriate). The goal is a repeatable onboarding path that minimizes repo “noise” while keeping sync behavior reliable.

Agent Update Instructions

Always update "Last Updated" to today's date (ISO: YYYY-MM-DD) when editing this file. Get the current date by explicitly running date +%Y-%m-%d first, then use the output for the "Last Updated" field.
Progress Log: Append a new entry at the end in the form - [YYYY-MM-DD] Event: concise update, links to files. Do not rewrite or delete prior entries. Use the date retrieved from date +%Y-%m-%d for the date portion.
Implementation Checklist: Mark items as [x] when complete, [~] for partial with a short note. Add new items if discovered; avoid removing items—strike through only when obsolete.
Key Decisions: Record important decisions as - [YYYY-MM-DD] Decision: rationale, links. Use the date retrieved from date +%Y-%m-%d for the date portion.
References: Keep links current to latest spec, research, and tasks. Add additional references as they are created.
Scope: Edits here should reflect coordination/progress only; do not include application code changes. Preserve history.

Key Decisions

[2026-01-19] Decision: Start by documenting existing Beads sync-branch + normal sync setups, then add “separate repo” (BEADS_DIR) and multi-repo routing/hydration variants for clean-code-repo workflows.
[2026-01-20] Decision: Recommended default for DevAgent-like repos (today) is sync-branch mode; submodule remains “target / blocked” pending upstream support. Source of truth for instructions is .devagent/core/docs/beads-setup.md.

Progress Log

[2026-01-19] Event: Task hub scaffolded.
[2026-01-19] Event: Added research packet on “separate repo” (BEADS_DIR) + multi-repo options, including what is (and is not yet) evidenced in .devagent/**: .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/research/2026-01-19_beads-separate-repo-and-multi-repo-options.md.
[2026-01-19] Event: Add investigation note — consider a dedicated Beads setup for Ralph E2E runs (separate BEADS_DIR + E2E-specific BEADS_DB) to keep the main .beads database clean.
[2026-01-20] Event: Completed first clarification pass for “low-noise Beads sync” (target: .beads/ as submodule; bundled-only pointer bumps; hooks/setup needed): .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/clarification/2026-01-20_initial-clarification.md.
[2026-01-20] Event: Added updated research packet reflecting clarified submodule target + decision tree and unresolved validations: .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/research/2026-01-20_low-noise-beads-submodule-setup-research.md.
[2026-01-20] Event: Drafted plan document for low-noise Beads setup instructions: .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/plan/2026-01-20_repeatable-beads-setup-instructions-plan.md.
[2026-01-20] Event: Task 1 completed: created .devagent/core/docs/beads-setup.md draft and linked from .devagent/core/README.md.
[2026-01-20] Event: Task 2 completed: added evidence-tagged decision tree and recommended defaults to .devagent/core/docs/beads-setup.md.
[2026-01-20] Event: Task 3 completed: recorded submodule validation results in .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/research/2026-01-20_beads-submodule-validation.md and updated core doc notes.
[2026-01-20] Event: Task 4 completed: documented drift mitigation, hook strategy, and fresh-clone setup steps in .devagent/core/docs/beads-setup.md.
[2026-01-20] Event: Task 5 completed: added troubleshooting + verification checklist and recorded fresh-clone validation in .devagent/workspace/tasks/completed/2026-01-19_repeatable-beads-setup-instructions/research/2026-01-20_fresh-clone-validation.md.
[2026-01-20] Event: Ran bd doctor and attempted bd doctor --fix + hook refresh; fixes blocked by .git/ write permissions in this environment. Updated .devagent/core/docs/beads-setup.md with doctor/health check guidance and hook refresh notes.
[2026-01-20] Event: Re-ran the blocked fixes with normal git permissions: forced hook refresh (bd hooks install --force), resolved DB/JSONL sync and hook health, rebuilt a readonly DB from JSONL + migrated (bd import, bd migrate --update-repo-id, bd migrate), ran bd sync to reconcile/push beads-sync, renamed “Test …” titled tasks to avoid pollution heuristics, and validated commit-time churn prevention (post-commit git diff --name-only unchanged; .beads/issues.jsonl hashes stable). Remaining warning: Claude integration not configured; bd doctor still prints a “Test Pollution” summary warning even when bd doctor --check=pollution reports clean.
[2026-01-20] Event: Clarified remaining completion gaps: default is sync-branch; canonical output is core doc; “done enough” is default walkthrough only. Added DB-only Ralph E2E variant notes to .devagent/core/docs/beads-setup.md and captured decisions in task clarification.
[2026-01-20] Event: Task moved to completed. Updated all status references and file paths from active/ to completed/ throughout task directory.

Implementation Checklist

Open Questions

(Resolved 2026-01-20) Output format/location: core doc only (.devagent/core/docs/beads-setup.md).
(Resolved 2026-01-20) Default recommendation (today): sync-branch mode.

References

[2026-01-19] .devagent/workspace/research/2026-01-14_beads-syncing-setup.md — Existing DevAgent Beads syncing setup patterns and verification steps.
[2026-01-19] .devagent/workspace/research/2026-01-14_beads-sync-branch-setup.md — Sync-branch mode architecture notes and daily workflow.
[2026-01-19] .devagent/workspace/research/2026-01-14_beads-setup-audit.md — Audit notes; highlights common setup mismatches and verification gaps.
[2026-01-19] .devagent/workspace/research/2026-01-14_beads-best-practices-compliance.md — Best-practices checklist and re-init guidance for reliable sync.

Next Steps

devagent research (focus: “separate beads repo via BEADS_DIR”, “multi-repo routing/hydration”, “recommended default for new setups”, verification + troubleshooting)
devagent create-plan (turn research into a concrete doc plan + acceptance checklist)

2026-01-19_repeatable-beads-setup-instructions

About