@orderful/droid 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @orderful/droid
 
+## 0.25.2
+
+### Patch Changes
+
+- [#132](https://github.com/Orderful/droid/pull/132) [`b4ad140`](https://github.com/Orderful/droid/commit/b4ad1406308f38db58d6a0706c3b0252eed60c2a) Thanks [@frytyler](https://github.com/frytyler)! - codex: add progressive disclosure pattern for project loading
+
+  CONTEXT.md is now the first layer loaded automatically for projects. Full PRD/TECH-DESIGN/DECISIONS files are only loaded when deeper detail is explicitly needed. This avoids loading 30KB+ of docs for simple context questions.
+
+## 0.25.1
+
+### Patch Changes
+
+- [#129](https://github.com/Orderful/droid/pull/129) [`d3264c4`](https://github.com/Orderful/droid/commit/d3264c493e1c243e812ab742103351888092ac79) Thanks [@frytyler](https://github.com/frytyler)! - fix(codex): add git preamble to Loading procedure
+
+  The "Loading an Entry" procedure wasn't running the git preamble before
+  reading files, causing potential stale data issues. Now explicitly calls
+  `git-preamble` as step 1 before reading the index.
+
 ## 0.25.0
 
 ### Minor Changes

package/dist/tools/codex/TOOL.yaml

@@ -1,6 +1,6 @@
 name: codex
 description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries."
-version: 0.1.2
+version: 0.1.4
 status: beta
 
 includes:

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

@@ -179,20 +179,30 @@ The codex has five categories:
 
 **Procedure:**
 
-1. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
-2. Match `{name}` against index keys and aliases (case-insensitive, partial match)
-3. If multiple matches → show list, let user pick
-4. If single match → load directly from the matched path
-5. For projects with multiple files → show file list, let user pick which to load
-6. Check freshness (see below)
-7. Output loaded content
+1. **Run preamble first:**
+   ```bash
+   droid config codex | droid exec droid-codex git-preamble --config -
+   ```
+2. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
+3. Match `{name}` against index keys and aliases (case-insensitive, partial match)
+4. If multiple matches → show list, let user pick
+5. If single match → load directly from the matched path
+6. **For projects → use progressive disclosure:**
+   - If CONTEXT.md exists → load it automatically (layer 1)
+   - Offer deeper files only if user needs more detail
+   - If no CONTEXT.md → synthesise one first (see below)
+7. Check freshness (see below)
+8. Output loaded content with "need more detail?" options
 
 **Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
+**Progressive disclosure:** CONTEXT.md is the first layer - a synthesised summary (~2KB) that handles most queries. Only load full PRD/TECH-DESIGN/DECISIONS files when deeper detail is explicitly needed. This avoids loading 30KB+ of docs for simple context questions.
+
 **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}"
+- Spawn background agent to synthesise (non-blocking)
+- Immediately ask user which file to load - don't make them wait
+- Background agent: reads PRD.md + TECH-DESIGN.md + DECISIONS.md, synthesises, creates PR
+- Notify user when complete: "CONTEXT.md ready - PR #{number}"
 
 Full procedure: `references/loading.md`
 

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

@@ -51,25 +51,47 @@ projects/transaction-templates/
 ├── PRD.md
 ├── TECH-DESIGN.md
 ├── DESIGN.md        # Optional
-├── CONTEXT.md       # Optional, auto-generated
+├── CONTEXT.md       # Auto-generated summary (progressive disclosure layer 1)
 └── DECISIONS.md
 ```
 
-**Procedure:**
+### 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. Show file list to user:
+1. **List files** in project folder
+2. **Check for CONTEXT.md:**
+
+   **If CONTEXT.md exists:**
    ```
-   Found transaction-templates with:
-   - PRD.md (updated 2026-01-05)
-   - TECH-DESIGN.md (updated 2026-01-03)
-   - DECISIONS.md (updated 2026-01-07)
+   📂 Loading transaction-templates
+
+   CONTEXT.md available (updated 2026-01-05, ~2KB)
+   → Loading summary for general context...
+
+   [CONTEXT.md content]
 
-   Which files should I load? (or 'all' for everything)
+   ---
+   Need more detail? Available files:
+   - PRD.md - Full requirements and goals
+   - TECH-DESIGN.md - Architecture and implementation
+   - DECISIONS.md - Decision log
    ```
-3. Load selected file(s)
-4. Set project as **active** for scoped operations
-5. Check freshness (see below)
+   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
 
@@ -103,11 +125,38 @@ topics/organization-hierarchy.md
 
 ## Auto-Generating CONTEXT.md
 
-If loading a project and no CONTEXT.md exists:
+If loading a project and no CONTEXT.md exists, generate it **asynchronously** so the user isn't blocked.
+
+**User sees:**
+```
+📂 Loading transaction-templates
+
+No CONTEXT.md found - I'll generate one in the background.
+Meanwhile, which file do you want to load?
 
-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:**
+Available files:
+- PRD.md - Full requirements and goals
+- TECH-DESIGN.md - Architecture and implementation
+- DECISIONS.md - Decision log
+```
+
+**Procedure:**
+
+1. **Spawn background agent** to synthesize CONTEXT.md (non-blocking):
+   ```
+   Use Task tool with subagent_type: "general-purpose" 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}"
+
+### Background Agent Task
+
+The background agent should:
+
+1. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
+2. **Generate unified summary:**
    ```markdown
    ---
    title: {Project Name}
@@ -147,7 +196,12 @@ If loading a project and no CONTEXT.md exists:
    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"
+5. **Return result** (background agent outputs to task output file):
+   ```
+   ✅ CONTEXT.md synthesised and PR #{number} created for {project}
+   ```
+
+   The main conversation will be notified when the background task completes.
 
 ## Freshness Checking
 

package/package.json

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

package/src/tools/codex/TOOL.yaml

@@ -1,6 +1,6 @@
 name: codex
 description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries."
-version: 0.1.2
+version: 0.1.4
 status: beta
 
 includes:

package/src/tools/codex/skills/droid-codex/SKILL.md

@@ -179,20 +179,30 @@ The codex has five categories:
 
 **Procedure:**
 
-1. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
-2. Match `{name}` against index keys and aliases (case-insensitive, partial match)
-3. If multiple matches → show list, let user pick
-4. If single match → load directly from the matched path
-5. For projects with multiple files → show file list, let user pick which to load
-6. Check freshness (see below)
-7. Output loaded content
+1. **Run preamble first:**
+   ```bash
+   droid config codex | droid exec droid-codex git-preamble --config -
+   ```
+2. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
+3. Match `{name}` against index keys and aliases (case-insensitive, partial match)
+4. If multiple matches → show list, let user pick
+5. If single match → load directly from the matched path
+6. **For projects → use progressive disclosure:**
+   - If CONTEXT.md exists → load it automatically (layer 1)
+   - Offer deeper files only if user needs more detail
+   - If no CONTEXT.md → synthesise one first (see below)
+7. Check freshness (see below)
+8. Output loaded content with "need more detail?" options
 
 **Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
 
+**Progressive disclosure:** CONTEXT.md is the first layer - a synthesised summary (~2KB) that handles most queries. Only load full PRD/TECH-DESIGN/DECISIONS files when deeper detail is explicitly needed. This avoids loading 30KB+ of docs for simple context questions.
+
 **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}"
+- Spawn background agent to synthesise (non-blocking)
+- Immediately ask user which file to load - don't make them wait
+- Background agent: reads PRD.md + TECH-DESIGN.md + DECISIONS.md, synthesises, creates PR
+- Notify user when complete: "CONTEXT.md ready - PR #{number}"
 
 Full procedure: `references/loading.md`
 

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

@@ -51,25 +51,47 @@ projects/transaction-templates/
 ├── PRD.md
 ├── TECH-DESIGN.md
 ├── DESIGN.md        # Optional
-├── CONTEXT.md       # Optional, auto-generated
+├── CONTEXT.md       # Auto-generated summary (progressive disclosure layer 1)
 └── DECISIONS.md
 ```
 
