@orderful/droid 0.6.0 → 0.7.0

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

@@ -0,0 +1,45 @@
+---
+description: Collaborative scratch pad for planning and research
+argument-hint: [plan|research|review|note|add|check|done] {topic/text}
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir:*), Bash(ls:*)
+---
+
+# /brain
+
+Entry point for brain doc management. See the **brain skill** for full behavior.
+
+## Arguments
+
+$ARGUMENTS
+
+## Usage
+
+```
+/brain                      # List recent docs or create new
+/brain {topic}              # Open existing (fuzzy match) → active
+/brain plan {topic}         # Create planning doc → active
+/brain research {topic}     # Create research doc → active
+/brain review {topic}       # Create review doc → active
+/brain note {text}          # Quick capture (fire-and-forget)
+/brain add {text}           # Append to active doc
+/brain check                # Address @droid comments in active doc
+/brain done                 # Finalize active doc
+```
+
+## Configuration
+
+From `~/.droid/skills/brain/overrides.yaml`:
+- `brain_dir` - Where docs live (default varies by AI tool)
+- `inbox_folder` - Subfolder for new docs (empty = flat)
+
+## 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
+- **Adding**: Append to active doc with timestamp
+- **Checking**: Find and address @droid comments
+- **Finalizing**: Update status, suggest next steps
+
+The skill's `references/` folder contains detailed specs for workflows, templates, naming, and metadata.

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

@@ -0,0 +1,59 @@
+# Brain Doc Metadata
+
+Inline metadata and status lifecycle for brain docs.
+
+## Format
+
+Status and type tracked inline at top of doc:
+
+```markdown
+# {Topic}
+
+**Type:** plan
+**Status:** exploring
+**Created:** 2025-01-15
+
+...
+```
+
+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) |
+
+## Status Lifecycle
+
+```
+exploring → drafting → decided → done
+    ↓          ↓          ↓
+  stale      stale      stale
+```
+
+### 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 |
+
+### Transitions
+
+- **exploring → drafting**: When you have enough info to start forming opinions
+- **drafting → decided**: When a clear decision/direction emerges
+- **decided → done**: When the work is complete
+- **any → stale**: When doc hasn't been touched in 30+ days without resolution
+
+## 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

@@ -0,0 +1,48 @@
+# Brain Doc Naming
+
+Conventions for naming brain docs.
+
+## Format
+
+```
+{type}-{topic-slug}.md
+```
+
+## Components
+
+| Component | Description | Examples |
+|-----------|-------------|----------|
+| `{type}` | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note` |
+| `{topic-slug}` | Lowercase, hyphen-separated topic | `auth-refactor`, `caching-strategies` |
+
+## Slug Rules
+
+1. **Lowercase** all words
+2. **Replace spaces** with hyphens
+3. **Remove special characters** (keep alphanumeric and hyphens only)
+4. **Limit length** to ~50 characters (truncate at word boundary)
+5. **No trailing hyphens**
+
+## 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` |
+
+## Notes
+
+For notes, include the date in the filename:
+```
+note-{YYYYMMDD}-{slug}.md
+```
+
+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

@@ -0,0 +1,102 @@
+# Brain Doc Templates
+
+Templates for each doc type. All templates use simple markdown.
+
+## Plan Template
+
+```markdown
+# {Topic}
+
+**Type:** plan
+**Status:** exploring
+**Created:** {date}
+
+Planning {brief description}.
+
+## Context
+
+What we're solving and why.
+
+## Exploration
+
+Options and approaches considered.
+
+## Decision
+
+What we chose and why.
+
+## Next Steps
+
+- [ ] Action items
+```
+
+## Research Template
+
+```markdown
+# {Topic}
+
+**Type:** research
+**Status:** exploring
+**Created:** {date}
+
+Researching {brief description}.
+
+## Questions
+
+What we're trying to understand.
+
+## Findings
+
+What we've learned.
+
+## Summary
+
+Key takeaways.
+```
+
+## Review Template
+
+```markdown
+# {Topic}
+
+**Type:** review
+**Status:** exploring
+**Created:** {date}
+
+Reviewing {brief description}.
+
+## Overview
+
+What's being reviewed and scope.
+
+## Observations
+
+Key findings and notes.
+
+## Recommendations
+
+Suggested changes or actions.
+
+## Verdict
+
+Overall assessment.
+```
+
+## Note Template
+
+```markdown
+# Note: {Brief Title}
+
+**Created:** {date}
+
+{content}
+```
+
+## Template Variables
+
+| 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) |

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

