Imported from Ouonnki/PicOK-Image-Hosting (AGENTS.md). Install upstream with npx skills add Ouonnki/PicOK-Image-Hosting. Copyright stays with the author.

Repository rules

PicOK is currently a docs-only, pre-code repository. Keep changes narrow and traceable to source documents.

Source precedence

1. docs/PRD.md is product source of truth.
2. docs/DESIGN.md must follow PRD scope and constraints.
3. docs/IMPLEMENTION.md must follow PRD and design.
4. docs/history/Plan.md is historical context only.

If documents conflict, update lower-precedence docs or stop and request review. Never expand P0 from historical plan alone.

Change workflow

1. Read relevant docs before editing.
2. Preserve document intent, technical decisions, API contracts, and acceptance criteria unless task explicitly asks to change them.
3. Update only docs affected by change.
4. Keep same relative link style inside docs/: PRD, DESIGN, IMPLEMENTION same directory; historical plan under history/.
5. After moving docs, update only path references caused by move.

Implementation collaboration

1. Read the current phase record in docs/implementation-records/ before any phase work.
2. Keep execution steps, live TODOs, acceptance criteria, evidence, validation log, feedback log, and user acceptance fields updated while work happens.
3. Keep docs/implementation-records/README.md and the phase record in sync when execution workflow, status, or record location changes.
4. User acceptance stops phase progression. Don't start the next phase, create its code, or create its configuration until the current phase record is accepted.
5. User feedback stays in the same phase record. Apply changes there, revalidate, update evidence, then request acceptance again.
6. These rules don't change source precedence or P0 scope control. docs/PRD.md remains product source of truth, and excluded P0 work still needs PRD review first.

P0 scope control

P0 excludes OAuth, GitHub App, database, queue, multi-user, multi-tenant, user registration, roles, repository selection, repository creation, SVG, batch upload, paste upload, recursive delete, image preview modal, conversion, compression, crop, CDN refresh, private-repo public delivery guarantee, and performance or SLA promises.

Any change adding these needs PRD review before design or implementation docs change.

Document update triggers

Update docs/PRD.md when product scope, goals, constraints, API behavior, security requirements, deployment variables, acceptance criteria, or non-goals change.

Update docs/DESIGN.md when architecture, API design, server/client boundary, security model, type model, UI state model, or error mapping changes.

Update docs/IMPLEMENTION.md when delivery order, phase dependencies, test strategy, validation matrix, or implementation file expectations change.

Do not edit docs/history/Plan.md except for historical preservation or path-only maintenance.

TDD and validation expectations

When code exists, write or update tests before implementation where practical. Run actual configured checks from repository files. Do not invent command names, package scripts, CI, or config files in docs-only changes.

For docs-only changes, verify Markdown paths and review diffs for unintended content edits.

Secrets

Never add real tokens, passwords, cookies, PATs, private keys, session secrets, or full sensitive request examples. Environment variable names are allowed; values are not.

Project OpenCode Configuration

.opencode/ stores project-local OpenCode configuration and shared skills. Follow .opencode/README.md; validate any configuration against https://opencode.ai/config.json before committing it.

AGENTS.md hierarchy

Do not create child AGENTS.md files until real module-specific directories exist with rules different from this root file.