---
applyTo: "**"
---

# General Coding Instructions — CoM Virtual Enterprise

## Language Priorities

This repo primarily contains Markdown, JSON, Shell (Bash), Python, and YARA.
The parent project (Syn_OS) is Rust-first with 92+ crates.

## Formatting Rules

- Indentation: 2 spaces for JSON/YAML/HTML, 4 spaces for Python, tabs for Makefiles
- Line endings: LF (Unix-style) — never CRLF
- Max line length: 100 characters for code, 120 for markdown prose
- Trailing whitespace: strip on save
- Final newline: always include

## Naming Conventions

- Agent files: `kebab-case.md` (e.g., `cto-alfred.md`, `os-architect-advisor.md`)
- Skill directories: `kebab-case/` with `skill.md` entry point
- Hook scripts: `kebab-case.sh` with descriptive names (e.g., `pre-tool-validate.sh`)
- JSON configs: `camelCase` keys internally, `kebab-case` filenames
- Environment variables: `SCREAMING_SNAKE_CASE`

## Documentation Standards

- Every directory must have a README.md or equivalent entry doc
- Agent files follow the standard personality template (role, archetype, shadow, capabilities, constraints)
- Skills follow the standard skill template (description, usage, agents involved, example output)
- All configs must have inline comments explaining non-obvious values

## Error Handling

- Shell: Use `set -euo pipefail` and trap ERR for cleanup
- Python: Use specific exception types, never bare `except:`
- JSON: Validate against schema before writing to production configs
- Always fail loudly — silent failures are the enemy

## Git Workflow

- Branch naming: `type/short-description` (e.g., `feat/websocket-daemon`, `security/hook-update`)
- Conventional Commits enforced: `type(scope): description`
- Never force-push to master
- Squash-merge feature branches for clean history
- Tag releases with semver: `v1.0.0`

## Dependencies

- Minimize external dependencies — prefer stdlib
- All new dependencies require supply chain audit
- Pin exact versions in requirements files
- Document why each dependency exists in a comment