@@ -0,0 +1,188 @@
+# Brain Workflows
+
+Detailed procedures for each brain operation.
+
+## Opening
+
+**Trigger:** `/brain {topic}` or user asks to open a brain doc
+
+**Steps:**
+
+1. **Resolve brain_dir** from config (default: `~/.claude/brain` for claude-code)
+
+2. **Search for matches**
+   ```
+   Glob: {brain_dir}/**/*{topic}*.md
+   ```
+   Fuzzy match the topic against doc filenames
+
+3. **Handle results:**
+   - **No matches**: Offer to create a new doc with that topic
+   - **One match**: Open it
+   - **Multiple matches**: Present list, let user choose
+
+4. **Read the doc** and summarize key points:
+   - Current status
+   - Main topic/context
+   - Any open `@droid` comments
+   - Recent updates
+
+5. **Set as active doc** - Remember path for subsequent `/brain add` and `/brain check` commands
+
+## Creating
+
+**Trigger:** `/brain plan {topic}` or `/brain research {topic}`
+
+**Steps:**
+
+1. **Resolve brain_dir** and **inbox_folder** from config
+
+2. **Generate filename** using naming conventions (see `naming.md`):
+   - Format: `{type}-{topic-slug}.md`
+   - Example: `plan-auth-refactor.md` or `research-caching-strategies.md`
+
+3. **Determine target path:**
+   - If `inbox_folder` is set: `{brain_dir}/{inbox_folder}/{filename}`
+   - Otherwise: `{brain_dir}/{filename}`
+
+4. **Create directory** if needed
+
+5. **Apply template** based on preset and type (see `templates.md`)
+
+6. **Gather initial context** from conversation:
+   - What problem are we solving?
+   - Any constraints or requirements mentioned?
+   - Related work or prior decisions?
+
+7. **Write the doc** with template structure and initial context
+
+8. **Set as active doc**
+
+9. **Confirm creation** and summarize what was captured
+
+## Notes
+
+**Trigger:** `/brain note {text}`
+
+**Steps:**
+
+1. **Resolve brain_dir** and **inbox_folder** from config
+
+2. **Generate filename:**
+   - Format: `note-{date}-{slug}.md` where date is `YYYYMMDD`
+   - Slug from first few words of text
+   - Example: `note-20250115-remember-rate-limits.md`
+
+3. **Determine target path:**
+   - If `inbox_folder` is set: `{brain_dir}/{inbox_folder}/{filename}`
+   - Otherwise: `{brain_dir}/{filename}`
+
+4. **Create simple note:**
+   - Markdown preset: Just the text
+   - Obsidian preset: Add frontmatter with `type: note`, `created: {date}`
+
+5. **Write the file** - Do NOT set as active (fire-and-forget)
+
+6. **Confirm** briefly: "Captured note to {filename}"
+
+## Adding
+
+**Trigger:** `/brain add {text}`
+
+**Steps:**
+
+1. **Check for active doc**
+   - If no active doc: Ask user which doc to add to, or offer to create new
+
+2. **Read current content** of active doc
+
+3. **Append new section:**
+   ```markdown
+
+   ---
+
+   ## Update ({date})
+
+   {text}
+   ```
+
+4. **Update the `updated` date** in frontmatter (if using obsidian preset)
+
+5. **Write changes**
+
+6. **Confirm** what was added
+
+## Checking
+
+**Trigger:** `/brain check`
+
+**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+
+**Steps:**
+
+1. **Check for active doc**
+   - If no active doc: Ask user which doc to check, or list docs with comments
+
+2. **Read active doc**
+
+3. **Find all `> @droid` comments**
+   - Pattern: Lines starting with `> @droid` (blockquote with mention)
+
+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
+
+5. **Update the doc** with responses
+
+6. **Summarize** what was addressed
+
+## Finalizing
+
+**Trigger:** `/brain done`
+
+**Steps:**
+
+1. **Check for active doc**
+   - If no active doc: Ask which doc to finalize
+
+2. **Read active doc**
+
+3. **Review content:**
+   - Are there unresolved `@droid` comments?
+   - Is there a clear decision/outcome?
+   - Any loose ends?
+
+4. **Update status** to `done` in frontmatter (obsidian preset) or add "Status: Done" (markdown preset)
+
+5. **Suggest next steps:**
+   - Promote to project? (if substantial work)
+   - Archive? (if complete)
+   - Create follow-up tasks?
+
+6. **Clear active doc** from session
+
+## Listing
+
+**Trigger:** `/brain` (no arguments)
+
+**Steps:**
+
+1. **Resolve brain_dir** from config
+
+2. **Find recent docs:**
+   ```
+   Glob: {brain_dir}/**/*.md
+   ```
+   Sort by modification time, limit to 10-15
+
+3. **Present list** with:
+   - Filename
+   - Type (plan/research/note)
+   - Status (if available)
+   - Last modified
+
+4. **Offer options:**
+   - Select a doc to open
+   - Create new plan/research doc

