Skip to content
This repository was archived by the owner on Feb 5, 2026. It is now read-only.

Latest commit

 

History

History
119 lines (96 loc) · 5.51 KB

AGENTS.md

File metadata and controls

119 lines (96 loc) · 5.51 KB

Repository Guidelines

This is a TypeScript port of subagent-py.

Project Structure & Module Organization

  • src/cli.ts: Main CLI entry point using Commander.js for argument parsing
  • src/vscode/: VS Code agent provisioning, dispatch, and workspace management
  • src/utils/: Shared utility modules (file system operations, time utilities)
  • dist/: Compiled JavaScript output (generated by TypeScript compiler)
  • src/vscode/subagent_template/: Template files copied into each provisioned subagent workspace

Build, Test, and Development Commands

  • bun install: Install all dependencies
  • bun run build: Compile TypeScript to JavaScript and copy template files to dist/
  • bun run typecheck: Verify TypeScript type safety
  • bun run dev -- <args>: Run CLI directly with hot reload
  • bun run start -- <args>: Run compiled JavaScript from dist/
  • bun run lint: Check code style with Biome
  • bun run format: Format code with Biome
  • bun run fix: Auto-fix linting and formatting issues
  • bun test: Run test suite
  • bun test --watch: Run tests in watch mode
  • bun test --coverage: Run tests with coverage report
  • bun link: Create global symlink for local testing

Version Management

This project uses Changesets for automated versioning and changelog generation.

Creating a changeset

When making changes that should be included in the next release:

  1. Run bun changeset to create a new changeset file
  2. Select the semver bump type (patch, minor, or major)
  3. Write a summary of the changes for the changelog
  4. Commit the generated .changeset/*.md file with your changes

Releasing a new version

  1. Run bun version to consume changesets and update package.json version
  2. Review the updated CHANGELOG.md
  3. Commit the version bump and changelog updates
  4. Create a git tag and push to trigger release workflow

Coding Style & Naming Conventions

  • Follow the TypeScript 5.x and ES2022 guidelines from .github/instructions/typescript-5-es2022.instructions.md
  • Use 2-space indentation (standard for TypeScript projects)
  • Prefer explicit types on public function signatures
  • Use async/await for asynchronous operations
  • Prefer named exports over default exports
  • Keep modules cohesive (provision.ts for provisioning, agentDispatch.ts for dispatch logic, etc.)
  • When adding new CLI commands, register them in cli.ts with appropriate options and handlers

Testing Guidelines

  • Use Bun's built-in test runner for testing
  • Name test files *.test.ts or *.spec.ts
  • Unit tests: Place in tests/unit/ directory
  • Integration tests: Place in tests/integration/ directory
  • Default bun test runs only unit tests (excludes integration tests)
  • Run integration tests with bun run test:integration
  • Run all tests with bun run test:all
  • Ensure tests pass via bun test before opening a PR

Commit & Pull Request Guidelines

  • Write commits in the imperative mood (e.g., Add Azure retry helper)
  • Reference related issues in commit bodies or PR descriptions when applicable
  • PRs should summarize behavior changes, note testing performed, and include relevant context
  • Keep commits focused and atomic when possible

Configuration & Secrets

  • Use environment variables or VS Code settings for configuration (no secrets in code)
  • API keys and credentials must never appear in config files or Git history
  • Template files in src/vscode/subagent_template/ should remain generic and not contain user-specific data

Dependencies & Package Management

  • Use Bun for package management (Bun 1.3.3+)
  • Keep dependencies minimal and well-justified
  • Prefer stable, well-maintained packages
  • Document any platform-specific dependencies or requirements
  • Bun provides faster installs, better disk space efficiency, and built-in TypeScript support

TypeScript Configuration

  • Target ES2022 for modern JavaScript features
  • Enable strict mode for type safety
  • Module resolution: Node with ESM imports
  • Output directory: dist/
  • Include source maps for debugging

Quality Assurance Workflow

After making any significant changes (refactoring, new features, bug fixes), always run the following verification steps in order:

  1. bun run build - Ensure code compiles without errors
  2. bun run typecheck - Verify TypeScript type safety
  3. bun run lint - Check code style and catch potential issues with Biome
  4. bun test - Run all tests to verify functionality

Only consider the work complete when all four steps pass successfully. This ensures code quality, prevents regressions, and maintains the integrity of the codebase.

Template File Handling

  • Template files must be copied to dist/vscode/subagent_template/ during build
  • Use the cpx package in the build script to ensure templates are bundled
  • The DEFAULT_TEMPLATE_DIR constant in constants.ts must resolve to the correct location

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/docs/openspec/AGENTS.md when the request:

  • Mentions planning or proposals (words like proposal, spec, change, plan)
  • Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
  • Sounds ambiguous and you need the authoritative spec before coding

Use @/docs/openspec/AGENTS.md to learn:

  • How to create and apply change proposals
  • Spec format and conventions
  • Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.