@orderful/droid 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @orderful/droid
 
+## 0.20.0
+
+### Minor Changes
+
+- [#109](https://github.com/Orderful/droid/pull/109) [`1014243`](https://github.com/Orderful/droid/commit/10142438bcd75723027d12ec7bdc23f012643ee3) Thanks [@frytyler](https://github.com/frytyler)! - Add codex tool for shared organizational knowledge
+
+  New tool providing access to the orderful-codex repo containing PRDs, tech designs, patterns, and explored topics. Features include:
+  - Load project context with `/codex {name}`
+  - Search across all categories
+  - Capture decisions during implementation
+  - Add explored topics with freshness tracking
+  - Auto-generate CONTEXT.md from project artifacts
+
 ## 0.19.0
 
 ### Minor Changes

package/dist/tools/codex/TOOL.yaml

@@ -0,0 +1,32 @@
+name: codex
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or adding explored topics."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: droid-codex
+      required: true
+  commands:
+    - codex
+  agents: []
+
+dependencies: []
+
+# Prerequisites checked on install
+prerequisites:
+  - name: gh
+    description: GitHub CLI for PR workflows
+    check: "gh --version"
+    install_hint: "brew install gh && gh auth login"
+
+config_schema:
+  codex_repo:
+    type: string
+    description: Path to local orderful-codex repository (required)
+    required: true
+    default: "~/src/github.com/orderful-codex"
+  freshness_days:
+    type: number
+    description: Days before showing staleness warning
+    default: 30

package/dist/tools/codex/commands/codex.md

@@ -0,0 +1,70 @@
+---
+description: Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics
+argument-hint: "[projects | patterns | topics | {name} | search {query} | new {name} | decision {text} | add topic {name}]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)
+---
+
+# /codex
+
+Entry point for shared organizational knowledge. See the **codex skill** for full behaviour.
+
+> Context is AI's multiplier. This is Orderful's.
+
+## Arguments
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before first use, verify:
+
+1. **Repo cloned** at configured `codex_repo` path
+2. **gh CLI** installed and authenticated
+
+## Usage
+
+```bash
+/codex                           # Show categories (projects, patterns, topics)
+/codex projects                  # List projects
+/codex patterns                  # List patterns
+/codex topics                    # List topics
+/codex {name}                    # Load entry (searches all categories)
+/codex search {query}            # Search across everything
+/codex new {name}                # Scaffold new project from templates
+/codex decision {text}           # Append to active project's DECISIONS.md
+/codex snapshot {file} {name}    # Import PDF/markdown to project
+/codex add topic {name}          # Add explored topic with freshness metadata
+```
+
+## Configuration
+
+**ALWAYS read `~/.droid/skills/codex/overrides.yaml` first.**
+
+- `codex_repo` - Path to local orderful-codex repository (required)
+- `freshness_days` - Days before showing staleness warning (default: 30)
+
+## Behaviour
+
+Refer to the codex skill for:
+- **Loading**: How to search, handle matches, check freshness, auto-generate CONTEXT.md
+- **Decisions**: How to append to active project's DECISIONS.md
+- **Topics**: How to capture explored codebase areas with freshness metadata
+- **Creating**: How to scaffold new projects from templates
+
+The skill's `references/` folder contains detailed procedures for each workflow.
+
+## Examples
+
+```bash
+# Load project context
+/codex transaction-templates
+
+# Search for webhook-related content
+/codex search webhook
+
+# Capture a decision during implementation
+/codex decision "Using UUIDv7 for IDs because it's sortable and includes timestamp"
+
+# Save today's exploration as a topic
+/codex add topic organization-hierarchy
+```

package/dist/tools/codex/skills/droid-codex/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: droid-codex
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Use when loading project context ('load transaction-templates'), searching codex ('search webhook'), capturing decisions ('codex decision'), or adding explored topics ('add topic'). User prompts like 'check the codex', 'what's in the codex about X', 'load the PRD for Y'."
+globs:
+  - "**/PRD.md"
+  - "**/TECH-DESIGN.md"
+  - "**/CONTEXT.md"
+  - "**/DECISIONS.md"
+alwaysApply: false
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)
+---
+
+# Codex Skill
+
+> Context is AI's multiplier. This is Orderful's.
+
+Shared organizational knowledge for humans and droids alike. Product requirements documents, tech designs, patterns, and explored topics - structured for AI-assisted development.
+
+## Prerequisites
+
+Before using codex, verify:
+
+1. **Repo cloned:** Check if `codex_repo` path exists
+2. **gh CLI:** Required for PR workflows (CONTEXT.md auto-generation)
+
+```bash
+# Check repo exists
+ls -la {codex_repo}
+
+# Check gh CLI
+gh --version
+```
+
+If prerequisites fail, guide user to fix:
+- Repo missing: `git clone git@github.com:orderful/orderful-codex.git {path}`
+- gh missing: `brew install gh && gh auth login`
+
+## Sync Before Reading
+
+**Before any read operation** (loading, searching, listing), pull latest:
+
+```bash
+git -C {codex_repo} pull --rebase --quiet
+```
+
+This ensures shared knowledge is always current. The pull is quiet to avoid noise, but if it fails (conflicts, network), warn the user.
+
+## Security
+
+### Input Validation
+
+**Always validate user-provided names before using in paths:**
+
+```bash
+# REJECT names containing path traversal attempts
+if [[ "{name}" == *".."* ]] || [[ "{name}" == *"/"* ]]; then
+  echo "Invalid name: must not contain '..' or '/'"
+  exit 1
+fi
+
+# REJECT names with shell metacharacters
+if [[ "{name}" =~ [\$\`\|\;\&\>\<] ]]; then
+  echo "Invalid name: contains unsafe characters"
+  exit 1
+fi
+```
+
+### Safe Git Commits
+
+**Use heredoc for commit messages to prevent injection:**
+
+```bash
+# GOOD - safe from injection
+git commit -F - <<EOF
+decision({active}): {summary}
+EOF
+
+# BAD - vulnerable to injection
+git commit -m "decision({active}): {summary}"
+```
+
+### Access Control
+
+**Check repo access before attempting write operations:**
+
+```bash
+# Verify push access before making changes
+if ! git -C {codex_repo} push --dry-run 2>/dev/null; then
+  echo "Error: No push access to codex repo. Check your permissions."
+  exit 1
+fi
+```
+
+## Configuration
+
+**ALWAYS read `~/.droid/skills/codex/overrides.yaml` first.**
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `codex_repo` | `~/src/github.com/orderful-codex` | Path to local codex repo |
+| `freshness_days` | `30` | Days before staleness warning |
+
+## Categories
+
+The codex has three categories:
+
+| Category | Path | Purpose |
+|----------|------|---------|
+| `projects` | `{codex_repo}/projects/` | Feature/project context (PRD, tech design, decisions) |
+| `patterns` | `{codex_repo}/patterns/` | Cross-cutting technical patterns |
+| `topics` | `{codex_repo}/topics/` | Explored codebase areas with freshness tracking |
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/codex` | Show categories overview |
+| `/codex projects` | List all projects |
+| `/codex patterns` | List all patterns |
+| `/codex topics` | List all topics |
+| `/codex {name}` | Load entry (searches all categories) |
+| `/codex search {query}` | Search across everything |
+| `/codex new {name}` | Scaffold new project from templates |
+| `/codex decision {text}` | Append to active project's DECISIONS.md |
+| `/codex snapshot {file} {name}` | Import PDF/markdown to project |
+| `/codex add topic {name}` | Add explored topic with freshness metadata |
+
+## Loading an Entry
+
+**Trigger:** `/codex {name}` or user asks to load/check codex for something
+
+**Procedure:**
+
+1. Search for `{name}` across all categories (fuzzy match on folder/file names)
+2. If multiple matches → show list, let user pick
+3. If single match → load it
+4. For projects with multiple files → show file list, let user pick which to load
+5. Check freshness (see below)
+6. Output loaded content
+
+**If no CONTEXT.md exists for a project:**
+- Synthesise unified context from PRD.md + TECH-DESIGN.md + DECISIONS.md
+- Create branch, commit CONTEXT.md, open PR
+- Inform user: "I've created a CONTEXT.md summarising this project - PR #{number}"
+
+Full procedure: `references/loading.md`
+
+## Freshness Checking
+
+All codex files have frontmatter:
+
+```yaml
+---
+title: Feature Name
+type: prd | tech-design | context | decisions | pattern | topic
+created: 2026-01-07
+updated: 2026-01-07
+confidence: high | medium | low
+source: confluence | exploration | implementation
+codebase_paths:
+  - apps/platform-api/src/...
+---
+```
+
+**When loading any file:**
+
+1. Parse frontmatter for `updated` date
+2. Calculate days since update
+3. If > `freshness_days` (default 30):
+   - Warn: "This doc was last updated {date} ({n} days ago). Want me to verify it's still accurate?"
+4. If `codebase_paths` present:
+   - Check if those paths have commits since `updated` date
+   - If yes: "Files in {paths} have changed since this doc was updated. Want me to review?"
+5. If `confidence: low`:
+   - Note: "This was a quick exploration and may be incomplete"
+
+## Active Project Tracking
+
+Scoped operations (`decision`, `snapshot`) require an active project:
+
+- When user loads a project via `/codex {project-name}`, set it as active
+- Store active project name in session context
+- If scoped operation called with no active project → show project list, let user pick
+
+## Adding Decisions
+
+**Trigger:** `/codex decision {text}` or user wants to capture a decision
+
+**Procedure:**
+
+1. Verify active project exists (if not, prompt to select)
+2. Read `{codex_repo}/projects/{active}/DECISIONS.md`
+3. Append new decision with today's date:
+   ```markdown
+   ## {YYYY-MM-DD}: {Decision summary from text}
+
+   **Context:** {Extract from conversation}
+
+   **Decision:** {The decision}
+
+   **Rationale:** {Why this choice}
+   ```
+4. Update `updated` date in frontmatter
+5. Create branch, commit, and open PR via `gh pr create`
+
+Full procedure: `references/decisions.md`
+
+## Adding Topics
+
+**Trigger:** `/codex add topic {name}` or user wants to save exploration
+
+**Procedure:**
+
+1. Create `{codex_repo}/topics/{name}.md`
+2. Use template from `{codex_repo}/templates/TOPIC.md`
+3. Fill in frontmatter:
+   - `explored`: today's date
+   - `confidence`: ask user or infer from exploration depth
+   - `codebase_paths`: paths that were explored
+4. Fill in content from current exploration/conversation
+5. Create branch, commit, and open PR via `gh pr create`
+
+Full procedure: `references/topics.md`
+
+## Creating New Projects
+
+**Trigger:** `/codex new {name}` or user wants to start new project entry
+
+**Procedure:**
+
+1. Create `{codex_repo}/projects/{name}/`
+2. Copy templates from `{codex_repo}/templates/`:
+   - PRD.md
+   - TECH-DESIGN.md
+   - DECISIONS.md
+3. Fill in frontmatter with today's date
+4. Create branch, commit, and open PR via `gh pr create`
+
+Full procedure: `references/creating.md`
+
+## Integration with /project
+
+The codex holds **shared** organizational knowledge. The `/project` skill holds **personal** working memory.
+
+```
+/codex transaction-templates              → load shared context
+/project create --from codex:{name}       → seed personal PROJECT.md
+/codex publish                            → promote learnings back (future)
+```
+
+When user runs `/project create --from codex:{name}`:
+1. Load the codex entry
+2. Extract key context for personal PROJECT.md
+3. Create project in user's projects_dir
+
+## Git Workflow
+
+**All codex changes must go through PRs** (main branch is protected):
+
+1. Create branch: `codex/{action}-{name}` (e.g., `codex/decision-uuid-format`)
+2. Make changes
+3. Commit with descriptive message
+4. Push and create PR via `gh pr create`
+5. Share PR link with user
+
+Safe changes (new files, decision appends) are auto-merged by GitHub Action. Modifications to existing content require review.

package/dist/tools/codex/skills/droid-codex/references/creating.md

@@ -0,0 +1,150 @@
+# Creating New Projects
+
+Detailed procedure for scaffolding new project entries in the codex.
+
+## When to Use
+
+- Starting work on a new feature/project
+- `/codex new {name}` command
+- User asks to create a codex entry for something new
+
+## Procedure
+
+### 1. Determine Project Name
+
+From user input:
+- Use kebab-case: `transaction-templates`, `audit-logging`
+- Should match how the team refers to the feature
+
+### 2. Check for Existing Entry
+
+```bash
+ls {codex_repo}/projects/ | grep -i {name}
+```
+
+If exists:
+```
+A project named '{name}' already exists. Did you mean to load it?
+→ /codex {name}
+```
+
+### 3. Create Project Directory
+
+```bash
+mkdir -p {codex_repo}/projects/{name}
+```
+
+### 4. Copy Templates
+
+```bash
+cp {codex_repo}/templates/PRD.md {codex_repo}/projects/{name}/
+cp {codex_repo}/templates/TECH-DESIGN.md {codex_repo}/projects/{name}/
+cp {codex_repo}/templates/DECISIONS.md {codex_repo}/projects/{name}/
+```
+
+### 5. Update Frontmatter
+
+In each file, update:
+- `title`: Project name (Title Case)
+- `created`: Today's date
+- `updated`: Today's date
+
+### 6. Optionally Pre-Fill Content
+
+If user provides context, fill in what we know:
+- PRD.md: Problem statement, goals if discussed
+- TECH-DESIGN.md: Any architectural decisions mentioned
+- DECISIONS.md: Leave as template (decisions come during impl)
+
+### 7. Create Branch and PR
+
+```bash
+cd {codex_repo}
+git checkout -b codex/new-{name}
+git add projects/{name}/
+git commit -F - <<EOF
+feat(codex): scaffold {name} project
+EOF
+git push -u origin codex/new-{name}
+gh pr create --title "New project: {name}" --body "Scaffold for {name} project"
+```
+
+### 8. Confirm to User
+
+```
+✅ Created codex project: {name}
+
+📁 {codex_repo}/projects/{name}/
+├── PRD.md          (template - fill in requirements)
+├── TECH-DESIGN.md  (template - fill in technical design)
+└── DECISIONS.md    (ready for decisions during implementation)
+
+PR: {pr_url}
+(Auto-merges for new projects)
+
+Next steps:
+1. Fill in PRD.md with product requirements
+2. Fill in TECH-DESIGN.md with technical approach
+3. Use `/codex decision` to capture decisions as you implement
+```
+
+## Example
+
+**User:** `/codex new audit-logging`
+
+**Result:**
+
+```
+✅ Created codex project: audit-logging
+
+📁 ~/src/github.com/orderful-codex/projects/audit-logging/
+├── PRD.md          (template - fill in requirements)
+├── TECH-DESIGN.md  (template - fill in technical design)
+└── DECISIONS.md    (ready for decisions during implementation)
+
+Next steps:
+1. Fill in PRD.md with product requirements
+2. Fill in TECH-DESIGN.md with technical approach
+3. Use `/codex decision` to capture decisions as you implement
+
+Want me to help fill in any of these based on what we've discussed?
+```
+
+## With Pre-Existing Context
+
+If the user has already discussed the feature:
+
+**User:** "We're building audit logging to track all API changes for compliance. It'll use an event sourcing pattern."
+
+**User:** `/codex new audit-logging`
+
+**Result:** (PRD.md pre-filled with discussed context)
+
+```markdown
+---
+title: Audit Logging
+type: prd
+created: 2026-01-07
+updated: 2026-01-07
+confidence: medium
+source: implementation
+---
+
+# Audit Logging - PRD
+
+## Problem Statement
+
+Need to track all API changes for compliance requirements.
+
+## Goals
+
+- Track all API changes
+- Support compliance auditing
+- {More goals to be defined}
+
+## Non-Goals
+
+- {To be defined}
+
+...
+```

package/dist/tools/codex/skills/droid-codex/references/decisions.md

@@ -0,0 +1,128 @@
+# Adding Decisions
+
+Detailed procedure for capturing decisions during implementation.
+
+## When to Use
+
+- User explicitly asks to record a decision
+- `/codex decision {text}` command
+- During implementation when a significant choice is made
+
+## Prerequisites
+
+- **Active project** must be set (from previous `/codex {project}` load)
+- If no active project, prompt user to select one first
+
+## Procedure
+
+### 1. Verify Active Project
+
+```
+If no active project:
+  "No project is currently active. Which project should I add this decision to?"
+  → List projects, let user pick
+  → Set as active
+```
+
+### 2. Parse Decision Text
+
+From the user's input, extract:
+- **Summary:** Brief title for the decision
+- **Context:** What situation prompted this?
+- **Decision:** What was decided?
+- **Rationale:** Why this choice?
+
+If any parts are unclear, ask:
+```
+I'll add this decision. Can you clarify:
+- What prompted this decision?
+- Were there alternatives you considered?
+```
+
+### 3. Read Existing DECISIONS.md
+
+```bash
+cat {codex_repo}/projects/{active}/DECISIONS.md
+```
+
+### 4. Append New Decision
+
+Add at the end, before the template marker:
+
+```markdown
+---
+
+## {YYYY-MM-DD}: {Summary}
+
+**Context:** {What situation prompted this decision?}
+
+**Decision:** {What was decided?}
+
+**Rationale:** {Why this choice over alternatives?}
+
+**Alternatives Considered:**
+- {Alternative 1} - {Why rejected}
+- {Alternative 2} - {Why rejected}
+
+**Consequences:**
+- {Expected outcomes, trade-offs}
+```
+
+### 5. Update Frontmatter
+
+Update the `updated` field to today's date.
+
+### 6. Create Branch and PR
+
+```bash
+cd {codex_repo}
+git checkout -b codex/decision-{short-summary}
+git add projects/{active}/DECISIONS.md
+git commit -F - <<EOF
+decision({active}): {summary}
+EOF
+git push -u origin codex/decision-{short-summary}
+gh pr create --title "Decision: {summary}" --body-file - <<EOF
+{full decision text}
+EOF
+```
+
+### 7. Confirm to User
+
+```
+✅ Added decision to {active}/DECISIONS.md:
+   "{summary}"
+
+PR: {pr_url}
+(Auto-merges for append-only changes)
+```
+
+## Example
+
+**User:** `/codex decision "Using UUIDv7 for all new IDs because it's sortable and includes timestamp"`
+
+**Active project:** transaction-templates
+
+**Result appended to DECISIONS.md:**
+
+```markdown
+---
+
+## 2026-01-07: Using UUIDv7 for ID Generation
+
+**Context:** Need to choose ID format for new transaction template records.
+
+**Decision:** Use UUIDv7 for all new IDs.
+
+**Rationale:** UUIDv7 is sortable (timestamp-based prefix) and includes creation timestamp, making it ideal for ordered data and debugging.
+
+**Alternatives Considered:**
+- UUIDv4 - Random, not sortable, no timestamp
+- Auto-increment - Database-specific, exposes record count
+- ULID - Similar benefits but less standard
+
+**Consequences:**
+- IDs will be longer than auto-increment (36 chars)
+- Natural ordering by creation time
+- No database sequence dependencies
+```