@orderful/droid 0.4.0 → 0.5.0

package/src/skills/project/SKILL.md

@@ -0,0 +1,93 @@
+---
+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.
+globs:
+  - "**/PROJECT.md"
+alwaysApply: false
+---
+
+# Project Skill
+
+Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`.
+
+## Why Projects?
+
+Chat history disappears. Projects persist.
+
+- **Context accumulates** - Each session starts with full project knowledge
+- **Decisions are captured** - No re-explaining why something was built a certain way
+- **Progress is tracked** - Semantic versioning + changelog show evolution
+
+## When NOT to Use
+
+- One-off tasks that don't need persistence
+- Simple questions or lookups
+- Tasks with sufficient context already in conversation
+- Quick fixes that don't warrant project tracking
+
+## Configuration
+
+Check `~/.droid/skills/project/overrides.yaml` for user settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `projects_dir` | `~/{ai_tool}/projects` | Where projects are stored (varies by AI tool) |
+| `preset` | `markdown` | Output format: `markdown` or `obsidian` |
+
+Default `projects_dir` by AI tool:
+- **claude-code**: `~/.claude/projects`
+- **opencode**: `~/.opencode/projects`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/project` | List and select a project |
+| `/project {keywords}` | Fuzzy-match and load |
+| `/project create {name}` | Create new project |
+| `/project update` | Update from conversation context |
+
+## Loading a Project
+
+**Trigger:** `/project {keywords}` or user asks to load/open a project
+
+**TLDR:** Fuzzy-match keywords against project folders, read PROJECT.md, summarize context.
+
+Full procedure: `references/loading.md`
+
+## Updating a Project
+
+**Trigger:** `/project update` or user asks to capture/save learnings
+
+**TLDR:** Analyze conversation for decisions/patterns/progress, propose changes, bump version, update changelog.
+
+Full procedure: `references/updating.md`
+Version rules: `references/versioning.md`
+Changelog format: `references/changelog.md`
+
+## Creating a Project
+
+**Trigger:** `/project create {name?}` or user asks to start a new project
+
+**TLDR:** Create folder in `projects_dir`, generate PROJECT.md + CHANGELOG.md from templates.
+
+Full procedure: `references/creating.md`
+Templates: `references/templates.md`
+
+## The Flywheel
+
+Projects work best in a cycle:
+
+1. **Load** - `/project {name}` gives Claude full context
+2. **Research/Plan** - Explore the problem, consider approaches
+3. **Document** - Capture decisions in PROJECT.md before implementing
+4. **Implement** - Build with full context of why decisions were made
+5. **Capture** - `/project update` saves new learnings
+6. **Repeat** - Next session starts with accumulated knowledge
+
+Each cycle starts further ahead than the last.

package/src/skills/project/SKILL.yaml

@@ -0,0 +1,35 @@
+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.0
+status: beta
+dependencies: []
+provides_output: false
+config_schema:
+  projects_dir:
+    type: string
+    description: Path to projects directory (default varies by AI tool)
+  preset:
+    type: string
+    description: Output format for templates
+    default: "markdown"
+    enum:
+      - markdown
+      - obsidian
+examples:
+  - title: "Load project by name"
+    code: |
+      /project transaction templates
+      # Fuzzy matches "transaction-templates" folder
+  - title: "Update after work session"
+    code: |
+      /project update
+      # Analyzes conversation, proposes PROJECT.md updates
+  - title: "Create new project"
+    code: |
+      /project create billing-refactor
+      # Creates folder with PROJECT.md and CHANGELOG.md

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

