@orderful/droid 0.48.0 → 0.51.0

package/src/tools/brain/TOOL.yaml

@@ -1,7 +1,9 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.4.2
+version: 0.4.3
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/src/tools/brain/skills/brain/SKILL.md

@@ -34,6 +34,8 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 | `inbox_folder` | (empty) | Root folder for new docs (e.g., `0-Inbox`) |
 | `override`     | (none)  | User-defined behaviour overrides |
 
+**Optional dependency:** `droid config --get tools.project` → `save_related_in_project` (for project-aware routing)
+
 **If not configured:** Ask the user:
 > "Where would you like to store brain docs? Common choices:
 > - `~/Documents/brain` - Easy to find in Finder
@@ -107,6 +109,8 @@ Full procedure: `references/workflows.md` § Opening
 
 Templates vary by category (see `references/templates.md`), but all follow the same creation flow.
 
+**Project-aware routing:** When a `/project` is active and `save_related_in_project` is true (check `droid config --get tools.project`), ALL new docs route to `{project_folder}/{category}s/` instead of the brain inbox — no category filtering. Plans, research, ideas, thoughts, spikes, whatever the user creates. If it's related to the project, it lives with the project. Disable with `save_related_in_project: false` in project config.
+
 **Note:** `idea` category docs do NOT become active (fire-and-forget capture).
 
 Full procedure: `references/workflows.md` § Creating

package/src/tools/brain/skills/brain/references/workflows.md

@@ -62,13 +62,27 @@ Detailed procedures for each brain operation.
    - Example: `auth-refactor.md` or `caching-strategies.md`
 
 3. **Determine target path based on category:**
-   - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
-   - Category becomes plural folder: `{base}/{category}s/{filename}`
-   - Examples:
-     - `plan` → `{base}/plans/{filename}`
-     - `research` → `{base}/research/{filename}`
-     - `spike` → `{base}/spikes/{filename}`
-     - `meeting` → `{base}/meetings/{filename}`
+
+   a. **Check for active project:**
+      - If `/project` is active in session AND `save_related_in_project` is true
+        (run `droid config --get tools.project` to check):
+        - Route ALL categories to project folder: `{projects_dir}/{project}/{category}s/{filename}`
+        - No category filtering — plans, research, ideas, thoughts, spikes, anything goes
+        - Example: `/brain research caching` with project "droid" active
+          → `{projects_dir}/droid/research/caching.md`
+        - Example: `/brain idea wild-thought` with project "droid" active
+          → `{projects_dir}/droid/ideas/wild-thought.md`
+      - If `/project` active but `save_related_in_project` is false (default), OR no project active:
+        - Fall through to default routing below
+
+   b. **Default routing (no active project or opt-out):**
+      - Base: `{brain_dir}/{inbox_folder}` (or just `{brain_dir}` if no inbox_folder)
+      - Category becomes plural folder: `{base}/{category}s/{filename}`
+      - Examples:
+        - `plan` → `{base}/plans/{filename}`
+        - `research` → `{base}/research/{filename}`
+        - `spike` → `{base}/spikes/{filename}`
+        - `meeting` → `{base}/meetings/{filename}`
 
 4. **Create directory** if needed (category folder may not exist yet)
 

package/src/tools/coach/TOOL.yaml

@@ -2,6 +2,10 @@ name: coach
 description: "Learning-mode AI assistance - AI as coach, not crutch. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions."
 version: 0.3.0
 status: beta
+audience:
+  - engineering
+  - product
+  - design
 
 includes:
   skills:

package/src/tools/code-review/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-code-review",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.",
   "author": {
     "name": "Orderful",
@@ -23,6 +23,7 @@
     "./agents/edi-standards-reviewer.md",
     "./agents/error-handling-reviewer.md",
     "./agents/test-coverage-analyzer.md",
-    "./agents/type-reviewer.md"
+    "./agents/type-reviewer.md",
+    "./agents/codex-context-researcher.md"
   ]
 }

package/src/tools/code-review/TOOL.yaml

@@ -1,7 +1,9 @@
 name: code-review
 description: "Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring."
-version: 0.2.4
+version: 0.3.0
 status: alpha
+audience:
+  - engineering
 
 includes:
   skills:
