@jmylchreest/aide-plugin 0.0.24 → 0.0.26

package/skills/design/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: design
+description: Technical design and architecture for implementation
+triggers:
+  - design this
+  - design the
+  - architect this
+  - architect the
+  - spec this
+  - spec the
+  - plan this
+  - plan the
+---
+
+# Design Mode
+
+**Recommended model tier:** smart (opus) - this skill requires complex reasoning
+
+Output a technical design specification that downstream SDLC stages can consume.
+
+## Purpose
+
+Create a structured design document that defines:
+1. **What** to build (interfaces, types, components)
+2. **How** it fits together (data flow, interactions)
+3. **Why** key decisions were made (rationale)
+4. **Success criteria** (acceptance criteria for TEST stage)
+
+## Workflow
+
+### Step 1: Understand the Request
+
+Read the request and identify:
+- Core functionality required
+- Constraints (tech stack, patterns, performance)
+- Integration points with existing code
+
+### Step 2: Explore the Codebase
+
+Use search tools to understand existing patterns:
+
+- Use `Grep` for similar patterns, interfaces, types
+- Use `Glob` for relevant files
+- Use `mcp__plugin_aide_aide__decision_list` to review all decisions
+- Use `mcp__plugin_aide_aide__decision_get` with the relevant topic to check specific decisions
+
+### Step 3: Define Interfaces
+
+Define the public API/interfaces first:
+
+```typescript
+// Example TypeScript interface
+interface UserService {
+  createUser(data: CreateUserInput): Promise<User>;
+  getUser(id: string): Promise<User | null>;
+  updateUser(id: string, data: UpdateUserInput): Promise<User>;
+}
+
+interface CreateUserInput {
+  email: string;
+  name: string;
+}
+```
+
+```go
+// Example Go interface
+type UserService interface {
+    CreateUser(ctx context.Context, input CreateUserInput) (*User, error)
+    GetUser(ctx context.Context, id string) (*User, error)
+    UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*User, error)
+}
+```
+
+### Step 4: Document Data Flow
+
+Describe how components interact:
+
+```
+Request → Controller → Service → Repository → Database
+                ↓
+           Validator
+                ↓
+          Error Handler → Response
+```
+
+### Step 5: Record Key Decisions
+
+Store architectural decisions for future reference:
+
+```bash
+aide decision set "<feature>-storage" "PostgreSQL with JSONB for metadata" \
+  --rationale="Need flexible schema for user preferences"
+
+aide decision set "<feature>-auth" "JWT with refresh tokens" \
+  --rationale="Stateless auth, mobile client support"
+```
+
+### Step 6: Define Acceptance Criteria
+
+List specific, testable criteria for the TEST stage:
+
+```markdown
+## Acceptance Criteria
+
+- [ ] User can be created with email and name
+- [ ] Duplicate emails are rejected with 409 status
+- [ ] Created user has UUID identifier
+- [ ] User can be retrieved by ID
+- [ ] Non-existent user returns null (not error)
+- [ ] User email can be updated
+- [ ] User name can be updated
+```
+
+## Required Output Format
+
+```markdown
+# Design: [Feature Name]
+
+## Overview
+[1-2 sentence summary of what this feature does]
+
+## Interfaces
+
+### [Interface/Type Name]
+\`\`\`typescript
+// Interface definition with comments
+\`\`\`
+
+## Data Flow
+[Diagram or description of component interactions]
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Storage | PostgreSQL | [why] |
+| Auth | JWT | [why] |
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Files to Create/Modify
+- `path/to/file.ts` - [purpose]
+- `path/to/test.ts` - [test scope]
+
+## Dependencies
+- [External packages needed]
+- [Internal modules to import]
+
+## Out of Scope
+- [Explicitly excluded items]
+```
+
+## Failure Handling
+
+### Unclear Requirements
+1. List specific ambiguities
+2. State assumptions you're making
+3. Record assumptions: `aide memory add --category=decision "Assumed X because Y"`
+4. Proceed with reasonable defaults
+
+### Conflicting Patterns Found
+1. Document the conflicting patterns
+2. Choose one and record the decision:
+   ```bash
+   aide decision set "<topic>" "<choice>" --rationale="<why this over alternatives>"
+   ```
+
+### Too Large / Too Vague
+1. Break into smaller, focused designs
+2. Design the core/MVP first
+3. Note future phases in "Out of Scope"
+
+## Verification Checklist
+
+Before completing design:
+- [ ] Interfaces are defined with types
+- [ ] Data flow is documented
+- [ ] Key decisions are recorded in aide
+- [ ] Acceptance criteria are testable
+- [ ] Files to modify are listed
+- [ ] Dependencies are identified
+
+## Completion
+
+When design is complete:
+1. Output the full design document
+2. Confirm: "Design complete. Ready for TEST stage."
+
+The design document feeds directly into the TEST stage, where acceptance criteria become test cases.

