@orderful/droid 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @orderful/droid
 
+## 0.22.0
+
+### Minor Changes
+
+- [#113](https://github.com/Orderful/droid/pull/113) [`37245c2`](https://github.com/Orderful/droid/commit/37245c2a54427dc57f54ec80399d827997089e0a) Thanks [@frytyler](https://github.com/frytyler)! - Add `/codex artifact` command for adding supplementary documents to projects. Artifacts are supporting materials like customer interviews, research notes, and meeting summaries that live in `projects/{name}/artifacts/`.
+
+## 0.21.0
+
+### Minor Changes
+
+- [#111](https://github.com/Orderful/droid/pull/111) [`c14a3e2`](https://github.com/Orderful/droid/commit/c14a3e2acbf7a87052c9d5dba251502b8be067f9) Thanks [@frytyler](https://github.com/frytyler)! - Add codex-document-processor agent for importing documents to the codex. The agent handles PDF/markdown processing, frontmatter generation, and file writing - keeping the main conversation context lean during document imports.
+
 ## 0.20.0
 
 ### Minor Changes

package/dist/tools/codex/TOOL.yaml

@@ -9,7 +9,8 @@ includes:
       required: true
   commands:
     - codex
-  agents: []
+  agents:
+    - codex-document-processor
 
 dependencies: []
 

package/dist/tools/codex/agents/codex-document-processor.md

@@ -0,0 +1,145 @@
+---
+name: codex-document-processor
+description: "Process documents (PDF, markdown) into codex-ready markdown with proper frontmatter. Use when importing files to the codex - handles extraction, formatting, and writing to the correct location."
+tools:
+  - Read
+  - Write
+  - Glob
+color: yellow
+---
+
+You are a document processor for the Orderful codex. Your job is to transform source documents (PDFs, markdown files) into properly structured codex entries.
+
+## Input
+
+You will receive:
+1. **File path** - The source document to process
+2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`
+3. **Project/entry name** - Where this should be stored in the codex
+4. **Codex repo path** - The local path to orderful-codex repository
+5. **Artifact filename** (optional, for artifacts) - Name for the artifact file
+
+## Validation (Do This First)
+
+Before processing, validate all inputs:
+
+1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`. Reject anything else.
+2. **File path** - Must exist and be readable. Use Read tool to verify.
+3. **Project/entry name** - Must be safe for filesystem paths:
+   - Only allow: alphanumeric, dashes, underscores
+   - **Reject** if contains: `..`, `/`, `\`, or any shell metacharacters (`$`, backtick, `|`, `;`, `&`, `>`, `<`)
+   - If invalid, return error immediately (do not attempt to sanitize)
+4. **Codex repo path** - Must exist and contain expected structure
+
+If any validation fails, return an error (see Error Handling below).
+
+## Process
+
+### 1. Read Source Document
+
+Read the file at the provided path. For PDFs, extract all text content. For markdown, read as-is.
+
+### 2. Extract Key Information
+
+From the content, identify:
+- **Title** - The document/feature name
+- **Main content** - The substantive information
+- **Codebase paths** (if tech-design) - Any code paths mentioned
+- **Source** - Default based on type:
+  - PRD/tech-design: `confluence`
+  - Topic/pattern: `exploration`
+  - Artifact: infer from content (`interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, `analysis`)
+- **Status** - Default based on type:
+  - PRD/tech-design: `draft` (new imports start as drafts)
+  - Topic/pattern/artifact: `active`
+
+### 3. Read and Apply Frontmatter Template
+
+**Read the template from the codex repo** - don't hardcode frontmatter structure:
+
+| Type | Template Path |
+|------|---------------|
+| `prd` | `{codex_repo}/templates/PRD.md` |
+| `tech-design` | `{codex_repo}/templates/TECH-DESIGN.md` |
+| `topic` | `{codex_repo}/templates/TOPIC.md` |
+| `pattern` | `{codex_repo}/templates/PATTERN.md` |
+| `artifact` | `{codex_repo}/templates/ARTIFACT.md` |
+
+1. Read the appropriate template file
+2. Extract its frontmatter structure
+3. Fill in the values:
+   - `title` → extracted title
+   - `created` / `explored` → today's date (YYYY-MM-DD)
+   - `updated` → today's date (YYYY-MM-DD)
+   - `status` → `draft` for PRD/tech-design, `active` for topic/pattern
+   - `codebase_paths` → extracted paths, or omit if none found
+   - Keep other fields from template as-is
+
+This ensures frontmatter stays in sync with the codex repo's templates.
+
+### 4. Structure Content
+
+Transform the source content into the codex format:
+- Preserve the original information and structure where sensible
+- Use markdown headings, lists, and tables appropriately
+- Remove any PDF artifacts or formatting noise
+- Keep the content substantive - don't pad with empty template sections
+
+### 5. Write Output
+
+Write the processed markdown to the correct location:
+
+| Type | Output Path |
+|------|-------------|
+| `prd` | `{codex_repo}/projects/{name}/PRD.md` |
+| `tech-design` | `{codex_repo}/projects/{name}/TECH-DESIGN.md` |
+| `topic` | `{codex_repo}/topics/{name}.md` |
+| `pattern` | `{codex_repo}/patterns/{name}.md` |
+| `artifact` | `{codex_repo}/projects/{name}/artifacts/{filename}.md` |
+
+For artifacts, derive `{filename}` from the artifact filename input or the source file's name (slugified).
+
+Create the directory if it doesn't exist.
+
+**If file already exists:** Return an error. Do not overwrite without explicit confirmation from the main conversation. The error response should indicate the file exists so the user can decide whether to proceed.
+
+### 6. Return Result
+
+Return a brief JSON summary:
+
+```json
+{
+  "status": "success",
+  "file_path": "/path/to/written/file.md",
+  "title": "Extracted document title",
+  "type": "prd",
+  "summary": "One sentence describing what was processed"
+}
+```
+
+## Important Notes
+
+- **Preserve substance over form** - The goal is to capture the document's information, not perfectly replicate its layout
+- **Don't invent content** - Only include information that exists in the source document
+- **Handle missing sections gracefully** - If the source doesn't have a section (e.g., no "Testing Strategy"), omit it rather than leaving empty placeholders
+- **Omit empty frontmatter fields** - If `codebase_paths` can't be determined, omit the field entirely rather than using placeholders
+- **Canadian spelling** - Use behaviour, colour, etc.
+
+## Error Handling
+
+If anything fails, return an error response instead of the success format:
+
+```json
+{
+  "status": "error",
+  "error_type": "validation_failed" | "file_not_found" | "extraction_failed" | "file_exists" | "write_failed",
+  "message": "Human-readable description of what went wrong"
+}
+```
+
+**Error types:**
+- `validation_failed` - Invalid document type, unsafe name, or missing codex repo
+- `file_not_found` - Source file doesn't exist or isn't readable
+- `extraction_failed` - Couldn't extract meaningful content from the document
+- `file_exists` - Target file already exists (user must confirm overwrite)
+- `write_failed` - Couldn't write to target location (permissions, disk space, etc.)

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

@@ -122,7 +122,8 @@ The codex has three categories:
 | `/codex search {query}` | Search across everything |
 | `/codex new {name}` | Scaffold new project from templates |
 | `/codex decision {text}` | Append to active project's DECISIONS.md |
-| `/codex snapshot {file} {name}` | Import PDF/markdown to project |
+| `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent) |
+| `/codex artifact {file} {project}` | Add supporting artifact to project (uses agent) |
 | `/codex add topic {name}` | Add explored topic with freshness metadata |
 
 ## Loading an Entry
@@ -153,6 +154,7 @@ All codex files have frontmatter:
 ---
 title: Feature Name
 type: prd | tech-design | context | decisions | pattern | topic
+status: draft | active | complete | archived
 created: 2026-01-07
 updated: 2026-01-07
 confidence: high | medium | low
@@ -162,6 +164,14 @@ codebase_paths:
 ---
 ```
 
+**Status values:**
+- `draft` - Initial capture, not ready for consumption
+- `active` - Current, being used for implementation
+- `complete` - Project shipped, kept for reference
+- `archived` - No longer relevant, kept for history
+
+Note: Topics use `draft | active | archived` (no "complete"). Patterns use `active | archived` (no draft phase).
+
 **When loading any file:**
 
 1. Parse frontmatter for `updated` date
@@ -222,6 +232,71 @@ Full procedure: `references/decisions.md`
 
 Full procedure: `references/topics.md`
 
+## Importing Documents
+
+**Trigger:** `/codex snapshot {type} {file} {name}` or user wants to add a file to the codex
+
+**IMPORTANT:** Always use the `codex-document-processor` agent to process documents. This keeps the main conversation context lean by offloading heavy document processing.
+
+**Procedure:**
+
+1. Determine the document type (required): `prd`, `tech-design`, `topic`, or `pattern`
+2. Spawn the `codex-document-processor` agent with:
+   - File path to the source document
+   - Document type
+   - Project/entry name
+   - Codex repo path from config
+3. Agent processes the document:
+   - Reads and extracts content
+   - Applies appropriate frontmatter template
+   - Writes to correct location in codex repo
+   - Returns file path and summary
+4. **Back in main conversation:** Handle git workflow
+   - Create branch: `codex/snapshot-{name}`
+   - Commit the new file
+   - Push and create PR via `gh pr create`
+5. Share PR link with user
+
+**Example invocations:**
+
+```bash
+# Explicit snapshot command
+/codex snapshot prd ~/Downloads/transaction-templates-prd.pdf transaction-templates
+
+# Natural language (still uses the agent)
+"Add this PRD to the transaction-templates project" + attach file
+"Import this tech design to generic-scenario-testing"
+```
+
+The agent handles: PDF reading, content extraction, frontmatter generation, file writing.
+The main conversation handles: git branch, commit, PR creation, user interaction.
+
+## Adding Artifacts
+
+**Trigger:** `/codex artifact {file} {project}` or user wants to add supporting material to a project
+
+Artifacts are supplementary documents that support a project but aren't core document types (PRD, TECH-DESIGN, DECISIONS). Examples:
+- Customer interviews / transcripts
+- Research notes
+- Meeting summaries
+- Spike findings
+- Competitor analysis
+
+**Procedure:**
+
+1. Use the `codex-document-processor` agent with type `artifact`
+2. Agent writes to `{codex_repo}/projects/{project}/artifacts/{filename}.md`
+3. Handle git workflow (branch, commit, PR)
+
+**Example invocations:**
+
+```bash
+/codex artifact ~/Downloads/customer-interview-acme.pdf transaction-templates
+/codex artifact ~/notes/spike-handlebars-perf.md partnership-automation
+```
+
+Artifacts get lighter frontmatter with `type: artifact` and source like `interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, or `analysis`.
+
 ## Creating New Projects
 
 **Trigger:** `/codex new {name}` or user wants to start new project entry

package/package.json

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

package/src/tools/codex/TOOL.yaml

@@ -9,7 +9,8 @@ includes:
       required: true
   commands:
     - codex
-  agents: []
+  agents:
+    - codex-document-processor
 
 dependencies: []
 

package/src/tools/codex/agents/codex-document-processor.md

@@ -0,0 +1,145 @@
+---
+name: codex-document-processor
+description: "Process documents (PDF, markdown) into codex-ready markdown with proper frontmatter. Use when importing files to the codex - handles extraction, formatting, and writing to the correct location."
+tools:
+  - Read
+  - Write
+  - Glob
+color: yellow
+---
+
+You are a document processor for the Orderful codex. Your job is to transform source documents (PDFs, markdown files) into properly structured codex entries.
+
+## Input
+
+You will receive:
+1. **File path** - The source document to process
+2. **Document type** - One of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`
+3. **Project/entry name** - Where this should be stored in the codex
+4. **Codex repo path** - The local path to orderful-codex repository
+5. **Artifact filename** (optional, for artifacts) - Name for the artifact file
+
+## Validation (Do This First)
+
+Before processing, validate all inputs:
+
+1. **Document type** - Must be one of: `prd`, `tech-design`, `topic`, `pattern`, `artifact`. Reject anything else.
+2. **File path** - Must exist and be readable. Use Read tool to verify.
+3. **Project/entry name** - Must be safe for filesystem paths:
+   - Only allow: alphanumeric, dashes, underscores
+   - **Reject** if contains: `..`, `/`, `\`, or any shell metacharacters (`$`, backtick, `|`, `;`, `&`, `>`, `<`)
+   - If invalid, return error immediately (do not attempt to sanitize)
+4. **Codex repo path** - Must exist and contain expected structure
+
+If any validation fails, return an error (see Error Handling below).
+
+## Process
+
+### 1. Read Source Document
+
+Read the file at the provided path. For PDFs, extract all text content. For markdown, read as-is.
+
+### 2. Extract Key Information
+
+From the content, identify:
+- **Title** - The document/feature name
+- **Main content** - The substantive information
+- **Codebase paths** (if tech-design) - Any code paths mentioned
+- **Source** - Default based on type:
+  - PRD/tech-design: `confluence`
+  - Topic/pattern: `exploration`
+  - Artifact: infer from content (`interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, `analysis`)
+- **Status** - Default based on type:
+  - PRD/tech-design: `draft` (new imports start as drafts)
+  - Topic/pattern/artifact: `active`
+
+### 3. Read and Apply Frontmatter Template
+
+**Read the template from the codex repo** - don't hardcode frontmatter structure:
+
+| Type | Template Path |
+|------|---------------|
+| `prd` | `{codex_repo}/templates/PRD.md` |
+| `tech-design` | `{codex_repo}/templates/TECH-DESIGN.md` |
+| `topic` | `{codex_repo}/templates/TOPIC.md` |
+| `pattern` | `{codex_repo}/templates/PATTERN.md` |
+| `artifact` | `{codex_repo}/templates/ARTIFACT.md` |
+
+1. Read the appropriate template file
+2. Extract its frontmatter structure
+3. Fill in the values:
+   - `title` → extracted title
+   - `created` / `explored` → today's date (YYYY-MM-DD)
+   - `updated` → today's date (YYYY-MM-DD)
+   - `status` → `draft` for PRD/tech-design, `active` for topic/pattern
+   - `codebase_paths` → extracted paths, or omit if none found
+   - Keep other fields from template as-is
+
+This ensures frontmatter stays in sync with the codex repo's templates.
+
+### 4. Structure Content
+
+Transform the source content into the codex format:
+- Preserve the original information and structure where sensible
+- Use markdown headings, lists, and tables appropriately
+- Remove any PDF artifacts or formatting noise
+- Keep the content substantive - don't pad with empty template sections
+
+### 5. Write Output
+
+Write the processed markdown to the correct location:
+
+| Type | Output Path |
+|------|-------------|
+| `prd` | `{codex_repo}/projects/{name}/PRD.md` |
+| `tech-design` | `{codex_repo}/projects/{name}/TECH-DESIGN.md` |
+| `topic` | `{codex_repo}/topics/{name}.md` |
+| `pattern` | `{codex_repo}/patterns/{name}.md` |
+| `artifact` | `{codex_repo}/projects/{name}/artifacts/{filename}.md` |
+
+For artifacts, derive `{filename}` from the artifact filename input or the source file's name (slugified).
+
+Create the directory if it doesn't exist.
+
+**If file already exists:** Return an error. Do not overwrite without explicit confirmation from the main conversation. The error response should indicate the file exists so the user can decide whether to proceed.
+
+### 6. Return Result
+
+Return a brief JSON summary:
+
+```json
+{
+  "status": "success",
+  "file_path": "/path/to/written/file.md",
+  "title": "Extracted document title",
+  "type": "prd",
+  "summary": "One sentence describing what was processed"
+}
+```
+
+## Important Notes
+
+- **Preserve substance over form** - The goal is to capture the document's information, not perfectly replicate its layout
+- **Don't invent content** - Only include information that exists in the source document
+- **Handle missing sections gracefully** - If the source doesn't have a section (e.g., no "Testing Strategy"), omit it rather than leaving empty placeholders
+- **Omit empty frontmatter fields** - If `codebase_paths` can't be determined, omit the field entirely rather than using placeholders
+- **Canadian spelling** - Use behaviour, colour, etc.
+
+## Error Handling
+
+If anything fails, return an error response instead of the success format:
+
+```json
+{
+  "status": "error",
+  "error_type": "validation_failed" | "file_not_found" | "extraction_failed" | "file_exists" | "write_failed",
+  "message": "Human-readable description of what went wrong"
+}
+```
+
+**Error types:**
+- `validation_failed` - Invalid document type, unsafe name, or missing codex repo
+- `file_not_found` - Source file doesn't exist or isn't readable
+- `extraction_failed` - Couldn't extract meaningful content from the document
+- `file_exists` - Target file already exists (user must confirm overwrite)
+- `write_failed` - Couldn't write to target location (permissions, disk space, etc.)

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

