@vibe-agent-toolkit/vat-development-agents 0.1.29 → 0.1.30-rc.2

package/dist/skills/vibe-agent-toolkit/SKILL.md

@@ -182,12 +182,12 @@ You've successfully adopted VAT when:
 
 ## Documentation Index
 
-- [Getting Started Guide](resources/getting-started.md)
-- [Agent Authoring Guide](resources/agent-authoring.md) — patterns and code examples
-- [Orchestration Guide](resources/orchestration.md) — multi-agent workflows
-- [RAG Usage Guide](resources/rag-usage-guide.md)
-- [Resource Compiler Guide](resources/compiling-markdown-to-typescript.md)
-- [Runtime Adapters](resources/adding-runtime-adapters.md)
+- Getting Started Guide
+- Agent Authoring Guide — patterns and code examples
+- Orchestration Guide — multi-agent workflows
+- RAG Usage Guide
+- Resource Compiler Guide
+- Runtime Adapters
 - Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
 
 ## Running VAT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.29",
+  "version": "0.1.30-rc.2",
   "description": "VAT development agents - dogfooding the vibe-agent-toolkit",
   "type": "module",
   "keywords": [
@@ -65,13 +65,13 @@
     "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.29",
-    "@vibe-agent-toolkit/cli": "0.1.29",
+    "@vibe-agent-toolkit/agent-schema": "0.1.30-rc.2",
+    "@vibe-agent-toolkit/cli": "0.1.30-rc.2",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.29",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.30-rc.2",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/debugging/resources/CLAUDE.md

@@ -1,539 +0,0 @@
-# CLI Package Development Guidelines
-
-This document provides guidance specific to developing the vat CLI tool.
-
-## Running vat Commands in Development
-
-**In this monorepo during development**, use one of these approaches to run vat commands:
-
-### From Root Directory
-```bash
-# Use the convenience script (recommended)
-bun run vat <command> <args>
-
-# Example:
-bun run vat skills build
-bun run vat resources validate docs/
-```
-
-### From Package Scripts
-When calling vat from another package's build script, use the relative path:
-
-```json
-{
-  "scripts": {
-    "build": "bun run build:code && node ../cli/dist/bin/vat.js skills build"
-  }
-}
-```
-
-**Why relative paths?** Workspace bin linking doesn't work reliably across Bun/npm/pnpm. Relative paths work everywhere and make dependencies explicit.
-
-### For End Users (Self-Hosting)
-Users who install VAT in their own projects should use:
-
-```bash
-# If installed globally
-vat skills build
-
-# If installed as dev dependency
-npx vat skills build
-# or
-bunx vat skills build
-```
-
-## Debugging VAT Behavior & Testing Fixes
-
-When VAT produces unexpected results and you need to test a code change in an adopter
-project, use `VAT_ROOT_DIR` to redirect the installed `vat` binary to your local build:
-
-```bash
-export VAT_ROOT_DIR=/path/to/vibe-agent-toolkit
-bun run build   # always build first
-cd /path/to/adopter-project
-vat resources validate .   # now uses your local build
-```
-
-Full debugging guide: [docs/debug-and-test-vat-fixes.md](debug-and-test-vat-fixes.md)
-
-## CLI Package Architecture Principles
-
-### The CLI Must Remain "Dumb"
-
-**Critical Rule**: The CLI package sits at the top of the dependency chain. No other package can depend on it. This means:
-
-✅ **CLI SHOULD contain**:
-- Command definitions and argument parsing (Commander.js)
-- User-facing help text and documentation
-- Orchestration logic (calling other packages in sequence)
-- Error handling and user-friendly error messages
-- Output formatting (YAML, progress indicators)
-
-❌ **CLI SHOULD NOT contain**:
-- Business logic that other packages might need
-- Path resolution algorithms
-- File system utilities
-- Validation logic
-- Build/conversion logic
-- Any reusable functionality
-
-### Why This Matters
-
-If you put logic in the CLI that other packages need, you create an impossible dependency situation:
-- Other packages can't depend on CLI (circular dependency)
-- Logic gets duplicated across packages (DRY violation)
-- Changes require coordinating multiple packages
-
-### The Right Place for Logic
-
-| Logic Type | Wrong Place | Right Place | Why |
-|------------|-------------|-------------|-----|
-| Find agent's package root | CLI | agent-skills or utils | Other runtimes (langchain, etc.) will need this |
-| Determine default output path | CLI | agent-skills | Each runtime knows where its bundles should go |
-| Validate agent manifest | CLI | agent-config | Validation used by all consumers |
-| Parse YAML | CLI | utils or agent-config | Common across many packages |
-| Format user messages | CLI | ✅ CLI is fine | This is CLI-specific UX |
-
-### Example: Agent Build Command
-
-**Before (WRONG)** - Logic in CLI:
-```typescript
-// packages/cli/src/commands/agent/build.ts
-function findAgentPackageRoot(agentPath: string): string {
-  // 50 lines of path-walking logic...
-  // ❌ This belongs elsewhere!
-}
-
-function determineOutputPath(target: string, agentPath: string): string {
-  const packageRoot = findAgentPackageRoot(agentPath);
-  return path.join(packageRoot, 'dist', 'vat-bundles', target);
-}
-```
-
-**After (CORRECT)** - Logic in runtime package:
-```typescript
-// packages/cli/src/commands/agent/build.ts
-const buildOptions = options.output
-  ? { agentPath, target, outputPath: options.output }
-  : { agentPath, target };
-// ✅ CLI just passes options, runtime figures out the rest
-result = await buildAgentSkill(buildOptions);
-```
-
-```typescript
-// packages/agent-skills/src/builder.ts
-function getDefaultOutputPath(manifestPath: string, target: string): string {
-  const agentPackageRoot = findAgentPackageRoot(manifestPath);
-  return path.join(agentPackageRoot, 'dist', 'vat-bundles', target);
-}
-// ✅ Logic lives where it can be reused by other runtimes
-```
-
-### Quick Check: Does This Belong in CLI?
-
-Ask yourself:
-1. **"Could another package need this logic?"** → If yes, move to utils or the specific runtime package
-2. **"Is this about user interaction?"** → If yes, CLI is probably fine
-3. **"Does this involve file paths/resolution?"** → Probably belongs in utils or the consumer package
-4. **"Is this domain logic?"** → Belongs in the domain package (agent-config, rag, runtime-*, etc.)
-
-### Self-Hosting Consideration
-
-Remember: **Other agent repos won't have packages/cli/**. If an agent package needs to build itself, it can depend on `@vibe-agent-toolkit/agent-skills` directly. The CLI is just one convenient way to invoke the build - not the only way.
-
-### Audit Command Independence
-
-**Intentional Architectural Decision**: The `vat skills audit` command maintains custom scanning logic rather than using `discovery.scan()`.
-
-**Why**:
-- `discovery.scan()` is optimized for VAT agent resources (finds markdown files, extracts frontmatter)
-- Audit needs to find multiple file types in specific directory structures (`.claude-plugin/` directories, JSON manifests, TypeScript/JavaScript files)
-- Different scanning requirements = different scanning implementations
-
-**What IS Shared**:
-- ✅ Skill validation logic (uses shared `validateSkill` from agent-skills)
-- ✅ Validation result formatting (uses shared `validate` function)
-- ✅ Claude paths resolution (uses `@vibe-agent-toolkit/utils/claude-paths`)
-
-**What is NOT Shared**:
-- ❌ Directory scanning (audit's requirements differ from discovery's design)
-- ❌ File type detection (audit looks for `.claude-plugin/` structure, not markdown)
-
-**This is not technical debt** - it's recognition that discovery and audit have fundamentally different scanning needs. Forcing them to share scanning logic would violate single responsibility principle and make both implementations more complex.
-
-## Writing Useful CLI Help Documentation
-
-**Golden Rule**: Help text should answer "What does this do?" and "How do I use it?" without requiring users to read external documentation.
-
-### Principles for Effective CLI Help
-
-#### 1. Be Descriptive, Not Terse
-
-❌ **Bad**: "Validate resources"
-✅ **Good**: "Validate markdown resources (link integrity, anchors)"
-
-❌ **Bad**: "Scan directory"
-✅ **Good**: "Discover markdown resources in directory and report statistics"
-
-**Why**: Users need to understand what the command actually does before running it.
-
-#### 2. Document What Happens
-
-Every command should explain:
-- **Input**: What does it operate on? (files, directories, config)
-- **Processing**: What does it check/do?
-- **Output**: What does it produce? (format, destination)
-- **Side effects**: Does it modify anything?
-
-**Example**:
-```typescript
-.addHelpText('after', `
-Description:
-  Validates all markdown files for broken links, missing anchors, and
-  invalid references. Outputs YAML summary to stdout and test-format
-  errors to stderr.
-
-  Default path: current directory
-  Respects: vibe-agent-toolkit.config.yaml include/exclude patterns
-`)
-```
-
-#### 3. Explain Output Format
-
-Users need to know:
-- What format is the output? (YAML, JSON, plain text)
-- Where does it go? (stdout, stderr, file)
-- What fields/structure to expect?
-
-**Example**:
-```typescript
-Output:
-  - status: success/error
-  - filesScanned: number of markdown files found
-  - linksFound: total links discovered
-  - duration: scan time in milliseconds
-
-Output Format:
-  YAML summary → stdout (for programmatic parsing)
-  Error details → stderr (file:line:column: message)
-```
-
-#### 4. Document Exit Codes
-
-Critical for scripting and CI/CD:
-
-```typescript
-Exit Codes:
-  0 - All validations passed
-  1 - Validation errors found (broken links, missing anchors)
-  2 - System error (config invalid, directory not found, etc.)
-```
-
-**Why**: Scripts need to know when to fail builds, send alerts, etc.
-
-#### 5. Show One Good Example
-
-**Principle**: One example is good, two is too many. Help text is not a tutorial.
-
-Show the **most common use case** that demonstrates the command clearly:
-
-**Pattern**:
-```typescript
-Example:
-  $ vat resources validate docs/        # Validate markdown in docs folder
-```
-
-If you need to show advanced usage, put it in verbose help (`--help --verbose`) or documentation.
-
-**Why**: Users scan help text. Too many examples → information overload → users skip everything.
-
-#### 6. Clarify Design Decisions
-
-When something might surprise users, explain why:
-
-```typescript
-Validation Checks:
-  - Internal file links (relative paths)
-  - Anchor links within files (#heading)
-  - Cross-file anchor links (file.md#heading)
-  - External URLs are NOT validated (by design)
-```
-
-**Why**: Prevents user confusion and support requests.
-
-#### 7. Keep It Concise
-
-**Less is more**. Every line in help text should earn its place.
-
-✅ **Do**: Essential information only
-❌ **Don't**: Repeat information users already know
-❌ **Don't**: Multiple examples when one suffices
-❌ **Don't**: Verbose explanations of obvious things
-
-Users who need more detail will use `--help --verbose` or read the docs.
-
-### Commander.js Patterns
-
-#### Basic Command with Enhanced Help
-
-```typescript
-program
-  .command('mycommand [arg]')
-  .description('Short one-line description for command list')
-  .option('-d, --debug', 'Enable debug logging')
-  .action(myCommandHandler)
-  .addHelpText('after', `
-Description:
-  Detailed explanation of what this command does and what users
-  should expect. Keep it under 3 sentences.
-
-Output:
-  - field1: description of field
-  - field2: description of field
-
-Example:
-  $ vat mycommand docs/         # Most common use case
-`);
-```
-
-#### Command Group with Example
-
-```typescript
-const group = new Command('groupname');
-
-group
-  .description('Brief description of command group')
-  .helpCommand(false)  // Remove redundant help command
-  .addHelpText('after', `
-Example:
-  $ vat groupname subcommand docs/    # Most common workflow
-
-Configuration:
-  Create config.yaml in project root. See --help --verbose for details.
-`);
-```
-
-### Help Text Organization
-
-Use this structure for `.addHelpText('after', ...)`:
-
-```
-Description:
-  [2-3 sentences max - what it does, input, output]
-
-[Optional command-specific section]:
-  Validation Checks: / Output Fields: / etc.
-  - Brief bullets only if essential
-
-Exit Codes: (only for commands with multiple exit codes)
-  0 - Success
-  1 - Validation/expected failures
-  2 - System/unexpected errors
-
-Example:  (singular - one example only)
-  $ command common-case         # The most typical usage
-```
-
-**Remember**: Brevity beats completeness. When in doubt, remove text.
-
-### Testing Help Text
-
-Always test help output:
-
-```bash
-# Test all help variations
-node packages/cli/dist/bin.js --help
-node packages/cli/dist/bin.js resources --help
-node packages/cli/dist/bin.js resources scan --help
-node packages/cli/dist/bin.js resources validate --help
-
-# Test piping (help should go to stdout)
-node packages/cli/dist/bin.js --help | less
-node packages/cli/dist/bin.js --help | grep validate
-```
-
-### Anti-Patterns to Avoid
-
-❌ **Don't**: Use terse descriptions
-"Validate resources" tells users nothing useful
-
-❌ **Don't**: Assume users know the output format
-They won't know if it's YAML, JSON, or plain text
-
-❌ **Don't**: Hide exit codes
-Scripts and CI systems need this information
-
-❌ **Don't**: Skip examples
-Examples are the fastest way for users to understand
-
-❌ **Don't**: Leave design decisions unexplained
-"Why doesn't it validate external URLs?" will be asked
-
-❌ **Don't**: Forget about piping
-UNIX users expect `--help | less` to work (stdout, not stderr)
-
-### When to Use Verbose Help
-
-Use `--help --verbose` for:
-- Comprehensive reference documentation
-- Configuration file schemas
-- Advanced usage patterns
-- Architecture explanations
-- Links to external resources
-
-Regular `--help` should be complete enough for 90% of use cases.
-
-## Command Implementation Patterns
-
-### Command File Structure
-
-```typescript
-// commands/mycommand.ts
-export interface MyCommandOptions {
-  debug?: boolean;
-  // ... other options
-}
-
-export async function myCommand(
-  pathArg: string | undefined,
-  options: MyCommandOptions
-): Promise<void> {
-  const logger = createLogger(options.debug ? { debug: true } : {});
-  const startTime = Date.now();
-
-  try {
-    // 1. Validate inputs
-    // 2. Process
-    // 3. Output results (YAML to stdout)
-    // 4. Exit with appropriate code
-
-    process.exit(0);
-  } catch (error) {
-    handleCommandError(error, logger, startTime, 'MyCommand');
-  }
-}
-```
-
-### Output Conventions
-
-**Structured output (YAML)** → stdout
-**Human-readable errors** → stderr
-**Exit codes**: 0 = success, 1 = expected failure, 2 = unexpected error
-
-This enables:
-```bash
-vat command | jq .status           # Parse YAML
-vat command 2>&1 | less            # View all output
-vat command > results.yaml         # Save results
-vat command && echo "Success"      # Use in scripts
-```
-
-### Error Handling
-
-Use the `handleCommandError` helper for consistent error handling:
-
-```typescript
-try {
-  // Command implementation
-} catch (error) {
-  handleCommandError(error, logger, startTime, 'CommandName');
-  // handleCommandError calls process.exit() internally
-}
-```
-
-This ensures:
-- Consistent error format
-- Duration logging
-- Proper exit codes (1 for expected errors, 2 for unexpected)
-
-## Testing CLI Commands
-
-### System Tests
-
-Create system tests in `test/system/` for end-to-end CLI testing:
-
-```typescript
-describe('MyCommand (system test)', () => {
-  let tempDir: string;
-
-  beforeAll(() => {
-    tempDir = createTestTempDir('vat-mycommand-test-');
-  });
-
-  afterAll(() => {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  it('should handle basic usage', () => {
-    const { result, parsed } = executeCommandAndParse(binPath, projectDir);
-
-    expect(result.status).toBe(0);
-    expect(parsed.status).toBe('success');
-  });
-
-  it('should handle errors correctly', () => {
-    // Test error scenarios with exit code 1 or 2
-  });
-});
-```
-
-### Help Text Tests
-
-Add tests to verify help text contains key information:
-
-```typescript
-it('should show comprehensive help', () => {
-  const result = spawnSync('node', [binPath, 'mycommand', '--help'], {
-    encoding: 'utf-8',
-  });
-
-  expect(result.status).toBe(0);
-  expect(result.stdout).toContain('Description:');
-  expect(result.stdout).toContain('Examples:');
-  expect(result.stdout).toContain('Exit Codes:');
-});
-```
-
-## Documentation Maintenance
-
-### CLI Help Documentation
-
-The CLI help documentation lives in `packages/cli/docs/*.md`:
-- `docs/index.md` - Root level verbose help (`vat --help --verbose`)
-- `docs/resources.md` - Resources command verbose help (`vat resources --help --verbose`)
-
-These markdown files are the single source of truth and are:
-- Loaded at runtime by the CLI via `help-loader.ts`
-- Included in the published npm package (in the `files` array)
-- Browsable on GitHub and npm
-
-**This ensures documentation never drifts from actual CLI behavior** - there is only one source.
-
-### When to Update Help Text
-
-Update help text when:
-- ✅ Adding new commands or options
-- ✅ Changing command behavior
-- ✅ Adding new output fields
-- ✅ Changing exit code meanings
-- ✅ Users report confusion (help wasn't clear)
-
-Don't wait to update help - do it in the same PR as the feature.
-
-## Summary Checklist
-
-When adding a new CLI command, ensure:
-
-- [ ] Short description (for command list)
-- [ ] Detailed description (what it does)
-- [ ] Default behavior explained
-- [ ] Output format documented
-- [ ] Exit codes documented (if not 0-only)
-- [ ] At least 3 examples (basic, intermediate, advanced)
-- [ ] Configuration usage explained (if applicable)
-- [ ] Design decisions clarified (if surprising)
-- [ ] Help text goes to stdout (not stderr)
-- [ ] System tests cover the command
-- [ ] CLI reference docs regenerated
-
-**Remember**: If you have to explain something in a GitHub issue or Slack, that explanation should be in the help text.

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/debugging/resources/debug-and-test-vat-fixes.md

@@ -1,111 +0,0 @@
-# Debugging & Testing VAT Fixes
-
-Reference guide for diagnosing unexpected VAT behavior, testing local code changes
-in adopter projects, and validating fixes before publishing.
-
-> **Quick reference**: Also available as `vibe-agent-toolkit:debugging` skill
-> when working in Claude Code.
-
-## Check Which Version Is Running
-
-```bash
-# In the adopter project
-cat node_modules/@vibe-agent-toolkit/cli/package.json | grep '"version"'
-
-# Or via the binary
-vat --version
-```
-
-Many "VAT bugs" are version mismatches — the adopter project has an older RC installed.
-
-## Enable Debug Output
-
-```bash
-VAT_DEBUG=1 vat <command>
-```
-
-Prints: binary path resolution, context detection, config file found, and project root.
-Use to confirm that VAT is reading the config and root you expect.
-
-Other env vars:
-
-| Variable | Purpose |
-|---|---|
-| `VAT_DEBUG=1` | Print resolution and context detection details |
-| `VAT_ROOT_DIR=/path` | Redirect to a local monorepo build (see below) |
-| `VAT_TEST_ROOT=/path` | Override project root (skips `.git` detection) |
-| `VAT_TEST_CONFIG=/path` | Override config file path |
-
-## Test With a Local Monorepo Build
-
-To test a fix from your local `vibe-agent-toolkit` checkout in an adopter project
-without publishing to npm, use `VAT_ROOT_DIR`:
-
-```bash
-# 1. Build the monorepo first (always required after code changes)
-cd /path/to/vibe-agent-toolkit
-bun run build
-
-# 2. Point the adopter project at your local build
-export VAT_ROOT_DIR=/path/to/vibe-agent-toolkit
-
-# 3. Run any vat command — it now uses your local build
-cd /path/to/adopter-project
-vat resources validate .
-```
-
-The globally-installed `vat` wrapper detects `VAT_ROOT_DIR` and re-dispatches to
-`$VAT_ROOT_DIR/packages/cli/dist/bin.js` automatically.
-
-**Alternative (no global install needed):**
-
-```bash
-node /path/to/vibe-agent-toolkit/packages/cli/dist/bin/vat.js resources validate .
-```
-
-## Write a Failing Test Before Fixing
-
-Reproduce the bug as a test before touching source code:
-
-| Bug type | Test location |
-|---|---|
-| Pure logic, parsing, schema | `packages/<package>/test/*.test.ts` (unit) |
-| CLI command behavior | `packages/cli/test/integration/*.integration.test.ts` |
-| End-to-end workflow | `packages/cli/test/system/*.system.test.ts` |
-
-See [docs/writing-tests.md](writing-tests.md) for patterns and classification guide.
-
-Run just the test you added:
-```bash
-bun run test:unit -- <pattern>          # unit
-bun run test:integration -- <pattern>  # integration
-bun run test:system -- <pattern>       # system
-```
-
-## Validate Before Committing
-
-After fixing, run the full pipeline from the monorepo root:
-
-```bash
-bun run validate
-```
-
-Results are cached by git tree hash — instant if code is unchanged, re-runs only
-what changed. Do not commit until this passes.
-
-## Common Symptoms & Causes
-
-| Symptom | Likely cause |
-|---|---|
-| Wrong anchor slugs in link validation | Check `generateSlug` in `packages/resources/src/link-parser.ts` |
-| Headings not found in a file | Spurious ` ``` ` fence swallowing the heading — scan file for unclosed fences |
-| Config not loading | Run `VAT_DEBUG=1 vat <command>` — shows which config file is found |
-| Fix works locally but adopter still wrong | `bun run build` not run after the change, or adopter uses old installed version |
-| Path wrong on Windows | Use `toForwardSlash()` from `@vibe-agent-toolkit/utils` for path comparisons |
-| Test passes, CI fails | Different Node version; check matrix (Node 22/24 × Ubuntu/Windows) |
-
-## See Also
-
-- [docs/writing-tests.md](writing-tests.md) — Full test classification and patterns
-- [packages/cli/CLAUDE.md](CLAUDE.md) — CLI development guidelines
-- [docs/build-system.md]() — Build configuration reference