career-copilot

Imported from xhuandy666/career-copilot (AGENTS.md). Install upstream with npx skills add xhuandy666/career-copilot. Copyright stays with the author.

AGENTS.md

This file is for Codex, AI coding agents, and human collaborators working in this repository.

Scope: these instructions apply to the entire repository unless a more specific AGENTS.md is added in a subdirectory.

Start Here

Before making code changes, read:

• README.md
• docs/index.md
• docs/vision.md
• docs/roadmap.md
• docs/architecture.md
• docs/engineering-plan.md
• docs/contributing.md
• docs/testing-strategy.md
• docs/risks-and-tech-debt.md
• docs/adr/

When working on Web/API/product UI, also read:

• PRODUCT.md
• DESIGN.md
• docs/v0.2-frontend-architecture-and-design.md

After reading, briefly summarize:

• current project direction
• key engineering rules
• modules affected by the task
• verification plan

Do this before modifying code, unless the task is a tiny documentation-only change.

Project Direction

Career Copilot Agent is a long-term job-search agent/workbench for AI, Agent, LLM application, RAG, and engineering-oriented algorithm internship candidates.

Current MVP:

• CLI commands: career-agent project, profile, interview, all
• LangGraph Studio graphs: project_research_graph, profile_targeting_graph, interview_prep_graph
• Core modules: project research, resume/profile targeting, interview preparation
• LLM providers: OpenAI, Anthropic, DeepSeek, Qwen, Kimi, OpenRouter, Ollama, LMStudio, custom OpenAI-compatible

Accepted direction:

• V0.2 Web workbench will use Next.js + FastAPI.
• Keep the Python career_agent package as the reusable business/agent core.
• Continue the rule: no configured LLM means no generated report.
• Storage is not finalized yet. Prefer SQLite-first, PostgreSQL-ready unless a design/ADR says otherwise.

Non-Negotiable Rules

• Do not hardcode user-specific target role, time budget, taste, run depth, company scope, model, or provider.
• Do not generate fake/template/offline heuristic reports when no LLM is configured.
• Do not claim real-time job openings, hiring probabilities, or guaranteed outcomes.
• Treat resumes, JDs, user profiles, interview feedback, and application records as sensitive data.
• Do not commit API keys, secrets, real resumes, private JDs, or personal user data.
• Do not revert unrelated user changes in the working tree.

Ask Before These Changes

Pause and ask for confirmation before:

• large refactors
• deleting files or removing legacy modules
• adding major dependencies
• changing database schema or persistence strategy
• changing core LangGraph graph architecture
• changing CLI argument names or report file formats
• changing the "LLM required" product decision

Low-risk documentation, tests, small bug fixes, and local consistency improvements can proceed directly.

Architecture Rules

• Keep entrypoints thin: CLI, Studio, and future FastAPI routes should call shared business services.
• Keep defaults in career_agent.defaults, not scattered through prompts or handlers.
• Keep LLM provider logic in career_agent.llm.
• Keep structured task prompting and schema expectations in career_agent.llm_tasks.
• Validate LLM outputs before writing reports or returning API responses.
• For judgment-heavy Agent behavior, do not let keyword-only heuristics stand in for semantic understanding. Use deterministic rules for evidence collection, guardrails, and validation; use LLM-backed structured tasks for user-fit reasoning, project understanding, ranking rationale, and modification planning.
• For project discovery, GitHub/search modules should produce real evidence and objective health signals. LLM modules may plan searches, profile repositories, evaluate fit, and explain rankings, but must not invent repositories, URLs, or unverified evidence.
• New modules must define inputs, outputs, configuration, failure modes, privacy impact, and tests.

Testing And Verification

Before claiming completion, run the relevant checks:

.venv/bin/python -m pytest -q
.venv/bin/ruff check src/career_agent tests
.venv/bin/langgraph validate

For documentation-only changes, at least inspect the changed Markdown and state that code tests were not necessary.

For LLM-related changes:

• use mock LLM tests in CI/local unit tests
• verify missing-provider behavior
• verify JSON parsing or schema validation
• verify exact question counts for interview generation

For future Web/API changes:

• add backend tests for FastAPI routes
• add contract tests for request/response payloads
• verify file upload, report generation, error states, and data deletion behavior

Collaboration Style

Prefer small, reviewable changes. Explain why a change is needed, what tradeoff it makes, and how it was verified.

PRs or handoff summaries should include:

• what changed
• why it changed
• files touched
• tests/checks run
• remaining risks
• decisions needed from the project owner