# Repository Guidelines

## Project Structure & Module Organization
- `projects/` holds project-specific orchestrations, with architecture notes, exported n8n workflows (`*.json`), and `.mcp.json` agent configs. Keep new project docs in PascalCase directories and update `projects/PROJECT_SUMMARY.md`.
- `scripts/` includes shell helpers for starting services and inspecting logs; keep additions POSIX compatible.
- `workflows/` is reserved for in-progress n8n exports prior to promotion into `projects/`.
- `logs/` caches session transcripts consumed by `view-agent-logs.sh`; scrub secrets before committing.

## Build, Test, and Development Commands
- `./scripts/start_servers.sh` boots the local n8n container stack, prompts for or stores the API key, and waits for both services to report healthy.
- `docker compose up -d` offers a non-interactive start; pair with `docker compose down` when shutting the stack down.
- `./scripts/view-agent-logs.sh` or `./scripts/view-agent-logs-v2.sh` tails orchestrator output; run after workflow edits to confirm behavior.
- `./scripts/clear-agent-logs.sh` resets `logs/` when capturing a fresh session.

## Coding Style & Naming Conventions
- Markdown docs: prefer sentence-case headings, hard wrap near 100 characters, and surface task context early.
- n8n exports (`*.json`): commit the pretty-printed files generated by n8n, preserving two-space indentation.
- Directory names use PascalCase for client initiatives (`AdBridge/`, `EnergyHouse/`) and lowercase kebab-case for shared utilities (`scripts/`, `workflows/`).

## Testing Guidelines
- Validate workflows in the n8n UI with the built-in “Test” or “Execute Workflow” actions before exporting.
- When using MCP tools, run `n8n_list_workflows` and `n8n_get_workflow` to confirm deployments match expectations.
- Update validation or deployment notes (e.g., `projects/*/VALIDATION_REPORT.md`) with observed results, failure handling, and next steps.

## Commit & Pull Request Guidelines
- Follow Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`) as reflected in recent history.
- Limit each commit to one logical change and include the affected agent or project in the subject when practical (`docs: update EnergyHouse validation report`).
- Pull requests should describe workflow impact, link supporting architecture docs, and attach n8n execution screenshots or tool output when UI changes apply.
- Ensure secrets are redacted from logs, JSON exports, and screenshots prior to review.

## Agent-Specific Tips
- Keep `.mcp.json` files aligned with the tool inventory exposed by `start_servers.sh`.
- Capture operational runbooks alongside new automations so Claude agents can surface them in future queries.