@orderful/droid 0.32.0 → 0.33.1

package/src/tools/plan/skills/plan/references/templates.md

@@ -0,0 +1,176 @@
+# Plan Doc Template
+
+## Full Template
+
+```markdown
+# Plan: {topic}
+
+**Status:** draft | in-progress | ready | done
+**Created:** {date}
+**Updated:** {date}
+**Project:** {from /project if active, else omit}
+**Ticket:** {if provided}
+
+---
+
+## Context
+
+{What we're planning and why. Loaded from /project, /codex, or user input.}
+
+---
+
+## Locked-In Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| | | |
+
+---
+
+## Tasks
+
+### Task 1: {name}
+
+**Files:** {paths to create/modify}
+
+**Context:**
+{Detailed context - patterns to follow, edge cases, dependencies}
+
+**Verify:** `{command to check success}`
+
+**Done:** {Human-readable success criteria}
+
+---
+
+### Task 2: {name}
+
+**Files:** ...
+
+---
+
+## Discussion Log
+
+### Open: {topic}
+> @droid - {user's question or comment}
+
+### Resolved: {topic} ({date})
+> @droid - {original question}
+> @{user} - {response}
+> **Resolved:** {one-line summary - also add to Locked-In table}
+```
+
+## Section Reference
+
+### Status
+
+| Value | Meaning |
+|-------|---------|
+| `draft` | Still exploring, gathering context |
+| `in-progress` | Actively iterating on tasks and decisions |
+| `ready` | All discussions resolved, ready to implement |
+| `done` | Implementation complete |
+
+### Context Section
+
+**Purpose:** Ground the plan in why this work matters and what's already known.
+
+**Good:**
+```markdown
+## Context
+
+We need to add rate limiting to the API to prevent abuse. Current state:
+- No rate limiting exists
+- We've seen 3 incidents of API abuse in the last month
+- Team decided on token bucket algorithm (see ADR-042)
+
+Related codex entries: [rate-limiting-patterns], [api-security-guidelines]
+```
+
+**Weak:**
+```markdown
+## Context
+
+Add rate limiting.
+```
+
+### Locked-In Decisions Table
+
+**Purpose:** Capture decisions that are no longer up for debate. These graduate from the Discussion Log when resolved.
+
+**Good:**
+```markdown
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Algorithm | Token bucket | Allows bursting, industry standard |
+| Storage | Redis | Already in stack, handles distributed state |
+| Limit | 100 req/min | Based on current usage patterns + 2x headroom |
+```
+
+### Task Semantic Sections
+
+Each task uses semantic markdown sections:
+
+| Section | Purpose | Example |
+|---------|---------|---------|
+| `**Files:**` | What to create/modify | `src/middleware/rateLimit.ts`, `src/config/limits.ts` |
+| `**Context:**` | How to do it | "Follow existing middleware pattern in `auth.ts`" |
+| `**Verify:**` | Command to check | `bun test src/middleware/rateLimit.test.ts` |
+| `**Done:**` | Success criteria | "Rate limit returns 429 after 100 requests" |
+
+**Good task:**
+```markdown
+### Task 1: Create rate limit middleware
+
+**Files:** `src/middleware/rateLimit.ts`, `src/middleware/rateLimit.test.ts`
+
+**Context:**
+Follow pattern from `src/middleware/auth.ts`. Use Redis client from `src/lib/redis.ts`.
+Token bucket with 100 tokens, refill 1/second. Return 429 with `Retry-After` header.
+
+**Verify:** `bun test src/middleware/rateLimit.test.ts`
+
+**Done:** Middleware exports `rateLimit()` function, tests pass including 429 case
+```
+
+**Weak task:**
+```markdown
+### Task 1: Add rate limiting
+
+**Files:** TBD
+
+**Context:** Add rate limiting to the API
+
+**Verify:** Test it
+
+**Done:** Works
+```
+
+### Discussion Log
+
+**Purpose:** Async back-and-forth between user and AI. Resolved discussions graduate to Locked-In Decisions.
+
+**Open discussion:**
+```markdown
+### Open: Redis vs in-memory storage
+> @droid - Should we use Redis or in-memory for rate limit counters? Redis adds complexity but works across instances.
+```
+
+**Resolved discussion:**
+```markdown
+### Resolved: Redis vs in-memory storage (2026-01-18)
+> @droid - Should we use Redis or in-memory for rate limit counters?
+> @{user} - Redis. We run 3 API instances, need shared state.
+> **Resolved:** Use Redis for distributed rate limit state.
+```
+
+## File Naming
+
+Plans are named `plan-{topic}.md` with kebab-case topic:
+
+- `plan-rate-limiting.md`
+- `plan-auth-refactor.md`
+- `plan-tdt-1953-templates.md` (ticket-based)
+
+## Location
+
+Plans live in `{brain_dir}/{inbox_dir}/plans/` or `{projects_dir}/{project}/plans/` if project-nested.

