Implement decision graph tool (#1)

Author: jayvdb

.config/lingo.dic

@@ -6,6 +6,7 @@ ADR
 ADRs
 Agilab
 CD
+CLI
 CRICOS
 Curtin
 EECMS

.config/spellcheck.toml

@@ -35,7 +35,6 @@ skip_os_lookups = true
 # for topic specific lingo.
 use_builtin = true
 
-
 [Hunspell.quirks]
 # Transforms words that are provided by the tokenizer
 # into word fragments based on the capture groups which are to

.dg/org.kdl

@@ -0,0 +1,3 @@
+org "edge-toolkit" {
+    name "edge-toolkit"
+}

.editorconfig

@@ -8,6 +8,19 @@ indent_style = space
 max_line_length = 120
 trim_trailing_whitespace = true
 
+[SKILL.md]
+max_line_length = 200
+
+[AGENTS.md]
+max_line_length = 300
+
+[CLAUDE.md]
+max_line_length = 300
+
 # Markdown files can have flexible indentation for lists
 [*.md]
 indent_size = unset
+
+[.cache.json]
+end_of_line = unset
+insert_final_newline = unset

.gemini/hooks/check-code.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Check if edited files match decision doc code_paths.
+# Delegates to dg hooks check-code for the actual logic.
+if [ -n "$1" ]; then
+  exec dg hooks check-code "$1"
+fi

.gemini/hooks/check-fixme.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Minimal wrapper - delegates to dg hooks check-fixme
+# This allows upgrading dg to get new functionality
+exec dg hooks check-fixme "$@"

.gemini/settings.json

@@ -0,0 +1,22 @@
+{
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  },
+  "hooks": {
+    "AfterTool": [
+      {
+        "matcher": "^(Edit|WriteFile)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".gemini/hooks/check-fixme.sh"
+          },
+          {
+            "type": "command",
+            "command": ".gemini/hooks/check-code.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.gemini/skills/adr/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: adr
+description: Create architecture decision records using MADR 4.0 format
+---
+
+# Create Architecture Decision Record
+
+Capture a technical architecture decision using MADR 4.0 format.
+
+## When to Use
+
+- Technical architecture choices (database, framework, protocol)
+- Infrastructure decisions (hosting, CI/CD, deployment)
+- Code organization choices (monorepo vs multi-repo, module structure)
+- API design decisions
+
+## Workflow
+
+1. **Check existing context**:
+   ```bash
+   dg list
+   dg validate
+   ```
+
+2. **Link to OPP when applicable**: If this ADR implements a business opportunity, reference it.
+
+3. **Create the ADR**:
+   ```bash
+   dg new adr "Use Ruby on Rails with PostgreSQL"
+   ```
+
+4. **Fill in the document**:
+   - **Context and Problem Statement**: What is the issue?
+   - **Decision Drivers**: What factors matter?
+   - **Considered Options**: At least 2-3 alternatives
+   - **Decision Outcome**: Which option and why
+   - **Consequences**: Good, bad, and neutral
+
+## Status Lifecycle
+
+- `draft` — Incomplete, not ready for review
+- `proposed` — Under discussion, not yet decided
+- `accepted` — Decision is final and active
+- `deprecated` — No longer relevant
+- `superseded` — Replaced by a newer ADR (link to it)
+- `rejected` — Decision was considered but rejected (link to alternatives)
+
+## Tips
+
+- Good title: "Use Ruby on Rails with PostgreSQL"
+- Bad title: "Tech stack decision"
+- Always document rejected alternatives — they prevent revisiting the same discussion
+- Link to OPPs this decision realizes using `implements:` field
+- Link to POLs that constrain this decision using `implements:` or `conflicts_with:` fields
+- Use `depends_on:` for decisions that block or are blocked by other docs
+- Use `<!-- FIXME: ... -->` for information gaps that need follow-up

.gemini/skills/diagram/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: diagram
+description: Create effective D2/Mermaid diagrams optimized for terminal display
+---
+
+# Create Diagram
+
+Create effective D2 or Mermaid diagrams optimized for terminal display.
+
+## When to Use
+
+- Architecture or infrastructure diagrams
+- System interaction flows (request paths, failure cascades)
+- Process flowcharts or state machines
+- Incident failure diagrams showing what went wrong
+
+## Workflow
+
+1. **Identify components**: Ask what nodes (services, databases, users) and edges (connections, data flows) to show
+2. **Draft the D2/Mermaid code**: Write a first version following the terminal best practices below
+3. **Review for readability**: Check label lengths, node count, layout direction
+4. **Place in document**: Add as a fenced code block in the appropriate section
+
+## Terminal Best Practices
+
+Diagrams render as ASCII art in the terminal. Follow these rules for clean output.
+
+### Keep it small
+
+Aim for **5-7 nodes** max. Terminals are typically 80-120 columns wide. More nodes = unreadable overlaps.
+
+If you need more, use **containers** to group related nodes:
+
+```d2
+vpc: VPC {
+  api: API
+  db: Database {shape: cylinder}
+  api -> db
+}
+client: Client
+client -> vpc.api
+```
+
+### Use short labels
+
+Edge labels over ~15 characters get moved to a legend at the bottom, disconnecting them from context.
+
+- Bad: `api -> db: "sends authenticated read requests for user data"`
+- Good: `api -> db: reads`
+
+Node labels should also be concise. Use the key as short ID and label for display:
+
+```d2
+pg: PostgreSQL {shape: cylinder}
+```
+
+### Set direction
+
+Default is top-to-bottom. For terminal, `direction: right` often works better as it uses horizontal space:
+
+```d2
+direction: right
+a: Service A
+b: Service B
+a -> b: calls
+```
+
+### Use shapes for meaning
+
+Supported shapes that render distinctly:
+
+- `shape: cylinder` — databases, connection pools, queues
+- `shape: diamond` — decision points
+- `shape: hexagon` — APIs or key services
+- `shape: circle` — users, external actors
+- Default rectangle — everything else
+
+### Cycles are warned
+
+A cycle like `A -> B -> C -> A` triggers a D002 warning. This is informational — cycles in incident/failure diagrams are often intentional. To avoid warnings on return paths, restructure as:
+
+```d2
+# Instead of A -> B and B -> A, use:
+a <-> b: request/response
+```
+
+### Mermaid vs D2
+
+Both work. D2 is simpler for architecture diagrams. Mermaid is better for state machines and sequence diagrams.
+
+```mermaid
+stateDiagram-v2
+  proposed --> accepted
+  proposed --> rejected
+  accepted --> deprecated
+  accepted --> superseded
+```
+
+## Common Patterns
+
+### Incident failure diagram
+
+```d2
+users: Users {shape: circle}
+api: API
+db: Database {shape: cylinder}
+
+users -> api: requests
+api -> db: queries
+api -> users: 503 errors
+```
+
+### Architecture overview
+
+```d2
+direction: right
+client: Browser
+api: API {shape: hexagon}
+db: PostgreSQL {shape: cylinder}
+cache: Redis {shape: cylinder}
+
+client -> api: HTTPS
+api -> db: reads/writes
+api -> cache: cached reads
+```
+
+### Decision flow
+
+```d2
+direction: right
+start: Request
+auth: Authenticated? {shape: diamond}
+allow: Allow
+deny: Deny
+
+start -> auth
+auth -> allow: yes
+auth -> deny: no
+```
+
+## Tips
+
+- Always test rendering width: `dg show DOC-ID` shows actual terminal output
+- If labels overflow to legend, shorten them — inline labels are always more readable
+- Use comments (`# ...` in D2) to document intent without affecting rendering
+- Prefer D2 for static architecture, Mermaid `stateDiagram-v2` for lifecycles

.gemini/skills/image/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: image
+description: Add an image to a decision document — rename, move to docs/assets/, insert reference
+---
+
+# Add Image to Document
+
+Add an image to a decision document. Handles renaming, moving to docs/assets/, and inserting the markdown reference.
+
+## When to Use
+
+- User pastes or provides an image to include in a document
+- User asks to add a screenshot, diagram, or photo to a doc
+- User provides an image file path that needs to be moved to the correct location
+
+## Workflow
+
+1. **Identify the image source**: The user may paste an image (saved to a temp path), provide a file path, or provide a URL.
+
+2. **Determine the target document**: Ask which document (e.g. ADR-001, OPP-002) the image belongs to, if not obvious from context.
+
+3. **Name the image file**: Use a descriptive, kebab-case name based on content:
+   - `architecture-overview.png`
+   - `incident-timeline.png`
+   - `deployment-flow.svg`
+   - Format: `{doc-id-lowercase}-{description}.{ext}` e.g. `adr-001-architecture-overview.png`
+
+4. **Ensure docs/assets/ exists**:
+   ```bash
+   mkdir -p docs/assets
+   ```
+
+5. **Move/copy the image**:
+   ```bash
+   cp /path/to/source/image.png docs/assets/adr-001-architecture-overview.png
+   ```
+
+6. **Insert markdown reference** in the target document using `dg set`:
+   ```bash
+   dg set ADR-001 --section "Context and Problem Statement" --append '![Architecture overview](../assets/adr-001-architecture-overview.png)'
+   ```
+   Or for documents that reference from project root:
+   ```markdown
+   ![Architecture overview](docs/assets/adr-001-architecture-overview.png)
+   ```
+
+7. **Validate**:
+   ```bash
+   dg validate
+   ```
+
+## Image Path Rules
+
+- All local images MUST be stored in `docs/assets/`
+- Reference from within docs/ subdirs: `../assets/filename.png`
+- Reference from project root: `docs/assets/filename.png`
+- External URLs (https://...) are allowed anywhere
+- `dg validate` will flag images stored outside docs/assets/ (error C002)
+
+## Tips
+
+- Prefer SVG for diagrams (scalable, small file size)
+- Prefer PNG for screenshots (lossless, good for text)
+- Keep file sizes reasonable — compress large screenshots
+- Use descriptive alt text for accessibility
+- Prefix image filenames with the doc ID to avoid naming collisions