Skip to content

Add visual README and universal agent init - #1

Merged
dalonsogomez merged 7 commits into
mainfrom
codex/braid-layout-rename
Jun 5, 2026
Merged

dalonsogomez merged 7 commits into
mainfrom
codex/braid-layout-rename

Conversation

@dalonsogomez

@dalonsogomez dalonsogomez commented Jun 5, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Adds braid agent-init as the universal activation command for Claude, Codex, Cursor, and Copilot.
  • Rewrites the public README as a GitHub-ready technical landing page.
  • Adds editable Excalidraw sources plus SVG exports for memory boundaries, agent activation, and retrieval flow.

Test Plan

  • Validated README image links and parsed all Excalidraw/SVG assets.
  • PYTHONPATH=src .venv/bin/python -m pytest -q
  • PYTHONPATH=src .venv/bin/python -m braid.cli --help
  • braid agent-init --check --json
  • rg -n "wikiforge|fairlead" README.md only shows explicit legacy alias note.
  • git diff --check
  • git diff --cached --check

Summary by cubic

Adds a universal braid agent-init across Claude, Codex, Cursor, and Copilot, plus braid doctor, status --json, a new braid patterns playbook, and Obsidian export. Replaces the README with a visual, GitHub-ready landing page and updated diagrams.

  • New Features

    • braid agent-init with --agent, --check, --fix, --remove, --json. Idempotent; no indexing; respects nearest project boundary. Sets Claude SessionStart hook + MCP (braid mcp-serve), Codex session hook, and Cursor/Copilot discovery symlinks. braid claude-init now delegates.
    • Diagnostics: braid doctor [--json] [--fix] checks install, context, agents, secrets, and drift. braid status --json emits a stable payload. Config hardening preserves invalid JSON instead of overwriting.
    • Playbook: braid patterns [--json] exposes the operational patterns read-only, aligned with the new diagrams.
    • Wiki export: braid wiki build --obsidian creates an Obsidian vault in .braid/wiki/obsidian/ or writes to --vault (under Braid/<dataset_id>/). Supports --output for a fresh vault.
    • Docs/CI: visual README with refreshed diagrams (agent activation, memory boundaries, retrieval flow, operational patterns). CI validates README assets and uses actions/checkout@v6, actions/setup-python@v6 on Python 3.11. ADR 0017/0018/0019/0020 included. Tests cover drift detection, fix/remove, boundary resolution, JSON outputs, patterns, and Obsidian export.
    • DuckLake: SQL formatting fix for Python 3.11 and auto-install of DuckDB FTS in clean environments.
  • Migration

    • Run braid agent-init --fix in each repo to normalize hooks, MCP, and discovery symlinks.
    • Use braid agent-init --check --json and/or braid doctor --json in CI to detect drift; --remove uninstalls only Braid-managed blocks.
    • Optional: export memory to Obsidian with braid wiki build --obsidian.

Written for commit 91e6716. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • New Features

    • Added braid agent-init (apply/check/fix/remove) with --json and backward-compatible claude-init delegation.
    • New CLI commands: braid doctor (diagnostics, optional --fix/--json), braid status --json, and braid patterns [--json].
    • braid wiki gains Obsidian vault export mode (--obsidian, --vault/--output handling).
  • Documentation

    • Expanded README and added diagrams for agent activation, memory boundaries, retrieval flow, and operational patterns.
  • Tests & CI

    • New test suites for agent-init, doctor/status/patterns/wiki workflows and CI pipeline validating docs, tests, and CLI smoke checks.

@qodo-code-review

Copy link
Copy Markdown

Review Summary by Qodo

Add universal agent-init command and visual README documentation

✨ Enhancement 📝 Documentation

Grey Divider

Walkthroughs

Description
• Adds braid agent-init universal command for Claude, Codex, Cursor, Copilot activation
• Implements check/fix/remove modes for agent integration management
• Refactors claude-init to delegate to new agent-init command
• Expands README with visual diagrams and comprehensive architecture documentation
• Adds ADR 0017 decision record for universal agent initialization
Diagram
flowchart LR
  CLI["braid agent-init<br/>--check/fix/remove"]
  CLI -->|Claude| Claude["settings.json<br/>hook + MCP"]
  CLI -->|Codex| Codex["hooks.json<br/>SessionStart"]
  CLI -->|Cursor| Cursor["rules/main.mdc<br/>symlink"]
  CLI -->|Copilot| Copilot["instructions.md<br/>symlink"]
  Claude -->|manages| Legacy["Migrate legacy<br/>fairlead/wikiforge"]

