{"_id":"@adlele/claude-skill-tools","name":"@adlele/claude-skill-tools","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@adlele/claude-skill-tools","version":"0.1.0","description":"A collection of AI development tools, primarily built with Claude Code CLI in mind","type":"module","engines":{"node":">=18"},"bin":{"composer":"dist/bin/composer.js","sandbox":"dist/bin/sandbox.js","session-explorer":"dist/bin/session-explorer.js","session-analyzer":"dist/bin/session-analyzer.js"},"scripts":{"build":"tsc && node scripts/copy-assets.mjs","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"devDependencies":{"@types/node":"^25.3.0","@vitest/coverage-v8":"^4.0.18","typescript":"^5.9.3","vitest":"^4.0.18"},"gitHead":"38703f0bc5a647e1ce0f83ff0caef919a695c152","_id":"@adlele/claude-skill-tools@0.1.0","_nodeVersion":"20.19.5","_npmVersion":"11.11.0","dist":{"integrity":"sha512-yQ2rBBQqLvZfReUixkxuKXs+H2/MBdzHbO4EF0eVu2VmBwxtUhewVyKv/ohWCAjalcRJNB/lRL2VbTXrMulfgw==","shasum":"19c108a15efcb13aa10ce2beb97469e4c12fc3f3","tarball":"https://registry.npmjs.org/@adlele/claude-skill-tools/-/claude-skill-tools-0.1.0.tgz","fileCount":207,"unpackedSize":1308193,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBsrVvPeOOXoaqmQgbfnsHg6xWM7f1hoShrc/qWUqmn1AiEA4VJiNq0F5mVZZBqPZCV6yuGOpLg3cO6e8hPwxADF8F4="}]},"_npmUser":{"name":"adityalele","email":"aditya.lele@gmail.com"},"directories":{},"maintainers":[{"name":"adityalele","email":"aditya.lele@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-skill-tools_0.1.0_1774739375899_0.8282146982887975"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-28T23:09:35.829Z","0.1.0":"2026-03-28T23:09:36.105Z","modified":"2026-03-28T23:09:36.278Z"},"maintainers":[{"name":"adityalele","email":"aditya.lele@gmail.com"}],"description":"A collection of AI development tools, primarily built with Claude Code CLI in mind","readme":"# claude-skill-tools\n\nA collection of AI development tools, primarily built with Claude Code CLI in mind.\n\n[Documentation](https://adlele.github.io/claude-skill-tools/)\n\n## Features\n\n- **Composer** — Orchestrate multi-step workflows (analyst, architect, developer, reviewer) with session state, auto-retry, and tmux integration\n- **Sandbox** — Create isolated git worktree sandboxes with role-based system prompts and a PreToolUse guard hook\n- **Ralph loop** — Automated developer/reviewer iteration cycle with comment tracking and ignore lists\n- **Prompt overrides** — Override any shipped role prompt per-repo via `.claude/prompts/`\n- **Config overrides** — Per-repo config at `.claude/.skill-state/config.json` merges over user-level defaults\n- **PR creation** — Auto-generate Azure DevOps pull requests from sandbox artifacts\n- **ADO integration** — Fetch work items as markdown context for compositions\n- **Session metrics** — Track Claude CLI session IDs per composition step and generate cost/token/tool usage reports\n- **Session explorer** — Deep-dive analysis of individual sessions with timeline visualization and subagent tracking\n\n## Requirements\n\n- Node.js >= 18\n- Git\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command available in PATH)\n- Azure CLI (`az`) for ADO/PR features (optional)\n\n## Installation\n\n```bash\n# From npm (once published)\nnpm install -g claude-skill-tools\n\n# From source\ngit clone <repo-url>\ncd claude-skill-tools\nnpm install\nnpm run build\nnpm link\n```\n\n## Quick Start\n\n```bash\n# List available composition types\ncomposer list\n\n# Start a full workflow from an ADO work item\ncomposer compose full --ado 12345\n\n# Automated dev/review with inline context\ncomposer compose ralph-only --context \"Add dark mode support to the settings page\"\n\n# Single role session\ncomposer compose role --role architect --context \"Design a caching layer\"\n\n# Resume a paused session\ncomposer resume a1b2\n\n# Manage sandboxes directly\nsandbox list\nsandbox roles\nsandbox start --role analyst --context \"Refactor the settings service\"\nsandbox clean --all\n```\n\n## Roles\n\nEach role is a markdown system prompt that defines an AI agent's behavior. Shipped roles:\n\n| Role | Description |\n|------|-------------|\n| `analyst` | Requirements Analyst — produces `requirements.md` from a feature request |\n| `architect` | Solution Architect — produces `spec.md` from requirements |\n| `developer` | Developer (Team Lead) — breaks spec into tasks, delegates to sub-agents via TDD |\n| `developer_single` | Developer (Solo) — implements tasks directly using TDD (used in headless/ralph) |\n| `reviewer` | Code Reviewer — reviews changes against spec, produces `comments.md` |\n| `tester` | Test Writer — writes test plans and test code |\n\n### Prompt Overrides\n\nYou can override any shipped prompt on a per-repo basis by placing markdown files in `.claude/prompts/` at the root of your target repository:\n\n```\nmy-repo/\n  .claude/\n    prompts/\n      developer.md        # overrides the shipped developer.md\n      my-custom-role.md   # adds a new role not in the package\n```\n\nResolution order:\n\n1. **Repo-local** (`.claude/prompts/<role>.md`) — checked first\n2. **Package default** (`prompts/<role>.md` in the installed package) — fallback\n\nRepo-local files take precedence per-file. You only need to override the prompts you want to customize — the rest are inherited from the package. Repo-local-only files (like `my-custom-role.md` above) are also included.\n\nThis is useful for adding project-specific coding standards, build commands, or framework rules to your developer/reviewer prompts without forking the package.\n\n## Composer\n\nThe composer orchestrates multi-step workflows called **compositions**. Each composition is a sequence of steps (sandbox creation, Claude sessions, ralph loops, PR creation) that run in order with an interactive stepper UI.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `composer list` | List available composition types with descriptions |\n| `composer compose <type> [opts]` | Start a new composition |\n| `composer resume <session-id>` | Resume a paused or in-progress session |\n| `composer sessions` | Show all sessions with status, step, and branch |\n| `composer clean <target>` | Remove session state (`<id>`, `--all`, `--completed`, `--stale`) |\n| `composer report [session-id]` | Generate metrics report for a session |\n| `composer distill [session-id]` | Distill improved feature request from session artifacts |\n\n### Composition Types\n\n| Type | Pipeline |\n|------|----------|\n| `full` | sandbox → analyst → architect → ralph (dev/review loop) → PR |\n| `ralph-only` | sandbox → ralph (automated dev/review) → PR |\n| `manual` | sandbox → analyst → architect → developer → reviewer → PR |\n| `role` | sandbox → single role session → PR |\n| `headless` | sandbox → background developer → status check → PR |\n\n### Compose Options\n\n```\n--context \"...\"          Inline context string\n--context-file <path>    Read context from a file\n--ado <work-item-id>     Fetch context from Azure DevOps\n--model <model>          Model to use (default: opus)\n--max-iterations <n>     Max dev/review iterations (default: 5)\n--role <name>            Role (required for 'role' composition)\n--name <session-name>    Custom session name (auto-deduped if taken)\n--base <branch>          Base branch for sandbox worktree (default: master)\n--skip-sandbox           Skip sandbox creation, run on current branch\n```\n\n### Report Options\n\n```\n[session-id]             Session to report on (interactive picker if omitted)\n--html                   HTML report with charts (default, opens in browser)\n--text                   Plain text report to stdout\n--json                   JSON output\n--out <path>             Write report to a specific file path\n```\n\n### Distill Options\n\n```\n[session-id]             Session to distill (defaults to most recent with a worktree)\n--model <model>          Model to use (default: sonnet)\n--from-impl              Generate from actual code diff instead of planning artifacts\n--base <branch>          Base branch for --from-impl diff (default: session's base or master)\n```\n\n### Step Navigation\n\nDuring composition execution, each step pauses with an interactive prompt:\n\n- **n** / **Enter** — run the current step\n- **s** — skip current step\n- **p** — go back to previous step\n- **q** — quit (session is saved and can be resumed)\n- **?** / **status** — show current session status and pipeline\n\nAfter the first manual prompt, subsequent steps use a 10-second countdown with auto-run. Steps marked `autoAdvance` (like sandbox creation) run immediately without prompting.\n\nWhen running inside tmux, steps execute in split panes with automatic completion detection. For ralph steps, the main pane spinner shows the current phase and iteration (e.g. `dev 2/5`, `rev 2/5`) by detecting `ralph-dev-N.log` / `ralph-rev-N.log` files in the worktree. Press `a` to toggle auto-advance (lets ralph continue without manual prompts between iterations).\n\n## Sandbox\n\nThe sandbox creates isolated git worktree environments for AI sessions. Each sandbox gets its own branch, working directory, and a copy of all role prompts. Worktrees are created in a sibling directory to the repo (e.g. `../myrepo-sandboxes/<slug>/`).\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `sandbox create [opts]` | Create a worktree sandbox without launching Claude |\n| `sandbox start [opts]` | Create sandbox and launch a Claude role session |\n| `sandbox ralph [opts]` | Run the automated dev/review loop |\n| `sandbox distill [opts]` | Distill an improved feature request from sandbox artifacts |\n| `sandbox status [opts]` | Show sandbox status (commits, diff, process state) |\n| `sandbox clean [target]` | Remove sandbox (worktree, branch, state) |\n| `sandbox list` | List all sandboxes with status |\n| `sandbox roles` | List available role prompts |\n\n### Create Options\n\n```\n--branch <name>          Git branch name (auto-generated if omitted)\n--base <branch>          Base branch to fork from (default: master)\n--setup                  Run full dependency install (instead of symlinking node_modules)\n--context \"...\"          Seed feature-request.md with inline context\n--context-file <path>    Seed feature-request.md from a file\n```\n\n### Start Options\n\n```\n--role <name>            Role to launch (e.g. analyst, architect, developer)\n--idea <text>            Auto-generate a custom role from a description\n--context \"...\"          Context string seeded as feature-request.md\n--context-file <path>    Read context from a file\n--branch <name>          Git branch name (auto-generated if omitted)\n--base <branch>          Base branch (default: master)\n--model <model>          Model to use (default: opus)\n--headless               Run in background (detached process)\n--ralph                  Start in ralph mode (automated dev/review loop)\n--max-iterations <n>     Max ralph iterations (default: 10)\n--setup                  Run full dependency install\n--skip-sandbox           Reuse an existing sandbox (requires --branch)\n```\n\n### Ralph Options\n\n```\n--branch <name>          Branch of existing sandbox (required)\n--max-iterations <n>     Max dev/review iterations (default: 10)\n--model <model>          Model to use (default: sonnet)\n--headless               Run without interactive prompts\n--review                 Start with reviewer (skip first dev pass)\n--no-agents              Disable sub-agent delegation (use solo developer)\n--composer-session <id>  Link to a composer session for metrics tracking\n```\n\n### Status Options\n\n```\n<short-id>               Lookup by short ID (from 'sandbox list')\n--branch <name>          Lookup by branch name\n--id <slug>              Lookup by slug\n```\n\nIf no target is given, `status` falls back to showing the sandbox list.\n\n### Clean Options\n\n```\n<short-id>               Clean by short ID (from 'sandbox list')\n--branch <name>          Clean by branch name\n--all                    Clean all sandboxes\n--stopped                Clean stopped sandboxes\n--active                 Clean active sandboxes\n--running                Clean running sandboxes\n--missing                Clean sandboxes with missing worktrees\n--orphans                Clean orphaned worktree directories\n--keep-branch            Remove worktree but keep the git branch\n--force                  Skip confirmation prompts\n```\n\nWhen run with no arguments in a TTY, `clean` shows an interactive picker.\n\n### Distill Options\n\n```\n--branch <name>          Branch to distill from (required)\n--model <model>          Model to use (default: sonnet)\n```\n\n## Ralph Loop\n\nThe ralph loop (`sandbox ralph`) automates developer/reviewer iterations:\n\n1. **Developer phase** — Claude runs as the developer role (team lead with sub-agents, or solo in `--no-agents` mode). On iteration 1, it reads `feature-request.md` and implements from scratch. On subsequent iterations, it reads `comments.md` and fixes flagged issues.\n\n2. **Reviewer phase** — Claude runs as the reviewer role. It reviews all changes against the spec and writes `comments.md` with categorized feedback (Must Fix, Should Fix, Consider).\n\n3. **User decision** (interactive mode) — After each review, you can:\n   - **c** — continue to next iteration (developer addresses comments)\n   - **i** — ignore specific comments (they won't be addressed in future iterations)\n   - **s** — stop the loop\n\n4. **Exit conditions** — The loop ends when:\n   - Review is clean (no Must Fix / Should Fix comments)\n   - Max iterations reached\n   - User stops manually\n\nArtifacts produced: `ralph-log.md` (iteration history), `comments.md` (latest review), `ignored-comments.txt` (user-ignored items), `audit-log.md` (tool call audit summary, generated from `audit-raw.jsonl` if present).\n\n## Distill\n\nThe `sandbox distill` command generates an improved, self-contained feature request by combining:\n\n- `feature-request.md` — the original user request\n- `requirements.md` — clarified requirements from the analyst\n- `spec.md` — technical specification from the architect\n\nThe output (`improved-feature-request.md`) is detailed enough that a developer can go straight to implementation with no clarifying questions. A changes summary (`feature-request-changes-summary.md`) is also generated, listing what was added, clarified, or scoped out.\n\nThis enables a **zero-intervention loop**: run the full pipeline once, distill the result, then re-run with the improved feature request for a cleaner pass:\n\n```bash\nsandbox distill --branch users/me/first-pass\nsandbox start --ralph --context-file <worktree>/improved-feature-request.md\n```\n\n## Sandbox Guard Hook\n\nEach sandbox includes a PreToolUse guard hook (`hooks/sandbox-guard.sh`) that restricts file operations to the sandbox directory via the `SANDBOX_DIR` environment variable. This prevents the AI agent from modifying files outside its worktree.\n\nA TypeScript equivalent (`src/sandbox/sandbox-guard.ts`, compiled to `dist/sandbox/sandbox-guard.js`) is available for Windows environments where a POSIX shell is not available.\n\n## Project Structure\n\n```\nprompts/           Role prompt markdown files (analyst, architect, developer, reviewer, tester)\nhooks/             PreToolUse guard hook (sandbox-guard.sh)\nsrc/\n  shared/          Common utilities, path resolution, config, UI helpers\n  composer/        Composer orchestration engine\n  sandbox/         Sandbox worktree management and ralph loop\n  connectors/      External service integrations (ADO PR creation, work item fetching)\n  metrics/         Session metrics tracking and batch analysis (session-metrics.ts)\n  session-explorer/ Deep single-session analysis with timeline (session-explorer)\n  bin/             CLI entry point shims (composer, sandbox, session-explorer)\n```\n\n## State Storage\n\nSession and sandbox state is stored repo-locally at:\n\n- Composer: `<repo>/.claude/.skill-state/composer/`\n- Sandbox: `<repo>/.claude/.skill-state/sandbox/`\n\nDurable metrics data is stored at the user level:\n\n- Session maps: `~/claude-skill-tools/session-maps/`\n- Parsed session cache: `~/claude-skill-tools/parsed-sessions.json`\n- User-level config: `~/claude-skill-tools/config.json`\n- Repo-level config (optional, overrides user-level): `<repo>/.claude/.skill-state/config.json`\n\nSession maps survive `composer clean` so you can generate reports for deleted sessions.\n\nAdd `.claude/.skill-state/` to your `.gitignore`.\n\n### Config Resolution\n\nConfiguration is resolved by merging repo-level overrides with user-level defaults:\n\n1. **Repo-level** (`<repo>/.claude/.skill-state/config.json`) — checked first, per-field override\n2. **User-level** (`~/claude-skill-tools/config.json`) — fallback\n\nRepo-level fields take precedence. For nested objects like `adoFields`, sub-keys are merged (repo sub-keys override user sub-keys). You only need to specify the fields you want to override at the repo level.\n\nExample repo-level config that overrides only the ADO org for this repo:\n\n```json\n{\n  \"adoOrg\": \"https://dev.azure.com/my-team-org\"\n}\n```\n\n## Session Explorer\n\nThe `session-explorer` CLI provides deep single-session analysis with an interactive timeline.\n\n### Usage\n\n```bash\n# Launch interactive session browser (local web app)\nsession-explorer\n\n# Generate HTML report for a specific session\nsession-explorer <sessionId>\n\n# Output raw analysis as JSON\nsession-explorer <sessionId> --json\n\n# Custom port for the browser\nsession-explorer --port 8080\n\n# Save report to a specific file\nsession-explorer <sessionId> --out report.html\n```\n\n### Features\n\n- **Metrics tab** — Token usage, cost breakdown by model, tool call distribution, task classification\n- **Timeline tab** — Every event in order: user messages, assistant text, tool uses, tool results, thinking blocks — each with human-readable summaries\n- **Subagent tracking** — Loads subagent JSONL files, merges them into the timeline, and computes per-subagent metrics\n- **Browser mode** — Local HTTP server with a session sidebar for on-demand parsing\n\nThis complements `composer report` (batch metrics across sessions) by drilling into a single session in detail.\n\n## Cross-Platform Notes\n\n- Works on macOS, Linux, and Windows (via Node.js)\n- Build script uses a cross-platform Node.js copy script instead of shell `cp`\n- Path resolution uses `node:path` throughout for OS-appropriate separators\n- The bash sandbox guard hook (`hooks/sandbox-guard.sh`) requires a POSIX shell; on Windows, use the TypeScript guard (`dist/sandbox/sandbox-guard.js`) instead\n\n## Development\n\n```bash\nnpm install\nnpm run build    # Compile TypeScript + copy assets to dist/\n```\n\n## License\n\nISC\n","readmeFilename":"README.md","_rev":"1-faeba0e82ed1323266767d7588a80d6c"}