# TASKS.md

## Phase 0 - Repository Setup

### Task 0.1 - Create repository skeleton

Create:

- README.md
- ARCHITECTURE.md
- TASKS.md
- PROJECT_STATE.md
- AGENT_HANDOFF.md
- src/
- test/
- context/

Do not implement functionality yet.

Status: ✅ Complete

### Task 0.2 - Add package.json and dependencies

Add `package.json` with MCP SDK, OpenAI SDK, Zod, Vitest.

Status: ✅ Complete

---

## Phase 1 - Core Utilities

### Task 1.1 - Configuration loader

Create `src/config/env.js`.

Requirements:
- Read environment variables and validate OPENAI_API_KEY exists.
- Apply defaults from ARCHITECTURE.md section 13.
- Return a structured config object.
- Throw clear configuration errors for missing or invalid values.
- Use plain JavaScript validation (no Zod yet).
- Single exported `loadConfig()` function.

Create `test/config/env.test.js`.

Requirements:
- Test all default values.
- Test all custom overrides (strings, numbers, booleans).
- Test error cases: missing API key, invalid numbers, invalid booleans.
- No external dependencies in the loader.

Status: ✅ Complete

### Task 1.2 - Secret redaction utility

Create `src/utils/redact.js`.

Requirements:
- Detect likely secrets (API keys, tokens, passwords, Bearer tokens, private keys, SSH keys, PEM blocks, DB URLs with credentials).
- Replace detected secrets with `[REDACTED]`.
- Return the redacted string.

Status: ✅ Complete

### Task 1.3 - Context budget utility

Create `src/utils/context-budget.js`.

Requirements:
- Character limit checks (max total, per file, max files).
- Priority-based trimming when limits exceeded.
- Reject oversized input with safe message.

Status: ✅ Complete

### Task 1.4 - Safe logging helper

Create `src/utils/logging.js`.

Requirements:
- Minimal logging to stderr only.
- Log safe metadata (tool name, timestamp, model, input/output size, duration, success/failure, error type).
- No stack traces in logs.
- No sensitive data in logs.
- Defensive redaction of secret field names and Bearer tokens in metadata values.
- Support levels: info, warn, error, silent (invalid levels throw).

Status: ✅ Complete

---

## Phase 2 - OpenAI Integration

### Task 2.1 - OpenAI client wrapper

Create `src/openai/client.js`.

Requirements:
- Create a minimal OpenAI API client using the OpenAI SDK.
- Accept API key from configuration (never hardcoded).
- Support configurable model and temperature.
- Implement streaming via the Responses API.

Status: ✅ Complete

### Task 2.2 - Response builder

Create `src/openai/responses.js`.

Requirements:
- Build structured OpenAI Responses API payloads from tool inputs.
- Apply character budget checks before sending.
- Redact secrets using `redact()` before constructing the request.
- Never include openaiApiKey in request logs or error messages.
- Handle OpenAI API errors gracefully (authentication, rate limits, timeouts).
- Return safe advisory-formatted text responses.

Status: ✅ Complete

### Task 2.3 - Error handling and edge cases for OpenAI integration

Update `src/openai/responses.js` test coverage.

Requirements:
- Add tests for additional error kinds (timeout, unknown API status, empty response body).
- Test boundary conditions for maxOutputTokens validation (non-positive floats, non-integers, zero).
- Mock OpenAI SDK network timeout errors separately from rate-limit errors.
- Verify that no API keys or secrets are ever leaked in error messages across all tested paths.

Status: ✅ Complete

---

## Phase 3 — Tool Inputs and Prompts

### Task 3.1 - Zod input validation schemas

Create `src/tools/schemas.js`.

Requirements:
- Export `baseInputSchema` — a single `z.object({...}).strict()` for the common tool input shape (ARCHITECTURE.md §7).
- Export `validateToolInput(raw)` — returns `{ ok: true, data }` or `{ ok: false, errors }`. Never throws.
- Export `assertValidToolInput(raw)` — returns validated data or throws a `ValidationError`.
- No per-tool schemas. No toolName parameters. Unknown keys must fail via `.strict()`.

Create `test/tools/schemas.test.js`.

Requirements:
- ~26 tests covering schema, validate, and assert paths.
- Test all fields: question (required, min(1)), context, constraints, expectedOutput, projectSummary, taskSummary, relevantFiles (nested object), logs.
- Test strict mode rejects unknown keys.
- Test type rejections for each field.
- Test assert throws `ValidationError` with `.kind` and message content.
- No MCP code. No OpenAI calls. Pure Zod validation only.

Status: ✅ Complete

### Task 3.2 - Base prompt template (NEXT)

Create `src/prompts/base.js`.

Requirements:
- Export a `buildBasePrompt()` function that returns the base system prompt (ARCHITECTURE.md §11).
- The base prompt must be injected as the first message in all tool payloads.
- Must include all rules from ARCHITECTURE.md §10 and §11.
- No per-tool variations yet — that belongs to Task 3.3.

Create `test/prompts/base.test.js`.

Requirements:
- Test that the returned prompt includes all key rules from ARCHITECTURE.md §11.
- Test that the prompt is a non-empty string.
- Test that the prompt does not include tool-specific content (review/code/debug/architecture).

### Task 3.3 - ask_chatgpt prompt builder

Create `src/prompts/ask-chatgpt.js`.

Requirements:
- Export a `buildAskChatGptPrompt(input)` function that returns a tool-specific prompt for the ask_chatgpt MCP tool.
- Compose with `buildBasePrompt()` — call it internally and append the result with `---` separator.
- The final prompt has two parts: [base system prompt] + [ask_chatgpt user instructions].
- Instruct ChatGPT to answer the question directly, act as a second-opinion advisor, identify assumptions, identify risks, suggest safer approaches, state uncertainty clearly.
- Support `expectedOutput` — if provided, append "Expected output: <value>" to the task section.
- Question is required; throw TypeError when missing or empty.
- No review_plan, review_code, debug_issue, or architecture_review content yet.