@@ -15,5 +17,6 @@ includes:
     - error-handling-reviewer
     - test-coverage-analyzer
     - type-reviewer
+    - codex-context-researcher
 
 dependencies: []

package/src/tools/code-review/agents/codex-context-researcher.md

@@ -0,0 +1,99 @@
+---
+name: codex-context-researcher
+description: "Search codex for domain knowledge relevant to code changes. Enriches code review findings with organisational context from PRDs, tech designs, and architectural decisions."
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+color: cyan
+---
+
+You are a codex research agent that finds organisational domain knowledge relevant to a set of code changes. Your output enriches code review findings — you do NOT review code yourself.
+
+## Inputs
+
+You will receive:
+
+- A list of changed file paths
+- A brief summary of the diff (module names, domain concepts)
+- Optionally, custom instructions from the user
+
+## Procedure
+
+### Step 1: Check Codex Availability
+
+Run: `droid config --get tools.codex`
+
+Parse the output for `codex_repo`. If not set or the command fails, return:
+
+```json
+{
+  "status": "not_configured",
+  "entries_searched": 0,
+  "entries_matched": 0,
+  "domain_context": "",
+  "sources": []
+}
+```
+
+### Step 2: Read Index
+
+Read `{codex_repo}/index.yaml` — this is the codex inventory. It lists every entry by category (projects, patterns, topics, domains, proposals) with names, titles, and aliases.
+
+If the index doesn't exist or is empty, return `status: "not_configured"`.
+
+### Step 3: Extract Search Terms
+
+From the changed file paths, extract terms to match against the index:
+
+- **Module/service names** from paths (e.g., `transactionTemplate` from `src/modules/transactionTemplate/`)
+- **Directory segments** that suggest feature areas (e.g., `billing`, `partnership`, `webhook`)
+
+Do NOT hardcode domain concepts — let the index be the source of truth for what knowledge exists.
+
+### Step 4: Match Against Index
+
+Match extracted terms against index entry names, titles, and aliases across all categories. Select up to **5** most relevant entries. Prioritise:
+
+1. Exact name/alias matches
+2. Partial matches on entry titles
+3. Related entries where extracted terms appear in the name or title
+
+If no entries match, return `status: "no_relevant_entries"`.
+
+### Step 5: Read and Extract
+
+For each matched entry, read the full content. Extract **only**:
+
+- Key patterns and conventions
+- Architectural decisions and their rationale
+- Gotchas, constraints, and explicit rules
+- Domain-specific validation requirements
+
+**Skip** generic content, background sections, and anything not actionable for a code reviewer.
+
+### Step 6: Return Structured Output
+
+Return a JSON block:
+
+```json
+{
+  "status": "ok",
+  "entries_searched": 12,
+  "entries_matched": 3,
+  "domain_context": "Bullet points of reviewer-actionable domain knowledge (~300 words max)",
+  "sources": ["entry-name-1", "entry-name-2"]
+}
+```
+
+- `entries_searched`: total entries in index
+- `entries_matched`: entries that matched search terms
+- `domain_context`: concise, reviewer-actionable bullet points. Focus on what a reviewer should look for or verify. Max ~300 words
+- `sources`: entry names used (for citation in the review report)
+
+## Important
+
+- Do NOT review code. Your job is context retrieval only.
+- Keep `domain_context` focused and actionable — reviewers will read this alongside their own findings.
+- If codex isn't configured or has no relevant entries, return early with the appropriate status. Don't fabricate context.

package/src/tools/code-review/skills/code-review/SKILL.md

@@ -15,6 +15,8 @@ Code-review has no configuration of its own. Optional integration with other too
 
 - **Brain skill** (optional): If installed, offers to save review results to a `/brain review` doc
   - Check with: `droid config --get tools.brain` to see if `brain_dir` is configured
+- **Codex skill** (optional): If configured, enriches EDI findings with organisational domain knowledge
+  - Check with: `droid config --get tools.codex` to see if `codex_repo` is configured
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
@@ -32,6 +34,7 @@ The `/code-review` command orchestrates multiple specialized agents in parallel:
 2. **test-coverage-analyzer** - Test completeness and edge cases
 3. **error-handling-reviewer** - Silent failures, missing error handling
 4. **type-reviewer** - TypeScript type design, interface contracts
