@orderful/droid 0.35.4 → 0.37.0

package/dist/tools/codex/skills/codex/references/creating.md

@@ -1,112 +0,0 @@
-# Creating New Projects
-
-Detailed procedure for scaffolding new project entries in the codex.
-
-## When to Use
-
-- Starting work on a new feature/project
-- `/codex new project {name}` command
-- User asks to create a codex entry for something new
-
-## Procedure
-
-### 1. Determine Project Name
-
-From user input:
-- Use kebab-case: `transaction-templates`, `audit-logging`
-- Should match how the team refers to the feature
-
-### 2. Check for Existing Entry
-
-```bash
-ls {codex_repo}/projects/ | grep -i {name}
-```
-
-If exists:
-```
-A project named '{name}' already exists. Did you mean to load it?
-→ /codex search {name}
-```
-
-### 3. Start Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-start-write --config - --branch codex/new-{name}
-```
-
-This runs the git preamble (ensures clean main + pulls latest) and creates the branch.
-
-### 4. Create Project Directory and Copy Templates
-
-```bash
-mkdir -p {codex_repo}/projects/{name}
-cp {codex_repo}/templates/PRD.md {codex_repo}/projects/{name}/
-cp {codex_repo}/templates/TECH-DESIGN.md {codex_repo}/projects/{name}/
-cp {codex_repo}/templates/DECISIONS.md {codex_repo}/projects/{name}/
-```
-
-### 5. Update Frontmatter
-
-In each file, update:
-- `title`: Project name (Title Case)
-- `created`: Today's date
-- `updated`: Today's date
-
-### 6. Optionally Pre-Fill Content
-
-If user provides context, fill in what we know:
-- PRD.md: Problem statement, goals if discussed
-- TECH-DESIGN.md: Any architectural decisions mentioned
-- DECISIONS.md: Leave as template (decisions come during impl)
-
-### 7. Finish Write Operation
-
-```bash
-droid config --get tools.codex | droid exec droid-codex git-finish-write --config - \
-  --message "feat(codex): scaffold {name} project" \
-  --pr-title "New project: {name}" \
-  --pr-body "Scaffold for {name} project"
-```
-
-This commits, pushes, creates PR, and returns to main.
-
-### 8. Confirm to User
-
-```
-✅ Created codex project: {name}
-
-📁 {codex_repo}/projects/{name}/
-├── PRD.md          (template - fill in requirements)
-├── TECH-DESIGN.md  (template - fill in technical design)
-└── DECISIONS.md    (ready for decisions during implementation)
-
-PR: {pr_url}
-(Auto-merges for new projects)
-
-Next steps:
-1. Fill in PRD.md with product requirements
-2. Fill in TECH-DESIGN.md with technical approach
-3. Use `/codex decision` to capture decisions as you implement
-```
-
-## Example
-
-**User:** `/codex new audit-logging`
-
-**Result:**
-
-```
-✅ Created codex project: audit-logging
-
-📁 ~/src/github.com/orderful-codex/projects/audit-logging/
-├── PRD.md          (template - fill in requirements)
-├── TECH-DESIGN.md  (template - fill in technical design)
-└── DECISIONS.md    (ready for decisions during implementation)
-
-Next steps:
-1. Fill in PRD.md with product requirements
-2. Fill in TECH-DESIGN.md with technical approach
-3. Use `/codex decision` to capture decisions as you implement
-
-Want me to help fill in any of these based on what we've discussed?
-```

package/dist/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/dist/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}
-```