Create `test/prompts/ask-chatgpt.test.js`.

Requirements:
- ~27 tests covering base composition, ask_chatgpt instructions, optional field append/omit, expectedOutput present/absent, tool-specific guard, input validation, and full integration.
- No MCP code. No OpenAI calls. Pure prompt string assertions only.

Status: ✅ Complete

### Task 3.4 - review_plan prompt builder (completed)

Create `src/prompts/review-plan.js`.

Requirements:
- Export a `buildReviewPlanPrompt(input)` function that returns a tool-specific prompt for the review_plan MCP tool.
- Compose with `buildBasePrompt()` — call it internally and append the result with `---` separator.
- Instruct ChatGPT to review a proposed implementation plan before Claude Code acts.
- Look for: missing steps, unsafe assumptions, scope creep, better sequencing, test gaps.
- No other tool prompts yet (debug_issue, architecture_review, etc.).

Create `test/prompts/review-plan.test.js`.

Requirements:
- Mirror structure of ask-chatgpt tests: base composition, review_plan-specific instructions, optional fields, expectedOutput, input validation, tool guard, full integration.

Status: ✅ Complete

### Task 3.5 - review_code prompt builder (NEXT)

Create `src/prompts/review-code.js`.

Requirements:
- Export a `buildReviewCodePrompt(input)` function that returns a tool-specific prompt for the review_code MCP tool.
- Compose with `buildBasePrompt()` — call it internally and append the result with `---` separator.
- Instruct ChatGPT to review focused code snippets, patches, or diffs.
- Look for: correctness issues, bugs, maintainability concerns, security issues, test gaps, simpler approaches.
- Request response in structured format: Issues by Severity, Suggested Fixes, Test Suggestions.
- No other tool prompts yet (debug_issue, architecture_review, etc.).

Create `test/prompts/review-code.test.js`.

Requirements:
- Mirror structure of ask-chatgpt and review-plan tests: base composition, review_code-specific instructions, optional fields, expectedOutput, input validation, tool guard, full integration.

Status: ✅ Complete

### Task 3.6 - debug_issue prompt builder (NEXT)

Create `src/prompts/debug-issue.js`.

Requirements:
- Export a `buildDebugIssuePrompt(input)` function that returns a tool-specific prompt for the debug_issue MCP tool.
- Compose with `buildBasePrompt()` — call it internally and append the result with `---` separator.
- Instruct ChatGPT to analyse errors, logs, failed tests, or stack traces.
- Look for: likely root causes, fast checks, minimal safe experiments, what not to change yet.
- Request response in structured format: Likely Causes, Fast Checks, Minimal Safe Experiments, What Not To Do Yet.
- Support `relevantFiles` and `logs` input fields.
- No other tool prompts yet (architecture_review, etc.).

Create `test/prompts/debug-issue.test.js`.

Requirements:
- Mirror structure of ask_chatgpt, review-plan, and review-code tests: base composition, debug_issue-specific instructions, optional fields, expectedOutput, input validation, tool guard, full integration.

Status: ✅ Complete

### Task 3.7 - architecture_review prompt builder (NEXT)

Create `src/prompts/architecture-review.js`.

Requirements:
- Export a `buildArchitectureReviewPrompt(input)` function that returns a tool-specific prompt for the architecture_review MCP tool.
- Compose with `buildBasePrompt()` — call it internally and append the result with `---` separator.
- Instruct ChatGPT to review architecture decisions and trade-offs.
- Look for: local vs cloud trade-offs, simplicity, maintainability, operational risk, vendor lock-in, future extension paths.
- Support `relevantFiles` and `context` input fields.
- No other tool prompts yet.

Create `test/prompts/architecture-review.test.js`.

Requirements:
- Mirror structure of ask_chatgpt, review-plan, review-code, and debug-issue tests: base composition, architecture_review-specific instructions, optional fields, expectedOutput, input validation, tool guard, full integration.

Status: ✅ Complete

### Task 3.8 - Phase 3 completion summary (NEXT)

**Phase 3 — Tool Inputs and Prompts** is now complete.

All six prompt builders are implemented and tested:

| # | Prompt Builder | File | Tests |
|---|---|---|---|
| 0 | `buildBasePrompt` | `src/prompts/base.js` | ✅ |
| 1 | `buildAskChatGptPrompt` | `src/prompts/ask-chatgpt.js` | ✅ |
| 2 | `buildReviewPlanPrompt` | `src/prompts/review-plan.js` | ✅ |
| 3 | `buildReviewCodePrompt` | `src/prompts/review-code.js` | ✅ |
| 4 | `buildDebugIssuePrompt` | `src/prompts/debug-issue.js` | ✅ |
| 5 | `buildArchitectureReviewPrompt` | `src/prompts/architecture-review.js` | ✅ |

**What Phase 3 established:**

- Prompt composition pattern: `buildBasePrompt()` → explicit `\n\n---\n\n` separator → tool-specific section.
- All builders share the same input shape, validation rules, and optional field handling.
- Guard rails in every builder: Claude Code remains executor; ChatGPT is advisory only.
- `relevantFiles` inclusion with path, language (when present), and content — omitted when absent/empty.
- Each builder passes full integration tests covering all dimensions, response structure, optional fields, and negative guards.

**What Phase 3 did NOT do:**

- No MCP tool registration yet.
- No tool handlers yet.
- No OpenAI API calls from the builders.
- No file loading, logging, or context budget within the builders.

---

Phase 2 complete. Phase 3 complete. Phase 4 next: Tool Handlers.