@orderful/droid 0.18.0 → 0.20.0

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

package/src/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/src/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.2.5
+version: 0.2.6
 status: beta
 
 includes:

package/src/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/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.1.4
+version: 0.1.5
 status: beta
 
 includes: