275 lines
9.9 KiB
Markdown
275 lines
9.9 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: ⬜ Pending
|
|
|
|
---
|
|
|
|
Phase 2 complete. Phase 3 in progress.
|