@@ -122,7 +122,8 @@ The codex has three categories:
 | `/codex search {query}` | Search across everything |
 | `/codex new {name}` | Scaffold new project from templates |
 | `/codex decision {text}` | Append to active project's DECISIONS.md |
-| `/codex snapshot {file} {name}` | Import PDF/markdown to project |
+| `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent) |
+| `/codex artifact {file} {project}` | Add supporting artifact to project (uses agent) |
 | `/codex add topic {name}` | Add explored topic with freshness metadata |
 
 ## Loading an Entry
@@ -153,6 +154,7 @@ All codex files have frontmatter:
 ---
 title: Feature Name
 type: prd | tech-design | context | decisions | pattern | topic
+status: draft | active | complete | archived
 created: 2026-01-07
 updated: 2026-01-07
 confidence: high | medium | low
@@ -162,6 +164,14 @@ codebase_paths:
 ---
 ```
 
+**Status values:**
+- `draft` - Initial capture, not ready for consumption
+- `active` - Current, being used for implementation
+- `complete` - Project shipped, kept for reference
+- `archived` - No longer relevant, kept for history
+
+Note: Topics use `draft | active | archived` (no "complete"). Patterns use `active | archived` (no draft phase).
+
 **When loading any file:**
 
 1. Parse frontmatter for `updated` date