Loading

Grey Divider

File Changes

1. src/braid/cli.py ✨ Enhancement +22/-0

Add agent-init subcommand with mode flags

src/braid/cli.py


2. src/braid/commands/agent.py ✨ Enhancement +357/-0

Implement universal agent activation logic

src/braid/commands/agent.py


3. src/braid/commands/claude.py ✨ Enhancement +3/-62

Refactor claude-init to delegate to agent-init

src/braid/commands/claude.py


View more (8)
4. tests/test_agent_init.py 🧪 Tests +170/-0

Add comprehensive tests for agent-init functionality

tests/test_agent_init.py


5. .braid/memory/MEMORY.md 📝 Documentation +1/-0

Record ADR 0017 universal agent init decision

.braid/memory/MEMORY.md


6. .braid/memory/decisions/0017-universal-agent-init.md 📝 Documentation +47/-0

Document universal agent init architecture decision

.braid/memory/decisions/0017-universal-agent-init.md


7. AGENTS.md 📝 Documentation +2/-0

Document agent-init command and usage patterns

AGENTS.md


8. README.md 📝 Documentation +219/-18

Rewrite as visual technical landing page with diagrams

README.md


9. docs/diagrams/braid-agent-activation.excalidraw 📝 Documentation +409/-0

Add Excalidraw diagram for agent activation flow

docs/diagrams/braid-agent-activation.excalidraw


10. docs/diagrams/braid-memory-boundaries.excalidraw 📝 Documentation +308/-0

Add Excalidraw diagram for memory scope boundaries

docs/diagrams/braid-memory-boundaries.excalidraw


11. docs/diagrams/braid-retrieval-flow.excalidraw 📝 Documentation +373/-0

Add Excalidraw diagram for retrieval architecture

docs/diagrams/braid-retrieval-flow.excalidraw


Grey Divider

Qodo Logo

@qodo-code-review

qodo-code-review Bot commented Jun 5, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0)

Grey Divider


Action required

1. Agent-init wrong root 🐞 Bug ≡ Correctness
Description
agent-init prefers find_project_root() (marker-based, e.g. any directory with README.md) over
the git root, so invoking it from a nested folder can write .claude/settings.json /
.codex/hooks.json into that folder and the hook integration may not be discovered where the agent
expects. This also makes claude-init behavior contradict its <git_root>/.claude/settings.json
help text and diverges from claude-session-start, which still reports status using
find_git_root().
Code

src/braid/commands/agent.py[R36-38]

+def _root() -> Path:
+    return find_project_root() or find_git_root() or Path.cwd().resolve()
+
Evidence
The new agent-init root selection prioritizes marker-based project roots, while the hook command
(claude-session-start) still resolves the git root; delegating claude-init to agent-init
therefore changes where .claude/settings.json may be written and can desynchronize activation vs
status.

src/braid/commands/agent.py[36-38]
src/braid/paths.py[23-38]
src/braid/commands/claude.py[94-107]
src/braid/commands/claude.py[214-218]
src/braid/cli.py[100-105]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`agent-init` resolves `root` using `find_project_root()` first, while `claude-session-start` uses `find_git_root()`. This can cause hooks/config to be written under a nested marker directory but status (and potentially other commands) to read state from the git root, breaking activation in nested-project scenarios and contradicting CLI help for `claude-init`.

## Issue Context
- `find_project_root()` treats `README.md` as a project marker, so many subdirectories can become “project roots”.
- `claude-init` now delegates to `agent-init`, inheriting this behavior.

## Fix Focus Areas
- src/braid/commands/agent.py[36-38]
- src/braid/commands/claude.py[214-218]
- src/braid/commands/claude.py[94-107]
- src/braid/cli.py[100-105]

## Suggested fix approach
- Decide a single canonical root resolution for *agent activation* and for `claude-session-start` (e.g., use `resolve_context().root` everywhere, or enforce git-root semantics for Claude/Codex configs).
- Update `claude-session-start` to use the same root resolution so the hook reports the correct project boundary.
- If `claude-init` is intended to remain git-root-scoped, enforce `find_git_root()` and error outside git, and/or adjust its help text accordingly.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

