# Repository Guidelines

## Project Structure & Module Organization
Use this repository as a conversion-focused toolchain with a small, testable core.

- `src/` contains the runnable implementation modules.
- `tests/` contains unit and integration tests for each converter path.
- `assets/` stores input/output fixtures used by tests and manual verification.
- `scripts/` contains one-off developer scripts (data migration, bootstrapping, local checks).
- `docs/` holds reference notes and usage examples.
- `tooling.toml` / `pyproject.toml` / `package.json` (if present) are the source of truth for local tooling.

## Build, Test, and Development Commands
- `npm run lint` (or `pnpm lint` / `yarn lint`): format/lint project files before changes.
- `npm test` (or `python -m pytest`): run automated tests.
- `npm run build` (or `python -m build`): compile/transpile and package outputs if configured.
- `npm run dev` / local script: start the converter in development mode for manual smoke testing.

Run commands from repository root after installing dependencies.

## Coding Style & Naming Conventions
- Use 2-space indentation for JS/TS, 4-space for Python, and keep line length reasonable (100–120 chars).
- Use `kebab-case` for file names (`skill-schema-updater.py`, `convert-task.ts`), `snake_case` for Python variables/functions, and `camelCase` for JS/TS variables.
- Prefer clear action-oriented function names (`convert_markdown_to_skill`, `normalize_skill_entry`).
- Apply formatter/linter hooks before committing: `prettier`, `eslint`, `ruff`, or equivalent tool configured by the project.

## Testing Guidelines
- Primary frameworks: project defaults (`pytest`/`vitest`/`jest` as configured).
- Tests should validate: normal conversion, edge cases, and failure handling.
- Naming convention:
  - Python: `tests/test_<feature>.py`
  - JS/TS: `*.test.ts` or `*.spec.ts`
- Aim for meaningful coverage of converter logic and I/O parsing paths; add regression fixtures when fixing a bug.

## Commit & Pull Request Guidelines
- Follow the existing project history if present; otherwise use Conventional Commits:  
  `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
- Keep commits scoped and one logical change per commit.
- PRs should include:
  - Brief summary and testing evidence (`npm test` / `pytest`)
  - Linked issue or rationale
  - Before/after examples for behavior changes
  - Screenshots only when output format/UI output changes.

## Security & Configuration Tips
- Never commit credentials, API keys, or raw user artifacts.
- Store secrets in local environment variables only.
- Add new config defaults conservatively and document any environment variable in `docs/`.