# Basic usage
/bkff:writeadr --decision="Use PostgreSQL for primary data storage"

# With context and specific sources
/bkff:writeadr --decision="Implement event sourcing" --context="High audit requirements" --sources="src/domain,docs/requirements.md"

# Custom output directory
/bkff:writeadr --decision="Adopt microservices" --output="architecture/decisions"

┌─────────────────────────────────────────────────────────────┐
│                     ADR GENERATION PIPELINE                  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    1. ADR Writer Agent                       │
│  • Analyzes codebase and context                            │
│  • Generates initial ADR content using MADR template        │
│  • Documents options, decision drivers, and consequences    │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                   2. ADR Validator Agent                     │
│  • Validates claims against grounding sources               │
│  • Checks technical accuracy                                │
│  • Identifies unsupported assertions                        │
│  • Suggests corrections or clarifications                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  3. ADR Formatter Agent                      │
│  • Assigns sequential ADR number                            │
│  • Formats for consistency with existing ADRs               │
│  • Generates final markdown output                          │
│  • Creates index entry if needed                            │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                     OUTPUT                                   │
│  • ADR file: docs/adr/NNNN-decision-title.md                │
│  • Updated index (if exists)                                │
└─────────────────────────────────────────────────────────────┘

# [ADR-NNNN] Title

* Status: [proposed | accepted | deprecated | superseded]
* Date: YYYY-MM-DD
* Deciders: [list of people involved]
* Technical Story: [optional link to issue/story]

## Context and Problem Statement

[Describe the context and problem]

## Decision Drivers

* [driver 1]
* [driver 2]

## Considered Options

* [option 1]
* [option 2]
* [option 3]

## Decision Outcome

Chosen option: "[option N]", because [justification].

### Positive Consequences

* [e.g., improvement of quality attribute satisfaction]

### Negative Consequences

* [e.g., compromising quality attribute, follow-up decisions required]

## Pros and Cons of the Options

### [option 1]

[description]

* Good, because [argument a]
* Bad, because [argument b]

### [option 2]

[description]

* Good, because [argument a]
* Bad, because [argument b]

## Links

* [Link type] [Link to ADR]
* ...

Info: Generating ADR for decision: Use PostgreSQL for primary data storage

Pipeline Progress
─────────────────────────────────────
  Writer:     ✓ Draft generated
  Validator:  ✓ Claims verified (3 sources checked)
  Formatter:  ✓ ADR-0005 created

✓ ADR generated successfully

Output: docs/adr/0005-use-postgresql-for-primary-data-storage.md

Info: Generating ADR for decision: Use PostgreSQL for primary data storage

Pipeline Progress
─────────────────────────────────────
  Writer:     ✓ Draft generated
  Validator:  ⚠ 2 claims need verification
              - "PostgreSQL supports 10M TPS" - not found in sources
              - "License is MIT" - actually PostgreSQL License

Validation warnings incorporated into final ADR.

✓ ADR generated with notes

Output: docs/adr/0005-use-postgresql-for-primary-data-storage.md

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
source "$PLUGIN_DIR/lib/common.sh"

# Parse arguments
decision=""
context=""
sources="."
output_dir="docs/adr"

for arg in "$@"; do
    case "$arg" in
        --decision=*) decision="${arg#--decision=}" ;;
        --context=*) context="${arg#--context=}" ;;
        --sources=*) sources="${arg#--sources=}" ;;
        --output=*) output_dir="${arg#--output=}" ;;
    esac
done

# Validate prerequisites
require_worktree

if [[ -z "$decision" ]]; then
    error_exit "Decision description required. Use --decision=\"...\""
fi

# Ensure output directory exists
root=$(get_worktree_path)
mkdir -p "$root/$output_dir"

info "Generating ADR for decision: $decision"

# Pipeline execution is handled by Claude invoking the agents in sequence:
# 1. bkff:adr-writer - generates initial content
# 2. bkff:adr-validator - validates claims
# 3. bkff:adr-formatter - formats and numbers

# The orchestration is performed by Claude based on this skill's instructions
echo "Pipeline ready. Invoke agents: adr-writer -> adr-validator -> adr-formatter"