2. Non-dict JSON crashes ✓ Resolved 🐞 Bug ☼ Reliability
Description
agent-init assumes settings JSON is a dict and that SessionStart entries contain lists of dict
hooks; valid JSON with an unexpected shape (e.g., a top-level list/object mismatch) can trigger
AttributeError via .get() and crash the command. This can prevent --check/--fix/--remove from
running on real-world, hand-edited or corrupted agent config files.
Code

src/braid/commands/agent.py[R40-46]

+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        return json.loads(path.read_text()) or {}
+    except (OSError, json.JSONDecodeError):
+        return {}
Evidence
_load_json returns the raw parsed JSON (which can be any type), but subsequent logic uses
dict-only APIs (.get) on settings, event, and hook without type checks, making a crash
likely for malformed-but-parseable configs.

src/braid/commands/agent.py[40-46]
src/braid/commands/agent.py[85-100]
src/braid/commands/agent.py[109-116]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`_load_json()` can return non-dict values (e.g., a list) when the file contains valid JSON that isn’t an object. Downstream code (`_session_start_events`, `_hook_drift`, `_strip_braid_hooks`) calls `.get()` on values from that structure without validating types, which can crash `agent-init`.

## Issue Context
This command touches user-controlled config files (`.claude/settings.json`, `.codex/hooks.json`). Defensive parsing is important to avoid hard crashes and to surface drift clearly.

## Fix Focus Areas
- src/braid/commands/agent.py[40-46]
- src/braid/commands/agent.py[85-106]
- src/braid/commands/agent.py[109-121]

## Suggested fix approach
- In `_load_json`, after `json.loads`, return `{}` unless the parsed value is a `dict`.
- In `_hook_drift` / `_strip_braid_hooks`, skip non-dict `event` items and non-dict `hook` items (or treat them as drift) instead of calling `.get()`.
- Optionally treat decoding errors (`UnicodeDecodeError`) as a safe `{}` parse (or explicit drift) to avoid crashing on non-UTF8 files.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Qodo Logo

@coderabbitai

coderabbitai Bot commented Jun 5, 2026 •

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Adds a canonical braid agent-init command with CLI wiring, implementation for JSON/symlink-based agents, ADRs/docs/diagrams, diagnostic/status/patterns/wiki command additions, DuckLake extension helpers, CI workflow, and comprehensive tests.

Changes

Universal agent initialization and related ops