package/src/tools/plan/skills/plan/references/workflows.md

@@ -0,0 +1,299 @@
+# Workflow Reference
+
+Detailed command flows for the plan skill.
+
+## `/plan new {topic}`
+
+### Step 1: Read Configuration
+
+```bash
+droid config brain   # → brain_dir, inbox_dir
+droid config comments # → user_mention
+```
+
+If brain not configured, ask user for `brain_dir` location.
+
+### Step 2: Determine Location
+
+Check if `/project` is active (check `{projects_dir}/{project}/PROJECT.md` exists):
+
+**If project active:**
+```
+Offer choice via AskUserQuestion:
+- "Project folder" → {projects_dir}/{project}/plans/plan-{topic}.md
+- "Inbox" → {brain_dir}/{inbox_dir}/plans/plan-{topic}.md
+```
+
+**If no project:**
+```
+Use: {brain_dir}/{inbox_dir}/plans/plan-{topic}.md
+```
+
+### Step 3: Check for Existing Plan
+
+```bash
+# Check if plan already exists
+ls {determined_path}
+```
+
+If exists, ask:
+- "Open existing plan"
+- "Create new with different name"
+
+### Step 4: Offer Context Loading
+
+**If `/project` active:**
+```
+"Include project context in the plan?"
+- Yes → Read {projects_dir}/{project}/PROJECT.md, extract relevant sections
+- No → Skip
+```
+
+**Search `/codex` for relevant entries:**
+
+Use `/codex search {topic}` to find related entries.
+
+If matches found:
+```
+"Found codex entries related to '{topic}': [entry1], [entry2]. Include?"
+- Yes → Read and include summaries
+- No → Skip
+```
+
+### Step 5: Ask Clarifying Questions
+
+Use AskUserQuestion with these prompts:
+
+1. **Goal:** "What's the goal of this work?"
+2. **Scope:** "What's the scope?" (options: "This PR", "This ticket", "Small feature")
+3. **Constraints:** "Any constraints or decisions already made?"
+
+### Step 6: Generate Plan
+
+Create plan file from template (see `templates.md`) with:
+- Topic from command
+- Date from system
+- Project from active project (if any)
+- Context from gathered information
+
+### Step 7: Set Active
+
+Store active plan path for session (in-memory or temp file).
+
+---
+
+## `/plan search {topic}`
+
+### Step 1: Search for Plans
+
+```bash
+# Find all plan files
+find {brain_dir} -name "plan-*.md" -type f
+```
+
+### Step 2: Fuzzy Match
+
+Match topic against file names and content. Rank by:
+1. Exact name match (`plan-{topic}.md`)
+2. Partial name match (`plan-*{topic}*.md`)
+3. Content match (topic appears in file)
+
+### Step 3: Handle Multiple Matches
+
+If multiple matches, use AskUserQuestion:
+```
+"Found multiple plans matching '{topic}':"
+- plan-auth-refactor.md (ready)
+- plan-auth-migration.md (draft)
+- plan-oauth-integration.md (done)
+```
+
+### Step 4: Display Summary
+
+Read selected plan and show:
+```markdown
+**Plan:** {title}
+**Status:** {status}
+**Tasks:** {count} ({completed} done)
+**Open discussions:** {count}
+```
+
+### Step 5: Set Active
+
+Store as active plan for session.
+
+---
+
+## `/plan check`
+
+### Step 1: Load Active Plan
+
+If no active plan, prompt to search for one.
+
+### Step 2: Find Comments
+
+Search for `> @droid` lines (user comments addressed to AI):
+
+```bash
+grep -n "> @droid" {plan_path}
+```
+
+### Step 3: Address Each Comment
+
+For each comment:
+
+1. **Read context** - surrounding lines, section it's in
+2. **Respond** - add response below with `> @{user_mention}`
+3. **Ask resolution** - "Is this resolved?"
+
+### Step 4: Graduation Pattern
+
+When a discussion is resolved:
+
+1. Mark as resolved in Discussion Log:
+   ```markdown
+   ### Resolved: {topic} ({date})
+   > @droid - {original question}
+   > @{user} - {response}
+   > **Resolved:** {one-line summary}
+   ```
+
+2. Add to Locked-In Decisions table:
+   ```markdown
+   | {decision} | {choice} | {rationale from discussion} |
+   ```
+
+3. Move from "Open:" to "Resolved:" header
+
+### Step 5: Update Doc
+
+Write changes back to plan file.
+
+---
+
+## `/plan ready`
+
+### Step 1: Load Active Plan
+
+If no active plan, prompt to search for one.
+
+### Step 2: Check Unresolved Discussions
+
+Search for `### Open:` sections:
+
+```bash
+grep -c "### Open:" {plan_path}
+```
+
+If any found, warn:
+```
+"Found {n} unresolved discussions. Mark as ready anyway?"
+- "Resolve first" → List open discussions
+- "Mark ready anyway" → Continue
+```
+
+### Step 3: Validate Required Sections
+
+Check for:
+- `## Context` section with content
+- At least one `### Task` section
+
+If missing, warn and list what's needed.
+
+### Step 4: Update Status
+
+Change `**Status:** draft` or `**Status:** in-progress` to `**Status:** ready`
+
+### Step 5: Offer Distribution
+
+Ask via AskUserQuestion:
+```
+"Plan is ready. What next?"
+- "Keep in brain" → Done
+- "Copy to PR description" → Generate PR-friendly format with <details> wrapper
+- "Link in project file" → Add reference to {projects_dir}/{project}/PROJECT.md
+```
+
+---
+
+## `/plan implement`
+
+### Step 1: Load Plan
+
+If no active plan, prompt to search for one.
+
+Check status - warn if not `ready`:
+```
+"This plan is still '{status}'. Implement anyway?"
+```
+
+### Step 2: Parse Tasks
+
+Find all `### Task N:` sections. For each, extract:
+- **Name** from header
+- **Files** from `**Files:**` line
+- **Context** from `**Context:**` section
+- **Verify** from `**Verify:**` line
+- **Done** from `**Done:**` line
+
+### Step 3: Optional XML Conversion
+
+For complex multi-task plans, offer:
+```
+"Convert to XML for AI efficiency?"
+- "Yes" → Convert (see xml-conversion.md)
+- "No" → Use markdown as-is
+```
+
+### Step 4: Execute Tasks
+
+For each task in order:
+
+1. **Announce:** "Starting Task {n}: {name}"
+2. **Load context:** Read files mentioned in `**Files:**`
+3. **Execute:** Create/modify files per task description
+4. **Verify:** Run `**Verify:**` command
+5. **Check:** Validate against `**Done:**` criteria
+6. **Mark complete:** Update plan doc
+
+If verification fails:
+```
+"Task {n} verification failed: {output}. What next?"
+- "Fix and retry"
+- "Skip this task"
+- "Stop implementation"
+```
+
+### Step 5: Update Status
+
+When all tasks complete, change `**Status:** ready` to `**Status:** done`
+
+Add completion note:
+```markdown
+**Completed:** {date}
+```
+
+---
+
+## Discussion Graduation Flow
+
+The pattern for moving discussions to decisions:
+
+```
+1. User leaves comment:
+   > @droid - Should we use Redis or Postgres?
+
+2. AI responds:
+   > @{user} - Redis for this use case because {reasons}
+
+3. User confirms resolution (via /plan check):
+   > **Resolved:** Use Redis for rate limit state
+
+4. Entry added to Locked-In Decisions:
+   | Storage | Redis | Better for distributed counters |
+
+5. Discussion header changes:
+   ### Resolved: Storage choice (2026-01-18)
+```
+
+This creates an audit trail while keeping decisions accessible in the table.

