@orderful/droid 0.9.0 → 0.10.1

package/src/skills/coach/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: coach
+description: "Learning-mode AI assistance - AI as coach, not crutch. Triggers on phrases like 'help me think through', 'coach me on', 'I want to learn how to', or 'don't just give me the answer'. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions on your code."
+alwaysApply: false
+---
+
+# Coach Skill
+
+Learning-mode AI assistance - **"AI as coach, not crutch"**.
+
+## Philosophy
+
+The workflow matters more than the tool. "AI implements, human reviews" risks hollowing out learning. "AI scaffolds, human implements, AI coaches" preserves growth.
+
+```
+plan → AI scaffolds → human implements → AI coaches → iterate → ship
+```
+
+**Why it works:**
+
+1. Human writes the actual logic (muscle memory)
+2. "Defend your decisions" is Socratic teaching
+3. Psychologically different: "I implemented this, Claude helped me improve it"
+4. Preserves learning-through-doing
+
+## When to Use
+
+- Learning a new codebase or domain
+- Building skills you want to retain
+- When you want to understand deeply, not just ship fast
+- Any engineer working in unfamiliar territory
+
+## When NOT to Use
+
+- Time-critical tasks where velocity matters most
+- Familiar territory you've mastered
+- Simple fixes that don't need the learning loop
+
+## Commands
+
+| Command            | Purpose                                                 |
+|--------------------|---------------------------------------------------------|
+| `/coach plan`      | Co-authored planning with Socratic questions            |
+| `/coach scaffold`  | Generate types/signatures/stubs with hints              |
+| `/coach review`    | Inline questions via comments skill                     |
+| `/coach check`     | Process comment responses (defers to `/comments check`) |
+| `/coach challenge` | Productive struggle on your own code                    |
+
+## Configuration
+
+| Setting              | Default  | Description                                             |
+|----------------------|----------|---------------------------------------------------------|
+| `scaffold_verbosity` | `medium` | How detailed hints are: `minimal`, `medium`, `detailed` |
+
+> @fry Not yet - droid currently shows config as free text input. But we could add an `enum` type to the config schema that presents as a select dropdown in the TUI. Good feature request - want me to create an issue for it?
+> @droid yes lets do that
+
+Read from `~/.droid/skills/coach/overrides.yaml` if present.
+
+---
+
+## /coach plan
+
+**Purpose:** Co-authored planning. AI proposes structure and asks clarifying questions. Human shapes the direction.
+
+**Behaviour:**
+
+- Ratio: ~40% proposing, ~60% questioning
+- Ask questions that probe requirements, edge cases, and design tradeoffs
+- Propose structure but let human refine
+- Offer to create a brain doc: "Would you like me to create a brain doc to capture this plan?"
+
+**Example questions:**
+
+- "What problem are we actually solving?"
+- "What happens if {edge case}?"
+- "How does this fit with {existing pattern in codebase}?"
+- "Is this the right scope for a single task?"
+
+**Do NOT:**
+
+- Write the full plan yourself
+- Skip to implementation
+- Answer your own questions
+
+---
+
+## /coach scaffold
+
+**Purpose:** Generate structure for the human to implement. Types, function signatures, stubs with hint comments.
+
+**Behaviour:**
+
+- Generate types and interfaces
+- Create function signatures with clear parameter and return types
+- Add hint comments that point at what to think about (not the answer)
+- Leave the actual logic for the human to write
+
+**Hint comment examples:**
+
+```typescript
+// HINT: Consider what happens if items is empty
+// TODO: Handle the edge case where user is not found
+// HINT: This might need to be async - think about what you're awaiting
+```
+
+**Verbosity levels:**
+
+- `minimal` - Signatures only, no hints
+- `medium` - Signatures with hint comments (default)
+- `detailed` - Signatures with pseudocode outline
+
+**Do NOT:**
+
+- Implement the actual logic
+- Give away the answer in hints
+- Write code that "just works" - leave thinking for the human
+
+---
+
+## /coach review
+
+**Purpose:** Review human's implementation with Socratic questions. Uses comments skill for inline feedback.
+
+**Requires:** `comments` skill installed
+
+**Behaviour:**
+
+- Read the implementation
+- Add inline `// @{user} {question}` comments using the comments skill pattern
+- Questions should probe reasoning, not just confirm choices
+- Focus on: design decisions, edge cases, potential issues, alternatives
+
+**Example inline comments:**
+
+```typescript
+// @fry Why did you choose a Map here instead of an object?
+// @fry What happens if this promise rejects?
+// @fry I notice you're mutating state directly - was that intentional?
+```
+> @droid is it worth mentioning using the correct comment syntax for the file language? We typically use TS but could be others
+
+**Key principle:** Vary questions based on specific code and context. Avoid formulaic patterns. Questions show the _spirit_, not a script.
+
+**Do NOT:**
+
+- Fix the code directly
+- Rewrite their implementation
+- Say "this is wrong, here's the fix" (no growth)
+- Use the same 4 questions every time
+
+---
+
+## /coach check
+
+**Purpose:** Process responses to coach review comments.
+
+**Behaviour:** Defers to `/comments check`. The comments skill handles the back-and-forth.
+
+---
+
+## /coach challenge
+
+**Purpose:** Productive struggle mode. Challenge slightly exceeds current skill level.
+
+**Scope:** Specific file or selection (bounded context)
+
+- `/coach challenge` - Current file or recent changes
+- `/coach challenge path/to/file.ts` - Specific file
+- `/coach challenge --staged` - Staged changes
+
+**Behaviour:**
+
+- Identify alternative approaches the human might not have considered
+- Use Socratic prompting to guide discovery
+- Ask questions like:
+  - "What if I told you there's a potential issue here? Can you find it?"
+  - "I can think of another way to implement this. What might it be?"
+  - "What happens under {edge condition}?"
+
+**Distinct from review:** Review asks about what you did. Challenge pushes you to find what you missed.
+
+**Do NOT:**
+
+- Just point out the issue
+- Give away the answer
+- Be patronizing - challenge is opt-in for those seeking growth
+
+---
+
+## Session Continuity
+
+Coach modes work well with brain docs for multi-session continuity:
+
+1. `/coach plan` suggests creating a brain doc
+2. Brain doc tracks current phase and context
+3. New session: `/brain {topic}` loads context, then `/coach scaffold` or `/coach review` continues
+
+The brain doc is the session artifact - no separate "save progress" needed.
+
+---
+
+## The Golden Rule
+
+**In coach mode, never write code unless explicitly asked.** Only:
+
+- Ask questions
+- Explain tradeoffs
+- Provide hints
+- Generate structure (scaffold only)
+
+The human does the thinking. AI provides guardrails and feedback.

