@orderful/droid 0.35.3 → 0.36.0

package/src/tools/codex/skills/codex/references/decisions.md

@@ -1,124 +0,0 @@
-# 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 search {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. Start Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-start-write --config - --branch codex/decision-{short-summary}
-```
-
-### 4. Read and Update DECISIONS.md
-
-```bash
-cat {codex_repo}/projects/{active}/DECISIONS.md
-```
-
-Append new decision at the end:
-
-```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}
-```
-
-Update the `updated` field in frontmatter to today's date.
-
-### 5. Finish Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-finish-write --config - \
-  --message "decision({active}): {summary}" \
-  --pr-title "Decision: {summary}" \
-  --pr-body "{full decision text}"
-```
-
-### 6. 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/codex/references/loading.md

@@ -1,292 +0,0 @@
-# Loading Codex Entries
-
-Detailed procedure for loading entries from the codex.
-
-## Search and Match
-
-**IMPORTANT:** Use the index file for fast lookups. This avoids expensive file-by-file searching.
-
-1. **Get codex repo path** by running `droid config --get tools.codex` and parsing the JSON output
-2. **Read the index file** at `{codex_repo}/index.yaml`:
-   ```yaml
-   # index.yaml structure
-   projects:
-     partnership-automation:
-       title: "Partnership Automation & Sample Transaction Engine"
-       aliases: ["transaction-templates", "template-transactions"]
-   patterns:
-     jsdoc-config-directives:
-       title: "JSDoc @config Directives"
-       aliases: ["config-directives", "comment-directives"]
-   topics:
-     handlebars-template-security:
-       title: "Handlebars Template Security"
-       aliases: []
-   domains: {}
-   proposals: {}
-   ```
-3. **Match `{name}` against the index:**
-   - Check each entry's key (folder/file name)
-   - Check each entry's `aliases` array
-   - Match is case-insensitive and supports partial matching
-   - Example: "template transactions" matches `partnership-automation` via alias "template-transactions"
-4. **Handle matches:**
-   - No matches → "No codex entry found for '{name}'. Did you mean one of these?" + suggest entries from index
-   - Single match → proceed to load from the matched category/path
-   - Multiple matches → show list with category, let user pick
-
-**Fallback:** If `index.yaml` doesn't exist, fall back to directory scanning:
-
-```bash
-ls {codex_repo}/projects/ | grep -i {name}
-ls {codex_repo}/domains/ | grep -i {name}
-# ... etc
-```
-
-## Loading a Project
-
-Projects are folders with multiple files:
-
-```
-projects/transaction-templates/
-├── PRD.md
-├── TECH-DESIGN.md
-├── DESIGN.md        # Optional
-├── CONTEXT.md       # Auto-generated summary (progressive disclosure layer 1)
-└── DECISIONS.md
-```
-
-### Progressive Disclosure
-
-CONTEXT.md is the **first layer** - a synthesised summary that's enough for most queries. Only load full documents when deeper detail is needed.
-
-| Layer | What              | When to use                                                  |
-| ----- | ----------------- | ------------------------------------------------------------ |
-| 1     | CONTEXT.md (~2KB) | General questions, getting oriented, "what is this project?" |
-| 2     | Specific file     | Deep dives - "show me the full technical architecture"       |
-| 3     | All files         | Comprehensive review, major updates, onboarding              |
-
-### Procedure
-
-1. **List files** in project folder
-2. **Check for CONTEXT.md:**
-
-   **If CONTEXT.md exists:**
-
-   ```
-   📂 Loading transaction-templates
-
-   CONTEXT.md available (updated 2026-01-05, ~2KB)
-   → Loading summary for general context...
-
-   [CONTEXT.md content]
-
-   ---
-   Need more detail? Available files:
-   - PRD.md - Full requirements and goals
-   - TECH-DESIGN.md - Architecture and implementation
-   - DECISIONS.md - Decision log
-   ```
-
-   Load CONTEXT.md automatically. Only load additional files if user asks.
-
-   **If no CONTEXT.md:**
-   → Trigger auto-generation (see below)
-
-3. **Set project as active** for scoped operations
-4. **Check freshness** (see below)
-
-## Loading a Domain or Proposal
-
-Domains and proposals are single files:
-
-```
-domains/partnerships.md
-proposals/caching-layer.md
-```
-
-**Procedure:**
-
-1. Read the file
-2. Check freshness
-3. Output content
-
-## 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, generate it immediately.
-
-**User sees:**
-
-```
-📂 Loading transaction-templates
-
-No CONTEXT.md found - generating summary from available artifacts...
-
-Reading PRD.md...
-  → Extracting problem statement, goals, success metrics
-Reading TECH-DESIGN.md...
-  → Extracting architecture overview, key decisions
-Reading DECISIONS.md...
-  → Extracting decision log summary
-
-Synthesising unified context...
-```
-
-**Procedure:**
-
-Generate CONTEXT.md either synchronously or asynchronously:
-
-### Option A: Synchronous (works everywhere)
-
-1. **Inform user:** "No CONTEXT.md found - generating summary from available artifacts"
-2. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
-3. **Generate unified summary** (see template below)
-4. **Create PR** (see git workflow below)
-5. **Output the new CONTEXT.md** with "need more detail?" options
-
-### Option B: Asynchronous (Claude Code only, optional)
-
-1. **Spawn background agent** to synthesize CONTEXT.md (non-blocking):
-   ```
-   Use Task tool with subagent_type: "general" and run_in_background: true
-   Prompt: "Generate CONTEXT.md for {project} from PRD.md, TECH-DESIGN.md, DECISIONS.md. Create branch, commit, open PR."
-   ```
-2. **Immediately ask user** which file to load (don't wait for synthesis)
-3. **Load selected file** and continue working
-4. **When background agent completes**, inform user: "CONTEXT.md ready - PR #{number}"
-
-**Choose whichever approach works best.** Synchronous is simpler and works everywhere. Asynchronous avoids blocking but requires background agent support.
-
-### CONTEXT.md Template
-
-Generate a unified summary from the project files:
-
-```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_
-```
-
-### Git Workflow for CONTEXT.md
-
-After generating the CONTEXT.md content:
-
-```bash
-cd {codex_repo}
-git checkout -b auto/context-{project-name}
-# Write CONTEXT.md to projects/{project}/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."
-```
-
-Then inform the user:
-
-```
-✅ CONTEXT.md created and PR #{number} opened
-
-[Show CONTEXT.md content]
-
----
-Need more detail? Available files:
-- PRD.md - Full requirements and goals
-- TECH-DESIGN.md - Architecture and implementation
-- DECISIONS.md - Decision log
-```
-
-## 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/codex/references/topics.md

@@ -1,215 +0,0 @@
-# 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. Start Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-start-write --config - --branch codex/topic-{name}
-```
-
-### 5. Read Template
-
-```bash
-cat {codex_repo}/templates/TOPIC.md
-```
-
-### 6. 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}
-```
-
-### 7. Finish Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-finish-write --config - \
-  --message "topic: add {name}" \
-  --pr-title "Topic: {name}" \
-  --pr-body "New topic from codebase exploration"
-```
-
-### 8. 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
-```