Imported from asif-reh/punk (AGENTS.md). Install upstream with npx skills add asif-reh/punk. Copyright stays with the author.

AGENTS.md — Punk Engineering Contract

This document is the operational contract for all engineering work (human or AI agent) on Punk. It is intentionally concise and practical. When in doubt, this file wins over assumptions.

1. Product definition

Punk is an evidence-first AI search engine for developers, AI engineers, founders and technical decision-makers. It answers technical questions with citation-backed, evidence-grounded answers rather than generic chat responses.

2. Current MVP scope

The MVP flow is limited to:

1. User submits a technical question.
2. Punk searches trusted web sources.
3. Punk retrieves and cleans source content.
4. Punk generates an evidence-backed answer.
5. Important claims include citations.
6. The interface displays the answer and source cards.

Everything beyond this (claim verification, contradiction detection, Compare Mode, Evidence Graph, Build Mode, saved research monitoring/Punk Watch) is planned only and must not be implemented ahead of its ticket.

3. Planned technology stack

• Frontend: Next.js, TypeScript, App Router, Tailwind CSS.
• Backend: Python 3.12, FastAPI, Pydantic.
• JS package manager: pnpm.
• Python dependency manager: uv.
• Database: PostgreSQL.
• Cache: Redis.
• Vector database: Qdrant.
• Local infrastructure: Docker Compose.

No component of this stack is installed or scaffolded until its corresponding ticket.

4. Repository conventions

• Monorepo layout: apps/ (deployable applications), packages/ (shared libraries), docs/ (engineering documentation), infra/ (infrastructure-as-code and local infra config), scripts/ (dev/ops scripts).
• Punk is built as a modular monolith for the MVP. No microservices.
• Every ticket has an ID (e.g. PUNK-000A) tracked in docs/TASKS.md. Work must map to an active ticket.

5. Backend and frontend engineering standards

• Keep HTTP handlers thin — parsing, validation, and delegation only.
• Put business logic in services, not in route handlers or React components.
• Validate all external data (requests, provider responses) through typed schemas (Pydantic on backend, TypeScript types/zod on frontend).
• Prefer explicit, readable code over clever abstractions.

6. External-provider adapter requirements

• All external search, extraction, and model vendors must be accessed through provider interfaces (e.g. SearchProvider, ContentExtractor, ModelProvider), never called directly from business logic.
• Swapping a vendor must only require a new adapter implementation, not changes to calling code.

7. Error-handling and secret-management requirements

• Add explicit timeouts and error handling to every network call.
• Never expose secrets (API keys, tokens, credentials) in source code, commits, or logs.
• Never silently swallow exceptions — log or propagate with context.

8. Testing expectations

• New backend logic requires unit tests for services and provider adapters.
• New frontend logic requires component/unit tests where behavior is non-trivial.
• Tests must be runnable locally before a ticket is considered done.

9. Git safety requirements

• Never commit automatically.
• Never push automatically.
• Never modify files unrelated to the active ticket.
• Never force-push or rewrite shared history.

10. Agent workflow before editing

1. Identify the active ticket in docs/TASKS.md.
2. Inspect only the files relevant to that ticket (existing code, docs, rules, git status).
3. Report: relevant files found, files to be created/modified, a short implementation plan, and any blocking assumptions.
4. Proceed only within the ticket's declared scope.

11. Agent workflow after editing

1. Re-read changed files to confirm correctness.
2. Run relevant tests/linters/validation commands.
3. Run git status and git diff to confirm no unrelated changes.
4. Report files changed, validation results, and remaining issues.

12. Definition of done

A ticket is done when:

• All files listed in the ticket's scope exist and match its requirements.
• No unrelated files were created or modified.
• No functionality beyond the ticket's scope was implemented.
• Validation commands were run and results reported.
• The agent stops and does not proceed into the next ticket without explicit instruction.