Cascading fixes · Claudear Docs

#What it does

A fix in a shared library often means dependent applications need updating too. Cascading fixes automate this: when a fix merges in an upstream repo, Claudear opens follow-up PRs in every downstream repo that depends on it.

#How dependency chains work

Dependencies are auto-detected — on first run Claudear scans package manifests (package.json, composer.json) across your repos and builds a dependency graph automatically. The graph is refreshed in the background on a regular cycle, so new dependencies are picked up without manual intervention.
Upstream fix merges — when the PR in repo A is merged (or a release is created, depending on the trigger), Claudear walks the dependency graph.
Downstream PRs — for each downstream repo, Claudear opens a PR that updates the dependency version and applies any necessary code changes.
Depth control — cascades can chain: A→B→C. Use max_depth to limit how deep the chain goes.

Note: You do not need to manually declare every dependency. Auto-detection covers npm and Composer packages from your known_orgs. Use claudear repos link only for relationships that can't be inferred from manifests (e.g. git submodules, cross-org repos, or implicit code dependencies).

#Configuration

Settings live under [cascade] and [[cascade.rules]]. See the full reference for every option.

[cascade]
# Enable cascade chaining (default: false)
enabled = false

# Maximum cascade depth (default: 0 = unlimited)
max_depth = 0

You can add per-dependency rules for fine-grained control:

[[cascade.rules]]
upstream = "org/library"
downstream = "org/application"
trigger = "release"         # "merge" or "release" (default)
target_branch = "develop"   # Override downstream branch
version_update = true       # Update dependency version (default: true)
instructions = "Run composer install after updating the dependency"

#Example

Suppose org/database-sdk has a bug. Claudear fixes it and the PR merges. With cascading enabled, Claudear then:

Detects that org/api-server depends on org/database-sdk.
Opens a PR in org/api-server bumping the SDK version and adjusting any affected call sites.
If org/frontend depends on org/api-server, the cascade continues (up to max_depth).

#CLI commands

# View the auto-detected dependency graph
claudear repos graph

# Preview what a cascade would do
claudear repos cascade org/library

# Manually declare a dependency (for deps not in package manifests)
claudear repos link org/library org/application

#Tips

Start with trigger = "release" (the default) so cascades only fire on stable releases, not every merged PR.
Use max_depth = 2 initially to prevent runaway chains while you build confidence.
The instructions field in cascade rules is passed to the AI agent, so you can include repo-specific post-update steps.
Run claudear repos graph to visualise your dependency tree before enabling cascading.