Layer / File(s) Summary
ADRs, README, and diagrams
.braid/memory/MEMORY.md, .braid/memory/decisions/*.md, README.md, docs/diagrams/*
Adds ADRs 0017–0020, updates memory index, expands README and AGENTS.md, and adds Excalidraw diagrams for agent activation, memory boundaries, retrieval flow, and operational patterns.
CLI surface and dispatch
src/braid/cli.py
Adds agent-init subcommand and extends wiki, status, doctor, and patterns flags; wires dispatch to new command modules.
Agent reconciliation implementation
src/braid/commands/agent.py
Implements reconciliation for JSON-based agents (Claude/Codex) and symlink-based agents (Cursor/Copilot), with check/fix/remove modes, drift detection, repair/removal behavior, and top-level run() producing human or JSON output.
claude-init compatibility
src/braid/commands/claude.py
Refactors run_init() into a wrapper delegating to agent.run(agent="claude", ...).
Diagnostics, status, patterns, and wiki obsidian
src/braid/commands/doctor.py, src/braid/commands/status.py, src/braid/commands/patterns.py, src/braid/commands/wiki.py
Adds doctor diagnostic payload and --fix, structured status --json, patterns [--json] playbook generator, and Obsidian vault export support for wiki.
DuckLake robustness and SQL helpers
src/braid/ducklake.py
Adds load_duckdb_extension() with optional install fallback, _sql_str_or_null() for nullable SQL literals, conditional FTS loading, and refactors multiple INSERTs to use the helper.
Tests and test harness
tests/*, tests/conftest.py
Adds comprehensive tests for agent-init, status/doctor, patterns, wiki obsidian export, and DuckLake FTS loading; updates conftest to use the new extension loader.
CI workflow
.github/workflows/ci.yml
Adds CI job to install, validate README/diagram assets, run pytest, perform CLI smoke checks, and enforce whitespace diffs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A tiny rabbit hops and writes a fix so neat,
Four agents meet at one command — what a treat,
Docs and tests in baskets, CI lights the way,
Safe checks, JSON voices, symlinks tucked away,
One init to rule them all — the meadow's complete!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 15.83% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the two main changes: the addition of universal agent initialization and a comprehensive README rewrite with visual diagrams.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/braid-layout-rename

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@augmentcode

augmentcode Bot commented Jun 5, 2026

Copy link
Copy Markdown
🤖 Augment PR Summary

Summary: This PR standardizes agent activation by introducing braid agent-init as the universal entrypoint and refreshes the public README as a GitHub-friendly landing page.

Changes:

  • Adds ADR 0017 documenting agent-init behavior, flags, and legacy migration expectations.
  • Updates the CLI to expose braid agent-init for Claude/Codex/Cursor/Copilot with --check/--fix/--remove and optional JSON output.
  • Implements agent integration management (Claude/Codex JSON config + Cursor/Copilot discovery symlinks) under src/braid/commands/agent.py.
  • Makes braid claude-init a compatibility wrapper delegating to agent-init.
  • Rewrites README.md with updated positioning, quick start, activation guidance, and retrieval overview.
  • Adds editable Excalidraw diagram sources (and SVG exports) for memory boundaries, activation, and retrieval flow.
  • Adds a dedicated test suite covering drift detection, legacy migration, removal behavior, CLI JSON output, and child-boundary root selection.

Technical Notes: The command is designed to be idempotent, avoid indexing/LLM calls, and treat legacy fairlead/wikiforge hooks as drift that can be normalized.

🤖 Was this summary useful? React with 👍 or 👎

@augmentcode augmentcode Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review completed. 3 suggestions posted.

Fix All in Augment

Comment augment review to trigger a new review at any time.

Comment thread src/braid/commands/agent.py Outdated
if not path.is_file():
return {}
try:
return json.loads(path.read_text()) or {}

@augmentcode augmentcode Bot Jun 5, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_load_json() swallows JSON parse/read failures and returns {}, which can make agent-init overwrite a user’s existing (but slightly invalid / non-UTF8) config with a minimal Braid config on apply/remove without warning. Consider surfacing an explicit error/drift state (and also handling UnicodeDecodeError) to avoid accidental data loss.

Severity: medium

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

canonical = False
legacy = False
for event in events:
for hook in event.get("hooks", []) or []:

@augmentcode augmentcode Bot Jun 5, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_hook_drift() (and _strip_braid_hooks()) assume each SessionStart event and each hook are dicts; if the JSON contains unexpected shapes, .get(...) will raise and the command will crash. Since these are user-edited files, consider validating types before accessing .get so agent-init can report drift instead of throwing.

Severity: medium

Other Locations
  • src/braid/commands/agent.py:114

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

return (agent,) # type: ignore[return-value]


def _mode(check: bool, fix: bool, remove: bool) -> Mode:

@augmentcode augmentcode Bot Jun 5, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--fix is treated as mutually exclusive but _mode() never returns a distinct mode for it (it becomes apply), so JSON/human output will show mode=apply even when users explicitly request --fix. If consumers rely on the reported mode, this could be confusing.

Severity: low

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35b4dffd0c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +36 to +37
def _root() -> Path:
return find_project_root() or find_git_root() or Path.cwd().resolve()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Align hook root with project boundary

Cuando agent-init se ejecuta dentro de un proyecto hijo que tiene marcador propio pero comparte el .git de un contenedor, esta selección instala .claude/.codex bajo el hijo; sin embargo el hook instalado ejecuta braid claude-session-start, que todavía resuelve con find_git_root() en src/braid/commands/claude.py, por lo que reporta y valida la memoria del padre en lugar de la del proyecto donde se instaló. En ese escenario el banner puede pedir indexar el repo equivocado o ignorar .braid del hijo, justo el caso cubierto por test_agent_init_uses_child_project_boundary; el hook debería usar la misma frontera de proyecto que agent-init o recibirla explícitamente.

Useful? React with 👍 / 👎.

Comment on lines +36 to +38
def _root() -> Path:
return find_project_root() or find_git_root() or Path.cwd().resolve()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Agent-init wrong root 🐞 Bug ≡ Correctness

agent-init prefers find_project_root() (marker-based, e.g. any directory with README.md) over
the git root, so invoking it from a nested folder can write .claude/settings.json /
.codex/hooks.json into that folder and the hook integration may not be discovered where the agent
expects. This also makes claude-init behavior contradict its <git_root>/.claude/settings.json
help text and diverges from claude-session-start, which still reports status using
find_git_root().
Agent Prompt
## Issue description
`agent-init` resolves `root` using `find_project_root()` first, while `claude-session-start` uses `find_git_root()`. This can cause hooks/config to be written under a nested marker directory but status (and potentially other commands) to read state from the git root, breaking activation in nested-project scenarios and contradicting CLI help for `claude-init`.

## Issue Context
- `find_project_root()` treats `README.md` as a project marker, so many subdirectories can become “project roots”.
- `claude-init` now delegates to `agent-init`, inheriting this behavior.

## Fix Focus Areas
- src/braid/commands/agent.py[36-38]
- src/braid/commands/claude.py[214-218]
- src/braid/commands/claude.py[94-107]
- src/braid/cli.py[100-105]

## Suggested fix approach
- Decide a single canonical root resolution for *agent activation* and for `claude-session-start` (e.g., use `resolve_context().root` everywhere, or enforce git-root semantics for Claude/Codex configs).
- Update `claude-session-start` to use the same root resolution so the hook reports the correct project boundary.
- If `claude-init` is intended to remain git-root-scoped, enforce `find_git_root()` and error outside git, and/or adjust its help text accordingly.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
src/braid/commands/claude.py (1)

32-35: 💤 Low value

Consider extracting shared constants to reduce duplication.

HOOK_COMMAND, HOOK_MARKER, and LEGACY_HOOK_MARKERS are defined here and similarly in agent.py. Since run_init now delegates to the agent module, you could import these constants from there. This isn't blocking—the current approach works—but it would reduce future maintenance burden if hook commands change.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/braid/commands/claude.py` around lines 32 - 35, Extract the duplicated
hook constants from this file by importing them from the agent module instead of
redefining them here: replace the local definitions of HOOK_COMMAND,
HOOK_MARKER, and LEGACY_HOOK_MARKERS in src/braid/commands/claude.py with
imports from the agent module (the same source where run_init now delegates),
update any references in this file to use the imported symbols, and remove the
redundant local declarations to keep a single canonical definition.
src/braid/commands/agent.py (1)

136-140: 💤 Low value

Minor: Action reporting could be clearer.

When removed > 0, the function appends a new canonical hook AND reports normalized_hook. When removed == 0, it reports ensured_hook. Both cases add the canonical hook, but only one action is reported. Consider reporting both normalized_hook and ensured_hook when applicable, or rename normalized_hook to something like replaced_legacy_hook for clarity.

This is cosmetic—the reconciliation logic itself is correct.

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/braid/commands/claude.py`:
- Around line 32-35: Extract the duplicated hook constants from this file by
importing them from the agent module instead of redefining them here: replace
the local definitions of HOOK_COMMAND, HOOK_MARKER, and LEGACY_HOOK_MARKERS in
src/braid/commands/claude.py with imports from the agent module (the same source
where run_init now delegates), update any references in this file to use the
imported symbols, and remove the redundant local declarations to keep a single
canonical definition.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3a20b278-172c-4415-bfc6-d676f15a8118

📥 Commits

Reviewing files that changed from the base of the PR and between dfc979d and 35b4dff.

⛔ Files ignored due to path filters (3)
  • docs/diagrams/braid-agent-activation.svg is excluded by !**/*.svg
  • docs/diagrams/braid-memory-boundaries.svg is excluded by !**/*.svg
  • docs/diagrams/braid-retrieval-flow.svg is excluded by !**/*.svg
