docs(catalog): record the 2026-10-03 practitioner sweep

[R0SEWT]

Summary

Open research sweep for the kit: what people running Claude Code daily actually use and complain about, across git flow, parallel agents, guardrails, and context/data. Evidence from HN threads, GitHub, official docs and blogs, not papers. Reddit returned 403, so it is absent.

Changes

• New dated entry in catalog/setup-options.md: candidates with adopt / trial / reject verdicts and the HN links behind each.
• Beads: epic project-kit-62f with 7 children, one per adopt. dl7 (DuckDB MCP) closes: rejected as a default, trial opt-in per project.
• Headline finding: Claude Code reads AGENTS.md only when CLAUDE.md is absent, so the scaffold's AGENTS.md is invisible today (62f.1, filed as a bug).

Testing

Docs only. CI lint covers the rest of the repo.

Related

bd: project-kit-62f, project-kit-dl7

🤖 Generated with Claude Code

Summary by Sourcery

Document practitioner-informed setup recommendations for coding-agent workflows and track the resulting adoption work.

New Features:

• Record practitioner-backed recommendations for Git workflow, parallel agents, guardrails, and context/data practices, with adopt, trial, reject, and hold verdicts.
• Create follow-up beads for the recommended changes, including the identified CLAUDE.md/AGENTS.md visibility issue and DuckDB MCP decision.

Bug Fixes:

• Identify that the scaffold’s AGENTS.md is currently ignored when CLAUDE.md is present and track its resolution.

Enhancements:

• Document evidence-based guidance for native Claude Code worktrees, agent coordination, command guardrails, formatting, test-integrity checks, memory, and data exploration.
• Clarify that DuckDB MCP should be opt-in rather than a default and retain beads as the coordination layer.

Documentation:

• Add the 2026-10-03 practitioner research sweep to the setup-options catalog.

Chores:

• Update Beads issue tracking to reflect the adopted recommendations and related follow-ups.

[sourcery-ai]

Sorry @R0SEWT, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 3 days and 3 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

This docs-only change records the 2026-10-03 open research sweep and translates practitioner evidence into implementation decisions and follow-up beads for the kit, with particular attention to native Claude Code worktrees, deny-mode guardrails, CI checks, context-file behavior, and DuckDB usage.

Sequence diagram for Claude Code guard hook enforcement

sequenceDiagram
    participant ClaudeCode
    participant PreToolUse
    participant Bash

    ClaudeCode->>PreToolUse: Bash command
    PreToolUse->>PreToolUse: Check deny rules
    alt dangerous command
        PreToolUse-->>ClaudeCode: deny
        ClaudeCode-->>Bash: Command blocked
    else permitted command
        PreToolUse-->>ClaudeCode: allow
        ClaudeCode->>Bash: Execute command
    end

Loading

Flow diagram for Claude Code context-file loading

flowchart TD
    Start[Claude Code starts] --> Check{CLAUDE.md exists?}
    Check -->|Yes| LoadClaude[Read CLAUDE.md]
    Check -->|No| LoadAgents[Read AGENTS.md]
    LoadClaude --> Context[Agent context]
    LoadAgents --> Context
    Context --> End[Agent operates]

Loading

File-Level Changes

Change	Details	Files
Added a dated practitioner-research entry documenting adopt, trial, hold, and reject decisions across git workflow, parallel agents, guardrails, and context/data handling.	Recorded evidence and verdicts for native worktrees, attribution settings, PR-title validation, agent teams, Worktrunk, and rejected alternatives. Recommended guard hooks, formatting automation, CI test-integrity checks, and trials for prek, sandboxing, and secret scanning. Documented the CLAUDE.md-versus-AGENTS.md loading behavior and proposed a short importing CLAUDE.md plus data-query conventions. Evaluated DuckDB CLI versus DuckDB MCP, retaining the CLI as the default and closing the MCP follow-up as opt-in trial only. Captured the resulting adoption work as a beads epic with seven child issues, including the AGENTS.md visibility bug and DuckDB MCP decision.	catalog/setup-options.md .beads/issues.jsonl

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.