@@ -0,0 +1,26 @@
+# Project Commands
+
+Commands for managing project context files.
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/project` | Main command - load, update, or create projects |
+
+## How It Works
+
+The `/project` command handles multiple operations via subcommands:
+
+- `/project` or `/project {keywords}` - Load a project
+- `/project load {name}` - Explicit load
+- `/project update {name?}` - Update project from conversation
+- `/project create {name?}` - Create new project
+
+## Adding Commands
+
+If you want to add additional project-related commands (like `/project stats` or `/project archive`), create a new `.md` file in this directory. The command will be namespaced under the skill name.
+
+Example: `project-stats.md` -> `/project stats` (if following the hyphenated naming convention)
+
+See the skill's SKILL.md for the full behavior specification.

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

@@ -0,0 +1,39 @@
+---
+description: Manage project context files for persistent AI memory across sessions
+argument-hint: [name | update [name] | create [name]]
+allowed-tools: Read, Write, Edit, Glob, Bash(mkdir:*), Bash(ls:*)
+---
+
+# /project
+
+Entry point for project context management. See the **project skill** for full behavior.
+
+## Arguments
+
+$ARGUMENTS
+
+## Usage
+
+```
+/project                    # List and select a project
+/project {keywords}         # Fuzzy-match and load
+/project update             # Update from conversation context
+/project update {name}      # Update specific project
+/project create             # Create new project interactively
+/project create {name}      # Create with name
+```
+
+## Configuration
+
+From `~/.droid/skills/project/overrides.yaml`:
+- `projects_dir` - Where projects live (default varies by AI tool)
+- `preset` - Template format: `markdown` or `obsidian`
+
+## Behavior
+
+Refer to the project skill for:
+- **Loading**: How to fuzzy-match, handle multiple matches, summarize after load
+- **Updating**: What to extract from conversation, versioning rules, changelog format
+- **Creating**: Template structure by preset, required files
+
+The skill's `references/` folder contains detailed specs for versioning, changelog formatting, and templates.

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

@@ -0,0 +1,70 @@
+# Changelog Formatting
+
+Projects use a split file pattern to minimize context usage when loading.
+
+## File Structure
+
+- `CHANGELOG.md` (sibling to PROJECT.md) - Complete version history
+- `PROJECT.md` - Only 3 most recent entries + link to full history
+
+## On Update
+
+1. **Check for CHANGELOG.md** sibling
+   - If missing: Create it and migrate any existing entries from PROJECT.md
+
+2. **Add new entry to CHANGELOG.md** (prepend after header)
+
+3. **Update PROJECT.md changelog section**
+   - Keep only 3 most recent entries
+   - Ensure link to full history exists
+
+## CHANGELOG.md Format
+
+```markdown
+# Changelog
+
+All notable changes to the {Project Name} project.
+
+## X.Y.Z - YYYY-MM-DD
+- [Change description]
+- [Another change]
+
+## X.Y.Z - YYYY-MM-DD
+- [Previous changes]
+```
+
+## PROJECT.md Changelog Section Format
+
+**Markdown preset:**
+```markdown
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
+
+### X.Y.Z - YYYY-MM-DD
+- [Most recent]
+
+### X.Y.Z - YYYY-MM-DD
+- [Second most recent]
+
+### X.Y.Z - YYYY-MM-DD
+- [Third most recent]
+```
+
+**Obsidian preset:**
+```markdown
+## Changelog
+
+See [[CHANGELOG|full history]].
+
+### X.Y.Z - YYYY-MM-DD
+- [Most recent]
+```
+
+## Guidelines
+
+- Use present tense ("Add feature" not "Added feature")
+- Keep entries concise but descriptive
+- Group related changes in a single bullet when appropriate
+- Most recent version at the top
+- Use `##` headers in CHANGELOG.md, `###` in PROJECT.md

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

