@orderful/droid 0.10.0 → 0.10.2

package/src/skills/brain/SKILL.md

@@ -38,12 +38,13 @@ Ideas develop through iteration, not single prompts.
 
 **IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `brain_dir` setting.
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `brain_dir` | (see below) | Where docs are stored |
-| `inbox_folder` | (empty) | Optional subfolder for new docs (omit for flat structure) |
+| Setting        | Default     | Description                                               |
+| -------------- | ----------- | --------------------------------------------------------- |
+| `brain_dir`    | (see below) | Where docs are stored                                     |
+| `inbox_folder` | (empty)     | Optional subfolder for new docs (omit for flat structure) |
 
 Default `brain_dir` by AI tool (only if not configured):
+
 - **claude-code**: `~/.claude/brain`
 - **opencode**: `~/.config/opencode/brain`
 
@@ -52,28 +53,42 @@ Default `brain_dir` by AI tool (only if not configured):
 **Active doc:** Opening or creating a brain doc makes it "active" for the session. Subsequent `/brain add` commands append to it without specifying a path.
 
 **Doc types:**
+
 - `plan` - Structured: Context → Exploration → Decision → Next Steps
 - `research` - Open-ended exploration of a topic
 - `review` - Code review, document review, or any evaluation task
 - `note` - Quick capture (fire-and-forget, doesn't become active)
 
-**Comment conventions:** Use `@droid` / `@{user}` markers for async back-and-forth. If droid's `comments` skill is installed, use `/comments check` for full support.
+**Comment conventions:** In markdown files, ALWAYS use blockquote `>` prefix for @mention comments:
+
+- `> @droid` - User leaves comment for AI to address
+- `> @{user}` - AI leaves comment for user to address
+
+Example conversation:
+
+```markdown
+> @droid Should we add caching here?
+
+> @fry Yes, Redis would work well for this use case.
+```
+
+Read user's configured mention from `~/.droid/config.yaml` → `user_mention` (e.g., `@fry`). If droid's `comments` skill is installed, use `/comments check` for full support.
 
 **Status lifecycle:** `exploring` → `drafting` → `decided` → `done`
 
 ## Commands
 
-| Command | Action |
-|---------|--------|
-| `/brain` | List recent docs or create new |
-| `/brain {topic}` | **Search** for existing doc (fuzzy match) → becomes active |
-| `/brain plan {topic}` | Create planning doc (requires `plan` keyword) |
-| `/brain research {topic}` | Create research doc (requires `research` keyword) |
-| `/brain review {topic}` | Create review doc (requires `review` keyword) |
-| `/brain note {text}` | Quick capture (standalone, doesn't become active) |
-| `/brain add {text}` | Append to active doc |
-| `/brain check` | Address @droid comments in active doc |
-| `/brain done` | Finalize active doc, update status |
+| Command                   | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| `/brain`                  | List recent docs or create new                             |
+| `/brain {topic}`          | **Search** for existing doc (fuzzy match) → becomes active |
+| `/brain plan {topic}`     | Create planning doc (requires `plan` keyword)              |
+| `/brain research {topic}` | Create research doc (requires `research` keyword)          |
+| `/brain review {topic}`   | Create review doc (requires `review` keyword)              |
+| `/brain note {text}`      | Quick capture (standalone, doesn't become active)          |
+| `/brain add {text}`       | Append to active doc                                       |
+| `/brain check`            | Address @droid comments in active doc                      |
+| `/brain done`             | Finalize active doc, update status                         |
 
 **IMPORTANT:** The default action for `/brain {topic}` is to **SEARCH** for existing docs, NOT create. Only use `/brain plan {topic}` or `/brain research {topic}` when the user explicitly wants to create a new doc.
 
@@ -115,7 +130,7 @@ Full procedure: `references/workflows.md` § Adding
 
 **Trigger:** `/brain check`
 
-**TLDR:** Find `> @droid` comments in active doc, address each one.
+**TLDR:** Find `> @droid` comments in active doc, address each one with `> @{user_mention}` response (always use blockquote `>`).
 
 Full procedure: `references/workflows.md` § Checking
 
@@ -132,11 +147,18 @@ Full procedure: `references/workflows.md` § Finalizing
 Before creating or modifying brain docs, check if any `brain-*` extension skills are installed:
 
 ```
+# Claude Code
 ~/.claude/skills/brain-*/SKILL.md
+
+# OpenCode
+~/.config/opencode/skills/brain-*/SKILL.md
+
+# Shared (droid config)
 ~/.droid/skills/brain-*/SKILL.md
 ```
 
 If found (e.g., `brain-obsidian`), **ALWAYS** use the extension's templates, workflows, and configuration instead of this skill's defaults. Extensions may provide:
+
 - Alternative template formats (YAML frontmatter, wikilinks)
 - Folder organization (PARA structure)
 - Additional commands or integrations

package/src/skills/brain/commands/brain.md

@@ -42,6 +42,7 @@ $ARGUMENTS
 ## Behavior
 
 Refer to the brain skill for:
+
 - **Opening**: How to fuzzy-match, handle multiple matches, set active
 - **Creating**: Template structure by preset, naming conventions
 - **Notes**: Quick capture workflow

package/src/skills/brain/commands/scratchpad.md

@@ -42,6 +42,7 @@ $ARGUMENTS
 ## Behavior
 
 Refer to the brain skill for:
+
 - **Opening**: How to fuzzy-match, handle multiple matches, set active
 - **Creating**: Template structure by preset, naming conventions
 - **Notes**: Quick capture workflow

package/src/skills/brain/references/metadata.md

@@ -20,12 +20,12 @@ Simple and portable. Works anywhere markdown is supported.
 
 ## Fields
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `Type` | Yes | Doc type: `plan`, `research`, `review`, or `note` |
-| `Status` | Yes (except notes) | Current lifecycle stage |
-| `Created` | Yes | Creation date |
-| `Updated` | No | Last modification date (add when doc changes) |
+| Field     | Required           | Description                                       |
+| --------- | ------------------ | ------------------------------------------------- |
+| `Type`    | Yes                | Doc type: `plan`, `research`, `review`, or `note` |
+| `Status`  | Yes (except notes) | Current lifecycle stage                           |
+| `Created` | Yes                | Creation date                                     |
+| `Updated` | No                 | Last modification date (add when doc changes)     |
 
 ## Status Lifecycle
 
@@ -37,13 +37,13 @@ exploring → drafting → decided → done
 
 ### Status Definitions
 
-| Status | Meaning | Typical Actions |
-|--------|---------|-----------------|
-| `exploring` | Initial discovery, gathering information | Research, ask questions, explore options |
-| `drafting` | Forming opinions, narrowing options | Document trade-offs, propose approaches |
-| `decided` | Decision made, ready to act | Document decision rationale, plan implementation |
-| `done` | Work complete, doc is reference material | Archive or link from project |
-| `stale` | Abandoned or outdated | Review for archival or deletion |
+| Status      | Meaning                                  | Typical Actions                                  |
+| ----------- | ---------------------------------------- | ------------------------------------------------ |
+| `exploring` | Initial discovery, gathering information | Research, ask questions, explore options         |
+| `drafting`  | Forming opinions, narrowing options      | Document trade-offs, propose approaches          |
+| `decided`   | Decision made, ready to act              | Document decision rationale, plan implementation |
+| `done`      | Work complete, doc is reference material | Archive or link from project                     |
+| `stale`     | Abandoned or outdated                    | Review for archival or deletion                  |
 
 ### Transitions
 
@@ -55,5 +55,6 @@ exploring → drafting → decided → done
 ## Updating Metadata
 
 When modifying a doc:
+
 1. Add or update the `Updated` field to current date
 2. Update `Status` if the work has progressed

package/src/skills/brain/references/naming.md

@@ -10,10 +10,10 @@ Conventions for naming brain docs.
 
 ## Components
 
-| Component | Description | Examples |
-|-----------|-------------|----------|
-| `{type}` | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note` |
-| `{topic-slug}` | Lowercase, hyphen-separated topic | `auth-refactor`, `caching-strategies` |
+| Component      | Description                          | Examples                              |
+| -------------- | ------------------------------------ | ------------------------------------- |
+| `{type}`       | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note`            |
+| `{topic-slug}` | Lowercase, hyphen-separated topic    | `auth-refactor`, `caching-strategies` |
 
 ## Slug Rules
 
@@ -25,16 +25,17 @@ Conventions for naming brain docs.
 
 ## Examples
 
-| Input | Filename |
-|-------|----------|
-| `/brain plan Auth Refactor` | `plan-auth-refactor.md` |
-| `/brain research Caching Strategies` | `research-caching-strategies.md` |
-| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md` |
-| `/brain note Remember to check rate limits` | `note-20250115-remember-to-check-rate.md` |
+| Input                                        | Filename                                  |
+| -------------------------------------------- | ----------------------------------------- |
+| `/brain plan Auth Refactor`                  | `plan-auth-refactor.md`                   |
+| `/brain research Caching Strategies`         | `research-caching-strategies.md`          |
+| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md`  |
+| `/brain note Remember to check rate limits`  | `note-20250115-remember-to-check-rate.md` |
 
 ## Notes
 
 For notes, include the date in the filename:
+
 ```
 note-{YYYYMMDD}-{slug}.md
 ```
@@ -44,5 +45,6 @@ This prevents collisions and allows chronological sorting.
 ## Uniqueness
 
 If a file with the generated name already exists:
+
 1. Check if user wants to open existing doc
 2. Or append a numeric suffix: `plan-auth-refactor-2.md`

package/src/skills/brain/references/templates.md

@@ -94,9 +94,9 @@ Overall assessment.
 
 ## Template Variables
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `{Topic}` | Doc title from user input | "Auth Refactor" |
-| `{date}` | Current date (YYYY-MM-DD) | "2025-01-15" |
+| Variable              | Description               | Example                                 |
+| --------------------- | ------------------------- | --------------------------------------- |
+| `{Topic}`             | Doc title from user input | "Auth Refactor"                         |
+| `{date}`              | Current date (YYYY-MM-DD) | "2025-01-15"                            |
 | `{brief description}` | Context from conversation | "refactoring the authentication system" |
-| `{content}` | User-provided text | (for notes) |
+| `{content}`           | User-provided text        | (for notes)                             |

package/src/skills/brain/references/workflows.md

@@ -13,9 +13,11 @@ Detailed procedures for each brain operation.
    - Use `brain_dir` if configured, otherwise use default for current AI tool
 
 2. **Search for matches**
+
    ```
    Glob: {brain_dir}/**/*{topic}*.md
    ```
+
    Fuzzy match the topic against doc filenames
 
 3. **Handle results:**
@@ -59,11 +61,16 @@ Detailed procedures for each brain operation.
    - Any constraints or requirements mentioned?
    - Related work or prior decisions?
 
-7. **Write the doc** with template structure and initial context
+7. **Add placeholder comments** for sections needing user input:
+   - Read user's mention from `~/.droid/config.yaml` → `user_mention`
+   - Use `> @{user_mention}` for placeholders (e.g., `> @fry - Please provide requirements`)
+   - Do NOT use `> @droid` - that's for user-to-AI comments
 
-8. **Set as active doc**
+8. **Write the doc** with template structure and initial context
 
-9. **Confirm creation** and summarize what was captured
+9. **Set as active doc**
+
+10. **Confirm creation** and summarize what was captured
 
 ## Notes
 
@@ -105,8 +112,8 @@ Detailed procedures for each brain operation.
 2. **Read current content** of active doc
 
 3. **Append new section:**
-   ```markdown
 
+   ```markdown
    ---
 
    ## Update ({date})
@@ -139,8 +146,9 @@ Detailed procedures for each brain operation.
 4. **For each comment:**
    - Show the comment and surrounding context
    - Address the question/request
-   - Add response as `> @{user_mention}` reply
-   - Or resolve inline if it was a simple note
+   - Add response as blockquote with user's mention: `> @{user_mention} Your response here`
+   - Example: `> @fry Yes, the index covers that query pattern.`
+   - IMPORTANT: Always include the `>` prefix to maintain blockquote formatting
 
 5. **Update the doc** with responses
 
@@ -182,9 +190,11 @@ Detailed procedures for each brain operation.
    - Use `brain_dir` if configured, otherwise use default for current AI tool
 
 2. **Find recent docs:**
+
    ```
    Glob: {brain_dir}/**/*.md
    ```
+
    Sort by modification time, limit to 10-15
 
 3. **Present list** with:

package/src/skills/comments/SKILL.md

@@ -98,8 +98,8 @@ user_mention: "@fry"
 # Additional AI mentions to recognize (e.g., if you're used to @claude)
 ai_mentions: "@claude"
 
-# Keep comments after addressing them (default: false)
-preserve_comments: false
+# Keep comments after addressing them (default: true)
+preserve_comments: true
 ```
 
 ## File Type Support

package/src/skills/comments/SKILL.yaml

@@ -15,7 +15,7 @@ config_schema:
   preserve_comments:
     type: boolean
     description: Keep original comments after addressing (vs removing them)
-    default: false
+    default: true
 examples:
   - title: "Action request"
     code: |