+5. **codex-context-researcher** (optional) - Domain knowledge from codex for EDI enrichment
 
 Each agent returns issues with confidence scores (0-100). Issues below 80% confidence are filtered out to reduce noise.
 
@@ -117,14 +120,19 @@ For PR reviews, also fetch:
 
 ### Step 3: Parallel Agent Reviews
 
+**Check codex availability** before launching agents:
+
+Run `droid config --get tools.codex`. If `codex_repo` is configured, you will launch 5 agents. If not, launch the standard 4.
+
 Launch these agents in parallel using the Task tool with `run_in_background: true`:
 
 1. **edi-standards-reviewer**: EDI patterns, partnership handling, billing concerns
 2. **test-coverage-analyzer**: Test completeness and edge cases
 3. **error-handling-reviewer**: Silent failures, missing error handling
 4. **type-reviewer**: Type design, interface contracts
+5. **codex-context-researcher** (only if codex is configured): Pass changed file paths and a brief summary of the diff (module names, domain concepts extracted from paths and PR description). Do NOT pass full diff content — this agent reads codex, not code.
 
-Pass each agent:
+Pass agents 1–4:
 
 1. The diff content
 2. The full file content for changed files (for context)
@@ -139,6 +147,17 @@ Filter out issues with confidence < 80.
 
 ### Step 5: Synthesize Report
 
+**Codex enrichment** (if codex-context-researcher returned `status: "ok"` with non-empty `domain_context`):
+
+Before compiling the EDI findings, prefix the EDI section with a "Domain Context" block:
+
+> **Domain context** (from codex: entry-name-1, entry-name-2)
+> - Bullet points from the researcher's domain_context
+
+Use this context to strengthen or re-prioritise EDI findings. For example, if codex says "partnership billing events must always include account_id" and the EDI reviewer flagged a missing field, elevate that finding's priority.
+
+If codex returned `status: "not_configured"` or `"no_relevant_entries"`, omit the domain context block silently.
+
 Compile findings into a prioritized report:
 
 **PR #123: "Add partnership billing events"** (if reviewing a PR)