@@ -0,0 +1,58 @@
+# Creating a Project
+
+**Trigger:** `/project create {name?}` or user asks to start a new project
+
+## Procedure
+
+1. **Get project name**
+   - Use provided name, or ask if not provided
+   - Convert to kebab-case for folder name
+   - Convert to Title Case for display name
+
+2. **Create project folder**
+   - Path: `{projects_dir}/{kebab-case-name}/`
+   - Verify folder doesn't already exist
+
+3. **Create files from templates** (see `templates.md`)
+   - `PROJECT.md` - Main context file
+   - `CHANGELOG.md` - Version history
+   - Format varies by `preset` config (markdown vs obsidian)
+
+4. **Confirm creation**
+   - Show created folder path
+   - Offer to help fill in sections (Overview, Goals, Technical Details)
+
+## Naming Convention
+
+| Input | Folder Name | Display Name |
+|-------|-------------|--------------|
+| "billing refactor" | `billing-refactor` | "Billing Refactor" |
+| "API v2" | `api-v2` | "API V2" |
+| "my-feature" | `my-feature` | "My Feature" |
+
+## Example
+
+```
+User: /project create billing refactor
+
+Claude: Creating new project...
+
+Created: ~/.claude/projects/billing-refactor/
+├── PROJECT.md
+└── CHANGELOG.md
+
+Project "Billing Refactor" initialized at v0.1.0.
+
+Would you like help filling in the Overview, Goals, or Technical Details sections?
+```
+
+## Initial Structure
+
+New projects start minimal and grow organically. Common sections added over time:
+
+- **Current Work** - Active tasks and focus areas
+- **Decisions Log** - Key decisions with rationale
+- **Related** - Links to other docs, tickets, repos
+- **Roadmap** - Future phases
+
+See `templates.md` for the full initial template.

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

@@ -0,0 +1,40 @@
+# Loading a Project
+
+**Trigger:** `/project {keywords}` or user asks to load/open a project
+
+## Procedure
+
+1. **List projects** in configured `projects_dir`
+   - Each subfolder with a `PROJECT.md` is a project
+
+2. **If no name provided:**
+   - Use AskUserQuestion to present available projects
+   - Let user select which to load
+
+3. **If name/keywords provided:**
+   - Parse as space-separated keywords (e.g., "transaction templates" → `["transaction", "templates"]`)
+   - Find folders where name contains ALL keywords (case-insensitive, hyphens as word separators)
+
+4. **Based on matches:**
+   - **No matches**: List available projects, ask user to select
+   - **One match**: Read `{folder}/PROJECT.md`
+   - **Multiple matches**: Use AskUserQuestion to select from matches
+
+5. **After loading:**
+   - Confirm which project was loaded
+   - Summarize key context (2-3 sentences)
+   - Use project contents for all subsequent work in the session
+
+## Example
+
+```
+User: /project transaction templates
+
+Claude: Found project "transaction-templates". Loading...
+
+Loaded #project-transaction-templates (v1.16.1)
+
+This project covers Handlebars templates for EDI transaction generation.
+Key focus areas: template rendering service, permission controls, and
+the upcoming UI for template management.
+```

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

@@ -0,0 +1,124 @@
+# Project Templates
+
+Templates vary by `preset` setting.
+
+## Markdown Preset (default)
+
+### PROJECT.md
+
+```markdown
+---
+status: active
+---
+
+# Project: {Name}
+
+{Brief description}
+
+| | |
+|---|---|
+| **Version** | 0.1.0 |
+| **Started** | {today} |
+| **Status** | Active |
+
+## Overview
+
+{**What** this project does, **why** it exists}
+
+## Goals
+
+- {Goal 1}
+
+## Technical Details
+
+{Architecture, key files, patterns}
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
+
+### 0.1.0 - {today}
+- Initial project setup
+```
+
+### CHANGELOG.md
+
+```markdown
+# Changelog
+
+All notable changes to the {Name} project.
+
+## 0.1.0 - {today}
+- Initial project setup
+```
+
+---
+
+## Obsidian Preset
+
+### PROJECT.md
+
+```markdown
+---
+type: project
+status: active
+created: {today}
+updated: {today}
+---
+
+# Project: {Name}
+
+{Brief description}
+
+| | |
+|---|---|
+| **Version** | 0.1.0 |
+| **Started** | {today} |
+| **Status** | Active |
+
+## Overview
+
+{**What** this project does, **why** it exists}
+
+## Goals
+
+- {Goal 1}
+
+## Technical Details
+
+{Architecture, key files, patterns}
+
+## Related
+
+- {Links to related notes}
+
+## Changelog
+
+See [[CHANGELOG|full history]].
+
+### 0.1.0 - {today}
+- Initial project setup
+```
+
+### CHANGELOG.md
+
+Same as markdown preset.
+
+---
+
+## Template Variables
+
+| Variable | Expands To |
+|----------|------------|
+| `{today}` | YYYY-MM-DD |
+| `{Name}` | Project name (Title Case) |
+| `{name}` | Project name (lowercase) |
+| `{kebab-name}` | Folder name (kebab-case) |
+
+## Preset Differences Summary
+
+| Feature | Markdown | Obsidian |
+|---------|----------|----------|
+| Links | `[text](path)` | `[[path\|text]]` |
+| YAML properties | Minimal (`status`) | Rich (`type`, `created`, `updated`) |
+| Related section | Optional | Included |

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