package/src/skills/brain-obsidian/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: brain-obsidian
+description: >-
+  Obsidian extension for brain skill. Adds YAML frontmatter, wikilinks, and folder
+  organization. Requires brain skill. Install this to use brain docs with your
+  Obsidian vault.
+globs:
+  - "**/brain/**/*.md"
+alwaysApply: false
+---
+
+# Brain Obsidian Extension
+
+Extends the brain skill with Obsidian-specific features. **This skill overrides brain's default templates and workflows.**
+
+## Requirements
+
+- `brain` skill must be installed
+- Set `brain_dir` to your Obsidian vault path in brain skill overrides
+
+## Configuration
+
+**Required:** Set vault path in `~/.droid/skills/brain/overrides.yaml`:
+
+```yaml
+brain_dir: ~/path/to/your/vault
+```
+
+**Optional:** Configure folders in `~/.droid/skills/brain-obsidian/overrides.yaml`:
+
+| Setting            | Default       | Description                     |
+|--------------------|---------------|---------------------------------|
+| `inbox_folder`     | `0-Inbox`     | Where new docs are created      |
+| `archive_folder`   | `4-Archives`  | Where stale/done docs go        |
+| `para_structure`   | `false`       | Enable full PARA organization   |
+| `projects_folder`  | `1-Projects`  | Active project docs (PARA only) |
+| `areas_folder`     | `1-Areas`     | Area docs (PARA only)           |
+| `resources_folder` | `3-Resources` | Reference material (PARA only)  |
+
+## What This Adds
+
+| Feature             | Description                                |
+|---------------------|--------------------------------------------|
+| YAML frontmatter    | Type, status, dates, project links, tags   |
+| Wikilinks           | `[[note-name]]` syntax for linking         |
+| Folder organization | Inbox + Archive always; full PARA optional |
+| Project linking     | Associate brain docs with project files    |
+
+## Folder Organization
+
+**Always available:**
+- `inbox_folder` - New docs land here
+- `archive_folder` - Stale/completed docs
+
+**With `para_structure: true`:**
+```
+vault/
+├── {inbox_folder}/      # New docs (default: 0-Inbox)
+├── {projects_folder}/   # Active project docs (default: 1-Projects)
+├── {areas_folder}/      # Area docs (default: 2-Areas)
+├── {resources_folder}/  # Reference material (default: 3-Resources)
+└── {archive_folder}/    # Completed/stale (default: 4-Archives)
+```
+
+## Overridden Behavior
+
+When this skill is installed, **ALL brain operations use Obsidian format**:
+
+### Templates
+
+All docs get YAML frontmatter:
+
+```yaml
+---
+type: plan | research | review | note
+status: exploring | drafting | decided | done
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+project: "[[project-name]]"  # Optional
+tags: []                      # Optional
+---
+```
+
+See `references/templates.md` for full templates.
+
+### File Location
+
+Docs are created in your vault's inbox folder:
+- `{brain_dir}/{inbox_folder}/{filename}.md`
+
+### Finalizing
+
+When running `/brain done`:
+1. Updates status to `done` in frontmatter
+2. Suggests moving to archive (or projects/resources if PARA enabled)
+3. Confirms before moving
+
+## Commands
+
+Same commands as brain skill, but with Obsidian output:
+
+| Command                   | Obsidian Behavior                          |
+|---------------------------|--------------------------------------------|
+| `/brain plan {topic}`     | Creates in inbox with frontmatter          |
+| `/brain research {topic}` | Creates in inbox with frontmatter          |
+| `/brain review {topic}`   | Creates in inbox with frontmatter          |
+| `/brain note {text}`      | Quick capture to inbox                     |
+| `/brain done`             | Updates status, suggests archive/PARA move |

package/src/skills/brain-obsidian/SKILL.yaml

@@ -0,0 +1,45 @@
+name: brain-obsidian
+description: >-
+  Obsidian extension for brain skill. Adds YAML frontmatter, wikilinks, and folder
+  organization. Requires brain skill. Install this to use brain docs with your
+  Obsidian vault.
+version: 0.1.0
+status: beta
+dependencies:
+  - brain
+  # Optional: project skill enables linking features
+provides_output: false
+config_schema:
+  inbox_folder:
+    type: string
+    description: Folder for new brain docs
+    default: "0-Inbox"
+  archive_folder:
+    type: string
+    description: Folder for archived/stale docs
+    default: "4-Archives"
+  para_structure:
+    type: boolean
+    description: Enable full PARA folder organization
+    default: false
+  projects_folder:
+    type: string
+    description: Folder for active project docs (when para_structure is true)
+    default: "1-Projects"
+  areas_folder:
+    type: string
+    description: Folder for area docs (when para_structure is true)
+    default: "1-Areas"
+  resources_folder:
+    type: string
+    description: Folder for reference material (when para_structure is true)
+    default: "3-Resources"
+examples:
+  - title: "Create planning doc in vault"
+    code: |
+      /brain plan auth refactor
+      # Creates in vault's 0-Inbox/ with YAML frontmatter
+  - title: "Link to project"
+    code: |
+      /brain plan feature-x
+      # Frontmatter includes project: "[[feature-x]]"