package/skills/docs/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: docs
+description: Update documentation to match implementation
+triggers:
+  - update docs
+  - update documentation
+  - document this
+  - docs stage
+  - documentation
+---
+
+# Documentation Mode
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Update documentation to accurately reflect the implemented code.
+
+## Purpose
+
+This is the DOCS stage of the SDLC pipeline. Implementation is complete and verified. Your job is to ensure documentation matches reality.
+
+## What to Document
+
+### 1. README Updates
+
+If the feature affects how users interact with the project:
+- Installation steps changed?
+- New commands or options?
+- New configuration?
+- New dependencies?
+
+### 2. API Documentation
+
+If public APIs were added or changed:
+- Function/method signatures
+- Parameters and return types
+- Usage examples
+- Error conditions
+
+### 3. Inline Documentation
+
+If code needs explanation:
+- Complex algorithms
+- Non-obvious design decisions
+- Integration points
+- Edge cases
+
+### 4. Architecture Docs
+
+If structure changed:
+- New components
+- Changed data flow
+- New dependencies between modules
+
+## Workflow
+
+### Step 1: Identify Changed Files
+
+```bash
+# See what was changed
+git diff --name-only HEAD~5  # or appropriate range
+
+# Find related docs
+Glob for **/*.md
+Glob for **/docs/**/*
+```
+
+### Step 2: Check Existing Documentation
+
+Read current docs that might be affected:
+
+```bash
+Read README.md
+Read docs/api.md  # if exists
+Read CHANGELOG.md  # if exists
+```
+
+### Step 3: Read the Implementation
+
+Understand what was built:
+
+- Read the new code files
+- Use `mcp__plugin_aide_aide__decision_get` with the feature topic to check design decisions
+- Use `mcp__plugin_aide_aide__decision_list` to see all decisions
+
+### Step 4: Update Documentation
+
+#### README.md Updates
+
+Add/update sections as needed:
+
+```markdown
+## New Feature
+
+Description of what it does.
+
+### Usage
+
+\`\`\`bash
+command --new-flag
+\`\`\`
+
+### Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| newOption | string | "default" | What it does |
+```
+
+#### API Documentation
+
+Document public interfaces:
+
+```markdown
+### functionName(param1, param2)
+
+Brief description.
+
+**Parameters:**
+- `param1` (string): What it is
+- `param2` (number, optional): What it does. Default: 10
+
+**Returns:** `Promise<Result>`
+
+**Example:**
+\`\`\`typescript
+const result = await functionName("input", 20);
+\`\`\`
+
+**Throws:**
+- `ValidationError`: When param1 is empty
+```
+
+#### Inline Comments
+
+Add comments for non-obvious code:
+
+```typescript
+// Use exponential backoff to handle rate limiting
+// Starts at 100ms, doubles each retry, max 5 retries
+async function fetchWithRetry(url: string): Promise<Response> {
+  // ...
+}
+```
+
+### Step 5: Verify Documentation
+
+```bash
+# If docs have a build step
+npm run docs:build
+
+# Check for broken links (if tool available)
+npm run docs:check
+
+# Manual review - read what you wrote
+```
+
+### Step 6: Commit Documentation
+
+```bash
+git add -A
+git commit -m "docs: document <feature>"
+```
+
+## Documentation Standards
+
+### Be Accurate
+- Documentation must match code exactly
+- If code changes, docs must change
+- Never document aspirational features
+
+### Be Concise
+- One sentence per concept
+- Use examples over explanations
+- Bullet points over paragraphs
+
+### Be Complete
+- Cover happy path AND error cases
+- Include all public API
+- Document breaking changes
+
+### Be Findable
+- Use clear headings
+- Add to table of contents
+- Cross-reference related sections
+
+## What NOT to Document
+
+- Internal implementation details (unless complex)
+- Obvious code (self-documenting)
+- Temporary workarounds (use TODO instead)
+- Aspirational features (only document what exists)
+
+## Output Format
+
+```markdown
+## Documentation Updates
+
+### Files Modified
+- `README.md` - Added new feature section
+- `docs/api.md` - Documented new endpoints
+- `src/service.ts` - Added inline comments for complex logic
+
+### Summary of Changes
+1. Added usage instructions for `--new-flag`
+2. Documented `createUser` API with examples
+3. Updated configuration table with new options
+
+### Verification
+- [ ] Docs build successfully
+- [ ] Examples are copy-pasteable and work
+- [ ] No broken internal links
+```
+
+## Failure Handling
+
+### No Documentation Exists
+
+If this is a new project without docs structure:
+1. Create minimal README.md
+2. Document the feature inline
+3. Note: "Recommend creating docs/ structure in future"
+
+### Documentation Tool Broken
+
+If docs build fails:
+1. Fix the build issue if simple
+2. Document what was attempted
+3. Note: "Docs build issue - needs separate fix"
+
+### Unclear What to Document
+
+1. Focus on public API only
+2. Document what a new user would need
+3. Skip internal details
+4. When in doubt, add an example
+
+## Verification Checklist
+
+Before completing:
+- [ ] All new public APIs are documented
+- [ ] README is updated if user-facing changes
+- [ ] Examples are tested and work
+- [ ] Docs build (if applicable)
+- [ ] Changes are committed
+
+## Completion
+
+When documentation is complete:
+
+```
+Documentation complete.
+- Updated: [list of files]
+- Added: [new sections/files]
+
+SDLC pipeline complete for this story.
+```
+
+## Integration with SDLC Pipeline
+
+```
+[DESIGN] → [TEST] → [DEV] → [VERIFY] → [DOCS]
+                                          ↑
+                                     YOU ARE HERE
+```
+
+- **Input**: Verified, working implementation
+- **Output**: Updated documentation
+- **Next**: Story complete, ready for merge

