@orderful/droid 0.10.1 → 0.10.3

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

@@ -8,14 +8,18 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Search for matches**
+
    ```
    Glob: {brain_dir}/**/*{topic}*.md
    ```
+
    Fuzzy match the topic against doc filenames
 
 3. **Handle results:**
@@ -37,10 +41,12 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - Also check for `inbox_folder` setting
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename** using naming conventions (see `naming.md`):
    - Format: `{type}-{topic-slug}.md`
@@ -59,11 +65,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`)
+   - **CRITICAL:** NEVER use `@droid` - that's for user-to-AI comments, not AI-to-user
 
-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
 
@@ -71,10 +82,12 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - Also check for `inbox_folder` setting
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename:**
    - Format: `note-{date}-{slug}.md` where date is `YYYYMMDD`
@@ -105,8 +118,8 @@ Detailed procedures for each brain operation.
 2. **Read current content** of active doc
 
 3. **Append new section:**
-   ```markdown
 
+   ```markdown
    ---
 
    ## Update ({date})
@@ -133,18 +146,25 @@ Detailed procedures for each brain operation.
 
 2. **Read active doc**
 
-3. **Find all `> @droid` comments**
+3. **Check preserve_comments setting:**
+   - Read `~/.droid/skills/comments/overrides.yaml` if it exists
+   - Look for `preserve_comments` (default: `true`)
+
+4. **Find all `> @droid` comments**
    - Pattern: Lines starting with `> @droid` (blockquote with mention)
 
-4. **For each comment:**
+5. **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.`
+   - **CRITICAL:** NEVER use `@droid` in your responses. Use `@{user_mention}` from config (e.g., `@fry`)
+   - **CRITICAL:** Always include the `>` prefix to maintain blockquote formatting
+   - **CRITICAL:** If `preserve_comments: true`, keep the original `@droid` comment and add your response below it. Do NOT remove the original comment.
 
-5. **Update the doc** with responses
+6. **Update the doc** with responses
 
-6. **Summarize** what was addressed
+7. **Summarize** what was addressed
 
 ## Finalizing
 
@@ -177,14 +197,18 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Find recent docs:**
+
    ```
    Glob: {brain_dir}/**/*.md
    ```
+
    Sort by modification time, limit to 10-15
 
 3. **Present list** with:

package/dist/skills/comments/SKILL.md

@@ -31,21 +31,23 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 **CRITICAL: The `@mention` is who you're talking TO, not who is speaking.**
 
 Think of it like addressing someone in conversation:
+
 - "Hey @droid, what do you think?" → User talking TO the AI
 - "Good point @fry, here's my take..." → AI talking TO the user
 
 | When you see... | Who wrote it | Who it's addressed to |
-|-----------------|--------------|----------------------|
-| `> @droid ...`  | User         | AI (droid)           |
-| `> @fry ...`    | AI           | User (fry)           |
+| --------------- | ------------ | --------------------- |
+| `> @droid ...`  | User         | AI (droid)            |
+| `> @fry ...`    | AI           | User (fry)            |
 
 **Examples:**
+
 ```markdown
-> @droid Can you explain this function?     ← User asking AI
+> @droid Can you explain this function? ← User asking AI
 > @fry This function calculates the hash... ← AI responding to user
 
-> @droid Should we refactor this?           ← User asking AI
-> @fry Yes, I'd suggest extracting...       ← AI responding to user
+> @droid Should we refactor this? ← User asking AI
+> @fry Yes, I'd suggest extracting... ← AI responding to user
 ```
 
 **Never flip this.** When responding to a `@droid` comment, always use `@{user}` (e.g., `@fry`) because you're addressing the user, not yourself.
@@ -76,13 +78,19 @@ When you find a `@droid` marker:
 ## Behavior
 
 ### On `/comments check`:
