# international-press-zone Plugin

Audience: AI coding agents first.

## Agent

All implementation tasks MUST load `.claude/agents/expert.md` as the primary agent.

The agent defines:
- Which skills to load per task type (task mapping)
- Release gates that must pass before any commit
- Build commands for the project

## Skills

Skills live in `.claude/skills/` and contain all coding rules, patterns, and mistakes-to-avoid for their domain. The agent selects which skills to load based on the task.

When delegating to subagents, always include `Follow .claude/agents/expert.md` as the first line of the prompt.

## Incremental Delivery

Use trunk-based delivery. Split work into smallest independently verifiable tasks. Parallelize only non-overlapping files and state; keep dependencies/conflicts sequential.

Per task:
1. Define acceptance, affected files, activation state, rollback.
2. Implement frozen scope. NEVER refactor, clean baselines, mass-format, or redesign unrelated infrastructure.
3. Run affected deterministic gates only; reuse valid receipts.
4. Run independent code/security review; fix confirmed blockers.
5. Commit, then immediately land and push to `origin/master` through repository delivery controller. Worktree commit is NOT done.
6. Record concrete evidence in durable plan: command results, commit/push receipt, install/runtime result, URL/screenshots where applicable, activation state, and tested or mechanically validated rollback. Continue automatically.

Incomplete/risky user-facing behavior MUST use server-enforced temporary flag, default OFF. Use project's single canonical server-side feature-flag primitive. NEVER create competing flag systems or scattered direct option/environment checks. Give each independently releasable feature its own stable flag key; share a key only when components MUST activate and roll back as one unit. Backend/PHP is authority; frontend may read resulting state but MUST NOT decide access. Missing, invalid, or unreadable state MUST fail closed to OFF. Each flag MUST record owner, purpose, rollout state, kill switch, and removal task. Disabled means zero route, write, API, scheduled-job, or visible-UI effect; CSS hiding is forbidden. NEVER flag security fixes, tests, internal tooling, compatible API additions, or dormant schema preparation. Test flags locally; activate only after complete install/runtime/browser journey passes. Stage staff → limited users → everyone where supported; preserve kill switch; remove flag after rollout.

Database changes MUST use expand–migrate–contract: add compatible schema → deploy dual-state code → migrate/verify → enable → remove obsolete schema in later verified release. NEVER combine destructive removal with initial deployment.

Preserve dirty WIP. NEVER reset, stash, clean, or overwrite another session. Each task MUST declare a blocker investigation limit before work starts; when reached, record exact failure and use established path. NEVER invent bypass.

WordPress runtime/browser verification: canonical local `devzone-wordpress` only. Browser MUST use `e2e-remote`. NEVER test, smoke, or otherwise verify against `dev1.danzigeronline.com`, `dev3.press.zone`, `devzone-wordpress-snappy`, or any remote/client WordPress — those are customer environments and a blind deploy in place of local verification has broken them before. Local verification MUST pass first.

## Deploy to dev1

Deploying to dev1 is permitted once local verification has passed. Do NOT ask the owner how to deploy; use the script:

```
node tools/build-distribution.mjs            # writes dist/international-press-zone-<version>.zip (refuses on a dirty tree)
node tools/deploy-dev1.mjs dist/international-press-zone-<version>.zip
```

`deploy-dev1.mjs` re-verifies the archive, authenticates to https://dev1.danzigeronline.com, uploads/replaces the plugin, activates it, and verifies the deployed assets. Credentials come from `/home/user/Projects/Press.zone/.secrets` — the script reads them itself; never print or copy them. Deploy only what is on `origin/master`. Never run tests against dev1 afterwards.

## Build

- Admin JS/CSS: `cd admin && npm run build`

## Tests

- E2E: `tests/e2e/` (Playwright)
- Run Playwright only inside `e2e-remote`; NEVER invoke `npx playwright test` directly on workstation.