chatgpt-mcp/TASKS.md

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: " 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: ⬜ Pending

---

Phase 2 complete. Phase 3 in progress.