-1. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
-2. If there's a `git diff`, check those files first for relevant context
-3. For each comment, determine intent:
-   - **Action request** ("do X", "add Y", "fix Z") → Execute the action, remove the comment
-   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`, keep original comment
+
+1. **Read config first:** Check `~/.droid/skills/comments/overrides.yaml` for `preserve_comments` setting (default: `true`)
+2. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
+3. If there's a `git diff`, check those files first for relevant context
+4. For each comment, determine intent:
+   - **Action request** ("do X", "add Y", "fix Z") → Execute the action
+   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`
+5. **Handle original comment based on `preserve_comments`:**
+   - If `preserve_comments: true` → Keep the original `@droid` comment (add response below it)
+   - If `preserve_comments: false` → Remove the original comment after addressing
 
 ### On `/comments cleanup`:
+
 1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved
 2. Remove both markers
 3. Output a summary of what was discussed/decided
@@ -98,8 +106,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/dist/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: |

package/package.json

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

package/src/commands/install.ts

@@ -34,7 +34,11 @@ export async function installCommand(skillName: string): Promise<void> {
     // Check if skill has configurable options
     const manifest = loadSkillManifest(join(getBundledSkillsDir(), skillName));
     if (manifest?.config_schema && Object.keys(manifest.config_schema).length > 0) {
-      await promptForSkillConfig(skillName, manifest.config_schema, true);
+      // If any config option lacks a default, go straight to config (it's required)
+      const hasRequiredConfig = Object.values(manifest.config_schema).some(
+        (option) => option.default === undefined
+      );
+      await promptForSkillConfig(skillName, manifest.config_schema, !hasRequiredConfig);
     }
 
     // Show next steps

package/src/commands/setup.ts

@@ -240,11 +240,9 @@ export async function setupCommand(): Promise<void> {
       name: 'user_mention',
       message: 'What @mention should be used for you?',
       default: '@user',
-      validate: (input: string) => {
-        if (!input.startsWith('@')) {
-          return 'Mention should start with @';
-        }
-        return true;
+      filter: (input: string) => {
+        // Auto-add @ prefix if missing
+        return input.startsWith('@') ? input : `@${input}`;
       },
     },
     {

package/src/commands/skills.ts

@@ -127,7 +127,11 @@ export async function skillsCommand(): Promise<void> {
         // Prompt for config if skill has options
         const manifest = loadSkillManifest(join(getBundledSkillsDir(), skill.name));
         if (manifest?.config_schema && Object.keys(manifest.config_schema).length > 0) {
-          await promptForSkillConfig(skill.name, manifest.config_schema, true);
+          // If any config option lacks a default, go straight to config (it's required)
+          const hasRequiredConfig = Object.values(manifest.config_schema).some(
+            (option) => option.default === undefined
+          );
+          await promptForSkillConfig(skill.name, manifest.config_schema, !hasRequiredConfig);
         }
       } else {
         console.log(chalk.red(`\n✗ ${result.message}`));

package/src/commands/tui.tsx

@@ -23,7 +23,7 @@ import { getRandomQuote } from '../lib/quotes.js';
 
 type Tab = 'skills' | 'commands' | 'agents' | 'settings';
 type View = 'welcome' | 'setup' | 'menu' | 'detail' | 'configure' | 'readme';
-type SetupStep = 'ai_tool' | 'user_mention' | 'output_preference' | 'confirm';
+type SetupStep = 'ai_tool' | 'user_mention' | 'confirm';
 
 const colors = {
   primary: '#6366f1',
@@ -101,20 +101,28 @@ function getCommandsFromSkills(): Command[] {
   return commands;
 }
 
-function detectAITool(): AITool | null {
+function detectInstalledAITools(): Set<AITool> {
+  const installed = new Set<AITool>();
   try {
     execSync('claude --version', { stdio: 'ignore' });
-    return AITool.ClaudeCode;
+    installed.add(AITool.ClaudeCode);
   } catch {
     // Claude Code not found
   }
   try {
     execSync('opencode --version', { stdio: 'ignore' });
-    return AITool.OpenCode;
+    installed.add(AITool.OpenCode);
   } catch {
     // OpenCode not found
   }
-  return null;
+  return installed;
+}
+
+function getDefaultAITool(): AITool {
+  const installed = detectInstalledAITools();
+  if (installed.has(AITool.ClaudeCode)) return AITool.ClaudeCode;
+  if (installed.has(AITool.OpenCode)) return AITool.OpenCode;
+  return AITool.ClaudeCode;
 }
 
 function getOutputOptions(): Array<{ label: string; value: OutputPreference }> {
@@ -320,33 +328,29 @@ interface SetupScreenProps {
 function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
   const [step, setStep] = useState<SetupStep>('ai_tool');
   const [aiTool, setAITool] = useState<AITool>(
-    initialConfig?.ai_tool || detectAITool() || AITool.ClaudeCode
+    initialConfig?.ai_tool || getDefaultAITool()
   );
   const [userMention, setUserMention] = useState(initialConfig?.user_mention || '@user');
-  const [outputPreference, setOutputPreference] = useState<OutputPreference>(
-    initialConfig?.output_preference || BuiltInOutput.Terminal
-  );
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [error, setError] = useState<string | null>(null);
 
+  // Cache detection results once on mount (avoids re-running execSync on every render)
+  const installedTools = useMemo(() => detectInstalledAITools(), []);
   const aiToolOptions = useMemo(() => [
     { label: 'Claude Code', value: AITool.ClaudeCode },
     { label: 'OpenCode', value: AITool.OpenCode },
   ], []);
-  const outputOptions = useMemo(() => getOutputOptions(), []);
 
-  const steps: SetupStep[] = ['ai_tool', 'user_mention', 'output_preference', 'confirm'];
+  const steps: SetupStep[] = ['ai_tool', 'user_mention', 'confirm'];
   const stepIndex = steps.indexOf(step);
   const totalSteps = steps.length - 1; // Don't count confirm as a step
 
   const handleUserMentionSubmit = () => {
-    if (!userMention.startsWith('@')) {
-      setError('Mention should start with @');
-      return;
-    }
+    // Auto-add @ prefix if missing
+    const mention = userMention.startsWith('@') ? userMention : `@${userMention}`;
+    setUserMention(mention);
     setError(null);
-    setStep('output_preference');
-    setSelectedIndex(0);
+    setStep('confirm');
   };
 
   // Handle escape during text input (only intercept escape, nothing else)
@@ -362,11 +366,8 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     if (key.escape) {
       if (step === 'ai_tool') {
         onSkip();
-      } else if (step === 'output_preference') {
-        setStep('user_mention');
       } else if (step === 'confirm') {
-        setStep('output_preference');
-        setSelectedIndex(0);
+        setStep('user_mention');
       }
       return;
     }
@@ -378,20 +379,13 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
         setAITool(aiToolOptions[selectedIndex].value);
         setStep('user_mention');
       }
-    } else if (step === 'output_preference') {
-      if (key.upArrow) setSelectedIndex((prev) => Math.max(0, prev - 1));
-      if (key.downArrow) setSelectedIndex((prev) => Math.min(outputOptions.length - 1, prev + 1));
-      if (key.return) {
-        setOutputPreference(outputOptions[selectedIndex].value);
-        setStep('confirm');
-      }
     } else if (step === 'confirm') {
       if (key.return) {
         const config: DroidConfig = {
           ...loadConfig(),
           ai_tool: aiTool,
           user_mention: userMention,
-          output_preference: outputPreference,
+          output_preference: BuiltInOutput.Terminal, // Default to terminal
         };
         saveConfig(config);
         configureAIToolPermissions(aiTool);
@@ -424,7 +418,7 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
             <Text key={option.value}>
               <Text color={colors.textDim}>{index === selectedIndex ? '>' : ' '} </Text>
               <Text color={index === selectedIndex ? colors.text : colors.textMuted}>{option.label}</Text>
-              {option.value === detectAITool() && <Text color={colors.success}> (detected)</Text>}
+              {installedTools.has(option.value) && <Text color={colors.success}> (detected)</Text>}
             </Text>
           ))}
         </Box>
@@ -461,26 +455,6 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
     );
   }
 
-  if (step === 'output_preference') {
-    return (
-      <Box flexDirection="column" padding={1}>
-        {renderHeader()}
-        <Text color={colors.text}>Default output preference for skill results?</Text>
-        <Box flexDirection="column" marginTop={1}>
-          {outputOptions.map((option, index) => (
-            <Text key={option.value}>
-              <Text color={colors.textDim}>{index === selectedIndex ? '>' : ' '} </Text>
-              <Text color={index === selectedIndex ? colors.text : colors.textMuted}>{option.label}</Text>
-            </Text>
-          ))}
-        </Box>
-        <Box marginTop={1}>
-          <Text color={colors.textDim}>↑↓ select · enter next · esc back</Text>
-        </Box>
-      </Box>
-    );
-  }
-
   // Confirm step
   return (
     <Box flexDirection="column" padding={1}>
@@ -495,10 +469,6 @@ function SetupScreen({ onComplete, onSkip, initialConfig }: SetupScreenProps) {
           <Text color={colors.textDim}>Your @mention: </Text>
           <Text color={colors.text}>{userMention}</Text>
         </Text>
-        <Text>
-          <Text color={colors.textDim}>Output:        </Text>
-          <Text color={colors.text}>{outputOptions.find((o) => o.value === outputPreference)?.label || outputPreference}</Text>
-        </Text>
       </Box>
       <Box marginTop={2}>
         <Text backgroundColor={colors.primary} color="#ffffff" bold>
@@ -1032,12 +1002,6 @@ function SettingsDetails({
           <Text color={colors.textDim}>Your @mention: </Text>
           <Text color={colors.text}>{config.user_mention}</Text>
         </Text>
-        <Text>
-          <Text color={colors.textDim}>Output:        </Text>
-          <Text color={colors.text}>
-            {outputOptions.find((o) => o.value === config.output_preference)?.label || config.output_preference}
-          </Text>
-        </Text>
       </Box>
 
       <Box marginTop={1}>
@@ -1389,8 +1353,6 @@ function App() {
   useInput((input, key) => {
     if (message) setMessage(null);
 
-    if (view === 'welcome') return;
-
     if (input === 'q') {
       exit();
       return;
@@ -1528,8 +1490,18 @@ function App() {
               type: result.success ? 'success' : 'error',
             });
             if (result.success) {
-              setView('menu');
-              setSelectedAction(0);
+              // Check if skill has required config (options without defaults)
+              const configSchema = skill.config_schema || {};
+              const hasRequiredConfig = Object.values(configSchema).some(
+                (option) => (option as ConfigOption).default === undefined
+              );
+              if (hasRequiredConfig) {
+                // Go to configure view for required setup
+                setView('configure');
+              } else {
+                setView('menu');
+                setSelectedAction(0);
+              }
             }
           }
         }
@@ -1590,7 +1562,7 @@ function App() {
         }
       }
     }
-  });
+  }, { isActive: view !== 'welcome' && view !== 'setup' && view !== 'configure' });
 
   const selectedSkill = activeTab === 'skills' ? skills[selectedIndex] ?? null : null;
   const selectedCommand = activeTab === 'commands' ? commands[selectedIndex] ?? null : null;

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,44 @@ 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
+
+**CRITICAL:** When YOU (the AI) respond to a comment or create a placeholder, you MUST use `> @{user_mention}` (e.g., `> @fry`). NEVER use `@droid` for your own responses - that tag is for the USER to address YOU.
+
+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 +132,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 +149,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