{"id":40778298,"url":"https://github.com/sventorben/decider","last_synced_at":"2026-01-21T19:14:52.017Z","repository":{"id":333142819,"uuid":"1136195984","full_name":"sventorben/decider","owner":"sventorben","description":"Git-native ADRs as shared, enforceable context for humans and AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-01-17T15:19:50.000Z","size":122,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T00:59:31.258Z","etag":null,"topics":["adr","ai-integration","ai-workflows","architectural-decisions","claude","claude-code","claude-code-hooks","claude-code-skills","claude-code-subagents","context-management","decision-records","human-in-the-loop","llm-teams","shared-context","team-workflows"],"latest_commit_sha":null,"homepage":"https://github.com/sventorben/decider","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sventorben.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-17T08:39:08.000Z","updated_at":"2026-01-17T15:19:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sventorben/decider","commit_stats":null,"previous_names":["sventorben/decider"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sventorben/decider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fdecider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fdecider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fdecider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fdecider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sventorben","download_url":"https://codeload.github.com/sventorben/decider/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sventorben%2Fdecider/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28640656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T18:04:35.752Z","status":"ssl_error","status_checked_at":"2026-01-21T18:03:55.054Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","ai-integration","ai-workflows","architectural-decisions","claude","claude-code","claude-code-hooks","claude-code-skills","claude-code-subagents","context-management","decision-records","human-in-the-loop","llm-teams","shared-context","team-workflows"],"created_at":"2026-01-21T19:14:51.953Z","updated_at":"2026-01-21T19:14:52.009Z","avatar_url":"https://github.com/sventorben.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DECIDER\n\n**Turn architectural decisions into machine-readable constraints that both humans and AI coding agents can follow.**\n\nDECIDER is a Git-native system for managing Architecture Decision Records (ADRs) with structured metadata. It combines a fast CLI, an ADR Steward agent, and CI workflows to create a living decision system that scales with your team.\n\n```bash\n# Install (replace v0.1.0 with the latest release version)\ngo install github.com/sventorben/decider/cmd/decider@v0.1.0\n\n# Initialize and create your first ADR\ndecider init\ndecider new \"Use PostgreSQL for persistence\" --tags database --paths \"src/db/**\"\n```\n\n\u003e **⚠️ Early Draft / Exploratory Project**\n\u003e\n\u003e This repository is an early-stage draft of an idea and methodology that is still evolving.\n\u003e The concepts, structure, and tooling are intentionally experimental and subject to change.\n\u003e\n\u003e The goal at this stage is to explore and validate the approach in public, gather feedback,\n\u003e and iterate openly — not to provide a finished or production-hardened solution.\n\u003e \n\u003e If you are evaluating this project, please treat it as a foundation and conversation starter rather than a final recommendation.\n\n## Why DECIDER?\n\nSoftware teams make hundreds of architectural decisions. Most get lost in Slack threads, PR comments, or tribal knowledge. When a new team member joins—or an AI agent starts writing code—they have no way to know what constraints exist.\n\nDECIDER solves this by treating decisions as code:\n\n- **Decisions become constraints**: Each ADR defines rules that MUST be followed\n- **Constraints have scope**: Glob patterns specify which code paths they apply to\n- **Agents can query them**: `decider check diff --base main` returns applicable constraints\n- **CI can enforce them**: Fail builds when changes violate documented decisions\n\n### The Problem with AI Coding Agents\n\nAI agents write code fast, but they don't know your architecture. Without explicit constraints:\n\n- An agent might use raw SQL when you've decided on the repository pattern\n- It might add a new database when you've standardized on PostgreSQL\n- It might violate security invariants documented nowhere but someone's memory\n\nDECIDER gives agents the context they need to make decisions that align with your architecture.\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        Your Repository                          │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                 │\n│  docs/adr/                        src/                          │\n│  ├── index.yaml    ◄─────────────► ├── db/                      │\n│  ├── 0001-postgresql.md           │   └── users.go              │\n│  ├── 0002-rest-api.md             ├── api/                      │\n│  └── templates/                   │   └── handlers.go           │\n│                                   └── ...                       │\n│                                                                 │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │\n│  │   decider   │  │ ADR Steward │  │  CI Checks  │              │\n│  │    CLI      │  │   Agent     │  │  (GitHub)   │              │\n│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │\n│         │                │                │                     │\n│         └────────────────┴────────────────┘                     │\n│                          │                                      │\n│                   Read/Write ADRs                               │\n│                   Validate/Index                                │\n│                   Match to Changes                              │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n**Components:**\n\n1. **ADRs with YAML frontmatter**: Machine-readable metadata (constraints, invariants, scope paths)\n2. **Index file**: Auto-generated `index.yaml` for fast ADR discovery\n3. **CLI (`decider`)**: Create, validate, list, and query ADRs\n4. **ADR Steward agent**: Claude Code integration for ADR lifecycle management\n5. **CI workflows**: Validate ADRs and check index consistency on every PR\n\n## Quickstart\n\n### 1. Install\n\n```bash\n# Pinned install with checksum verification (recommended)\n./scripts/install-decider.sh\nexport PATH=\"$PWD/tools/decider:$PATH\"\n\n# Or with Go (replace v0.1.0 with pinned version)\ngo install github.com/sventorben/decider/cmd/decider@v0.1.0\n```\n\n### 2. Initialize\n\n```bash\ndecider init\n# Created: docs/adr/\n# Created: docs/adr/templates/adr.md\n# Created: docs/adr/index.yaml\n```\n\n### 3. Create an ADR\n\n```bash\ndecider new \"Use PostgreSQL for persistence\" \\\n  --tags database,storage \\\n  --paths \"src/db/**,migrations/**\"\n```\n\nThis creates `docs/adr/0001-use-postgresql-for-persistence.md`:\n\n```yaml\n---\nadr_id: ADR-0001\ntitle: \"Use PostgreSQL for persistence\"\nstatus: proposed\ndate: 2026-01-16\nscope:\n  paths:\n    - \"src/db/**\"\n    - \"migrations/**\"\ntags:\n  - database\n  - storage\nconstraints: []\ninvariants: []\n---\n\n# ADR-0001: Use PostgreSQL for persistence\n\n## Context\n\u003c!-- Why is this decision needed? --\u003e\n\n## Decision\n\u003c!-- What did we decide and why? --\u003e\n\n## Alternatives Considered\n\u003c!-- What other options were evaluated? --\u003e\n\n## Consequences\n\u003c!-- What are the positive and negative impacts? --\u003e\n```\n\n### 4. Fill in the ADR\n\nEdit the file to add your decision using the **mandatory rationale pattern**:\n\n```markdown\n## Decision\n\n### PostgreSQL: Adopted\n\n**Adopted because:**\n- Mature ecosystem with proven reliability at scale\n- Team has extensive PostgreSQL experience\n- Excellent JSON support for semi-structured data\n\n**Adopted despite:**\n- Higher operational complexity than SQLite\n- Requires dedicated infrastructure\n\n## Alternatives Considered\n\n### MongoDB: Rejected\n\n**Rejected because:**\n- Team lacks MongoDB expertise\n- Query patterns are primarily relational\n\n**Rejected despite:**\n- Better horizontal scaling characteristics\n- More flexible schema evolution\n```\n\nAlso add constraints and invariants:\n\n```yaml\nconstraints:\n  - \"All database access must go through the repository pattern\"\n  - \"Use prepared statements for all queries\"\n  - \"Never expose raw SQL outside the db package\"\ninvariants:\n  - \"Database connections are pooled\"\n  - \"All migrations are reversible\"\n```\n\nThe rationale pattern ensures every decision documents:\n- **Why it was adopted** (concrete reasons tied to drivers)\n- **What trade-offs were accepted** (despite sections)\n- **Why alternatives were rejected** (with acknowledged strengths)\n\n### 5. Query Applicable ADRs\n\nWhen making changes, check which ADRs apply:\n\n```bash\n$ decider check diff --base main\nADR-0001: Use PostgreSQL for persistence\n  Status: adopted\n  Matched files:\n    - src/db/users.go\n  Constraints:\n    - All database access must go through the repository pattern\n    - Use prepared statements for all queries\n```\n\n## Agent Integration\n\n### How Agents Use ADRs\n\nAI coding agents can query DECIDER before making changes:\n\n```bash\n# Agent workflow: get constraints for current changes (TOON format, default)\n$ decider check diff --base main --format toon\n{applicable_adrs:[{adr_id:ADR-0001 constraints:[\"Use repository pattern\" \"Use prepared statements\"]}]}\n\n# Use JSON format for traditional tooling\n$ decider check diff --base main --format json | jq '.applicable_adrs[].constraints'\n[\n  \"All database access must go through the repository pattern\",\n  \"Use prepared statements for all queries\"\n]\n\n# Get detailed explanation of why ADRs apply\n$ decider explain --base main\n```\n\n### Example: Agent Constrained by ADRs\n\nUser prompt:\n\u003e \"Add a function to get user by email\"\n\nWithout ADRs, an agent might write:\n\n```go\n// BAD: Raw SQL in handler\nfunc GetUserByEmail(db *sql.DB, email string) (*User, error) {\n    row := db.QueryRow(\"SELECT * FROM users WHERE email = '\" + email + \"'\")\n    // SQL injection vulnerability, not using repository pattern\n}\n```\n\nWith DECIDER, the agent first checks constraints:\n\n```bash\n$ decider check diff --base main --path src/api/handlers.go\nADR-0001 applies. Constraints:\n- All database access must go through the repository pattern\n- Use prepared statements for all queries\n```\n\nThe agent then writes compliant code:\n\n```go\n// GOOD: Uses repository pattern per ADR-0001\nfunc (h *Handler) GetUserByEmail(ctx context.Context, email string) (*User, error) {\n    return h.userRepo.FindByEmail(ctx, email)\n}\n```\n\n## ADR Steward Agent\n\nDECIDER includes an **ADR Steward** agent for Claude Code that manages the ADR lifecycle. The steward handles creation, supersession, validation, and index maintenance.\n\n### Using the Steward\n\nThe ADR Steward is available through Claude Code slash commands:\n\n```bash\n# Create a new ADR\n/adr-new Use Redis for session storage\n\n# Supersede an existing ADR\n/adr-supersede ADR-0003 Migrate from Redux to Zustand\n```\n\nYou can also invoke the steward directly:\n\n\u003e \"Create an ADR for our decision to use GraphQL instead of REST for the new API\"\n\n\u003e \"We need to supersede ADR-0005 because we're switching from Memcached to Redis\"\n\n\u003e \"Check if all our ADRs are valid and the index is up to date\"\n\n### What the Steward Does\n\n| Action | Steward Behavior |\n|--------|-----------------|\n| **Create ADR** | Runs `decider new`, fills sections, sets scope paths, updates index |\n| **Supersede ADR** | Creates new ADR, links both with `supersedes`/`superseded_by`, updates statuses |\n| **Validate** | Runs `decider check adr`, reports issues, suggests fixes |\n| **Update Index** | Runs `decider index` after any ADR changes |\n| **Query** | Uses `decider check diff` to find applicable ADRs for changes |\n\n### What Humans Decide\n\nThe steward assists but doesn't make architectural decisions:\n\n- **Humans decide**: What to document, whether to accept/reject, constraint wording\n- **Steward executes**: File creation, format compliance, linking, index updates\n\n## How Teams Use This\n\n### Sprint Workflow\n\n1. **Planning**: Create ADRs for significant decisions (`decider new` or `/adr-new`)\n2. **Development**: Agents and devs check constraints before coding (`decider check diff`)\n3. **Review**: PRs include ADR validation in CI\n4. **Evolution**: Supersede outdated decisions (`/adr-supersede`)\n\n### Adoption Path\n\n| Phase | What You Do | Benefit |\n|-------|-------------|---------|\n| **1. Docs only** | Write ADRs, no tooling | Decisions documented |\n| **2. Steward agent** | Use Claude Code integration | Consistent format, auto-indexing |\n| **3. CI checks** | Add validation to pipelines | Catch drift, enforce structure |\n| **4. Policy enforcement** | (Future) Block PRs violating constraints | Automated governance |\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `decider init` | Initialize ADR directory structure |\n| `decider new \"\u003ctitle\u003e\"` | Create a new ADR |\n| `decider list` | List ADRs with optional filters |\n| `decider show \u003cid\u003e` | Display ADR details |\n| `decider check adr` | Validate all ADRs |\n| `decider check adr --strict` | Validate ADRs (fail on missing rationale pattern) |\n| `decider check diff --base \u003cref\u003e` | Find ADRs applicable to changes |\n| `decider explain --base \u003cref\u003e` | Explain why ADRs apply |\n| `decider index` | Regenerate the ADR index |\n| `decider version` | Show version info |\n\nCommon flags:\n- `--dir PATH`: ADR directory (default: `docs/adr`)\n- `--format text|toon|json`: Output format (TOON is default for structured output)\n- `--status STATUS`: Filter by status\n- `--tag TAG`: Filter by tag\n- `--strict`: Treat warnings as errors (for `check adr`)\n\n### Output Formats\n\nDECIDER supports multiple output formats:\n- **text**: Human-readable (default for CLI)\n- **toon**: Token-Oriented Object Notation, compact and LLM-friendly (default for structured output)\n- **json**: Standard JSON for traditional tooling integration\n\nUse `--format=json` when integrating with tools that require JSON.\n\nSee [SPEC.md](SPEC.md) for complete CLI documentation.\n\n## Installation\n\n### Pinned Install (Recommended)\n\nUse the installer scripts for a pinned, checksum-verified install:\n\n```bash\n# macOS/Linux\n./scripts/install-decider.sh\n\n# Windows PowerShell\n.\\scripts\\install-decider.ps1\n```\n\nThis downloads the version pinned in `tools/decider.version`, verifies the checksum, and installs to `./tools/decider/`.\n\n### From GitHub Releases (Manual)\n\n```bash\n# Linux (amd64) - replace 0.1.0 with pinned version\ncurl -L https://github.com/sventorben/decider/releases/download/v0.1.0/decider_0.1.0_linux_amd64.tar.gz | tar xz\n\n# macOS (arm64) - replace 0.1.0 with pinned version\ncurl -L https://github.com/sventorben/decider/releases/download/v0.1.0/decider_0.1.0_darwin_arm64.tar.gz | tar xz\n\n# Windows - download zip from releases page\n```\n\n### From Source\n\n```bash\ngo install github.com/sventorben/decider/cmd/decider@v0.1.0\n```\n\n### Verify Installation\n\n```bash\ndecider version\n# decider version 0.1.0\n#   commit: abc123\n#   built:  2026-01-16T10:00:00Z\n```\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [docs/](docs/README.md) | Documentation portal |\n| [Adopting DECIDER](docs/guides/adopting-decider-in-a-team.md) | Team rollout guide |\n| [Using ADR Steward](docs/guides/using-adr-steward.md) | Claude Code agent guide |\n| [Why: Decisions as Constraints](docs/why/decisions-as-constraints.md) | ADRs as enforceable rules |\n| [Why: Shared Context](docs/why/shared-context-beats-bigger-models.md) | Context over model capability |\n| [SPEC.md](SPEC.md) | Complete specification |\n| [AGENTS.md](AGENTS.md) | Agent integration guide |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |\n| [demo/](demo/README.md) | Interactive demo |\n\n## Non-Goals\n\nDECIDER intentionally does not:\n\n- **Enforce constraints semantically**: The CLI surfaces constraints; enforcement is your CI/human review\n- **Manage approvals**: No built-in workflow for ADR acceptance; use your existing PR process\n- **Support remote ADR repos**: ADRs live in your project repository\n- **Provide policy engine**: No runtime enforcement; this is documentation with structure\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Run `make check` before opening a PR.\n\n## AI Assistance\n\nParts of this project were developed with AI-assisted tooling. Contributors and users should review code and documentation critically, as with any project. All contributions—whether human or AI-assisted—must meet the same project standards: tests must pass, ADRs must be followed, and human review is expected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsventorben%2Fdecider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsventorben%2Fdecider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsventorben%2Fdecider/lists"}