@orderful/droid 0.19.0 → 0.20.0

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/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 |