Never edit this file directly. To make additions or modifications, edit the appropriate section in ./vstack.toml. Then run vstack refresh.
Decider
Manages Architecture Decision Records (ADRs) — represented in this skill as numbered DXXX architectural decision documents indexed in INDEX.md (by default under docs/decisions/) — with canonical templates, creation/update workflows, and a search CLI. Provides the single source of truth for decision entry format and lifecycle.
.agents/skills/decider/scripts/decisions <command> [options]
Commands
| Command |
Purpose |
Output |
search --issue [ID] |
Find decisions linked to an issue |
JSON [{id, decision, path}] |
search "[KEYWORDS]" |
Ranked keyword search (AND, scored) |
JSON [{id, decision, path, score}] |
search "a|b" |
Regex OR search |
JSON [{id, decision, path}] |
list |
List all active decisions |
JSON [{id, decision, path}] |
next-id |
Get next available DXXX |
Single DXXX line |
get [DXXX] |
Get decision details |
JSON {id, decision, status, date, path} |
Options: --limit N (default: 5) for search results.
Workflows
| Workflow |
Trigger |
Purpose |
workflows/create-decision.md |
Research complete, significant path choice |
Assign ID, write file, add INDEX row, update superseded |
workflows/update-decision.md |
New decision affects existing |
Supersede, partial supersede, or revisit existing entries |
workflows/search-decisions.md |
Before implementing, reviewing, auditing |
Search by issue, keywords, or ID |
Templates
| Template |
Purpose |
templates/decision-entry.md |
Decision file format (minimal, standard, comprehensive) |
templates/index-row.md |
INDEX.md table row format |
Schemas
| Schema |
Purpose |
schemas/decision-format.md |
Canonical format constraints for decision documents and INDEX |
Project-level configuration:
| Variable |
Purpose |
Default |
$DECISIONS_DIR |
Path to decision documents directory |
Auto-discovers docs/decisions/, decisions/, doc/decisions/, or adr/ with INDEX.md |
Set DECISIONS_DIR in committed vstack.settings.toml under [env] when it is shared project policy. .env.local remains supported for local overrides.
If the decisions directory does not exist (never initialized), read-only lookups (search, list) emit an empty JSON array with a stderr note and exit 0 — no decisions recorded is not an error. next-id and get still require an initialized directory, and a configured path that exists but is not a directory is always a hard error.
Decision Lifecycle
Research Complete → Create Decision (§ 6.1)
↓
INDEX.md + DXXX-descriptor.md
↓
┌───────────┴───────────┐
↓ ↓
Search/Reference Update/Supersede
(review, audit, (new research,
implementation) revisit conditions met)
Quick Reference
Creating Decisions
- Get next ID:
decisions next-id
- Select template size (minimal/standard/comprehensive) from
templates/decision-entry.md
- Write decision file to
[project decision documents]/[DECISION_ID]-[DESCRIPTOR].md
- Add row to
[project decision documents]/INDEX.md
- Update any partially superseded decisions
Searching Decisions
- By issue:
decisions search --issue [ISSUE_ID]
- By keywords:
decisions search "[RELEVANT_KEYWORDS]"
- Read full decision files — index summaries are insufficient for understanding scope and rejected alternatives
- Suggestions contradicting active decisions are invalid unless decision is flawed
Decision Entry Format
All entries require: title (# DXXX: Title), date, status, research ref (or —), decision statement, rationale, revisit conditions. See schemas/decision-format.md for full constraints.
Decision Approval
Do not create decision documents without explicit user approval. If your work involves a significant architectural choice, technology selection, or trade-off that warrants a decision record, surface this in your response upon task completion — e.g., "This introduced a decision worth recording: [brief summary]. Want me to create a decision entry?" Let the user confirm before running the create workflow.
Content Guidelines
What to Log
- Technology selections with alternatives considered
- Performance trade-offs (chose X over Y for reason Z)
- Significant path choices where conditions might change
- Research-informed decisions
What NOT to Log
- Variable names, small refactors, bug fixes
- Obvious choices with no realistic alternatives
- Standard pattern applications
System Dependencies
bash 4+jq- GNU
grep with -P (PCRE) support (grep, ggrep, or Homebrew gnubin/grep)
sed, find
1---2name: decider3description: Architecture Decision Record (ADR) and architectural decision document management: templates, creation, search, supersession tracking, and INDEX maintenance.4license: MIT5---67> **Never edit this file directly.** To make additions or modifications, edit the appropriate section in `./vstack.toml`. Then run `vstack refresh`.89# Decider1011Manages Architecture Decision Records (ADRs) — represented in this skill as numbered `DXXX` architectural decision documents indexed in `INDEX.md` (by default under `docs/decisions/`) — with canonical templates, creation/update workflows, and a search CLI. Provides the single source of truth for decision entry format and lifecycle.1213```bash14.agents/skills/decider/scripts/decisions <command> [options]15```1617## Commands1819| Command | Purpose | Output |20|---------|---------|--------|21| `search --issue [ID]` | Find decisions linked to an issue | JSON `[{id, decision, path}]` |22| `search "[KEYWORDS]"` | Ranked keyword search (AND, scored) | JSON `[{id, decision, path, score}]` |23| `search "a\|b"` | Regex OR search | JSON `[{id, decision, path}]` |24| `list` | List all active decisions | JSON `[{id, decision, path}]` |25| `next-id` | Get next available DXXX | Single `DXXX` line |26| `get [DXXX]` | Get decision details | JSON `{id, decision, status, date, path}` |2728Options: `--limit N` (default: 5) for search results.2930## Workflows3132| Workflow | Trigger | Purpose |33|----------|---------|---------|34| `workflows/create-decision.md` | Research complete, significant path choice | Assign ID, write file, add INDEX row, update superseded |35| `workflows/update-decision.md` | New decision affects existing | Supersede, partial supersede, or revisit existing entries |36| `workflows/search-decisions.md` | Before implementing, reviewing, auditing | Search by issue, keywords, or ID |3738## Templates3940| Template | Purpose |41|----------|---------|42| `templates/decision-entry.md` | Decision file format (minimal, standard, comprehensive) |43| `templates/index-row.md` | INDEX.md table row format |4445## Schemas4647| Schema | Purpose |48|--------|---------|49| `schemas/decision-format.md` | Canonical format constraints for decision documents and INDEX |5051Project-level configuration:5253| Variable | Purpose | Default |54|----------|---------|---------|55| `$DECISIONS_DIR` | Path to decision documents directory | Auto-discovers `docs/decisions/`, `decisions/`, `doc/decisions/`, or `adr/` with `INDEX.md` |5657Set `DECISIONS_DIR` in committed `vstack.settings.toml` under `[env]` when it is shared project policy. `.env.local` remains supported for local overrides.5859If the decisions directory does not exist (never initialized), read-only lookups (`search`, `list`) emit an empty JSON array with a stderr note and exit 0 — no decisions recorded is not an error. `next-id` and `get` still require an initialized directory, and a configured path that exists but is not a directory is always a hard error.6061## Decision Lifecycle6263```64Research Complete → Create Decision (§ 6.1)65 ↓66 INDEX.md + DXXX-descriptor.md67 ↓68 ┌───────────┴───────────┐69 ↓ ↓70 Search/Reference Update/Supersede71 (review, audit, (new research,72 implementation) revisit conditions met)73```7475## Quick Reference7677### Creating Decisions78791. Get next ID: `decisions next-id`802. Select template size (minimal/standard/comprehensive) from `templates/decision-entry.md`813. Write decision file to `[project decision documents]/[DECISION_ID]-[DESCRIPTOR].md`824. Add row to `[project decision documents]/INDEX.md`835. Update any partially superseded decisions8485### Searching Decisions86871. By issue: `decisions search --issue [ISSUE_ID]`882. By keywords: `decisions search "[RELEVANT_KEYWORDS]"`893. Read full decision files — index summaries are insufficient for understanding scope and rejected alternatives904. Suggestions contradicting active decisions are invalid unless decision is flawed9192### Decision Entry Format9394All entries require: title (`# DXXX: Title`), date, status, research ref (or `—`), decision statement, rationale, revisit conditions. See `schemas/decision-format.md` for full constraints.9596## Decision Approval9798Do not create decision documents without explicit user approval. If your work involves a significant architectural choice, technology selection, or trade-off that warrants a decision record, surface this in your response upon task completion — e.g., "This introduced a decision worth recording: [brief summary]. Want me to create a decision entry?" Let the user confirm before running the create workflow.99100## Content Guidelines101102### What to Log103104- Technology selections with alternatives considered105- Performance trade-offs (chose X over Y for reason Z)106- Significant path choices where conditions might change107- Research-informed decisions108109### What NOT to Log110111- Variable names, small refactors, bug fixes112- Obvious choices with no realistic alternatives113- Standard pattern applications114115## System Dependencies116117- `bash` 4+118- `jq`119- GNU `grep` with `-P` (PCRE) support (`grep`, `ggrep`, or Homebrew `gnubin/grep`)120- `sed`, `find`
zenobi-us