loadouts 0.1.11

package/docs/authoring.md

@@ -0,0 +1,182 @@
+# Authoring Artifacts
+
+This guide covers creating rules, skills, and instructions. The typical workflow:
+
+1. **Create** an artifact (`loadouts rule add`, `loadouts skill add`, etc.)
+2. **Include** it in a loadout definition (`loadouts/<name>.yaml`)
+3. **Sync** to render outputs (`loadouts sync`)
+4. **Verify** with `loadouts status` or `loadouts info`
+
+---
+
+## Rules
+
+Rules are scoped advisory files with YAML frontmatter:
+
+```markdown
+---
+description: Go coding standards
+paths: ["**/*.go"]
+alwaysApply: false
+---
+
+# Go Standards
+
+Use errors.Join() for error wrapping.
+```
+
+**Frontmatter options:**
+- `description` — Brief summary (shown in listings)
+- `paths` — Glob patterns for when to apply (e.g., `["**/*.go", "**/*.mod"]`)
+- `alwaysApply` — If true, applies regardless of file context
+
+**Create a rule:**
+```bash
+loadouts rule add api-standards -d "REST API conventions" -p "**/*_handler.go"
+```
+
+After creating, add `rules/api-standards.md` to your loadout's `include` list.
+
+**Import existing:**
+```bash
+loadouts rule import .cursor/rules/code.mdc --keep
+```
+
+---
+
+## Skills
+
+Skills are directories with a `SKILL.md` and optional supporting files:
+
+```
+skills/debugging/
+├── SKILL.md              # Required: frontmatter + instructions
+├── references/           # Optional: supporting documents
+│   └── error-codes.md
+└── scripts/              # Optional: executable helpers
+    └── analyze.sh
+```
+
+**SKILL.md format:**
+```markdown
+---
+name: debugging
+description: Advanced debugging techniques for Python applications.
+---
+
+# Debugging Skill
+
+## When to Use
+
+Invoke this skill when debugging Python errors...
+
+## Instructions
+
+1. Identify the error type
+2. Check the stack trace
+...
+```
+
+**Required frontmatter:**
+- `name` — Skill identifier
+- `description` — Brief description (this is the "upfront" token cost; full content is lazy-loaded)
+
+**Create a skill:**
+```bash
+loadouts skill add deploy -d "Deployment procedures"
+```
+
+After creating, add `skills/deploy` to your loadout's `include` list.
+
+---
+
+## Instructions
+
+Per-loadout instruction files live at `.loadouts/instructions/AGENTS.<loadout>.md`. When activated, they render to `AGENTS.md` (or `CLAUDE.md` for Claude Code, which wraps and references `AGENTS.md`).
+
+**Create instructions:**
+```bash
+loadouts instructions init backend
+loadouts instructions edit backend
+```
+
+**Import existing:**
+```bash
+loadouts instructions import                    # Auto-detects AGENTS.md or CLAUDE.md
+loadouts instructions import --loadout backend  # Import to specific loadout
+```
+
+After creating or importing, run `loadouts sync` to render.
+
+---
+
+## Loadout Definitions
+
+Loadouts are YAML files in `.loadouts/loadouts/`:
+
+```yaml
+name: backend
+description: Backend development configuration
+extends: base
+
+tools:                                  # Optional: override defaults
+  - claude-code
+  - opencode
+
+include:
+  - rules/go.md                         # Simple path
+  - skills/deploy                       # Skill directory
+  - path: rules/cursor-only.md          # With options
+    tools: [cursor]
+```
+
+**Per-include tool targeting:**
+```yaml
+include:
+  - rules/general.md                    # All tools
+  - path: rules/cursor-only.md
+    tools: [cursor]
+  - path: skills/claude-debug
+    tools: [claude-code, pi]
+```
+
+---
+
+## Custom Kinds
+
+Define custom artifact types in `.loadouts/kinds/*.yaml`:
+
+```yaml
+# .loadouts/kinds/prompt.yaml
+id: myteam.prompt
+description: Reusable prompt snippets.
+
+detect:
+  pathPrefix: prompts/          # Match files in .loadouts/prompts/
+
+layout: file                     # One file → one output
+
+targets:
+  claude-code:
+    path: "{base}/prompts/{stem}{ext}"
+  cursor:
+    path: "{base}/prompts/{stem}.mdc"
+    ext: .mdc
+```
+
+**Path templates:** `{base}`, `{stem}`, `{ext}`, `{name}`
+
+**Detection:** `pathPrefix` or `pathExact`
+
+List all kinds: `loadouts kinds -v`
+
+---
+
+## Token Estimation
+
+`loadouts info` shows token estimates:
+
+- **Upfront** — Loaded at session start (rules, instructions, skill descriptions)
+- **Lazy** — Loaded on-demand (full skill content)
+
+Uses ~4 chars/token approximation. Good for comparing loadouts and catching bloat.