📒 Files selected for processing (11)
  • .braid/memory/MEMORY.md
  • .braid/memory/decisions/0017-universal-agent-init.md
  • AGENTS.md
  • README.md
  • docs/diagrams/braid-agent-activation.excalidraw
  • docs/diagrams/braid-memory-boundaries.excalidraw
  • docs/diagrams/braid-retrieval-flow.excalidraw
  • src/braid/cli.py
  • src/braid/commands/agent.py
  • src/braid/commands/claude.py
  • tests/test_agent_init.py

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 issues found across 14 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/braid/commands/agent.py">

<violation number="1" location="src/braid/commands/agent.py:97">
P2: `_hook_drift` can crash on malformed but parseable settings because it does not type-check `event`/`hook` entries.</violation>
</file>

<file name="src/braid/commands/claude.py">

<violation number="1" location="src/braid/commands/claude.py:218">
P2: `claude-init` wrapper changed root resolution semantics and can write `.claude/settings.json` outside `<git_root>`.</violation>
</file>

Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic

events = _session_start_events(settings)
canonical = False
legacy = False
for event in events:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: _hook_drift can crash on malformed but parseable settings because it does not type-check event/hook entries.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/braid/commands/agent.py, line 97:

<comment>`_hook_drift` can crash on malformed but parseable settings because it does not type-check `event`/`hook` entries.</comment>

