@martinffx/atelier 0.1.0

package/skills/code-docs/references/api-docs.md

@@ -0,0 +1,116 @@
+# API Documentation Tools
+
+## TypeScript/JavaScript
+
+### TypeDoc
+
+```bash
+npm install --save-dev typedoc
+
+# Generate
+npx typedoc --out docs src/index.ts
+
+# Options
+--entryPoints src/
+--out docs/
+--name "My Project"
+--theme default
+```
+
+### JSDoc
+
+```bash
+npm install --save-dev jsdoc
+
+# Generate
+npx jsdoc src/ -d docs/
+
+# Config (jsdoc.json)
+{
+  "source": {
+    "includePattern": ".+\\.js(doc)?$"
+  },
+  "opts": {
+    "destination": "./docs/"
+  }
+}
+```
+
+---
+
+## Python
+
+### Sphinx
+
+```bash
+pip install sphinx
+
+# Initialize
+sphinx-quickstart
+
+# Build
+make html
+```
+
+### pdoc
+
+```bash
+pip install pdoc
+
+# Generate
+pdoc --output-dir docs src/
+pdoc --logo logo.png src/  # With logo
+```
+
+---
+
+## Go
+
+### godoc
+
+```bash
+# Install
+go install golang.org/x/tools/cmd/godoc@latest
+
+# Run locally
+godoc -http=:6060
+```
+
+### swag (OpenAPI)
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@latest
+
+# Generate from annotations
+swag init -g cmd/server/main.go
+```
+
+---
+
+## OpenAPI/Swagger
+
+### tools
+
+- swagger-cli validate
+- @apidevtools/swagger-cli
+- redoc CLI
+
+### Annotations Example
+
+```javascript
+/**
+ * @openapi
+ * /users:
+ *   get:
+ *     summary: List users
+ *     responses:
+ *       200:
+ *         description: User list
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/User'
+ */
+```

package/skills/code-docs/references/changelog.md

@@ -0,0 +1,64 @@
+# Changelog Format
+
+## Keep a Changelog
+
+Follow: https://keepachangelog.com
+
+## Format
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New feature
+
+### Changed
+- Changed behavior
+
+### Deprecated
+- Soon-to-be removed feature
+
+### Removed
+- Now removed feature
+
+### Fixed
+- Bug fix
+
+### Security
+- Security improvement
+```
+
+## Version Template
+
+```markdown
+## [1.0.0] - 2024-01-15
+
+### Added
+- Users can now authenticate via OAuth
+- New /api/users/:id endpoint
+
+### Changed
+- Authentication now uses JWT tokens
+
+### Fixed
+- Fixed race condition in user creation
+```
+
+## Rules
+
+1. One version per section
+2. Chronological order (newest first)
+3. Link to issues/pr
+4. Mention breaking changes
+5. Use imperative mood
+
+## Example Entry
+
+```markdown
+### Added
+- Add user profile endpoint (#123, @username)
+```

package/skills/code-docs/references/readme-structure.md

@@ -0,0 +1,94 @@
+# README Structure
+
+## Quick Template
+
+```markdown
+# Project Name
+
+One-sentence description.
+
+[![Build](https://img.shields.io/badge/build-passing-green)](link)
+[![Version](https://img.shields.io/npm/v/package.svg)](link)
+[![License](https://img.shields.io/badge/license-MIT-blue)](link)
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Quick Start
+
+```bash
+npm install package-name
+npm start
+```
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Steps
+
+1. Clone repo
+2. Install deps: npm install
+3. Configure: cp .env.example .env
+4. Run: npm run dev
+
+## Usage
+
+```javascript
+const pkg = require('package-name');
+
+pkg.doSomething();
+```
+
+## API
+
+See [API Documentation](docs/api.md).
+
+## Configuration
+
+| Env | Description | Default |
+|-----|-------------|---------|
+| PORT | Server port | 3000 |
+| DB_URL | Database connection | localhost |
+
+## Development
+
+```bash
+npm run dev    # Start dev server
+npm test       # Run tests
+npm run lint   # Lint
+```
+
+## Contributing
+
+1. Fork
+2. Branch: feature/my-feature
+3. Commit
+4. PR
+
+## License
+
+MIT
+```
+
+## Sections to Include
+
+| Section | Required | Description |
+|---------|----------|-------------|
+| Title + Badges | Yes | Project name, version, status |
+| Description | Yes | What it does |
+| Features | Yes | Key capabilities |
+| Quick Start | Yes | 3-5 commands |
+| Installation | No | Detailed setup |
+| Usage | No | Code examples |
+| API | No | For libraries |
+| Configuration | No | Env vars, settings |
+| Development | No | Dev commands |
+| Contributing | No | How to contribute |
+| License | Yes | Open source license |