package/docs/commands.md

@@ -0,0 +1,192 @@
+# Command Reference
+
+## Active Configuration
+
+### `loadouts activate <names...>`
+Add loadout(s) to the active set and render outputs.
+```bash
+loadouts activate backend              # Single loadout
+loadouts activate base frontend        # Multiple loadouts
+loadouts activate ml -g                # Global scope
+loadouts activate backend --dry-run    # Preview only
+```
+
+### `loadouts deactivate <names...>`
+Remove loadout(s) from the active set.
+```bash
+loadouts deactivate backend
+```
+
+### `loadouts sync`
+Re-render active loadouts from latest definitions. Run after editing rules or skills.
+```bash
+loadouts sync              # All scopes
+loadouts sync -l           # Project only
+loadouts sync --dry-run    # Preview
+```
+
+### `loadouts status`
+Show drift status. Detects config drift (definition changed) and output drift (files modified/missing).
+```bash
+loadouts status
+```
+
+### `loadouts clear`
+Deactivate all loadouts and remove all outputs.
+```bash
+loadouts clear             # Project scope
+loadouts clear -g          # Global scope
+loadouts clear -a          # Both scopes
+```
+
+### `loadouts info [name]`
+Show loadout details including artifacts, tools, and token estimates.
+```bash
+loadouts info              # Active loadout(s)
+loadouts info backend      # Specific loadout
+```
+
+### `loadouts diff [name]`
+Preview what would change if a loadout were applied.
+```bash
+loadouts diff backend
+```
+
+---
+
+## Bundle Management
+
+### `loadouts init`
+Initialize a new `.loadouts/` directory. Creates structure, base loadout, and applies it.
+```bash
+loadouts init              # Project
+loadouts init -g           # Global
+loadouts init --force      # Overwrite existing
+```
+
+### `loadouts install`
+Discover and import existing tool configurations.
+```bash
+loadouts install                   # All configs
+loadouts install --dry-run         # Preview
+loadouts install -i                # Interactive
+loadouts install --rules           # Rules only
+loadouts install --from cursor     # From specific tool
+loadouts install --keep            # Don't delete originals
+```
+
+### `loadouts create <name>`
+Create a new loadout definition.
+```bash
+loadouts create backend            # Project loadout
+loadouts create ml -g              # Global loadout
+loadouts create api --extends base # Extend another loadout
+loadouts create test -d "Testing"  # With description
+```
+
+### `loadouts edit <name>`
+Open a loadout definition in `$EDITOR`.
+```bash
+loadouts edit backend
+```
+
+### `loadouts remove [name]`
+Remove applied loadout outputs.
+```bash
+loadouts remove            # All outputs
+loadouts remove backend    # Validate name first
+loadouts remove --dry-run  # Preview
+```
+
+### `loadouts list`
+List available loadouts with item count, description, and inheritance.
+```bash
+loadouts list              # All scopes
+loadouts list -l           # Project only
+loadouts list -g           # Global only
+```
+
+### `loadouts check`
+Validate configuration (YAML syntax, file references, circular extends, tool prerequisites).
+```bash
+loadouts check
+loadouts check -v          # Verbose
+```
+
+---
+
+## Artifact Authoring
+
+### Rules
+
+Create scoped advisory files that tools inject based on file context.
+
+```bash
+loadouts rule add my-rule                 # Create rule
+loadouts rule add go -p "**/*.go"         # With path pattern
+loadouts rule add strict --always-apply   # Always apply
+loadouts rule list                        # List rules
+loadouts rule edit my-rule                # Edit rule
+loadouts rule remove my-rule              # Remove rule
+loadouts rule import ./existing.md        # Import file
+```
+
+After creating a rule, add it to your loadout's `include` list and run `loadouts sync`.
+
+### Skills
+
+Create on-demand capabilities with instructions and supporting files.
+
+```bash
+loadouts skill add deploy                 # Create skill
+loadouts skill add debug -g               # Global skill
+loadouts skill list                       # List skills
+loadouts skill edit deploy                # Edit skill
+loadouts skill remove deploy              # Remove skill
+loadouts skill import ./my-skill          # Import directory
+```
+
+After creating a skill, add it to your loadout's `include` list and run `loadouts sync`.
+
+### Instructions
+
+Create per-loadout instruction files that render to `AGENTS.md` or `CLAUDE.md`.
+
+```bash
+loadouts instructions init                # Create for active loadout
+loadouts instructions init backend        # For specific loadout
+loadouts instructions edit                # Edit instructions
+loadouts instructions list                # List instruction files
+loadouts instructions import              # Import existing AGENTS.md
+loadouts instructions import --loadout backend  # Import to specific loadout
+```
+
+### Kinds
+```bash
+loadouts kinds             # List registered kinds
+loadouts kinds -v          # With detection rules
+```
+
+---
+
+## Scope Flags
+
+Most state commands (`activate`, `deactivate`, `sync`, `status`, `clear`, `list`, `info`, `check`) support scope flags:
+
+| Flag | Description |
+|------|-------------|
+| `-l, --local` | Project scope only |
+| `-g, --global` | Global scope only |
+| `-a, --all` | Both scopes |
+
+When omitted, commands auto-detect scope based on context. Use `--dry-run` to preview behavior before destructive operations.
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `EDITOR` | Editor for edit commands |
+| `VISUAL` | Fallback editor |
+| `PAGER` | Pager for docs (default: `less`) |

package/docs/concepts.md

@@ -0,0 +1,114 @@
+# Core Concepts
+
+## The `.loadouts/` Directory
+
+Project configuration lives in `.loadouts/` (global config lives in `~/.config/loadouts/`):
+
+```
+.loadouts/
+├── loadouts.yaml         # Root config (version, defaults)
+├── loadouts/             # Named configuration bundles
+│   └── base.yaml
+├── instructions/         # Per-loadout instruction files
+│   └── AGENTS.base.md
+├── rules/                # Portable rule files
+└── skills/               # Portable skill directories
+```
+
+## Scopes
+
+| Scope | Location | Flag | Purpose |
+|-------|----------|------|---------|
+| **Project** | `./.loadouts/` | `-l` | Project-specific config |
+| **Global** | `~/.config/loadouts/` | `-g` | User-wide config |
+
+Most commands auto-detect scope. Use `-l`/`-g` to be explicit, or `-a` for both.
+
+## Active State
+
+**Activating** a loadout adds it to the "active set" and renders its artifacts to tool directories. The active set persists in `.loadouts/.state.json` — you don't need to re-activate after restarting your terminal.
+
+- `loadouts activate <name>` — Add to active set and render
+- `loadouts deactivate <name>` — Remove from active set and clean up outputs
+- `loadouts sync` — Re-render active loadouts (after editing source files)
+- `loadouts status` — Show what's active and detect drift
+
+## Loadouts
+
+A **loadout** is a named bundle of artifacts:
+
+```yaml
+# .loadouts/loadouts/backend.yaml
+name: backend
+description: Backend development configuration
+extends: base
+
+include:
+  - rules/go.md
+  - rules/database.md
+  - skills/deploy
+```
+
+**Inheritance:** `extends: base` pulls in the parent's artifacts. Child items take precedence.
+
+**Multiple active:** Activate several loadouts together:
+
+```bash
+loadouts activate base backend ml    # All three active
+```
+
+When multiple loadouts define the same artifact, later arguments take precedence (`ml` wins over `backend` wins over `base`).
+
+**Per-artifact tool targeting:**
+
+```yaml
+include:
+  - rules/general.md                      # All tools
+  - path: rules/cursor-only.md
+    tools: [cursor]                       # Cursor only
+```
+
+## Artifact Kinds
+
+| Kind | Layout | Description |
+|------|--------|-------------|
+| `rule` | file | Scoped advisory rules (`.md`) |
+| `skill` | directory | On-demand capabilities with `SKILL.md` |
+| `instruction` | file | Always-on project instructions |
+| `prompt` | file | Slash command templates |
+| `extension` | directory | Runtime code extensions |
+| `theme` | file | UI theme configuration |
+
+## Supported Tools
+
+| Tool | Rules | Skills | Instructions |
+|------|-------|--------|--------------|
+| Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `CLAUDE.md` |
+| Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `AGENTS.md` |
+| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `AGENTS.md` |
+| Codex | — | `.agents/skills/` | `AGENTS.md` |
+| Pi | `.pi/rules/*.md` | `.pi/skills/` | `AGENTS.md` |
+
+## Sources (Cross-Project Config)
+
+Share configuration across projects:
+
+```yaml
+# packages/api/.loadouts/loadouts.yaml
+version: "1"
+sources:
+  - ../..                    # Parent monorepo
+  - ~/dotfiles               # Personal global config
+```
+
+**Resolution order:** Local `.loadouts/` → Sources (in declaration order) → Global `~/.config/loadouts/`.
+
+When two sources define a loadout with the same name, the first match wins. If a source path doesn't exist, loadouts warns and continues.
+
+## Output Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `symlink` | Target symlinks to source | Default; edits stay in sync |
+| `copy` | Target is a managed copy | Tools that don't follow symlinks |
+| `generate` | Target is rendered/wrapped | Tool-specific transformations |

package/docs/index.md

@@ -0,0 +1,60 @@
+# Loadouts
+
+**Composable configuration bundles for AI coding agents.**
+
+Loadouts organizes your rules, skills, and instructions into named **loadouts** that you can mix and match:
+
+- **Task-specific configs** — Activate `backend` for API work, `frontend` for UI work, or both
+- **Team flexibility** — Track all configs in one place; teammates activate what they need
+- **Tool portability** — Write once, apply to Claude Code, Cursor, OpenCode, Codex, and Pi
+
+```bash
+loadouts activate base backend     # Backend task
+loadouts activate base frontend    # Switch to frontend
+loadouts activate base backend ml  # Combine multiple
+```
+
+## Getting Started
+
+```bash
+npm install -g loadouts     # Requires Node.js 18+
+loadouts docs quickstart           # Step-by-step setup guide
+```
+
+## Quick Reference
+
+```bash
+# Setup
+loadouts init                      # Initialize .loadouts/
+loadouts install                   # Import existing configs
+
+# Daily use
+loadouts activate <name>           # Activate loadout(s)
+loadouts deactivate <name>         # Deactivate loadout(s)
+loadouts sync                      # Re-render after edits
+loadouts status                    # Check for drift (source/output changes)
+
+# Authoring
+loadouts rule add <name>           # Create a rule
+loadouts skill add <name>          # Create a skill
+loadouts instructions init         # Create instructions
+loadouts create <name>             # Create a loadout
+
+# Info
+loadouts list                      # List available loadouts
+loadouts info [name]               # Show loadout details
+loadouts check                     # Validate configuration
+```
+
+## Documentation Topics
+
+```bash
+loadouts docs quickstart       # Get started in 60 seconds
+loadouts docs concepts         # Loadouts, artifacts, scopes, tools
+loadouts docs commands         # Full command reference
+loadouts docs authoring        # Creating rules, skills, instructions
+loadouts docs workflows        # Team setup, git, CI/CD
+loadouts docs troubleshooting  # Common issues and solutions
+```
+
+Use `loadouts docs <topic>` to read any section, or `loadouts docs --list` for descriptions.

package/docs/quickstart.md

@@ -0,0 +1,100 @@
+# Quickstart
+
+Get loadouts running in under a minute.
+
+## Installation
+
+```bash
+npm install -g loadouts
+```
+
+Requires Node.js 18+.
+
+## Getting Started
+
+The fastest way to start is `loadouts init`, which detects and imports any existing agent configs:
+
+```bash
+loadouts init
+```
+
+This creates `.loadouts/`, scans for existing rules/skills in `.claude/`, `.cursor/`, `.opencode/`, etc., and offers to import them. If you have scattered configs, this is the recommended entry point.
+
+**To import explicitly** (or re-import later):
+
+```bash
+loadouts install                   # Discover and import existing configs
+loadouts install --dry-run         # Preview what would be imported
+loadouts install -i                # Interactive mode (select what to import)
+```
+
+## New Project (no existing configs)
+
+If you're starting fresh with no existing agent configs:
+
+```bash
+loadouts init                      # Creates .loadouts/ with a base loadout
+loadouts rule add coding-standards # Create a rule file
+loadouts sync                      # Render to tool directories
+```
+
+Your rule now appears in `.claude/rules/`, `.cursor/rules/`, and other configured tools.
+
+**Verify it worked:**
+```bash
+loadouts status                    # Should show "ok" with no drift
+```
+
+## Existing Project (with scattered configs)
+
+Already have rules in `.cursor/rules/` or `.claude/rules/`? The recommended flow:
+
+```bash
+loadouts init                      # Detects configs and offers to import
+```
+
+If you skipped import during init, or want to import additional configs later:
+
+```bash
+loadouts install                   # Import existing configs
+loadouts sync                      # Render unified config
+```
+
+This finds rules/skills across `.claude/`, `.cursor/`, `.opencode/`, etc. and consolidates them into `.loadouts/`.
+
+**Verify it worked:**
+```bash
+loadouts list                      # Shows your loadouts
+loadouts status                    # Shows rendered artifacts
+```
+
+## Task-Specific Loadouts
+
+Create separate loadouts for different work contexts:
+
+```bash
+loadouts create backend -e base    # New loadout extending base
+loadouts rule add api-standards    # Create a rule
+loadouts edit backend              # Add rules/api-standards.md to include list
+loadouts activate backend          # Apply it
+```
+
+Switch contexts by activating different loadouts:
+
+```bash
+loadouts activate base frontend    # Frontend work
+loadouts activate base backend ml  # Backend + ML combined
+```
+
+## How It Works
+
+1. **Source files** live in `.loadouts/` (rules, skills, loadout definitions)
+2. **Loadouts** bundle artifacts together (`loadouts/base.yaml`)
+3. **Activating** a loadout renders its artifacts to each tool's expected location
+4. **Syncing** re-renders after you edit source files
+
+## What's Next
+
+- `loadouts docs concepts` — Understand loadouts, scopes, and tools
+- `loadouts docs authoring` — Create rules, skills, instructions
+- `loadouts docs workflows` — Team onboarding, git hooks, CI setup