Initial commit
This commit is contained in:
Zhongwei Li
184
commands/adr-link.md
Normal file
184
commands/adr-link.md
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
description: Detect and create bidirectional relationships between existing ADRs with clickable links
|
||||
tags: [project, adr]
|
||||
---
|
||||
|
||||
Launches 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**:
|
||||
- Scans existing ADRs in `docs/adrs/generated/`
|
||||
- Detects 4 relationship types using temporal, semantic, and technical analysis
|
||||
- Creates bidirectional clickable links (A→B and B→A)
|
||||
- Updates ADR files automatically with relationship headers
|
||||
- Validates link integrity and generates comprehensive report
|
||||
- Uses git history + potential ADR hints for accurate detection
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Instructions
|
||||
|
||||
When the user invokes `/adr-link`:
|
||||
|
||||
### Step 1: Parse Arguments and Determine Scope
|
||||
|
||||
**Extract options**:
|
||||
- Module IDs (e.g., BILLING, API, DATA) - if provided
|
||||
- Flags: `--validate`, `--report-only`
|
||||
- Paths: `--adrs-path=<path>`, `--output-dir=<path>`
|
||||
|
||||
**Determine paths**:
|
||||
- ADRs path: `--adrs-path` value or default `docs/adrs/generated/`
|
||||
- Output directory: `--output-dir` value or default `docs/adrs/reports/`
|
||||
|
||||
**Determine scope**:
|
||||
- No modules specified: Process ALL modules in `{adrs-path}/`
|
||||
- Modules specified: Process only those modules in `{adrs-path}/{MODULE}/`
|
||||
- Flag behavior:
|
||||
- `--validate`: Read-only mode, check link integrity, save report to `{output-dir}/`
|
||||
- `--report-only`: Detect relationships, save report to `{output-dir}/`, don't update files
|
||||
|
||||
### Step 2: Discover ADR Files
|
||||
|
||||
**Scan 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**:
|
||||
- Main directory: `{adrs_path}/{MODULE}/ADR-*.md`
|
||||
- Subdirectories: `{adrs_path}/{MODULE}/needs-input/ADR-*.md`
|
||||
|
||||
**Exclude**:
|
||||
- Non-ADR files (README.md, index files)
|
||||
- Archived/deleted ADRs
|
||||
|
||||
**Build file list**:
|
||||
```
|
||||
Example output:
|
||||
Found 47 ADR files:
|
||||
- BILLING: 18 ADRs
|
||||
- API: 12 ADRs
|
||||
- AUTH: 7 ADRs
|
||||
- DATA: 6 ADRs
|
||||
- AUDIT: 4 ADRs
|
||||
```
|
||||
|
||||
### Step 3: Launch adr-linker Agent
|
||||
|
||||
**CRITICAL**: Launch SINGLE agent instance (NOT multiple in parallel)
|
||||
|
||||
The adr-linker agent processes ALL ADRs in a single execution to:
|
||||
- Build complete relationship graph
|
||||
- Ensure bidirectional consistency
|
||||
- Avoid file write conflicts
|
||||
|
||||
**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."
|
||||
```
|
||||
|
||||
|
||||
### Step 4: Handle Agent Response
|
||||
|
||||
Agent returns summary report containing:
|
||||
- **Success**: Number of relationships detected and ADRs updated, grouped by type (Supersedes, Depends on, Related to, Amends)
|
||||
- **Validation**: Link integrity check results, broken links if any
|
||||
- **Errors**: Git repository not found, invalid paths, permission issues
|
||||
|
||||
### Step 5: Integration Notes
|
||||
|
||||
**When to use**:
|
||||
- After parallel ADR generation (resolves race conditions)
|
||||
- After manual ADR creation
|
||||
- After ADR renumbering
|
||||
- Periodic maintenance
|
||||
|
||||
**When NOT to use**:
|
||||
- During ADR generation (let adr-generator handle initial relationships)
|
||||
- On potential ADRs (only works on generated ADRs)
|
||||
|
||||
## Error Reference
|
||||
|
||||
| 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` |
|
||||
|
||||
## Summary
|
||||
|
||||
The `/adr-link` command is a powerful post-processing tool that:
|
||||
1. Solves race condition problem in parallel ADR generation
|
||||
2. Creates bidirectional navigation between related decisions
|
||||
3. Maintains MADR compliance with clickable Markdown links
|
||||
4. Validates relationship integrity
|
||||
5. Provides comprehensive analysis of ADR evolution
|
||||
|
||||
Use after ADR generation to build a complete, navigable architecture decision graph.
|
||||
Reference in New Issue
Block a user