Initial commit

2025-11-29 18:19:31 +08:00
commit b399b50bc5
10 changed files with 2421 additions and 0 deletions
--- a/commands/adr-generate.md
+++ b/commands/adr-generate.md
@@ -0,0 +1,127 @@
+---
+description: Generate formal ADRs from potential ADRs
+tags: [project, adr]
+---
+
+Launches the `adr-generator` agent to generate formal ADRs from potential ADRs.
+
+When multiple modules or files are specified, launches agents in parallel for faster generation.
+
+**What it does**:
+- Generates formal ADRs using placeholder XXX for numbering
+- Executes multiple targets in parallel when 2+ targets are specified
+- Detects relationships with existing ADRs
+- Organizes by module: `generated/{MODULE}/` or `generated/{MODULE}/needs-input/`
+- Manual renumbering required after generation
+
+**Usage**:
+```
+/adr-generate [modules] [--context-dir=PATH] [--language=LOCALE] [--include-consider] [--output-dir=PATH]
+```
+
+**Examples**:
+```
+/adr-generate --all
+# Generate ALL potential ADRs to docs/adrs/generated/{MODULE}/
+# Excluding the "consider" priority if --include-consider is not specified
+
+/adr-generate BILLING
+# Generate to docs/adrs/generated/BILLING/
+
+/adr-generate BILLING API DATA
+# Generate multiple modules in parallel
+
+/adr-generate --include-consider BILLING
+# Include both must-document AND consider priorities
+
+/adr-generate --language=pt-BR --include-consider BILLING API
+# Generate in Portuguese with all priorities
+
+/adr-generate --context-dir=docs/context/ BILLING
+# Generate with strategic context
+
+/adr-generate --output-dir=output/adrs BILLING
+# Generate to custom output directory: output/adrs/generated/BILLING/
+```
+
+---
+
+## Implementation Instructions
+
+When the user invokes `/adr-generate`:
+
+### Step 1: Discover Potential ADR Files
+
+Parse arguments to get:
+- Module IDs (e.g., BILLING, API, DATA)
+- Options (--context-dir, --language, --include-consider, --output-dir)
+- Set output base directory (default: `docs/adrs`, or use `--output-dir` value)
+
+**Default behavior (without --include-consider):**
+Scan only must-document:
+```
+docs/adrs/potential-adrs/must-document/{MODULE}/*.md
+```
+
+**With --include-consider flag:**
+Scan both priorities:
+```
+docs/adrs/potential-adrs/must-document/{MODULE}/*.md
+docs/adrs/potential-adrs/consider/{MODULE}/*.md
+```
+
+Build list of ALL potential ADR files across ALL specified modules.
+
+### Step 2: Launch Agents in Parallel
+
+Launch MULTIPLE `adr-generator` agents **in parallel** using a SINGLE message with MULTIPLE Task tool calls - ONE agent per potential ADR file.
+
+**Example: `/adr-generate BILLING API`**
+
+If BILLING has 3 files and API has 2 files, launch 5 agents:
+
+```
+Single message with 5 Task tool calls:
+
+Task 1:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/must-document/BILLING/payment-gateway.md"
+
+Task 2:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/must-document/BILLING/dual-paypal.md"
+
+Task 3:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/consider/BILLING/cache-strategy.md"
+
+Task 4:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/must-document/API/rest-choice.md"
+
+Task 5:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/must-document/API/grpc-internal.md"
+```
+
+### With Options
+
+Include options in each agent's prompt:
+
+```
+Task 1:
+- subagent_type: adr-generator
+- prompt: "Generate formal ADR from docs/adrs/potential-adrs/must-document/BILLING/payment-gateway.md with --language=pt-BR and --context-dir=docs/context/"
+```
+
+**CRITICAL**:
+- MUST send a SINGLE message with MULTIPLE Task tool calls
+- ONE agent per potential ADR file (NOT one agent per module)
+- ALL agents run in parallel
+- Each agent uses placeholder XXX for numbering
+- Do NOT run sequentially
+
+### No Modules Specified (e.g., `/adr-generate`)
+1. Scan `docs/adrs/potential-adrs/` to discover all modules
+2. Ask user which modules to process
+3. Follow Step 1 and Step 2 above
--- a/commands/adr-identify.md
+++ b/commands/adr-identify.md
@@ -0,0 +1,167 @@
+---
+description: Identify potential ADRs for specific modules based on the codebase mapping (Phase 2)
+tags: [project, adr]
+---
+
+Launches the `adr-analyzer` agent to identify potential ADRs in specified modules.
+
+When multiple modules are specified, launches agents in parallel for faster analysis.
+
+**Prerequisites**: Run `/adr-map` first if mapping.md doesn't exist in the output directory.
+
+**What it does**:
+- Analyzes specified module(s) with strict architectural filtering
+- Executes multiple modules in parallel when 2+ modules are specified
+- Uses git history internally to enrich potential ADRs with temporal context
+- Creates individual ADR files in priority-based folders (NO numbers in filenames)
+- Weaves git insights naturally into content (dates, keywords, evolution)
+- Updates the index with findings
+
+**Usage**:
+```
+/adr-identify [module-ids] [--output-dir=PATH] [--adrs-dir=PATH]
+```
+
+**Examples**:
+```
+/adr-identify
+# Prompts which modules to analyze (uses docs/adrs by default)
+
+/adr-identify AUTH
+# Analyze only AUTH module
+
+/adr-identify AUTH DATA API
+# Analyze multiple modules
+
+/adr-identify --output-dir=output/adrs AUTH
+# Analyze AUTH module with custom output directory
+
+/adr-identify --adrs-dir=docs/adrs/generated AUTH
+# Uses existing ADRs from custom directory for context and duplicate detection
+```
+
+**Output Structure**:
+```
+{OUTPUT_DIR}/potential-adrs/          # Default: docs/adrs/potential-adrs
+├── must-document/    # High priority (score ≥100 out of 150)
+│   └── MODULE-ID/
+│       ├── decision-title-kebab-case.md
+│       └── another-architectural-decision.md
+└── consider/         # Medium priority (score 75-99 out of 150)
+    └── MODULE-ID/
+        └── medium-priority-decision.md
+```
+
+**Important**: Filenames use descriptive kebab-case WITHOUT numbers. Numbering happens in Phase 3 when formal ADRs are generated.
+
+**Existing ADR Integration**: Automatically scans {OUTPUT_DIR}/generated/ (or --adrs-dir path) for existing ADRs to:
+- Avoid duplicate identification (>70% similarity warning)
+- Detect relationships with existing decisions (40-70% similarity)
+- Provide timeline context (decision evolution, supersession patterns)
+- Suggest consolidation opportunities (implementation details of existing ADRs)
+
+**How It Works**:
+- **Scoring**: 3 dimensions (Scope+Impact, Cost to Change, Team Knowledge), 150 points total (75 base score from Step 0 + 75 from dimensions)
+- **Thresholds**: ≥100 pts (67%, high priority), 75-99 pts (50-66%, medium priority), <75 pts (discard)
+- **Filtering**: Step 0 (Positive Identification) + Red Flags 1-5
+- **Git Integration**: Enriches content with temporal context (dates, evolution, intent keywords)
+
+**Key Features**:
+- **Step 0 (Positive Identification)**: Base technology decisions (infrastructure services, framework, ORM, API, auth, payment, AI/ML) automatically trigger ADR creation with base score
+- **Red Flag 5**: Consolidates overly granular decisions into larger strategic ADRs (prevents ADR sprawl)
+- **Operational Impact**: Captures observability, resilience, and production reliability decisions
+
+**Expected Results**:
+- Only ~5% of findings become ADRs (strict filtering)
+- Potential ADRs enriched with git history (dates, evolution, intent keywords)
+- No separate "Git History" section - insights woven naturally into content
+
+**Note**: This identifies potential ADRs with evidence. You decide which to formally document in Phase 3.
+
+---
+
+## Implementation Instructions
+
+When the user invokes `/adr-identify` with module IDs:
+
+### Parse Arguments
+Extract from command:
+- Module IDs (e.g., AUTH, DATA, API)
+- `--output-dir=<path>`: Optional output directory (default: `docs/adrs`)
+- `--adrs-dir=<path>`: Optional existing ADRs directory (default: `{OUTPUT_DIR}/generated/`)
+
+### Single Module (e.g., `/adr-identify AUTH`)
+Launch a single `adr-analyzer` agent with the Task tool:
+
+**Without --output-dir:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the AUTH module"
+```
+
+**With --output-dir:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the AUTH module with --output-dir=custom/path"
+```
+
+**With --adrs-dir:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the AUTH module with --adrs-dir=docs/adrs/generated"
+```
+
+### Multiple Modules (e.g., `/adr-identify AUTH DATA API` or `/adr-identify --output-dir=output/adrs AUTH DATA`)
+Launch multiple `adr-analyzer` agents **in parallel** using a single message with multiple Task tool calls:
+
+**Without --output-dir:**
+```
+Single message with multiple Task tool calls:
+
+Task tool call 1:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the AUTH module"
+
+Task tool call 2:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the DATA module"
+
+Task tool call 3:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the API module"
+```
+
+**With --output-dir:**
+```
+Single message with multiple Task tool calls:
+
+Task tool call 1:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the AUTH module with --output-dir=custom/path"
+
+Task tool call 2:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the DATA module with --output-dir=custom/path"
+
+Task tool call 3:
+- subagent_type: adr-analyzer
+- prompt: "Identify potential ADRs for the API module with --output-dir=custom/path"
+```
+
+**IMPORTANT**:
+- When 2+ modules are specified, you MUST send a single message with multiple Task tool calls
+- Each agent should analyze only ONE specific module
+- Do NOT run agents sequentially - run them in parallel for better performance
+- Each agent will create its own potential ADR files in the appropriate priority folders
+- The index file will be updated by each agent independently
+- All agents must use the same --output-dir if specified
+
+### No Modules Specified (e.g., `/adr-identify` or `/adr-identify --output-dir=custom/path`)
+1. Determine output directory (from --output-dir or default `docs/adrs`)
+2. Read `{OUTPUT_DIR}/mapping.md` to get available modules
+3. Present the module list to the user
+4. Ask which module(s) they want to analyze
+5. Once specified, follow the logic above (single or multiple)
--- a/commands/adr-link.md
+++ b/commands/adr-link.md
@@ -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.
--- a/commands/adr-map.md
+++ b/commands/adr-map.md
@@ -0,0 +1,94 @@
+---
+description: Create a modular codebase mapping to prepare for ADR identification (Phase 1)
+tags: [project, adr]
+---
+
+Launch the `adr-analyzer` agent to execute Phase 1: Codebase Mapping.
+
+This will:
+1. Analyze the entire project structure
+2. Identify technologies, frameworks, and architectural patterns
+3. Divide the codebase into logical, independent modules
+4. Create mapping.md with modular structure
+
+The mapping file will include:
+- Project overview and technology stack
+- System modules with IDs, scope estimates, and descriptions
+- Cross-cutting concerns (infrastructure, authentication, data layer, etc.)
+- Guidelines for Phase 2 analysis
+
+**Usage**:
+```
+/adr-map [--project-dir=PATH] [--context-dir=PATH] [--output-dir=PATH]
+```
+
+**Examples**:
+```
+/adr-map
+# Maps current directory, outputs to docs/adrs/mapping.md
+
+/adr-map --project-dir=/path/to/project
+# Maps specific project directory
+
+/adr-map --context-dir=docs/architecture
+# Maps current directory using architecture docs/diagrams to inform mapping
+
+/adr-map --project-dir=/legacy --context-dir=/legacy/docs --output-dir=analysis/adrs
+# Full control: custom project, context, and output directories
+```
+
+**Context Files**: All file types supported - architecture docs, design docs, README files,
+diagrams (PNG, SVG), images, PDFs, tech stack documentation. These help the agent better
+understand module boundaries and business domains.
+
+**Output**: `{OUTPUT_DIR}/mapping.md` (default: `docs/adrs/mapping.md`)
+
+After Phase 1 completes, you can use `/adr-identify` to identify potential ADRs for specific modules.
+
+For large codebases (10,000+ files), this creates a foundation for incremental analysis without overwhelming the context window.
+
+---
+
+## Implementation Instructions
+
+When the user invokes `/adr-map`:
+
+Parse arguments to extract:
+- `--project-dir=<path>`: Optional directory to map (default: `.` - current working directory)
+- `--context-dir=<path>`: Optional context directory with docs/diagrams (default: none)
+- `--output-dir=<path>`: Optional output directory (default: `docs/adrs`)
+
+Launch the `adr-analyzer` agent with the Task tool:
+
+**Without options:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Execute Phase 1: Create codebase mapping"
+```
+
+**With --project-dir:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Execute Phase 1: Create codebase mapping with --project-dir=/path/to/project"
+```
+
+**With --context-dir:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Execute Phase 1: Create codebase mapping with --context-dir=docs/architecture"
+```
+
+**With multiple options:**
+```
+Task tool:
+- subagent_type: adr-analyzer
+- prompt: "Execute Phase 1: Create codebase mapping with --project-dir=/legacy --context-dir=/legacy/docs --output-dir=analysis/adrs"
+```
+
+The agent will:
+1. Analyze the project at --project-dir (or current directory)
+2. Load context files from --context-dir if provided (all file types)
+3. Create `{OUTPUT_DIR}/mapping.md` with complete codebase analysis and optional context notes