<file context>
@@ -0,0 +1,357 @@
+    events = _session_start_events(settings)
+    canonical = False
+    legacy = False
+    for event in events:
+        for hook in event.get("hooks", []) or []:
+            canonical = canonical or _is_canonical_hook(hook)
</file context>


_save_settings(target, settings)
return 0
return agent_cmd.run(agent="claude", remove=remove)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: claude-init wrapper changed root resolution semantics and can write .claude/settings.json outside <git_root>.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/braid/commands/claude.py, line 218:

<comment>`claude-init` wrapper changed root resolution semantics and can write `.claude/settings.json` outside `<git_root>`.</comment>

<file context>
@@ -212,66 +212,7 @@ def _strip_braid_hook(events: list[dict]) -> list[dict]:
-
-    _save_settings(target, settings)
-    return 0
+    return agent_cmd.run(agent="claude", remove=remove)
</file context>

Comment thread src/braid/commands/agent.py Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/ci.yml">

<violation number="1" location=".github/workflows/ci.yml:7">
P2: Workflow omits an explicit least-privilege `permissions` policy for `GITHUB_TOKEN`, increasing CI token exposure.</violation>
</file>

<file name="src/braid/commands/doctor.py">

<violation number="1" location="src/braid/commands/doctor.py:157">
P2: `doctor --fix` can modify agent config in the current directory while reporting a different root in global-profile mode.</violation>
</file>

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread .github/workflows/ci.yml
push:
pull_request:

jobs:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Workflow omits an explicit least-privilege permissions policy for GITHUB_TOKEN, increasing CI token exposure.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/ci.yml, line 7:

<comment>Workflow omits an explicit least-privilege `permissions` policy for `GITHUB_TOKEN`, increasing CI token exposure.</comment>

<file context>
@@ -0,0 +1,55 @@
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
</file context>



def _check_agents(ctx: paths_module.ProjectContext, fix: bool) -> DoctorCheck:
root = ctx.root if not ctx.global_profile else Path.cwd().resolve()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: doctor --fix can modify agent config in the current directory while reporting a different root in global-profile mode.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/braid/commands/doctor.py, line 157:

<comment>`doctor --fix` can modify agent config in the current directory while reporting a different root in global-profile mode.</comment>

<file context>
@@ -0,0 +1,279 @@
+
+
+def _check_agents(ctx: paths_module.ProjectContext, fix: bool) -> DoctorCheck:
+    root = ctx.root if not ctx.global_profile else Path.cwd().resolve()
+    mode: agent_cmd.Mode = "apply" if fix else "check"
+    results = [agent_cmd._run_one(name, root, mode) for name in agent_cmd.AGENTS]
</file context>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 22 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/ci.yml">

<violation number="1" location=".github/workflows/ci.yml:34">
P2: README image validation regex is over-escaped, so CI does not detect missing markdown image assets.</violation>
</file>

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread .github/workflows/ci.yml

root = Path.cwd()
readme = (root / "README.md").read_text()
links = re.findall(r'!\\[[^\\]]*\\]\\(([^)]+)\\)', readme)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: README image validation regex is over-escaped, so CI does not detect missing markdown image assets.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/ci.yml, line 34:

<comment>README image validation regex is over-escaped, so CI does not detect missing markdown image assets.</comment>

<file context>
@@ -0,0 +1,55 @@
+
+          root = Path.cwd()
+          readme = (root / "README.md").read_text()
+          links = re.findall(r'!\\[[^\\]]*\\]\\(([^)]+)\\)', readme)
+          missing = [link for link in links if not (root / link).is_file()]
+          if missing:
</file context>

@dalonsogomez
dalonsogomez merged commit 91e6716 into main Jun 5, 2026
3 of 4 checks passed
@dalonsogomez
dalonsogomez deleted the codex/braid-layout-rename branch October 6, 2026 15:02
@dalonsogomez
dalonsogomez restored the codex/braid-layout-rename branch November 18, 2026 06:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant