pdf-converter

Imported from z0zero/pdf-converter (AGENTS.md). Install upstream with npx skills add z0zero/pdf-converter. Copyright stays with the author.

Repository Guidelines

Repository State

This repository began as an empty project. It is now in established state because approved design documentation, Python configuration, source code, and tests exist. The bootstrap rules remain applicable if the project is reset or a technology choice is reopened.

Current project facts

• Purpose: local Windows PDF-to-JPG/PNG conversion for personal use.
• Runtime: Python 3.12 with FastAPI, Uvicorn, python-multipart, and PyMuPDF.
• Frontend: semantic HTML, CSS, and native JavaScript served by the same FastAPI origin.
• Start: double-click start.cmd; the service binds only to 127.0.0.1.
• Tests: .venv\Scripts\python.exe -m pytest -q.
• Lint: .venv\Scripts\python.exe -m ruff check ..
• Format check: .venv\Scripts\python.exe -m ruff format --check ..
• Temporary conversion data must stay under the application-owned system temp root and must never be committed.
• Preserve the one-job/one-page-at-a-time resource boundary unless a measured requirement justifies changing it.
• Treat upload validation, safe paths, same-origin checks, cleanup, and loopback binding as security boundaries.

Bootstrap state

Use bootstrap state while the repository is empty or the technology stack is not selected.

• Do not assume a language, framework, package manager, database, test framework, or deployment platform.
• Clarify the product goal, users, constraints, risks, and acceptance criteria before scaffolding.
• Prefer the smallest architecture that satisfies known requirements.
• Avoid speculative infrastructure, abstractions, integrations, configuration, and dependencies.
• Do not list build, test, lint, or run commands until those commands actually exist.
• Record approved major technology and architecture choices in durable project documentation.

Established state

Use established state after source code and configuration exist. Before changing code, inspect the relevant source, manifests, tests, configuration, documentation, and recent Git history. Use only commands and paths verified from the repository. Follow existing patterns unless evidence justifies changing them. Update this file when stable project conventions become known.

Project Overview and Verified Conventions

This project is a local, everyday-use PDF-to-image web application. Its approved scope accepts multiple PDFs, converts selected one-based page ranges to JPG or PNG, and provides individual image downloads plus ZIP archives. It must remain local-only: bind the application to 127.0.0.1, do not add cloud storage or outbound network calls, and treat uploaded documents and generated output as private user data.

The approved target architecture is a FastAPI backend with PyMuPDF for document rendering and a native HTML, CSS, and JavaScript frontend. Python dependencies are pinned in requirements.txt; development-only dependencies are in requirements-dev.txt. Do not add a database, frontend framework, cloud service, telemetry service, or new dependency unless an approved requirement justifies it.

Verified repository areas are:

• pdf_converter/: Python application package and domain logic.
• tests/: pytest regression tests.
• docs/superpowers/specs/: approved product and architecture specifications.
• docs/superpowers/plans/: binding implementation plans.

The current verified local setup, run, and checks on Windows PowerShell are:

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.venv\Scripts\python.exe -m pytest
.venv\Scripts\python.exe -m ruff check pdf_converter tests
.venv\Scripts\python.exe -m ruff format --check pdf_converter tests
.venv\Scripts\python.exe bootstrap.py

Use Python 3.12-compatible code. Pytest configuration and Ruff rules live in pyproject.toml. There is no verified build command, database, migration workflow, CI/CD pipeline, or deployment process. Do not document or assume one until it exists. start.cmd is the verified Windows double-click launcher; it creates .venv when absent, runs bootstrap.py, installs pinned runtime requirements only when their digest changes, and starts the loopback-only service.

Preserve the approved contracts: page ranges are one-based, ascending, bounded, and reject duplicates; job and file identifiers exposed through interfaces are opaque; invalid PDFs and conversion failures must produce explicit errors; temporary files require bounded cleanup; accessibility and Indonesian user-facing text are product requirements, not optional polish.

Instruction Precedence

Apply instructions in this order:

1. Explicit instructions from the user.
2. The nearest applicable nested AGENTS.md.
3. This root AGENTS.md.
4. Approved specifications, architecture decisions, and repository documentation.
5. Superpowers lifecycle instructions.
6. Agent Skills specialist guidance.
7. Ponytail minimalism guidance.
8. General engineering defaults.

A nested AGENTS.md may add module-specific rules but should not silently contradict root-level safety rules. Specialist skills must not replace or reorder the Superpowers lifecycle. Ponytail must never override explicit requirements, security controls, accessibility, data-integrity protection, required testing, or verification.

Core Engineering Principles

• Understand the requirement and trace the affected flow before editing.
• Solve the root cause rather than only the visible symptom.
• Make the smallest coherent change that fully satisfies the requirement.
• Reuse existing code and established patterns; avoid speculative abstractions and dependencies.
• Preserve backward compatibility unless a breaking change is approved.
• Validate input at trust boundaries. Protect secrets, user data, and destructive operations.
• Keep changes reviewable and independently verifiable.
• Never claim completion without fresh verification evidence.
• Never run destructive Git, database, infrastructure, or deployment commands without explicit authorization.

Skill Orchestration

One lifecycle authority

superpowers is the sole owner of development lifecycle and workflow routing. Use applicable Superpowers skills for requirements refinement, design exploration, isolated worktrees, plans, execution, subagent coordination, TDD, debugging, review, final verification, and branch integration.