package/skills/git/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: git
+description: Git operations and worktree management
+triggers:
+  - worktree
+  - git worktree
+  - create branch
+  - manage branches
+---
+
+# Git Mode
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Expert git operations including worktree management for parallel work.
+
+## Commit Guidelines
+
+### Message Format
+```
+<type>: <short description>
+
+[optional body]
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
+
+### Commit Process
+1. Check status: `git status`
+2. Review diff: `git diff`
+3. Stage specific files (not `git add .`)
+4. Write descriptive message
+5. Never skip hooks unless explicitly asked
+
+## Worktree Management
+
+### Create Worktree
+```bash
+# For feature work
+git worktree add ../feature-branch -b feature/name
+
+# For parallel tasks
+git worktree add ../aide-worktrees/task-1 -b aide/task-1
+```
+
+### List Worktrees
+```bash
+git worktree list
+```
+
+### Remove Worktree
+```bash
+git worktree remove ../feature-branch
+git branch -d feature/name  # if merged
+```
+
+## Common Operations
+
+### Feature Branch Workflow
+```bash
+git checkout -b feature/name
+# ... work ...
+git add <specific-files>
+git commit -m "feat: add feature"
+git push -u origin feature/name
+```
+
+### Rebase onto Main
+```bash
+git fetch origin
+git rebase origin/main
+# resolve conflicts if any
+git push --force-with-lease
+```
+
+### Cherry-Pick
+```bash
+git cherry-pick <commit-hash>
+```
+
+### Stash
+```bash
+git stash push -m "description"
+git stash list
+git stash pop
+```
+
+## Safety Rules
+
+**Never run without explicit user request:**
+- `git push --force` (use `--force-with-lease` if needed)
+- `git reset --hard`
+- `git clean -f`
+- `git checkout .` or `git restore .`
+
+**Safe operations:**
+- `git status`, `git diff`, `git log`
+- `git add <specific-files>`
+- `git commit`
+- `git push` (without force)
+- `git worktree` operations
+
+## Failure Handling
+
+### Commit failures:
+
+1. **Pre-commit hook failure** - Read the error, fix the issue, create NEW commit (never amend after hook failure)
+2. **Merge conflict** - Report conflicts, do not auto-resolve without explicit request
+3. **Push rejected** - Fetch and rebase, report if conflicts arise
+
+### Worktree failures:
+
+1. **Branch already exists** - Use different name or checkout existing
+2. **Dirty working tree** - Stash or commit before worktree operations
+3. **Locked worktree** - Check `git worktree list` for stale entries, use `git worktree prune`
+
+### Recovery commands:
+
+```bash
+# Recover from bad merge (before commit)
+git merge --abort
+
+# Recover from bad rebase (before complete)
+git rebase --abort
+
+# Prune stale worktrees
+git worktree prune
+```
+
+## Verification Criteria
+
+### After commit:
+
+```bash
+# Verify commit was created
+git log -1 --oneline
+
+# Verify expected files changed
+git show --stat HEAD
+```
+
+### After push:
+
+```bash
+# Verify remote updated
+git log origin/<branch> -1 --oneline
+```
+
+### After worktree creation:
+
+```bash
+# Verify worktree exists
+git worktree list | grep <worktree-path>
+
+# Verify branch created
+git branch -a | grep <branch-name>
+```
+
+## Parallel Work Pattern
+
+For swarm mode or parallel features:
+
+```bash
+# Setup
+git worktree add ../work-1 -b feature/part-1
+git worktree add ../work-2 -b feature/part-2
+
+# Work in parallel (different terminals/agents)
+cd ../work-1 && # ... implement part 1
+cd ../work-2 && # ... implement part 2
+
+# Merge
+git checkout main
+git merge feature/part-1
+git merge feature/part-2
+
+# Cleanup
+git worktree remove ../work-1
+git worktree remove ../work-2
+git branch -d feature/part-1 feature/part-2
+```