Detect and create bidirectional relationships between existing ADRs with clickable links
Creates bidirectional relationships between ADRs with clickable Markdown links.
/plugin marketplace add devfullcycle/claude-mkt-place/plugin install adrs-management@fullcycle-claude-marketplaceLaunches the adr-linker agent to analyze existing ADRs and create bidirectional relationship links.
Post-processes generated ADRs to detect relationships (Supersedes, Depends on, Related to, Amends) and update files with clickable Markdown links following MADR standard.
What it does:
docs/adrs/generated/Usage:
/adr-link [modules] [--validate] [--report-only] [--adrs-path=PATH] [--output-dir=PATH]
Examples:
/adr-link
# Process all ADRs across all modules
/adr-link BILLING API
# Process only BILLING and API modules
/adr-link --validate
# Validate existing links without modifying files
/adr-link --report-only
# Generate relationship report without updating files
/adr-link --adrs-path=output/adrs/generated
# Process ADRs in custom path
/adr-link --report-only --output-dir=docs/reports/
# Generate report in specific directory
/adr-link BILLING --adrs-path=custom/adrs --output-dir=reports/
# Process BILLING module with custom paths
When the user invokes /adr-link:
Extract options:
--validate, --report-only--adrs-path=<path>, --output-dir=<path>Determine paths:
--adrs-path value or default docs/adrs/generated/--output-dir value or default docs/adrs/reports/Determine scope:
{adrs-path}/{adrs-path}/{MODULE}/--validate: Read-only mode, check link integrity, save report to {output-dir}/--report-only: Detect relationships, save report to {output-dir}/, don't update filesScan strategy:
adrs_path = --adrs-path value OR "docs/adrs/generated/"
If modules specified:
Scan: {adrs_path}/{MODULE}/**/*.md
If no modules:
Scan: {adrs_path}/**/*.md
Include:
{adrs_path}/{MODULE}/ADR-*.md{adrs_path}/{MODULE}/needs-input/ADR-*.mdExclude:
Build file list:
Example output:
Found 47 ADR files:
- BILLING: 18 ADRs
- API: 12 ADRs
- AUTH: 7 ADRs
- DATA: 6 ADRs
- AUDIT: 4 ADRs
CRITICAL: Launch SINGLE agent instance (NOT multiple in parallel)
The adr-linker agent processes ALL ADRs in a single execution to:
Agent prompt construction:
Basic invocation (no modules):
Analyze and link all ADRs in {adrs_path}. Detect all relationship types (Supersedes, Depends on, Related to, Amends), create bidirectional clickable links, and update ADR files.
With modules:
Analyze and link ADRs in modules: BILLING, API at {adrs_path}. Detect all relationship types, create bidirectional clickable links, and update ADR files.
With --validate flag:
Validate existing ADR relationships in {adrs_path}. Check link integrity, bidirectionality, and target existence. DO NOT modify files. Save validation report to {output_dir}/adr-link-validation-{timestamp}.md.
With --report-only flag:
Analyze and detect relationships between ADRs in {adrs_path} but DO NOT update files. Generate comprehensive relationship report showing all detected relationships, grouped by type and module. Save report to {output_dir}/adr-link-report-{timestamp}.md.
Example Task calls:
1. Process all ADRs (default paths):
Task:
subagent_type: adr-linker
description: Link all ADRs
prompt: "Analyze and link all ADRs in docs/adrs/generated/. Detect all relationship types (Supersedes, Depends on, Related to, Amends), create bidirectional clickable links, and update ADR files. Use git history from repository root for temporal analysis."
Agent returns summary report containing:
When to use:
When NOT to use:
| Error | Solution |
|---|---|
| No ADR files found | Run /adr-generate first |
| Permission denied | Check file permissions: chmod 644 docs/adrs/generated/**/*.md |
| Circular dependency | Agent breaks lowest-confidence link automatically |
| Module not found | Check spelling or run /adr-generate MODULE |
| Custom path not found | Verify path exists or omit --adrs-path |
| Cannot create output dir | Use writable directory with --output-dir |
The /adr-link command is a powerful post-processing tool that:
Use after ADR generation to build a complete, navigable architecture decision graph.