Initial commit

2025-11-29 18:01:55 +08:00
commit 60782a2f51
22 changed files with 5228 additions and 0 deletions
--- a/commands/generate-adr.md
+++ b/commands/generate-adr.md
@@ -0,0 +1,186 @@
+---
+description: Create an Architecture Decision Record (ADR) following MADR format
+---
+
+# Generate ADR
+
+## Activated Agent
+
+**Activate**: `adr-author` agent
+
+The agent will help create a structured ADR document.
+
+## Objective
+
+Create an Architecture Decision Record (ADR) that documents an architectural decision with context, alternatives, and consequences following the MADR (Markdown Any Decision Record) format.
+
+## Prerequisites
+
+This command requires the **repo-investigator** plugin to be installed for codebase analysis capabilities.
+
+If you haven't installed it yet:
+```bash
+claude plugin install repo-investigator@brads-marketplace
+```
+
+## Activated Skills
+
+The agent will activate these skills:
+
+1. **`adr-authoring`** (document-generator) - MADR template and ADR best practices
+2. **`repository-analysis-methods`** (repo-investigator) - Understanding project architecture for context
+
+## Process
+
+**Before starting**, verify the repo-investigator plugin is available:
+
+1. Check if `repo-investigator` skills are accessible
+2. If `repository-analysis-methods` skill is not available:
+   - Display a clear message to the user:
+     ```
+     ⚠️  Missing Dependency: repo-investigator plugin
+
+     The generate-adr command requires the repo-investigator plugin for codebase analysis.
+
+     Please install it:
+       claude plugin install repo-investigator@brads-marketplace
+
+     Then re-run this command.
+     ```
+   - Stop execution and wait for user to install the plugin
+
+The agent will:
+
+1. **Choose Workflow** - Ask user to select their preferred approach:
+   - **Guided Interview**: Step-by-step questions with interactive clarification
+   - **Comprehensive Input**: Provide all information at once
+
+### Guided Interview Workflow
+
+If user selects guided interview, ask questions one at a time or in small groups:
+
+1. What architectural decision needs to be documented?
+2. When was this decision made?
+3. What problem does it solve?
+4. What alternatives were considered?
+5. What is the current status?
+6. What are the consequences (positive and negative)?
+
+### Comprehensive Input Workflow
+
+If user selects comprehensive input, present this summary of required information:
+
+```
+Please provide the following information about your architectural decision:
+
+**Required:**
+- Decision title and brief description
+- Problem/context that prompted this decision
+- Chosen solution/approach
+
+**Recommended:**
+- Date of decision (defaults to today if not provided)
+- Alternatives that were considered and why they were rejected
+- Positive consequences/benefits
+- Negative consequences/trade-offs
+- Decision drivers (key factors influencing the choice)
+- Current status (Proposed/Accepted/Deprecated/Superseded)
+
+You can provide this in any format - bullet points, paragraphs, or structured sections.
+```
+
+Then extract information from the user's response and ask targeted follow-up questions only for critical missing pieces.
+
+### Common Steps (Both Workflows)
+
+2. **Analyze** - Examine the codebase to understand:
+   - Current architecture and components
+   - Affected files and modules
+   - Existing ADRs (for numbering)
+
+3. **Generate** - Create ADR document with:
+   - Sequential ADR number
+   - MADR-compliant structure
+   - Evidence-based context
+   - Clear decision statement
+   - Documented alternatives
+   - Positive and negative consequences
+
+4. **Provide guidance** - Suggest:
+   - Filename: `adr/ADR-XXX-title-in-kebab-case.md`
+   - Where to store the file
+   - How to update status over time
+
+## Output Format
+
+Generate an ADR following this MADR template:
+
+```markdown
+# ADR-XXX: [Decision Title]
+
+Date: YYYY-MM-DD
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-YYY]
+
+## Context
+
+[Problem description, requirements, constraints]
+
+## Decision Drivers
+
+* [Factor 1]
+* [Factor 2]
+* [Factor 3]
+
+## Considered Options
+
+* [Option 1 - chosen]
+* [Option 2]
+* [Option 3]
+
+## Decision Outcome
+
+Chosen option: "[Option 1]", because [justification].
+
+### Positive Consequences
+
+* [Benefit 1]
+* [Benefit 2]
+
+### Negative Consequences
+
+* [Challenge 1]
+* [Challenge 2]
+
+## Pros and Cons of the Options
+
+### [Option 1]
+
+* Good, because [argument a]
+* Bad, because [argument b]
+
+### [Option 2]
+
+* Good, because [argument a]
+* Bad, because [argument b]
+
+## Links
+
+* [Related ADR or documentation]
+```
+
+## Constraints
+
+- **Evidence-based**: Reference actual code and file paths
+- **Balanced**: Present alternatives fairly
+- **Focused**: One decision per ADR
+- **No speculation**: Ask for missing information
+- **Sequential numbering**: Check existing ADRs to determine next number
+
+## Storage Location
+
+Default location: `adr/ADR-XXX-title-in-kebab-case.md`
+
+If `adr/` doesn't exist, create it.