package/src/tools/codex/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
   "author": {
     "name": "Orderful",

package/src/tools/codex/TOOL.yaml

@@ -1,7 +1,9 @@
 name: codex
 description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries."
-version: 0.3.1
+version: 0.4.0
 status: beta
+audience:
+  - all
 
 includes:
   skills:

package/src/tools/codex/skills/codex/SKILL.md

@@ -145,6 +145,7 @@ The codex skill includes three git scripts. **Always use these instead of raw gi
 |--------|---------|-------------|
 | git-preamble | Ensure clean main + pull latest | Before ANY operation |
 | git-start-write | Preamble + create branch | Before write operations |
+| normalize-frontmatter | Normalize YAML frontmatter format | After writing, before commit |
 | git-finish-write | Commit + PR + return to main | After write operations |
 
 ### Read Operations
@@ -159,7 +160,10 @@ The codex skill includes three git scripts. **Always use these instead of raw gi
 
     # 2. Make your changes (write files)
 
-    # 3. Finish write (commit + PR + return to main)
+    # 3. Normalize frontmatter (prevents fix-frontmatter PRs)
+    droid config --get tools.codex | droid exec codex normalize-frontmatter --config -
+
+    # 4. Finish write (commit + PR + return to main)
     droid config --get tools.codex | droid exec codex git-finish-write --config - \
       --message "{commit message}" \
       --pr-title "{PR title}" \

package/src/tools/codex/skills/codex/scripts/normalize-frontmatter.test.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect } from 'bun:test';
+import {
+  extractFrontmatter,
+  needsQuoting,
+  quoteValue,
+  unquoteDate,
+  normalizeFrontmatter,
+  normalizeFile,
+} from './normalize-frontmatter';
+
+describe('extractFrontmatter', () => {
+  it('extracts frontmatter from valid markdown', () => {
+    const content = '---\ntitle: Test\nstatus: active\n---\n\n# Body';
+    const { frontmatter, body } = extractFrontmatter(content);
+    expect(frontmatter).toEqual(['title: Test', 'status: active']);
+    expect(body).toBe('\n\n# Body');
+  });
+
+  it('returns null for files without frontmatter', () => {
+    const content = '# Just a heading\n\nSome text.';
+    const { frontmatter, body } = extractFrontmatter(content);
+    expect(frontmatter).toBeNull();
+    expect(body).toBe(content);
+  });
+
+  it('returns null for unclosed frontmatter', () => {
+    const content = '---\ntitle: Test\nstatus: active\n';
+    const { frontmatter } = extractFrontmatter(content);
+    expect(frontmatter).toBeNull();
+  });
+});
+
+describe('needsQuoting', () => {
+  it('does not quote simple strings', () => {
+    expect(needsQuoting('active')).toBe(false);
+    expect(needsQuoting('hello world')).toBe(false);
+  });
+
+  it('does not quote booleans or null', () => {
+    expect(needsQuoting('true')).toBe(false);
+    expect(needsQuoting('false')).toBe(false);
+    expect(needsQuoting('null')).toBe(false);
+  });
+
+  it('does not quote dates', () => {
+    expect(needsQuoting('2026-03-04')).toBe(false);
+  });
+
+  it('quotes strings with em dashes', () => {
+    expect(needsQuoting('AI-powered — fast delivery')).toBe(true);
+  });
+
+  it('quotes strings with en dashes', () => {
+    expect(needsQuoting('pages 1\u20135')).toBe(true);
+  });
+
+  it('quotes strings with accented characters', () => {
+    expect(needsQuoting('résumé of changes')).toBe(true);
+  });
+
+  it('quotes strings with @ symbol', () => {
+    expect(needsQuoting('@tylerfry')).toBe(true);
+  });
+
+  it('quotes strings with colon-space', () => {
+    expect(needsQuoting('Note: this is important')).toBe(true);
+  });
+
+  it('quotes strings with inline # comment', () => {
+    expect(needsQuoting('value #comment')).toBe(true);
+  });
+
+  it('quotes strings starting with special YAML chars', () => {
+    expect(needsQuoting('*bold*')).toBe(true);
+    expect(needsQuoting('!important')).toBe(true);
+  });
+});
+
+describe('quoteValue', () => {
+  it('wraps value in double quotes', () => {
+    expect(quoteValue('hello')).toBe('"hello"');
+  });
+
+  it('escapes internal double quotes', () => {
+    expect(quoteValue('say "hello"')).toBe('"say \\"hello\\""');
+  });
+
+  it('does not double-quote already quoted values', () => {
+    expect(quoteValue('"already quoted"')).toBe('"already quoted"');
+    expect(quoteValue("'single quoted'")).toBe("'single quoted'");
+  });
+});
+
+describe('unquoteDate', () => {
+  it('unquotes a quoted date', () => {
+    expect(unquoteDate('"2026-03-04"')).toBe('2026-03-04');
+    expect(unquoteDate("'2026-03-04'")).toBe('2026-03-04');
+  });
+
+  it('leaves non-date quoted values alone', () => {
+    expect(unquoteDate('"not a date"')).toBe('"not a date"');
+  });
+
+  it('leaves bare dates alone', () => {
+    expect(unquoteDate('2026-03-04')).toBe('2026-03-04');
+  });
+});
+
+describe('normalizeFrontmatter', () => {
+  it('flattens folded scalar (>) into single line', () => {
+    const lines = [
+      'title: >',
+      '  This is a long',
+      '  description that spans',
+      '  multiple lines',
+      'status: active',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'title: This is a long description that spans multiple lines',
+      'status: active',
+    ]);
+  });
+
+  it('flattens literal scalar (|) into single line', () => {
+    const lines = [
+      'description: |',
+      '  Line one',
+      '  Line two',
+      'status: active',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'description: Line one Line two',
+      'status: active',
+    ]);
+  });
+
+  it('flattens >- (strip) into single line', () => {
+    const lines = [
+      'title: >-',
+      '  Stripped trailing',
+      '  newline content',
+      'status: active',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'title: Stripped trailing newline content',
+      'status: active',
+    ]);
+  });
+
+  it('quotes values with em dashes after flattening', () => {
+    const lines = [
+      'description: >',
+      '  AI-powered platform —',
+      '  fast and reliable',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'description: "AI-powered platform \u2014 fast and reliable"',
+    ]);
+  });
+
+  it('quotes inline values with special characters', () => {
+    const lines = [
+      'title: Overview — EDI Platform',
+      'author: @tylerfry',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'title: "Overview \u2014 EDI Platform"',
+      'author: "@tylerfry"',
+    ]);
+  });
+
+  it('unquotes dates that are wrapped in quotes', () => {
+    const lines = [
+      'created: "2026-03-04"',
+      "updated: '2026-01-15'",
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'created: 2026-03-04',
+      'updated: 2026-01-15',
+    ]);
+  });
+
+  it('preserves already-correct frontmatter', () => {
+    const lines = [
+      'title: Simple Title',
+      'type: domain',
+      'status: active',
+      'created: 2026-03-04',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual(lines);
+  });
+
+  it('preserves list items', () => {
+    const lines = [
+      'related_domains:',
+      '- overview',
+      '- transaction',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'related_domains:',
+      '- overview',
+      '- transaction',
+    ]);
+  });
+
+  it('preserves comments', () => {
+    const lines = [
+      '# This is a comment',
+      'title: Test',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual(lines);
+  });
+
+  it('preserves blank lines', () => {
+    const lines = [
+      'title: Test',
+      '',
+      'status: active',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual(lines);
+  });
+
+  it('handles key with empty value (list follows)', () => {
+    const lines = [
+      'codebase_paths:',
+      '- ~/src/app',
+      '- ~/src/lib',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual(lines);
+  });
+
+  it('quotes list items with special characters', () => {
+    const lines = [
+      'participants:',
+      '- @tylerfry',
+      '- @thea',
+    ];
+    const result = normalizeFrontmatter(lines);
+    expect(result).toEqual([
+      'participants:',
+      '- "@tylerfry"',
+      '- "@thea"',
+    ]);
+  });
+});
+
+describe('normalizeFile', () => {
+  it('returns null when no changes needed', () => {
+    const content = '---\ntitle: Test\nstatus: active\ncreated: 2026-03-04\n---\n\n# Body';
+    expect(normalizeFile(content)).toBeNull();
+  });
+
+  it('returns null when no frontmatter exists', () => {
+    const content = '# Just a heading';
+    expect(normalizeFile(content)).toBeNull();
+  });
+
+  it('normalizes and reassembles the file', () => {
+    const content = '---\ntitle: "2026-03-04"\ndescription: >\n  A long\n  description\n---\n\n# Body';
+    const result = normalizeFile(content);
+    expect(result).toBe('---\ntitle: 2026-03-04\ndescription: A long description\n---\n\n# Body');
+  });
+
+  it('is idempotent — second run returns null', () => {
+    const content = '---\ntitle: >\n  Hello — world\nstatus: active\n---\n\n# Body';
+    const first = normalizeFile(content);
+    expect(first).not.toBeNull();
+
+    const second = normalizeFile(first!);
+    expect(second).toBeNull();
+  });
+
+  it('handles real-world codex frontmatter', () => {
+    const content = [
+      '---',
+      'title: Droid - AI Workflow Toolkit',
+      'type: context',
+      'status: active',
+      'created: 2025-12-09',
+      'updated: 2026-01-29',
+      'source: implementation',
+      'participants:',
+      '  tech_lead: tylerfry',
+      'codebase_paths:',
+      '- ~/src/github.com/droid',
+      'slack:',
+      '  channel: \'#droid\'',
+      '  canvas_id: F0AD41VF71V',
+      '---',
+      '',
+      '# Droid',
+    ].join('\n');
+
+    // Already well-formed — should return null
+    expect(normalizeFile(content)).toBeNull();
+  });
+
+  it('normalizes multiline scalar in real-world pattern', () => {
+    const content = [
+      '---',
+      'title: >',
+      '  Automated Partner Testing —',
+      '  End-to-end EDI validation',
+      'type: project',
+      'status: active',
+      'created: 2026-02-01',
+      '---',
+      '',
+      '# Content',
+    ].join('\n');
+
+    const result = normalizeFile(content);
+    expect(result).toContain('title: "Automated Partner Testing \u2014 End-to-end EDI validation"');
+    expect(result).toContain('type: project');
+    expect(result).toContain('created: 2026-02-01');
+
+    // Idempotent
+    expect(normalizeFile(result!)).toBeNull();
+  });
+});