package/src/skills/coach/SKILL.yaml

@@ -0,0 +1,25 @@
+name: coach
+description: "Learning-mode AI assistance - AI as coach, not crutch. Triggers on phrases like 'help me think through', 'coach me on', 'I want to learn how to', or 'don't just give me the answer'. Use /coach plan for co-authored planning, /coach scaffold for structure with hints, /coach review for Socratic questions on your code."
+version: 0.1.0
+status: beta
+dependencies:
+  - comments
+provides_output: false
+config_schema:
+  scaffold_verbosity:
+    type: string
+    description: "How detailed scaffold hints should be: minimal (signatures only), medium (hints), detailed (pseudocode)"
+    default: "medium"
+examples:
+  - title: "Start co-authored planning"
+    code: |
+      /coach plan add user authentication
+      # AI asks questions, proposes structure, offers to create brain doc
+  - title: "Get scaffold for implementation"
+    code: |
+      /coach scaffold
+      # AI generates types/signatures with hint comments, you fill in logic
+  - title: "Review your implementation"
+    code: |
+      /coach review src/auth/login.ts
+      # AI adds inline // @you questions via comments skill

package/src/skills/coach/commands/README.md

@@ -0,0 +1,9 @@
+# Coach Skill Commands
+
+Commands in this folder are installed to `~/.claude/commands/` (or equivalent for other AI tools).
+
+## /coach
+
+Main entry point for learning-mode AI assistance. See `coach.md` for details.
+
+Subcommands: `plan`, `scaffold`, `review`, `check`, `challenge`

package/src/skills/coach/commands/coach.md

