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.