@@ -222,6 +232,71 @@ Full procedure: `references/decisions.md`
 
 Full procedure: `references/topics.md`
 
+## Importing Documents
+
+**Trigger:** `/codex snapshot {type} {file} {name}` or user wants to add a file to the codex
+
+**IMPORTANT:** Always use the `codex-document-processor` agent to process documents. This keeps the main conversation context lean by offloading heavy document processing.
+
+**Procedure:**
+
+1. Determine the document type (required): `prd`, `tech-design`, `topic`, or `pattern`
+2. Spawn the `codex-document-processor` agent with:
+   - File path to the source document
+   - Document type
+   - Project/entry name
+   - Codex repo path from config
+3. Agent processes the document:
+   - Reads and extracts content
+   - Applies appropriate frontmatter template
+   - Writes to correct location in codex repo
+   - Returns file path and summary
+4. **Back in main conversation:** Handle git workflow
+   - Create branch: `codex/snapshot-{name}`
+   - Commit the new file
+   - Push and create PR via `gh pr create`
+5. Share PR link with user
+
+**Example invocations:**
+
+```bash
+# Explicit snapshot command
+/codex snapshot prd ~/Downloads/transaction-templates-prd.pdf transaction-templates
+
+# Natural language (still uses the agent)
+"Add this PRD to the transaction-templates project" + attach file
+"Import this tech design to generic-scenario-testing"
+```
+
+The agent handles: PDF reading, content extraction, frontmatter generation, file writing.
+The main conversation handles: git branch, commit, PR creation, user interaction.
+
+## Adding Artifacts
+
+**Trigger:** `/codex artifact {file} {project}` or user wants to add supporting material to a project
+
+Artifacts are supplementary documents that support a project but aren't core document types (PRD, TECH-DESIGN, DECISIONS). Examples:
+- Customer interviews / transcripts
+- Research notes
+- Meeting summaries
+- Spike findings
+- Competitor analysis
+
+**Procedure:**
+
+1. Use the `codex-document-processor` agent with type `artifact`
+2. Agent writes to `{codex_repo}/projects/{project}/artifacts/{filename}.md`
+3. Handle git workflow (branch, commit, PR)
+
+**Example invocations:**
+
+```bash
+/codex artifact ~/Downloads/customer-interview-acme.pdf transaction-templates
+/codex artifact ~/notes/spike-handlebars-perf.md partnership-automation
+```
+
+Artifacts get lighter frontmatter with `type: artifact` and source like `interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, or `analysis`.
+
 ## Creating New Projects
 
 **Trigger:** `/codex new {name}` or user wants to start new project entry