| name | paperecho-workflow |
| description | use when implementing, modifying, auditing, or debugging PaperEcho shared or cross-path behavior across Desktop, Web, and Local, including deterministic execution contracts, Stage1-Stage5, shared literature identity/index, Local state, title translation, Stage5 email, housekeeping/retention, and cross-path regression validation. |
PaperEcho Workflow
Treat PaperEcho as one shared domain workflow with three boundary adapters. Preserve correctness, idempotency, recovery, user data, and existing work before optimizing or adding code. Treat existing PAPERFLOW_* environment variables and internal lowercase paperflow identifiers as compatibility interfaces, not as the current product brand.
Start Here
- Read the repository root
AGENTS.md before acting.
- Run
git status --short; separate the requested scope from existing .planning/**, runtime data, caches, and user edits.
- Locate the owner with targeted
rg searches. Read the owner, direct callers, and nearest tests only.
- Classify the change before editing:
- Shared semantics belong in the shared Stage or library owner.
- Desktop CLI/JS bridge behavior belongs in the Desktop adapter.
- Web API HTTP, version, batching, and rate-limit behavior belongs in the Web adapter.
- Local import, snapshots, feedback, timings, and output layout belong in the Local adapter.
- Reuse the existing owner and test pattern. Do not add a second index, formatter, sender, cache, or path-specific Stage copy.
Progressive Loading
- Architecture or cross-path work: read architecture.md.
- Stage responsibility, inputs, outputs, or gates: read stage-contracts.md.
- Dedupe, identity, state, cache, or migration work: read identity-and-storage.md.
- Email, overview, attachments, receipt, or resend work: read stage5-email.md.
- Retention, run groups, path safety, or ephemeral cleanup work: read housekeeping.md.
- Before validation or commit: read validation.md.
- Production execution, preflight, continue, result validation, or exit codes: read execution.md.
Read only the references needed for the task. All references are one level below this file.
Execution Boundary
This skill owns the shared execution contract, not a second pipeline invocation. When a path Skill handles an explicit production request, it must invoke its own deterministic launcher exactly once; that launcher delegates to the shared Runner, which invokes the real Stage0 or Local entry exactly once after preflight. Do not invoke this main skill as an additional command, auto-switch paths, or rerun the production entry outside the Runner.
Unified Configuration
- Use the single schema v1 resolver in
workflow/tools/runner/config_loader.mjs. The user template is config/paperecho.config.example.json; the real config/paperecho.config.json stays local and gitignored.
- Keep settings partitioned as
common, desktop, web, and local. A path Skill reads only common plus its own section and fixes its own mode.
- Precedence is CLI -> unified config -> environment/
.env -> existing domain config/defaults. Never infer mode from secret/backend residue.
- Store only secret environment-variable names in JSON and report presence, never values. Do not duplicate full field tables here; use the configuration guide.
Implementation Loop
- State the current owner, intended minimum change, likely files, and path-specific risks.
- Trace every caller of a shared function before changing it; fix the shared cause once.
- Keep adapter details outside shared stages and keep Local outside all Zotero boundaries.
- Preserve schema compatibility, atomic writes, locks, idempotency, and failure degradation.
- Add or adjust the smallest test that would fail if the requested behavior regressed.
- Run the closest targeted validation first. Never use a real Zotero, SMTP, LLM, or external write unless the user explicitly authorizes it.
- If validation fails, use the first key error for one minimum repair and rerun the same check. If it still fails, stop and do not commit.
Commit Gate
Commit only when the requested outcome and required targeted checks pass. Stage explicit files or hunks; never use git add .. Do not stage .planning/**, review_results/**, secrets, receipts, caches, previews, workbooks, benchmark output, or unrelated edits.
