# arkouda

[![CI](https://github.com/manuelmauro/arkouda/actions/workflows/ci.yml/badge.svg)](https://github.com/manuelmauro/arkouda/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/arkouda.svg)](https://crates.io/crates/arkouda)

A small CLI for navigating and validating Architecture Decision Records (ADRs).

Arkouda treats ADRs as plain Markdown files with YAML frontmatter. It parses the collection, validates the schema, scaffolds new entries, and pulls a named `## Section` out for you. Anything a one-line shell pipeline does well — content search, counting, slicing, full-file printing — is left to `rg`, `grep`, `awk`, `cat`, and friends. See [`docs/adr/defer-to-unix-tools.md`](docs/adr/defer-to-unix-tools.md) and [`docs/adr/ls-style-list-and-decision.md`](docs/adr/ls-style-list-and-decision.md) for the rationale.

## Installation

```bash
# Quick install (downloads a release binary, falls back to cargo)
curl -sSfL https://raw.githubusercontent.com/manuelmauro/arkouda/main/install.sh | sh

# Or from crates.io
cargo install arkouda

# Or from a clone
make install
```

## Quick Start

```bash
arkouda list                         # one ADR path per line — pipe straight to xargs/rg/cat
arkouda list -l                      # long form: id, status, date, path, title (no header)
arkouda check                        # validate frontmatter + Markdown structure
arkouda new "Use Postgres"           # scaffold docs/adr/use-postgres.md
arkouda decision use-postgres        # print the Decision section
arkouda decision use-postgres \
  --section context                  # print another section's body
cat docs/adr/use-postgres.md         # full file — that's just cat
rg postgres docs/adr/                # content search — use rg/grep, not arkouda

# Pipe-friendly: list emits paths, shell takes it from there
arkouda list | xargs rg postgres
arkouda list -l | awk '$2=="accepted" {print $4}' | xargs cat
```

Run `arkouda --help` and `arkouda <subcommand> --help` for the full surface.

## Commands

| Command    | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `list`     | Print one ADR path per line; `-l` for the `id status date path title` table |
| `decision` | Print one ADR's `## Decision` section; `--section <name>` to pick another  |
| `check`    | Validate every ADR's frontmatter, filename, and required Markdown sections |
| `new`      | Scaffold a new ADR from the standard template                              |

Global flags: `--dir <path>` (also `ADR_DIR`), `-q/--quiet`.

## ADR shape

`arkouda check` enforces the contract.

```markdown
---
id: "use-postgres"            # lowercase slug, must match filename stem
title: "Use Postgres"
abstract: "One-line summary of the decision (what was decided)."
status: "proposed"            # proposed | accepted | superseded | deprecated | rejected
date: "2026-05-06"            # ISO YYYY-MM-DD, must be a real date
deciders: []                  # optional
tags: []                      # optional
---

# Use Postgres                # H1 must equal title

## Status

Proposed

## Context

Why we are deciding this.

## Decision

What we decided.

## Consequences

What follows from the decision.
```

Required keys: `id`, `title`, `abstract`, `status`, `date`. Required body sections (case-insensitive H2): `Status`, `Context`, `Decision`, `Consequences`. Filename stem must equal the frontmatter `id`. `arkouda check` reports each violation with a code (`E000`–`E010`) and a fix hint.

## Configuration

`--dir <path>` (and the `ADR_DIR` env var) point arkouda at a single directory and override everything else. With neither set, arkouda walks up from the working directory looking for `.arkoudarc.toml`; if found, its `dirs` list is used. With nothing configured, the default is `docs/adr`.

`.arkoudarc.toml` lists one or more directories — useful for monorepos that keep ADRs per service or area:

```toml
dirs = [
  "docs/adr",
  "services/billing/docs/adr",
  "services/identity/docs/adr",
]
```

Relative paths resolve against the location of the config file, so the same file works from any subdirectory. `arkouda list`, `check`, and `decision` aggregate across every listed directory; `arkouda new` writes into the first one (use `--dir` to target another).

| Setting   | Default     | Override (low → high precedence)                         |
| --------- | ----------- | -------------------------------------------------------- |
| ADR dirs  | `docs/adr`  | `.arkoudarc.toml` `dirs` → `ADR_DIR=<path>` → `--dir <path>` |

## Agent skill

`skills/use-arkouda/SKILL.md` is a portable, [skilo](https://github.com/manuelmauro/skilo)-validated agent skill that teaches an AI assistant to consult prior decisions before making non-trivial choices, capture new decisions afterwards, and use the four subcommands, the schema, and the diagnostic codes correctly. It's repo-agnostic — drop it into any project that uses arkouda.

## CI integration

```yaml
- name: Validate ADRs
  run: |
    curl -sSfL https://raw.githubusercontent.com/manuelmauro/arkouda/main/install.sh | sh
    arkouda check
```

`arkouda check` exits 0 on a clean collection, 1 on any error.

## Acknowledgements

The ADR body schema (`## Status`, `## Context`, `## Decision`, `## Consequences`) follows [Michael Nygard's template](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-michael-nygard) — the de-facto standard for Architecture Decision Records. Arkouda layers structured frontmatter, a slug-based id scheme, and validation on top of that template.

## License

MIT OR Apache-2.0
