diff --git a/AGENT-OPERATING-STANDARD.md b/AGENT-OPERATING-STANDARD.md new file mode 100644 index 0000000..192416e --- /dev/null +++ b/AGENT-OPERATING-STANDARD.md @@ -0,0 +1,145 @@ +# Agent Operating Standard — peptiderepo + +**Version:** 1.0.0 +**Effective:** 2026-04-14 +**Applies to:** every AI agent (Claude, Copilot, Cursor, future tools) working in any peptiderepo codebase. + +This document is the single source of truth for *how* agents must work in peptiderepo repos. It travels with the code — every repo contains a copy at its root and a `CLAUDE.md` pointer that requires reading this file before any edit. + +If this document conflicts with a per-repo `CONVENTIONS.md`, this document wins for **process**; `CONVENTIONS.md` wins for **code style**. + +--- + +## 1. The QA Gate — Non-Negotiable + +**No code reaches `main` without a signed QA verdict for its commit SHA.** + +The QA reviewer is a separate Claude subagent (the `qa-review` skill) with no prior conversation context. The agent that wrote the code cannot be the agent that approves it. This is enforced by the deploy skills — they refuse to push if no signed `APPROVE` verdict exists for the SHA being deployed. + +Verdicts are written to `qa-reviews//-.md` in the workspace root and signed with: commit SHA, reviewer model string, ISO-8601 timestamp, and verdict. + +### Verdict types + +- `APPROVE` — ship it. +- `APPROVE-WITH-P2-NOTES` — ship it; create follow-up tickets for the noted P2/P3 issues. +- `REJECT-P1` — do not ship; fix the listed issues and re-submit. +- `REJECT-P0` — do not ship; the change has a security, data-loss, or production-impact risk that must be resolved before any further work on the branch. + +### Severity definitions + +- **P0:** secrets exposure, auth bypass, data loss, production-down risk, unauthorized financial cost (e.g., uncapped LLM spend). +- **P1:** Definition-of-Done violation, missing input sanitization or output escaping, missing authorization on a sensitive action, missing test for new core logic, schema change without migration. +- **P2:** AI-readability gap (missing docblock, file >300 lines, magic value), inconsistent naming, missing `@see` cross-reference. +- **P3:** style nit, opinion-level suggestion. + +--- + +## 2. Definition of Done — every change must satisfy + +The QA reviewer runs this checklist against the diff. Any unchecked item is at minimum a P1. + +- [ ] Code follows the language/framework's standard coding conventions (per-repo `CONVENTIONS.md`) +- [ ] All input sanitized at boundary, all output escaped at render +- [ ] Authentication and authorization checks on all sensitive actions +- [ ] No hardcoded secrets — credentials live in env or config only +- [ ] All external API calls have error handling, timeout, and retry-with-backoff (max 3 retries) +- [ ] Cost/token impact documented for any AI-touching feature; budget hard-stop respected +- [ ] Unit tests for new core logic; integration tests for framework-specific behavior +- [ ] User-facing strings are translatable/localizable +- [ ] Consistent namespace/prefix on all global identifiers +- [ ] Teardown/uninstall path cleans up ALL project data +- [ ] Every new class has a preamble docblock (what / who triggers / dependencies) +- [ ] Every new public method has typed params, return type, and docblock noting side effects +- [ ] No magic methods, dynamic resolution, or clever indirection without explicit justification +- [ ] No file exceeds 300 lines (split if it does) +- [ ] `ARCHITECTURE.md` and `CONVENTIONS.md` updated if the change affects file structure, data flow, or patterns +- [ ] `@see` cross-references at top of files participating in multi-class flows +- [ ] Event/hook docblocks list known listeners and where they're registered +- [ ] Commits authored as `peptiderepo` (not `ongterence` or any personal identity) + +--- + +## 3. Git Workflow — PR-Gated, Soft-Enforced + +All four peptiderepo repos are private on the GitHub free plan, which does not support branch protection. The review gate is enforced at the agent layer via these rules. + +### Rules + +1. **Never push to `main` directly.** Every change lands via a pull request. No self-merging from agents. No force-pushing to `main`. +2. **Branch naming:** `claude/-` — e.g., `claude/cost-tracker-20260414`. +3. **Commit trailer:** every commit ends with `Agent-Session: ` so commits correlate back to the conversation that produced them. +4. **PR description template:** + - **What changed** (one paragraph) + - **Why** (motivation or incident link) + - **Risk flags** (schema changes, API contract changes, cost impact, compatibility) + - **Test plan** (what was run locally; what Terence should smoke-test after merge) + - **QA verdict path** (`qa-reviews//-.md`) +5. **Emergency push exception:** if the situation genuinely requires pushing to `main` without a PR (site down, CI broken, one-line hotfix), ask Terence in chat first. Every emergency push gets a follow-up PR for the audit trail. + +### Mechanics + +`gh` CLI is not installed in the Cowork sandbox. Use `curl` with the PAT from `.env.credentials` (workspace root). See `pr-workflow-rollout/project-instructions-addendum.md` for the exact `curl` snippet. + +--- + +## 4. Security Non-Negotiables + +- Sanitize all input at the boundary; escape all output at render. +- Authenticate and authorize every sensitive action. +- Secrets in environment/config only — never hardcoded, never committed, never exposed to the browser. +- Use a consistent namespace/prefix on all global identifiers. +- All paid-API calls happen server-side only. + +--- + +## 5. Cost-Conscious AI Integration + +Any feature that calls a paid LLM/AI API must: + +- Respect a token/dollar budget with a **hard stop** when exhausted. +- Log every call: timestamp, provider, model, prompt tokens, completion tokens, estimated cost. +- Use the cheapest model that does the job; expensive models only where required and configurable. +- Cache identical calls within a configurable window. +- Use structured output (JSON mode) when the API supports it. +- Batch where possible. +- Offer dry-run mode for user-facing operations. +- Fail with retry-and-backoff (max 3); never retry indefinitely. + +--- + +## 6. AI-Readability Requirements + +This codebase is maintained by AI agents. Code must be optimized for LLM comprehension. + +- Files under 300 lines. Split when they grow. +- Every class has a preamble: *what / who triggers / dependencies*. +- Every public method has typed params, return type, and a docblock listing side effects. +- Names are verb-noun and unambiguous (`generate_post_from_topic()`, not `process()`). +- Constants over magic values (`MAX_RETRIES`, not `3`). +- Event/hook names describe the event (`before_content_generation`, not `hook_1`). +- No clever indirection — flat, explicit call chains. +- Inline comments explain *why*, not *what*. +- `@see` cross-references at the top of files in multi-class flows. + +--- + +## 7. Documentation as Code + +Every change that touches structure or data flow must include doc updates **in the same commit**: + +- New file → add to `ARCHITECTURE.md` file tree. +- New pattern → update `CONVENTIONS.md`. +- New external integration → update `ARCHITECTURE.md` integrations section. +- Non-obvious decision → add to `ARCHITECTURE.md` "key decisions". + +Documentation that drifts from reality actively misleads the next agent. QA will reject changes that modify structure without updating docs (P1). + +--- + +## 8. When This Standard Changes + +This file is versioned. Bump the version in the header on any material change and add an entry to the changelog below. + +### Changelog + +- **1.0.0 (2026-04-14)** — initial standard, established centralized QA gate model. diff --git a/CLAUDE.md b/CLAUDE.md index 5338067..36eff98 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,79 +1,21 @@ -# Peptide Starter Theme +# Agent Bootstrap — peptide-starter-theme -WordPress theme for peptiderepo.com — a scientific peptide reference database. +**Read these files in order before making any edit:** -## Repository +1. `AGENT-OPERATING-STANDARD.md` — process rules, QA gate, Definition of Done. Required reading on every session. +2. `ARCHITECTURE.md` — this repo's structure, data flow, integrations, key decisions. +3. `CONVENTIONS.md` — this repo's code style and extension patterns. -- **GitHub**: `peptiderepo/peptide-starter-theme` (private) -- **Branch**: `main` is the production branch -- **Live site**: https://peptiderepo.com -- **Hosting**: Hostinger shared hosting +## Critical rules (full detail in AGENT-OPERATING-STANDARD.md) -## Deploy +- **No direct pushes to `main`.** PR-only. The deploy skills will refuse to push without a signed QA verdict for the commit SHA. +- **Commits authored as `peptiderepo`** (`git config user.name "peptiderepo"` / `user.email "peptiderepo@users.noreply.github.com"`). Verify before pushing. +- **Branch naming:** `claude/-`. +- **Commit trailer:** `Agent-Session: `. +- **Doc-in-same-commit:** any change to file structure or data flow must update `ARCHITECTURE.md` / `CONVENTIONS.md` in the same commit. -Push to `main` triggers GitHub Actions → rsync via SSH to Hostinger. -No CI lint step — the deploy workflow (`deploy.yml`) runs rsync directly. -LiteSpeed cache is purged automatically after deploy. +## QA gate -Theme path on server: `~/domains/peptiderepo.com/public_html/wp-content/themes/peptide-starter/` +Before any deploy, the `qa-review` skill spawns a fresh subagent to review the diff against `AGENT-OPERATING-STANDARD.md`. The verdict is written to `qa-reviews//-.md` in the workspace root and must be `APPROVE` or `APPROVE-WITH-P2-NOTES` for the deploy to proceed. -## Architecture - -This is a classic WordPress theme (no block/FSE). All styling is in `style.css` (no build step, no preprocessor). JavaScript is vanilla — no bundler. - -### Key files - -| File | Purpose | -|------|---------| -| `style.css` | All theme CSS (~44KB). Organized: reset → tokens → typography → globals → components → regions → pages → animations → a11y → dark mode → responsive | -| `functions.php` | Theme setup, script enqueueing, Customizer registration, nav walker, helper functions | -| `front-page.php` | Home page: hero section → PRAutoBlogger widget → Peptide News feed | -| `header.php` | Global header with nav, dark mode toggle, mobile menu | -| `footer.php` | 4-column widget footer with copyright | -| `archive-peptide.php` | Peptide CPT archive grid | -| `single-peptide.php` | Single peptide detail page | -| `assets/js/navigation.js` | Mobile menu and nav functionality | -| `assets/js/theme.js` | Dark mode toggle, theme utilities | - -### Template parts - -- `template-parts/content.php` — Post/page content loop -- `template-parts/content-peptide.php` — Peptide card in archive -- `template-parts/content-none.php` — Empty state - -## Coding Conventions - -- **PHP**: WordPress coding standards — tabs for indentation, Yoda conditions, braces on same line -- **CSS**: No preprocessor. Use CSS custom properties (defined in `:root`). All theme classes prefixed `.ps-` -- **JS**: Vanilla ES6+, no build step. Files in `assets/js/` must pass `node --check` -- **No `!important`** on global elements — prevents plugin conflicts -- Plugin CSS namespaces are untouched (`.pn-*` for Peptide News, `.psa-*` for Peptide Search AI, `.prab-*` for PRAutoBlogger) - -## Design System - -- **Font**: Inter (Google Fonts) with system fallback -- **Scale**: 1.125x modular, 8px grid base -- **Primary color**: `#0066CC` (light) / `#3B82F6` (dark) -- **Breakpoints**: 480px, 768px, 1024px, 1440px (mobile-first) -- **Dark mode**: CSS custom properties swap via `html[data-theme="dark"]` or `prefers-color-scheme: dark` - -## Plugin Integration - -The theme integrates with three companion plugins via shortcodes, all wrapped in `shortcode_exists()` for graceful degradation: - -1. **Peptide Search AI** (`[peptide_search]`) — AI search in hero section -2. **Peptide News** (`[peptide_news]`) — News feed on front page -3. **PRAutoBlogger** (`[prautoblogger_posts]`) — Auto-generated research articles on front page - -## Customizer Options - -Editable via Appearance → Customize: -- Hero title, subtitle, search placeholder -- Footer copyright text -- Dark mode default on/off - -## Version - -Current: **v1.3.1** (defined in `style.css` header and `PEPTIDE_STARTER_VERSION` constant in `functions.php`) - -When bumping version, update both locations. +The agent that wrote the code cannot self-approve. This is structural, not advisory.