package/src/tools/plan/skills/plan/references/xml-conversion.md

@@ -0,0 +1,123 @@
+# XML Conversion Reference
+
+How `/plan implement` converts semantic markdown to XML for AI efficiency.
+
+## Why XML?
+
+XML provides:
+- **Clear boundaries** - AI can parse task start/end unambiguously
+- **Structured extraction** - Files, verify commands, done criteria are explicit
+- **Reduced ambiguity** - No guessing where one section ends and another begins
+
+Use XML conversion for:
+- Complex plans with 5+ tasks
+- Plans with detailed context sections
+- Multi-file implementations where precision matters
+
+Skip XML conversion for:
+- Simple 2-3 task plans
+- Plans where you want to iterate interactively
+
+## Mapping
+
+| Markdown | XML |
+|----------|-----|
+| `### Task N: {name}` | `<task name="{name}">` |
+| `**Files:** {paths}` | `<files>{paths}</files>` |
+| `**Context:**` section | `<context>...</context>` |
+| `**Verify:** {cmd}` | `<verify>{cmd}</verify>` |
+| `**Done:** {criteria}` | `<done>{criteria}</done>` |
+
+## Example Conversion
+
+### Markdown Input
+
+```markdown
+### Task 1: Create rate limit middleware
+
+**Files:** `src/middleware/rateLimit.ts`, `src/middleware/rateLimit.test.ts`
+
+**Context:**
+Follow pattern from `src/middleware/auth.ts`. Use Redis client from `src/lib/redis.ts`.
+Token bucket with 100 tokens, refill 1/second. Return 429 with `Retry-After` header.
+
+**Verify:** `bun test src/middleware/rateLimit.test.ts`
+
+**Done:** Middleware exports `rateLimit()` function, tests pass including 429 case
+
+---
+
+### Task 2: Add middleware to API routes
+
+**Files:** `src/routes/api.ts`
+
+**Context:**
+Import rateLimit from middleware. Apply to all /api/* routes.
+Add before auth middleware in chain.
+
+**Verify:** `curl -I localhost:3000/api/health` (check for rate limit headers)
+
+**Done:** Rate limit headers present on API responses
+```
+
+### XML Output
+
+```xml
+<plan>
+  <task name="Create rate limit middleware">
+    <files>src/middleware/rateLimit.ts, src/middleware/rateLimit.test.ts</files>
+    <context>
+      Follow pattern from `src/middleware/auth.ts`. Use Redis client from `src/lib/redis.ts`.
+      Token bucket with 100 tokens, refill 1/second. Return 429 with `Retry-After` header.
+    </context>
+    <verify>bun test src/middleware/rateLimit.test.ts</verify>
+    <done>Middleware exports `rateLimit()` function, tests pass including 429 case</done>
+  </task>
+
+  <task name="Add middleware to API routes">
+    <files>src/routes/api.ts</files>
+    <context>
+      Import rateLimit from middleware. Apply to all /api/* routes.
+      Add before auth middleware in chain.
+    </context>
+    <verify>curl -I localhost:3000/api/health</verify>
+    <done>Rate limit headers present on API responses</done>
+  </task>
+</plan>
+```
+
+## Conversion Algorithm
+
+```
+1. Find all ### Task headers
+2. For each task:
+   a. Extract name from header (after "Task N: ")
+   b. Find **Files:** line, extract paths (strip backticks)
+   c. Find **Context:** section, capture until next ** or ---
+   d. Find **Verify:** line, extract command (strip backticks)
+   e. Find **Done:** line, extract criteria
+3. Wrap in <plan> root element
+4. Output XML
+```
+
+## When to Offer Conversion
+
+During `/plan implement`, check task count:
+
+```
+if (taskCount >= 5) {
+  // Offer XML conversion
+  "This plan has {n} tasks. Convert to XML for cleaner execution?"
+}
+```
+
+For smaller plans, skip the prompt and use markdown directly.
+
+## Preserving the Original
+
+XML conversion is for execution only. The original markdown plan stays unchanged in the brain - it's the source of truth for humans.
+
+The XML is:
+- Generated on-the-fly during `/plan implement`
+- Not persisted anywhere
+- Used only for the current implementation session

