# Repository Guidelines

## Project Structure & Module Organization
- `bin/` contains the executable entry point (`bin/zync`).
- `lua/zync/` is the main Lua package with API modules and utilities.
- `spec/` holds Busted tests, fixtures, and stubs (organized by module).
- `rockspec/` contains the LuaRocks spec used for building and packaging.
- `Dockerfile` and `.gitlab-ci.yml` describe CI and release flow.

## Build, Test, and Development Commands
- `luarocks make $(find rockspec -name "*zync*")` builds and installs the package locally.
- `busted -c` runs the test suite under `spec/` with coverage statistics.
- `luacov` generates a coverage report.
- `zync --help` shows CLI usage and available commands (build, flash, run, etc.).
- `luacheck lua/` lints for errors and inconsistencies in the codebase.

## Coding Style & Naming Conventions
- Use 4-space indentation for Lua code (see `lua/zync/` for patterns).
- Prefer module-style tables with clear file-level headers (e.g., `zync.lib.utils`).
- Name tests with `_spec.lua` and keep fixtures in `spec/fixtures/`.
- `stylua` formatter is configured; use it to format any changed files.

## Testing Guidelines
- Tests are written with Busted. Run `busted -c` from the repo root.
- Add tests alongside related modules (e.g., `lua/zync/lib/utils.lua` -> `spec/lib_spec/utils_spec.lua`).
- Keep fixtures minimal and focused; prefer stubs over heavy integration.
- Configured with `luacov` to generate coverage reports.
- Aim for 90%+ test coverage; however, prioritize meaningful tests over shallow line hits.

## Commit & Pull Request Guidelines
- Commit history is short, descriptive, and informal (e.g., "Updated readme", "Fixed run").
- Use concise, present-tense summaries and include the affected area when helpful.
- PRs should include a brief description, testing notes (`busted` output or rationale), and doc updates for user-facing changes.

## Configuration & Safety Notes
- `zconf.lua` can execute Lua code; it is sandboxed by default but can be unsafe with `--unsafe`.
- Avoid introducing new dependencies unless they are listed in the rockspec and justified.

<!-- BACKLOG.MD MCP GUIDELINES START -->

<CRITICAL_INSTRUCTION>

## BACKLOG WORKFLOW INSTRUCTIONS

This project uses Backlog.md MCP for all task and project management activities.

**CRITICAL GUIDANCE**

- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).

- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work

These guides cover:
- Decision framework for when to create tasks
- Search-first workflow to avoid duplicates
- Links to detailed guides for task creation, execution, and finalization
- MCP tools reference

You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.

</CRITICAL_INSTRUCTION>

<!-- BACKLOG.MD MCP GUIDELINES END -->
