@orderful/droid 0.19.0 → 0.21.0

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
+```

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

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

@@ -0,0 +1,213 @@
+# Adding Topics
+
+Detailed procedure for capturing explored codebase areas as institutional knowledge.
+
+## When to Use
+
+- After a deep exploration of a codebase area
+- User asks to save/capture exploration
+- `/codex add topic {name}` command
+- Converting ad-hoc research into persistent knowledge
+
+## The Value
+
+Topics turn ephemeral exploration into institutional memory:
+- Next time someone needs to understand this area, context is ready
+- AI can load it instantly instead of re-exploring
+- Freshness tracking ensures it stays current
+
+## Procedure
+
+### 1. Determine Topic Name
+
+From user input or infer from exploration:
+- Use kebab-case: `organization-hierarchy`, `webhook-processing`
+- Be specific but concise
+
+### 2. Gather Content
+
+From the current conversation/exploration, extract:
+- **Overview:** What is this area of the codebase?
+- **Key Concepts:** Important terms, patterns, relationships
+- **Architecture:** How components fit together
+- **Key Files:** Important files and their purposes
+- **Common Patterns:** Recurring patterns in this area
+- **Gotchas:** Things to watch out for
+
+### 3. Determine Metadata
+
+Ask user or infer:
+- **Confidence:** How thorough was the exploration?
+  - `high` - Comprehensive, covered most aspects
+  - `medium` - Good coverage but may have gaps
+  - `low` - Quick exploration, definitely incomplete
+- **Codebase paths:** Which directories/files were explored?
+
+### 4. Read Template
+
+```bash
+cat {codex_repo}/templates/TOPIC.md
+```
+
+### 5. Create Topic File
+
+```bash
+# Create the file
+touch {codex_repo}/topics/{name}.md
+```
+
+Fill in content:
+
+```markdown
+---
+title: {Topic Title}
+type: topic
+created: {today}
+updated: {today}
+confidence: {high|medium|low}
+source: exploration
+codebase_paths:
+  - {path/explored/1}
+  - {path/explored/2}
+---
+
+# {Topic Title}
+
+## Overview
+
+{Brief description of this area of the codebase}
+
+## Key Concepts
+
+### {Concept 1}
+
+{Explanation}
+
+### {Concept 2}
+
+{Explanation}
+
+## Architecture
+
+{How components fit together}
+
+```
+{Diagram or structure if helpful}
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `{path/to/file}` | {What it does} |
+
+## Common Patterns
+
+{Patterns used in this area}
+
+## Gotchas
+
+- {Thing to watch out for}
+- {Another gotcha}
+
+## Related
+
+- {Links to related topics, PRDs, or external docs}
+```
+
+### 6. Create Branch and PR
+
+```bash
+cd {codex_repo}
+git checkout -b codex/topic-{name}
+git add topics/{name}.md
+git commit -F - <<EOF
+topic: add {name}
+EOF
+git push -u origin codex/topic-{name}
+gh pr create --title "Topic: {name}" --body "New topic from codebase exploration"
+```
+
+### 7. Confirm to User
+
+```
+✅ Added topic: {name}
+
+📚 {codex_repo}/topics/{name}.md
+Confidence: {confidence}
+Paths covered: {codebase_paths}
+
+PR: {pr_url}
+(Auto-merges for new files)
+
+Next time someone asks about {topic}, I can load this context instantly.
+```
+
+## Example
+
+**User:** (after exploring organization hierarchy) `/codex add topic organization-hierarchy`
+
+**Result:**
+
+```markdown
+---
+title: Organization Hierarchy
+type: topic
+created: 2026-01-07
+updated: 2026-01-07
+confidence: high
+source: exploration
+codebase_paths:
+  - apps/platform-api/src/modules/organization/
+  - libs/shared/src/types/organization.ts
+---
+
+# Organization Hierarchy
+
+## Overview
+
+Orderful's multi-tenant organization structure with parent-child relationships, enabling enterprise customers to manage multiple business units under a single account.
+
+## Key Concepts
+
+### Organization
+
+The top-level entity. Has settings, billing, users.
+
+### Child Organizations
+
+Organizations can have children, creating a hierarchy. Children inherit some settings from parents.
+
+### Organization Context
+
+Request-scoped context determining which org's data to access.
+
+## Architecture
+
+```
+Organization (parent)
+├── Organization (child 1)
+│   └── Organization (grandchild)
+└── Organization (child 2)
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `organization.entity.ts` | TypeORM entity with parent/child relations |
+| `organization.service.ts` | Business logic for org operations |
+| `organization-context.middleware.ts` | Sets org context from request |
+
+## Common Patterns
+
+- Always check org context before data access
+- Use `organizationId` foreign key on tenant-scoped entities
+- Hierarchy queries use recursive CTEs
+
+## Gotchas
+
+- Child orgs don't automatically inherit all parent settings
+- Deleting a parent doesn't cascade to children (soft delete)
+- API keys are scoped to single org, not hierarchy
+```

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

@@ -147,6 +147,7 @@ for f in $(npm root -g)/@orderful/droid/dist/tools/*/TOOL.yaml; do echo "---"; c
 | **brain** | Collaborative scratchpad for planning and research |
 | **coach** | Learning-mode AI - scaffolds don't implement, questions don't fix |
 | **code-review** | Code review with specialized agents and confidence scoring |
+| **codex** | Shared organizational knowledge - PRDs, tech designs, patterns, topics |
 | **comments** | Inline conversations using @droid/@user markers |
 | **project** | Project context for persistent AI memory across sessions |
 
@@ -170,6 +171,12 @@ Comprehensive code review using specialized agents. Reviews PRs, staged changes,
 **Commands:** `/code-review`
 **Agents:** edi-standards-reviewer, error-handling-reviewer, test-coverage-analyzer, type-reviewer
 
+#### codex
+Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Load project context, search across the codex, capture decisions during implementation.
+
+**Commands:** `/codex`, `/codex projects`, `/codex search`, `/codex decision`, `/codex add topic`
+**Requires:** gh CLI, orderful-codex repo cloned locally
+
 #### comments
 Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Ideal for code review notes and async collaboration.
 
@@ -215,6 +222,7 @@ Run `droid` to see all available tools or install new ones.
 | brain | Planning and research scratchpad with `/brain` commands |
 | coach | Learning-mode AI that asks questions instead of giving answers |
 | code-review | PR review with specialized agents |
+| codex | Shared knowledge - PRDs, tech designs, patterns, topics |
 | comments | Inline @droid/@user conversations in any file |
 | project | Persistent project context across sessions |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {