380 lines
16 KiB
Markdown
380 lines
16 KiB
Markdown
# 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.
|
|
|
|
### Task 4.1 - ask_chatgpt MCP tool handler
|
|
|
|
Create `src/tools/ask-chatgpt.js` and `test/tools/ask-chatgpt.test.js`.
|
|
|
|
**Requirements:**
|
|
- Export `handleAskChatGpt(input, deps)` as standalone dependency-injected function.
|
|
- Execution order: validateToolInput → loadConfig → checkContextBudget → buildAskChatGptPrompt → createOpenAIClient → sendOpenAIResponse.
|
|
- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
|
|
- If budget check fails (`ok: false`), immediately return that result — do not call buildAskChatGptPrompt or create client.
|
|
- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
|
|
- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
|
|
- 27 orchestration-only tests covering: success path, validation failure, config failure, budget failure, client creation failure, OpenAI failure, dependency call order, error handling for null/string throws, warning propagation, result shape, and short-circuit behavior.
|
|
|
|
Status: ✅ Complete
|
|
|
|
### Task 4.2 - review_plan MCP tool handler
|
|
|
|
Create `src/tools/review-plan.js` and `test/tools/review-plan.test.js`.
|
|
|
|
**Requirements:**
|
|
- Export `handleReviewPlan(input, deps)` as standalone dependency-injected function.
|
|
- Execution order: validateToolInput → loadConfig → checkContextBudget → buildReviewPlanPrompt → createOpenAIClient → sendOpenAIResponse.
|
|
- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
|
|
- If budget check fails (`ok: false`), immediately return that result — do not call buildReviewPlanPrompt or create client.
|
|
- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
|
|
- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
|
|
- Mirror 4.1 structure: ~28 orchestration-only tests covering the same test categories (success path, validation failure, config failure, budget failure, client creation failure, OpenAI failure, dependency call order, buildReviewPlanPrompt integration, no throws escaping, warning propagation, result shape, short-circuit behavior).
|
|
|
|
Status: ✅ Complete
|
|
|
|
### Task 4.3 - review_code tool handler ✅
|
|
|
|
Create `src/tools/review-code.js` and `test/tools/review-code.test.js`.
|
|
|
|
**Requirements:**
|
|
- Export `handleReviewCode(input, deps)` as standalone dependency-injected function.
|
|
- Execution order: validateToolInput → loadConfig → checkContextBudget → buildReviewCodePrompt → createOpenAIClient → sendOpenAIResponse.
|
|
- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
|
|
- If budget check fails (`ok: false`), immediately return that result — do not call buildReviewCodePrompt or create client.
|
|
- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
|
|
- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
|
|
- Mirror 4.1 and 4.2 structure: ~28 orchestration-only tests covering the same test categories.
|
|
|
|
Status: ✅ Complete
|
|
|
|
### Task 4.4 - debug_issue tool handler (NEXT)
|
|
|
|
Create `src/tools/debug-issue.js` and `test/tools/debug-issue.test.js`.
|
|
|
|
**Requirements:**
|
|
- Export `handleDebugIssue(input, deps)` as standalone dependency-injected function.
|
|
- Execution order: validateToolInput → loadConfig → checkContextBudget → buildDebugIssuePrompt → createOpenAIClient → sendOpenAIResponse.
|
|
- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
|
|
- If budget check fails (`ok: false`), immediately return that result — do not call buildDebugIssuePrompt or create client.
|
|
- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
|
|
- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
|
|
- Mirror 4.1/4.2/4.3 structure: ~28 orchestration-only tests covering the same test categories.
|
|
|
|
Status: ✅ Complete
|
|
|
|
### Task 4.5 - architecture_review tool handler
|
|
|
|
Create `src/tools/architecture-review.js` and `test/tools/architecture-review.test.js`.
|
|
|
|
**Requirements:**
|
|
- Export `handleArchitectureReview(input, deps)` as standalone dependency-injected function.
|
|
- Execution order: validateToolInput → loadConfig → checkContextBudget → buildArchitectureReviewPrompt → createOpenAIClient → sendOpenAIResponse.
|
|
- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
|
|
- If budget check fails (`ok: false`), immediately return that result — do not call buildArchitectureReviewPrompt or create client.
|
|
- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
|
|
- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
|
|
- Mirror 4.1/4.2/4.3/4.4 structure: ~28 orchestration-only tests covering the same test categories.
|
|
|
|
Status: ⬜ Pending
|
|
|
|
---
|
|
|
|
Phase 2 complete. Phase 3 complete. Phase 4 next: Tool Handlers.
|