package/src/tools/project/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-project",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.",
   "author": {
     "name": "Orderful",

package/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.3.2
+version: 0.3.3
 status: beta
 
 includes:
@@ -17,7 +17,8 @@ dependencies: []
 config_schema:
   projects_dir:
     type: string
-    description: Path to projects directory (default varies by platform)
+    description: Path to projects directory (required - no default)
+    required: true
   preset:
     type: select
     description: Output format for templates

package/src/tools/project/skills/project/SKILL.md

@@ -26,20 +26,18 @@ Chat history disappears. Projects persist.
 
 ## Configuration
 
-**IMPORTANT:** Read `~/.droid/skills/project/overrides.yaml` first to determine the projects directory.
+**IMPORTANT:** Run `droid config project` first to get the merged configuration.
 
-- If `projects_dir` is configured → use **ONLY** that path (do NOT also search defaults)
-- If not configured → use the default for current AI tool
+| Setting        | Default      | Description                                        |
+| -------------- | ------------ | -------------------------------------------------- |
+| `projects_dir` | **required** | Where projects are stored (must be configured)     |
+| `preset`       | `markdown`   | Output format: `markdown` or `obsidian`            |
 
-| Setting        | Default     | Description                                       |
-| -------------- | ----------- | ------------------------------------------------- |
-| `projects_dir` | (see below) | Where projects are stored (use ONE location only) |
-| `preset`       | `markdown`  | Output format: `markdown` or `obsidian`           |
-
-Default `projects_dir` by AI tool (only if overrides.yaml is missing or lacks `projects_dir`):
-
-- **claude-code**: `~/.claude/projects`
-- **opencode**: `~/.config/opencode/projects`
+If `projects_dir` is not configured, inform the user they need to set it up:
+```bash
+mkdir -p ~/.droid/skills/project
+echo "projects_dir: /path/to/projects" >> ~/.droid/skills/project/overrides.yaml
+```
 
 ## Commands
 

package/src/tools/project/skills/project/references/creating.md

@@ -5,8 +5,8 @@
 ## Procedure
 
 1. **Read config first**
-   - Read `~/.droid/skills/project/overrides.yaml`
-   - Use `projects_dir` if configured, otherwise use default for current AI tool
+   - Run `droid config project` and parse the JSON output
+   - Use `projects_dir` (required - if not configured, inform user to set it up)
    - Use `preset` if configured (markdown or obsidian)
 
 2. **Get project name**
@@ -42,7 +42,7 @@ User: /project create billing refactor
 
 Claude: Creating new project...
 
-Created: ~/.claude/projects/billing-refactor/
+Created: {projects_dir}/billing-refactor/
 ├── PROJECT.md
 └── CHANGELOG.md
 
@@ -77,7 +77,7 @@ Bridge shared organizational knowledge (codex) to personal working memory (proje
    - If `{name} --from codex:{codex-name}` → use custom project name
 
 2. **Load codex entry**
-   - Read `~/.droid/skills/codex/overrides.yaml` for `codex_repo` path
+   - Run `droid config codex` and get `codex_repo` from the JSON output
    - Sync: `git -C {codex_repo} pull --rebase --quiet`
    - Locate `{codex_repo}/projects/{name}/`
    - If not found → error with suggestions from available projects
@@ -111,7 +111,7 @@ Bridge shared organizational knowledge (codex) to personal working memory (proje
    ```
    Created project "Transaction Templates" seeded from codex.
 
-   📁 ~/.claude/projects/transaction-templates/
+   📁 {projects_dir}/transaction-templates/
    ├── PROJECT.md (seeded with codex context)
    └── CHANGELOG.md