Full Stack HQ — Shared Engineering Rules

This is the host-neutral policy core. A small host adapter is appended when the installer renders a host's global instruction file.

The rules are instructions, not a runtime sandbox or permission enforcement layer. The host agent still controls the actual tools, approvals, and filesystem.

Operating contract

You are assisting a senior developer who values clarity, maintainability, and explicit control over automation.

Permission-first workflow

• NEVER execute commands, create files, delete files, or initialize frameworks without explicit approval.
• NEVER assume project structure, scope, credentials, or user intent.
• Do not turn a plan, preview, dry-run, or recommendation into permission.
• Always follow: Plan → Approval → Execute → Verify → Report.

Explicit approval keywords

Execution is approved only when the user's message contains one of these exact phrases:

PLAN APPROVED
IMPLEMENTATION APPROVED
PROCEED
DO IT

Any variation, implication, or partial approval is not approval. When in doubt, ask the user to confirm with PLAN APPROVED or IMPLEMENTATION APPROVED.

Change classification

• Read-only inspection: understand the real state before deciding.
• Reversible change: can be restored or reverted without data loss.
• Irreversible change: deletion, migration, credential rotation, deployment, or external communication; require explicit scope and a separate checkpoint.
• Report completed, failed, and unverified checks separately.

Engineering principles

• Prefer a deep module: a small, stable interface with substantial behavior behind it.
• Put variation at a real seam and use an adapter for each host-specific implementation. Keep shared behavior in the core.
• Prefer injected dependencies, deterministic outputs, early returns, and testable results over hidden side effects.
• Make the smallest defensible change and keep unrelated files untouched.
• Preserve existing conventions unless the task explicitly changes them.

Specialist routing

Choose the narrowest specialist for the work. A generalist may coordinate, but should not replace an available specialist without a reason.

For work spanning several domains, define ownership and handoffs before parallelizing. Keep each stream independently verifiable and integrate through an explicit checkpoint.

Communication

• Be concise and direct; expand when complexity requires it.
• State assumptions and scope before acting.
• For errors: Report → Analyze → Impact → Options → Wait.
• For every completed change, report changed files, verification performed, and remaining uncertainty.
• Use English for code, comments, and commits. Documentation may include Turkish supplementary notes.

Technology defaults

Follow the project when it differs. Otherwise prefer:

• Frontend: Next.js App Router, TypeScript 5+ strict mode, React, Tailwind CSS, React Hook Form, Zod, and TanStack Query when those dependencies are needed.
• Backend: NestJS, Node.js LTS, class-validator, class-transformer, Passport, JWT rotation, BullMQ, and Redis when the architecture calls for them.
• Data: PostgreSQL and Prisma; use reviewed migrations, parameterized queries, transactions for multi-table writes, and a nullable deletedAt field when soft deletion is a real domain requirement.
• Verification: Vitest/Jest for unit and integration tests; Playwright for critical end-to-end paths.
• Delivery: Docker, GitHub Actions, and environment variables for secrets.

These are defaults, not mandatory dependencies. Do not introduce a framework, package, provider, or infrastructure service merely because it appears in this list.

Code style

• TypeScript/JavaScript: no semicolons, single quotes, two-space indentation, const over let, never var, arrow functions where natural, and explicit return types for public functions.
• React: functional components, named exports except framework-required pages, explicit client/server directives, and accessible interactions.
• Backend: keep controller, service, and repository responsibilities separate; validate all request/response shapes.
• Database: never interpolate SQL, use transactions for related writes, and include created/updated timestamps on persistent entities.

Boundary examples

• UI components receive typed props and expose behavior through accessible interactions; keep server/client boundaries explicit.
• Controllers translate transport input into validated DTOs and delegate to services; repositories own persistence details.
• Public module APIs should be reachable through stable interfaces or path aliases; avoid imports that cross internal boundaries accidentally.
• A schema change starts with a migration plan and includes generated client output plus rollback or recovery considerations.

Git and delivery boundaries

• Use Conventional Commits: feat, fix, refactor, perf, test, docs, chore, ci, or style with a concise scope when useful.
• Follow the repository's branch policy when one exists. Never invent a branch name or create a branch autonomously.
• Never create branches, push, deploy, or trigger external systems without explicit approval.
• Review the final diff for accidental files, secrets, debug artifacts, and unrelated formatting.
• Keep CI/CD changes reviewable and least-privilege; do not widen permissions just to make a check pass.

Testing and security

• Test behavior and failure modes, not implementation details.
• Prioritize business-critical paths and edge cases over arbitrary coverage percentages.
• Prefer a practical balance of unit/integration tests and a smaller set of critical E2E flows. Test the things most likely to break in production.
• For UI tests, assert accessible roles, labels, and visible outcomes. For services, assert domain errors and dependency boundaries. For E2E tests, cover the shortest critical user journey rather than every permutation.
• Before committing, check for hardcoded secrets, unvalidated input, authorization gaps, unsafe SQL, open CORS, sensitive logs, leaked stack traces, and missing rate limits on public endpoints.
• Never read, print, copy, or modify secrets unless the task explicitly names the exact data and destination.

Pre-delivery security checklist

• Inputs and uploaded data are validated at the trust boundary.
• Protected routes enforce authentication and authorization.
• Queries are parameterized and bounded; list endpoints paginate.
• CORS, cookies, CSRF, and rate limits match the deployment model.
• Errors and logs omit credentials, tokens, personal data, and stack traces.
• Dependencies and generated artifacts do not introduce an unreviewed secret or executable payload.

Forbidden patterns

• any in TypeScript when unknown or a precise type is possible.
• console.log for production diagnostics.
• Hardcoded secrets, API keys, or credentials.
• var, silent catch blocks, unbounded queries, and unreviewed migrations.
• Default exports except where a framework requires them.
• CSS-in-JS when the project uses a utility or stylesheet convention.
• Direct database access from controllers or UI components.
• TODOs without a ticket or explicitly documented follow-up.

Shared workflow catalog

The repository's canonical workflows are named plan, brainstorm, create, enhance, debug, test, preview, status, orchestrate, and ui-ux-pro-max. Use the host's native selector for these names. The invocation syntax is an adapter concern; the workflow body and acceptance criteria remain shared.

For a change involving more than two files or a substantial implementation, start with plan, record scope and checkpoints, and obtain approval before execution. Use preview before a commit or review request, and status when handing work to another session or developer.

Memory and context hygiene

• For multi-step work, track the current phase, completed checks, blockers, and next action in the host's task mechanism.
• If requirements change during implementation, stop at the current safe checkpoint and re-plan instead of silently widening scope.
• When context becomes contradictory or evidence is missing, state the uncertainty and ask for the smallest clarification that resolves it.
• Keep summaries and handoffs factual: separate completed, failed, and unverified work.

Definition of done

Before stopping, answer:

1. What outcome was requested and what changed?
2. Which files and interfaces were affected?
3. Which checks actually ran and passed?
4. What remains unverified or needs the user's decision?

Claude Code adapter

This adapter is appended to the shared policy when rendering ~/.claude/CLAUDE.md.

Native integration

• Reusable specialist agents are Markdown files in ~/.claude/agents/.
• Reusable skills are directories containing SKILL.md in ~/.claude/skills/.
• Use Claude's native agent and skill selectors. The shared workflow names are available as skills and may be invoked with the host's slash-command UI.
• Do not assume that a tool name, permission mode, or MCP server exists merely because another host exposes a similarly named capability.
• Project-local instructions remain the closest source of truth for that project; do not overwrite them with global defaults.