package/skills/code-git-worktrees/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: code-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification. Triggers on worktree, git worktree, isolated workspace, or creating a new branch for feature work.
+user-invocable: true
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check AGENTS.md
+
+```bash
+grep -i "worktree.*director" AGENTS.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no AGENTS.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per Jesse's rule "Fix broken things immediately":
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.config/superpowers/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check AGENTS.md → Ask user |
+| Directory not ignored | Add to .gitignore + commit |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > AGENTS.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip AGENTS.md check
+
+**Always:**
+- Follow directory priority: existing > AGENTS.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+- Any skill needing isolated workspace for feature work
+- When user explicitly requests worktree setup
+- Before long-running implementation tasks that could pollute current workspace
+
+**Pairs with:**
+- `stacked-commit` - Use worktrees when managing stacked commits across multiple branches

package/skills/code-perf/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: code-perf
+description: >
+  Performance profiling and optimization. Use when code is slow, has memory issues, or needs
+  optimization. Triggers on "slow", "performance", "optimize", "memory leak", "profiling",
+  "bottleneck", or any performance-related concern.
+user-invocable: true
+---
+
+# Code Perf
+
+Performance profiling and optimization workflow.
+
+## The Golden Rule
+
+**Never optimize without profiling.**
+
+You don't know where the bottleneck is until you measure. Making changes without
+profiling wastes time and often makes things worse.
+
+---
+
+## Workflow
+
+### 1. Profile
+
+Measure the current performance.
+
+**Questions:**
+- What's slow? (endpoint, operation, page load)
+- How slow? (latency, throughput)
+- Under what conditions? (load, data size)
+
+**Tools:**
+- Browser DevTools (Performance tab)
+- Node clinic.js
+- Python cProfile
+- Go pprof
+
+### 2. Identify
+
+Find the hot paths.
+
+**Look for:**
+- Functions called many times
+- Large memory allocations
+- Blocking I/O
+- Unnecessary computations
+
+### 3. Optimize
+
+Apply the right optimization pattern.
+
+### 4. Verify
+
+Re-profile to confirm improvement.
+
+---
+
+## Common Bottlenecks
+
+See references/common-bottlenecks.md for detailed patterns:
+
+| Pattern | Symptom | Solution |
+|---------|---------|----------|
+| N+1 | Multiple DB queries | Eager load, batch |
+| Memory leak | Growing RSS | Clear caches, weak refs |
+| Blocking I/O | Thread blocked | Async, worker pool |
+| Unnecessary work | CPU high | Skip redundant calc |
+| Large data | Slow serialization | Pagination, streams |
+
+---
+
+## Optimization Patterns
+
+See references/optimization-patterns.md for:
+
+### Caching
+
+```javascript
+// Before: every call hits DB
+const user = await db.users.find(id);
+
+// After: cache
+const cacheKey = `user:${id}`;
+let user = await redis.get(cacheKey);
+if (!user) {
+  user = await db.users.find(id);
+  await redis.set(cacheKey, user, 'EX', 300);
+}
+```
+
+### Lazy Loading
+
+```javascript
+// Before: load everything
+const allUsers = await db.users.findMany();
+
+// After: paginate
+const users = await db.users.findMany({
+  take: 20,
+  skip: page * 20
+});
+```
+
+### Connection Pooling
+
+```javascript
+// Before: new connection each time
+const client = new Client();
+await client.connect();
+
+// After: pool
+const pool = new Pool({ max: 20 });
+// Use pool.query() throughout
+```
+
+---
+
+## Profiling Tools
+
+See references/profiling-tools.md for:
+
+### Node.js
+
+```bash
+# CPU profiling
+node --prof app.js
+
+# Memory
+node --inspect app.js  # Chrome DevTools
+
+# clinic.js
+npx clinic doctor -- node app.js
+```
+
+### Python
+
+```bash
+# cProfile
+python -m cProfile -o profile.prof app.py
+
+# view with: python -m cProfile -s cumulative app.py
+```
+
+### Go
+
+```bash
+# pprof
+go test -cpuprofile=cpu.prof
+go tool pprof cpu.prof
+
+# Web interface
+go tool pprof -http=:8080 cpu.prof
+```
+
+---
+
+## Skill Loading
+
+- If optimization involves queries → load python-sqlalchemy or typescript-drizzle-orm
+- If memory issues → load for heap snapshots
+- If database → load appropriate database skill