@@ -0,0 +1,71 @@
+---
+description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix"
+argument-hint: "[plan {task} | scaffold [{path}] | review [{path}] | check | challenge [{path}]]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*)
+---
+
+# /coach
+
+Entry point for learning-mode AI assistance. See the **coach skill** for full behaviour.
+
+## Arguments
+
+$ARGUMENTS
+
+## Philosophy
+
+**"AI as coach, not crutch"** - preserves learning-through-doing while leveraging AI for guardrails and feedback.
+
+## Usage
+
+```
+/coach plan {task}          # Co-authored planning with Socratic questions
+/coach scaffold             # Generate types/signatures for current context
+/coach scaffold {path}      # Generate scaffold for specific file/feature
+/coach review               # Review recent changes with inline questions
+/coach review {path}        # Review specific file with inline questions
+/coach check                # Process comment responses (defers to /comments check)
+/coach challenge            # Productive struggle on current file
+/coach challenge {path}     # Challenge on specific file
+/coach challenge --staged   # Challenge on staged changes
+```
+
+## Mode Behaviour
+
+### plan
+
+- Co-author, don't dictate
+- ~30% proposing, ~70% questioning
+- Offer to create brain doc for persistence
+
+### scaffold
+
+- Types, signatures, stubs with hint comments
+- Points at what to think about, not the answer
+- Human fills in the actual logic
+
+### review
+
+- Uses comments skill for inline `// @{user}` questions
+- Socratic - probe reasoning, don't fix code
+- Vary questions based on context
+
+### check
+
+- Defers to `/comments check`
+
+### challenge
+
+- Productive struggle - find what you missed
+- Guide discovery, don't give answers
+- Opt-in for those seeking growth
+
+## Configuration
+
+Read `~/.droid/skills/coach/overrides.yaml` for:
+
+- `scaffold_verbosity` - `minimal` | `medium` | `detailed`
+
+## The Golden Rule
+
+**Never write code unless explicitly asked.** Only ask questions, explain tradeoffs, provide hints, or generate structure.

package/src/skills/project/SKILL.md

@@ -27,14 +27,17 @@ Chat history disappears. Projects persist.
 
 ## Configuration
 
-**IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/project/overrides.yaml` first. If `projects_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `projects_dir` setting.
+**IMPORTANT:** Read `~/.droid/skills/project/overrides.yaml` first to determine the projects directory.
+
+- 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` | (see below) | Where projects are stored |
+| `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 not configured):
+Default `projects_dir` by AI tool (only if overrides.yaml is missing or lacks `projects_dir`):
 - **claude-code**: `~/.claude/projects`
 - **opencode**: `~/.config/opencode/projects`
 

package/src/skills/project/SKILL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load project context before working (/project {name}), update with new learnings (/project update), or create new projects (/project create). Use when working on multi-session features, refactors, or any work that benefits from accumulated context."
-version: 0.1.1
+version: 0.1.2
 status: beta
 dependencies: []
 provides_output: false

package/src/skills/project/commands/project.md

@@ -29,9 +29,10 @@ $ARGUMENTS
 
 ## Configuration
 
-**ALWAYS read `~/.droid/skills/project/overrides.yaml` first.** Use configured values if present, only fall back to defaults if missing.
+**ALWAYS read `~/.droid/skills/project/overrides.yaml` first.**
 
-- `projects_dir` - Where projects live (default varies by AI tool)
+- If `projects_dir` is set → use **ONLY** that path (do NOT also search defaults)
+- If not configured → use the default for current AI tool
 - `preset` - Template format: `markdown` or `obsidian`
 
 ## Behavior

package/src/skills/project/references/loading.md

@@ -6,12 +6,14 @@
 
 ## Procedure
 
-1. **Read config first**
+1. **Determine projects directory (pick ONE)**
    - Read `~/.droid/skills/project/overrides.yaml`
-   - Use `projects_dir` if configured, otherwise use default for current AI tool
+   - If `projects_dir` is set → use ONLY that path, do NOT search defaults
+   - If not configured → use default for current AI tool (`~/.claude/projects` or `~/.config/opencode/projects`)
 
-2. **List projects** in configured `projects_dir`
+2. **List projects** in the single configured directory
    - Each subfolder with a `PROJECT.md` is a project
+   - Do NOT search multiple locations
 
 3. **If no name provided:**
    - Use AskUserQuestion to present available projects