@@ -0,0 +1,64 @@
+# Updating a Project
+
+**Trigger:** `/project update` or user asks to capture/save learnings
+
+## Procedure
+
+1. **Identify the project:**
+   - If name provided: Find matching project (same logic as loading)
+   - If no name: Check conversation for prior project load
+   - If still unclear: List projects and ask which to update
+
+2. **Analyze the conversation for:**
+   - New implementation details or patterns
+   - Key decisions and rationale
+   - Technical constraints discovered
+   - Progress on features
+   - Important file paths or code locations
+   - Bug fixes or gotchas encountered
+
+3. **If significant new information found:**
+   - Propose specific sections/content to add or update
+   - Show what will be changed
+   - Ask for confirmation before proceeding
+
+4. **If no obvious updates:**
+   - Ask what the user would like to update
+   - Suggest sections: metadata, implementation details, technical decisions, notes
+
+5. **After approval:**
+   - Read current project file
+   - Make approved updates, preserving existing structure
+   - Determine version bump (see `versioning.md`)
+   - Add changelog entry (see `changelog.md`)
+   - Confirm what was updated
+
+## What to Capture
+
+Good project updates include:
+
+| Type | Examples |
+|------|----------|
+| **Decisions** | "Chose cursor-based pagination over offset" |
+| **Patterns** | "Using repository pattern for data access" |
+| **Constraints** | "Must support backwards compatibility with v1 API" |
+| **Gotchas** | "Watch out for timezone handling in date fields" |
+| **Progress** | "Completed validation layer, starting on UI" |
+| **File locations** | "Key files: `src/services/template.service.ts`" |
+
+## Example
+
+```
+User: /project update
+
+Claude: I'll update #project-transaction-templates with learnings from this session.
+
+Proposed changes:
+- Add "Permission Controls" section documenting the new RBAC approach
+- Update Technical Details with the Handlebars helper patterns we established
+- Note the decision to use soft deletes
+
+This looks like a minor version bump (0.16.0 → 0.17.0).
+
+Proceed with these updates?
+```

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

@@ -0,0 +1,36 @@
+# Version Bumping Rules
+
+Use semantic versioning for project docs.
+
+## When to Bump
+
+| Type | When | Examples |
+|------|------|----------|
+| **Major** | Breaking changes, complete rewrites, fundamental architecture changes | New approach that invalidates previous docs |
+| **Minor** | New features, new sections, significant additions | New helper added, new endpoint, new workflow |
+| **Patch** | Clarifications, small updates, typo fixes, status changes | Wording tweaks, deferred features, bug notes |
+
+## Auto-Determination
+
+Analyze the changes being made:
+
+1. Default to **minor** for most content additions
+2. Use **patch** for small clarifications or status updates
+3. Use **major** only for fundamental changes (rare)
+4. Only ask user if genuinely ambiguous
+
+## Examples
+
+**Patch (0.1.0 -> 0.1.1):**
+- Fixed typo in technical details
+- Updated status from active to reference
+- Added note about known limitation
+
+**Minor (0.1.1 -> 0.2.0):**
+- Added new "Authentication" section
+- Documented new API endpoint
+- Added architecture diagram
+
+**Major (0.2.0 -> 1.0.0):**
+- Complete rewrite of implementation approach
+- Switched from REST to GraphQL (invalidates prior docs)