@orderful/droid 0.19.0 → 0.20.0

package/src/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/src/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/src/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
+```

package/src/tools/codex/skills/droid-codex/references/loading.md

@@ -0,0 +1,163 @@
+# Loading Codex Entries
+
+Detailed procedure for loading entries from the codex.
+
+## Search and Match
+
+1. **Get codex repo path** from `~/.droid/skills/codex/overrides.yaml`
+2. **Search all categories** for `{name}`:
+   ```bash
+   # Search projects
+   ls {codex_repo}/projects/ | grep -i {name}
+
+   # Search patterns
+   ls {codex_repo}/patterns/ | grep -i {name}
+
+   # Search topics
+   ls {codex_repo}/topics/ | grep -i {name}
+   ```
+3. **Handle matches:**
+   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + list recent entries
+   - Single match → proceed to load
+   - Multiple matches → show list with category, let user pick
+
+## Loading a Project
+
+Projects are folders with multiple files:
+
+```
+projects/transaction-templates/
+├── PRD.md
+├── TECH-DESIGN.md
+├── DESIGN.md        # Optional
+├── CONTEXT.md       # Optional, auto-generated
+└── DECISIONS.md
+```
+
+**Procedure:**
+
+1. List files in project folder
+2. Show file list to user:
+   ```
+   Found transaction-templates with:
+   - PRD.md (updated 2026-01-05)
+   - TECH-DESIGN.md (updated 2026-01-03)
+   - DECISIONS.md (updated 2026-01-07)
+
+   Which files should I load? (or 'all' for everything)
+   ```
+3. Load selected file(s)
+4. Set project as **active** for scoped operations
+5. Check freshness (see below)
+
+## Loading a Pattern or Topic
+
+Patterns and topics are single files:
+
+```
+patterns/api-design.md
+topics/organization-hierarchy.md
+```
+
+**Procedure:**
+
+1. Read the file
+2. Check freshness
+3. Output content
+
+## Auto-Generating CONTEXT.md
+
+If loading a project and no CONTEXT.md exists:
+
+1. **Inform user:** "No CONTEXT.md found. I'll synthesise one from the available artifacts."
+2. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
+3. **Generate unified summary:**
+   ```markdown
+   ---
+   title: {Project Name}
+   type: context
+   created: {today}
+   updated: {today}
+   confidence: high
+   source: implementation
+   ---
+
+   # {Project Name} - Context
+
+   ## Overview
+   {Synthesised from PRD problem statement + goals}
+
+   ## Technical Approach
+   {Synthesised from TECH-DESIGN architecture + key decisions}
+
+   ## Key Decisions
+   {Summarised from DECISIONS.md}
+
+   ## Current Status
+   {Inferred from most recent updates}
+
+   ---
+   *Auto-generated from PRD.md, TECH-DESIGN.md, and DECISIONS.md*
+   ```
+4. **Create PR:**
+   ```bash
+   cd {codex_repo}
+   git checkout -b auto/context-{project-name}
+   # Write CONTEXT.md
+   git add projects/{project}/CONTEXT.md
+   git commit -F - <<EOF
+   feat: auto-generate CONTEXT.md for {project}
+   EOF
+   git push -u origin auto/context-{project-name}
+   gh pr create --title "Auto-generated CONTEXT.md for {project}" --body "Synthesised from PRD, TECH-DESIGN, and DECISIONS."
+   ```
+5. **Inform user:** "Created PR #{number} with auto-generated CONTEXT.md"
+
+## Freshness Checking
+
+After loading any file:
+
+1. **Parse frontmatter** for `updated` date
+2. **Calculate age:**
+   ```
+   days_old = today - updated
+   ```
+3. **Check against threshold** (`freshness_days` from config, default 30):
+   - If `days_old > freshness_days`:
+     ```
+     ⚠️ This doc was last updated {updated} ({days_old} days ago).
+     Want me to verify it's still accurate?
+     ```
+4. **Check codebase changes** (if `codebase_paths` present):
+   ```bash
+   cd {workspace}
+   git log --oneline --since="{updated}" -- {codebase_paths}
+   ```
+   - If commits found:
+     ```
+     ⚠️ Files in {paths} have changed since this doc was updated.
+     Recent commits: {list}
+     Want me to review for needed updates?
+     ```
+5. **Note confidence** (if `confidence: low`):
+   ```
+   ℹ️ This was a quick exploration and may be incomplete.
+   ```
+
+## Output Format
+
+After loading, output:
+
+```
+📚 Loaded: {category}/{name}
+Updated: {updated} ({days_old} days ago)
+Confidence: {confidence}
+
+---
+
+{file content}
+
+---
+
+{freshness warnings if any}
+```