-**Procedure:**
+### 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. Show file list to user:
+1. **List files** in project folder
+2. **Check for CONTEXT.md:**
+
+   **If CONTEXT.md exists:**
    ```
-   Found transaction-templates with:
-   - PRD.md (updated 2026-01-05)
-   - TECH-DESIGN.md (updated 2026-01-03)
-   - DECISIONS.md (updated 2026-01-07)
+   📂 Loading transaction-templates
+
+   CONTEXT.md available (updated 2026-01-05, ~2KB)
+   → Loading summary for general context...
+
+   [CONTEXT.md content]
 
-   Which files should I load? (or 'all' for everything)
+   ---
+   Need more detail? Available files:
+   - PRD.md - Full requirements and goals
+   - TECH-DESIGN.md - Architecture and implementation
+   - DECISIONS.md - Decision log
    ```
-3. Load selected file(s)
-4. Set project as **active** for scoped operations
-5. Check freshness (see below)
+   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
 
@@ -103,11 +125,38 @@ topics/organization-hierarchy.md
 
 ## Auto-Generating CONTEXT.md
 
-If loading a project and no CONTEXT.md exists:
+If loading a project and no CONTEXT.md exists, generate it **asynchronously** so the user isn't blocked.
+
+**User sees:**
+```
+📂 Loading transaction-templates
+
+No CONTEXT.md found - I'll generate one in the background.
+Meanwhile, which file do you want to load?
 
-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:**
+Available files:
+- PRD.md - Full requirements and goals
+- TECH-DESIGN.md - Architecture and implementation
+- DECISIONS.md - Decision log
+```
+
+**Procedure:**
+
+1. **Spawn background agent** to synthesize CONTEXT.md (non-blocking):
+   ```
+   Use Task tool with subagent_type: "general-purpose" 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}"
+
+### Background Agent Task
+
+The background agent should:
+
+1. **Read all available files:** PRD.md, TECH-DESIGN.md, DECISIONS.md
+2. **Generate unified summary:**
    ```markdown
    ---
    title: {Project Name}
@@ -147,7 +196,12 @@ If loading a project and no CONTEXT.md exists:
    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"
+5. **Return result** (background agent outputs to task output file):
+   ```
+   ✅ CONTEXT.md synthesised and PR #{number} created for {project}
+   ```
+
+   The main conversation will be notified when the background task completes.
 
 ## Freshness Checking