Relevant exact skill names include using-superpowers, brainstorming, using-git-worktrees, writing-plans, subagent-driven-development, executing-plans, dispatching-parallel-agents, test-driven-development, systematic-debugging, requesting-code-review, receiving-code-review, verification-before-completion, and finishing-a-development-branch. Do not activate another lifecycle router alongside using-superpowers.

Agent Skills as technical specialists

Use agent-skills only for technical expertise that does not duplicate the active Superpowers workflow. Allowed specialists include context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design, browser-testing-with-devtools, security-and-hardening, performance-optimization, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, and shipping-and-launch.

Their boundaries are strict:

• context-engineering prepares relevant context; it does not plan implementation.
• source-driven-development verifies framework, API, or library choices against authoritative sources.
• doubt-driven-development may challenge a high-risk decision; it is not a second review workflow.
• UI, API, security, performance, observability, migration, and CI/CD skills provide domain checks only.
• browser-testing-with-devtools supplies runtime evidence; it does not replace final verification.
• shipping-and-launch applies to actual deployment preparation, not branch completion or Git integration.

Do not activate overlapping Agent Skills when Superpowers owns the responsibility:

Do not use agent-skills:code-simplification; Ponytail owns implementation minimalism.

Ponytail as the minimalism constraint

Use the core ponytail skill in full mode as an implementation constraint, not a lifecycle router. After understanding the task and affected flow, apply this ladder:

1. Does the requested capability need to exist?
2. Does an equivalent capability already exist in the project?
3. Can the language standard library handle it?
4. Can a native platform feature handle it?
5. Can an already-installed dependency handle it?
6. Can the solution be expressed clearly with less code?
7. Only then write the minimum new implementation required.

Ponytail may reduce unnecessary files, duplicated helpers, speculative abstractions, dependencies, boilerplate, premature configuration, and custom implementations already covered by the platform. It must not reduce required tests, security protections, accessibility, trust-boundary validation, data-loss prevention, required error handling, approved requirements, necessary observability, or verification evidence.

Do not use ponytail-review or ponytail-audit as parallel workflows. The core ponytail skill may remain active while Superpowers owns workflow and Agent Skills provide specialist guidance.

Skill selection rule

For every task select exactly one Superpowers workflow owner, Ponytail for coding decisions, zero or more non-overlapping Agent Skills specialists, and one explicit verification path. Do not invoke skills mechanically. Internally identify the workflow owner, each specialist's narrow responsibility, why scopes do not overlap, and the evidence required for completion.

Task Classification

Trivial task

Examples (not current repository facts): a typo, comment correction, or one-line configuration adjustment with no behavioral risk. Inspect the target, apply Ponytail, make the smallest change, and run the narrowest relevant check. Do not force a full planning lifecycle.

Small, well-defined task

Examples: a localized defect or clearly specified behavior change. Use Superpowers systematic-debugging for defects and test-driven-development when behavior changes. Add specialists only for a real domain concern. Verify affected behavior and nearby regression risk.

Complex task

A task is complex when ambiguous, architectural, multi-module, multi-file, externally integrated, or likely to need several implementation steps. Use this lifecycle:

1. brainstorming
2. Design approval
3. using-git-worktrees when Git and a baseline commit are available
4. writing-plans
5. subagent-driven-development or executing-plans
6. Superpowers TDD during implementation
7. Applicable Agent Skills specialists
8. Superpowers code review
9. verification-before-completion
10. finishing-a-development-branch

Do not pretend worktree isolation exists when the directory is not a Git repository or lacks a usable baseline commit.

High-risk task

Authentication, authorization, payments, secrets, personal data, destructive migrations, public APIs, concurrency, production infrastructure, and irreversible operations are high risk. In addition to the Superpowers workflow, use relevant security, API, migration, observability, or source-driven specialists. Validate assumptions against authoritative documentation, test failure paths, include rollback or recovery considerations, and require stronger completion evidence.

Planning and Implementation Rules

Require plans for complex or high-risk work. Include goal and non-goals, verified assumptions, affected components, ordered tasks, exact files when known, dependencies, acceptance criteria, verification commands, and relevant security, migration, or rollback concerns.

During implementation, stay within approved scope, avoid unrelated cleanup, preserve behavior outside the request, and update tests with behavior. Stop and re-plan when evidence invalidates the plan. Never silently expand scope.

Testing and Verification

Tests are evidence, not ceremony. Run the narrowest relevant test during iteration and broader regression checks before completion. Run formatting, linting, type checking, builds, and tests when configured. Use runtime or browser checks when static checks cannot prove behavior, and test failure paths for high-risk logic. Never invent commands.

If no automated test system exists, use the smallest reproducible validation available, document what was checked, and limit confidence to that evidence. Before declaring success, report files changed, behavior implemented, commands or checks run, relevant results, anything unverified, and remaining risks or follow-up work.

Git and Change Safety

• Inspect status and diff before editing or finishing; never overwrite unrelated user changes.
• Do not force-push, hard-reset, destructively clean, or rewrite history without explicit approval.
• Keep commits focused when commits are authorized.
• Never push, merge, deploy, or delete remote resources without explicit user instruction.
• Use worktrees for non-trivial isolated work when the repository supports them.
• Keep generated files and dependency lockfiles consistent with approved tool usage.

Keeping This Guide Current

This universal file is a starting point. After scaffolding, update it with verified facts about project purpose, directory structure, language and framework, package manager, local development and build commands, formatter and linter, test frameworks, database and migration commands, environment-variable handling, CI/CD, deployment, naming, and architecture conventions.

Never replace verified project facts with generic assumptions. Nested modules may add an AGENTS.md when they require distinct commands or conventions.