mcoda 0.1.2 → 0.1.4

package/packages/shared/src/openapi/OpenApiTypes.ts

@@ -1,312 +0,0 @@
-export type AgentHealthStatus = "healthy" | "degraded" | "unreachable";
-
-export interface Agent {
-  id: string;
-  slug: string;
-  adapter: string;
-  defaultModel?: string;
-  rating?: number;
-  reasoningRating?: number;
-  bestUsage?: string;
-  costPerMillion?: number;
-  config?: Record<string, unknown>;
-  createdAt: string;
-  updatedAt: string;
-  capabilities?: string[];
-  health?: AgentHealth;
-  models?: AgentModel[];
-  prompts?: AgentPromptManifest;
-  auth?: AgentAuthMetadata;
-}
-
-export interface CreateAgentInput {
-  slug: string;
-  adapter: string;
-  defaultModel?: string;
-  rating?: number;
-  reasoningRating?: number;
-  bestUsage?: string;
-  costPerMillion?: number;
-  config?: Record<string, unknown>;
-  capabilities?: string[];
-  prompts?: AgentPromptManifest;
-  models?: AgentModel[];
-}
-
-export interface UpdateAgentInput {
-  adapter?: string;
-  defaultModel?: string;
-  rating?: number;
-  reasoningRating?: number;
-  bestUsage?: string;
-  costPerMillion?: number;
-  config?: Record<string, unknown>;
-  capabilities?: string[];
-  prompts?: AgentPromptManifest;
-  models?: AgentModel[];
-}
-
-export interface AgentCapability {
-  agentId: string;
-  capability: string;
-}
-
-export interface AgentModel {
-  agentId: string;
-  modelName: string;
-  isDefault?: boolean;
-  config?: Record<string, unknown>;
-}
-
-export interface AgentPromptManifest {
-  agentId?: string;
-  jobPrompt?: string;
-  characterPrompt?: string;
-  commandPrompts?: Record<string, string>;
-  jobPath?: string;
-  characterPath?: string;
-}
-
-export interface AgentAuthMetadata {
-  agentId: string;
-  configured: boolean;
-  lastUpdatedAt?: string;
-  lastVerifiedAt?: string;
-}
-
-export interface AgentAuthSecret extends AgentAuthMetadata {
-  encryptedSecret: string;
-}
-
-export interface AgentAuthRequest {
-  secret: string;
-}
-
-export type UpdateChannel = "stable" | "beta" | "nightly";
-
-export interface UpdateInfo {
-  currentVersion: string;
-  latestVersion: string;
-  channel: UpdateChannel;
-  updateAvailable: boolean;
-  notes?: string | null;
-}
-
-export interface ApplyUpdateResponse {
-  status: "started" | "already_up_to_date" | "completed";
-  logFile?: string | null;
-}
-
-export interface AgentHealth {
-  agentId: string;
-  status: AgentHealthStatus;
-  lastCheckedAt: string;
-  latencyMs?: number;
-  details?: Record<string, unknown>;
-}
-
-export interface WorkspaceDefault {
-  workspaceId: string;
-  commandName: string;
-  agentId: string;
-  qaProfile?: string;
-  docdexScope?: string;
-  updatedAt?: string;
-}
-
-export type RoutingDefault = WorkspaceDefault;
-export type RoutingDefaults = RoutingDefault[];
-
-export type RoutingProvenance = "override" | "workspace_default" | "global_default";
-
-export interface RoutingCandidate {
-  agent: Agent;
-  agentId: string;
-  agentSlug?: string;
-  source: RoutingProvenance;
-  capabilities?: string[];
-  health?: AgentHealth;
-  missingCapabilities?: string[];
-  notes?: string;
-}
-
-export interface RoutingPreview {
-  workspaceId: string;
-  commandName: string;
-  resolvedAgent: Agent;
-  provenance?: RoutingProvenance;
-  requiredCapabilities?: string[];
-  qaProfile?: string;
-  docdexScope?: string;
-  notes?: string;
-  candidates?: RoutingCandidate[];
-}
-
-export interface RoutingDefaultsUpdate {
-  set?: Record<string, string>;
-  reset?: string[];
-  qaProfile?: string;
-  docdexScope?: string;
-}
-
-export type VelocitySource = "config" | "empirical" | "mixed";
-
-export interface BacklogLaneTotals {
-  tasks: number;
-  story_points: number;
-}
-
-export interface BacklogTotals {
-  implementation: BacklogLaneTotals;
-  review: BacklogLaneTotals;
-  qa: BacklogLaneTotals;
-  done: BacklogLaneTotals;
-}
-
-export interface BacklogSummary {
-  scope: {
-    project?: string;
-    epic?: string;
-    story?: string;
-    assignee?: string;
-  };
-  totals: BacklogTotals;
-}
-
-export interface EffectiveVelocity {
-  implementationSpPerHour: number;
-  reviewSpPerHour: number;
-  qaSpPerHour: number;
-  source: VelocitySource;
-  windowTasks?: 10 | 20 | 50;
-  samples?: {
-    implementation?: number;
-    review?: number;
-    qa?: number;
-  };
-}
-
-export interface EstimateDurations {
-  implementationHours: number | null;
-  reviewHours: number | null;
-  qaHours: number | null;
-  totalHours: number | null;
-}
-
-export interface EstimateEtas {
-  readyToReviewEta?: string;
-  readyToQaEta?: string;
-  completeEta?: string;
-}
-
-export interface EstimateResult {
-  scope: {
-    project?: string;
-    epic?: string;
-    story?: string;
-    assignee?: string;
-    workspaceId: string;
-  };
-  backlogTotals: BacklogTotals;
-  effectiveVelocity: EffectiveVelocity;
-  durationsHours: EstimateDurations;
-  etas: EstimateEtas;
-}
-
-export type RefineStrategy = "split" | "merge" | "enrich" | "estimate" | "auto";
-
-export interface RefineTasksRequest {
-  projectKey: string;
-  epicKey?: string;
-  userStoryKey?: string;
-  taskKeys?: string[];
-  statusFilter?: string[];
-  strategy?: RefineStrategy;
-  maxTasks?: number;
-  dryRun?: boolean;
-  agentIdOverride?: string;
-  planInPath?: string;
-  planOutPath?: string;
-}
-
-export interface UpdateTaskOp {
-  op: "update_task";
-  taskKey: string;
-  updates: {
-    title?: string;
-    description?: string;
-    acceptanceCriteria?: string[];
-    type?: string;
-    storyPoints?: number | null;
-    priority?: number | null;
-    metadata?: Record<string, unknown>;
-    status?: string;
-  };
-}
-
-export interface SplitChildTask {
-  title: string;
-  description?: string;
-  acceptanceCriteria?: string[];
-  type?: string;
-  storyPoints?: number | null;
-  priority?: number | null;
-  metadata?: Record<string, unknown>;
-  dependsOn?: string[];
-}
-
-export interface SplitTaskOp {
-  op: "split_task";
-  taskKey: string;
-  keepParent?: boolean;
-  parentUpdates?: UpdateTaskOp["updates"];
-  children: SplitChildTask[];
-}
-
-export interface MergeTasksOp {
-  op: "merge_tasks";
-  targetTaskKey: string;
-  sourceTaskKeys: string[];
-  updates?: UpdateTaskOp["updates"];
-  cancelSources?: boolean;
-}
-
-export interface UpdateEstimateOp {
-  op: "update_estimate";
-  taskKey: string;
-  storyPoints?: number | null;
-  type?: string;
-  priority?: number | null;
-}
-
-export type RefineOperation = UpdateTaskOp | SplitTaskOp | MergeTasksOp | UpdateEstimateOp;
-
-export interface RefineTasksPlan {
-  strategy?: RefineStrategy;
-  operations: RefineOperation[];
-  warnings?: string[];
-  metadata?: {
-    generatedAt: string;
-    projectKey: string;
-    epicKeys?: string[];
-    storyKeys?: string[];
-    jobId?: string;
-    commandRunId?: string;
-    strategy?: RefineStrategy;
-  };
-}
-
-export interface RefineTasksResult {
-  jobId: string;
-  commandRunId: string;
-  plan: RefineTasksPlan;
-  applied: boolean;
-  createdTasks?: string[];
-  updatedTasks?: string[];
-  cancelledTasks?: string[];
-  summary?: {
-    tasksProcessed: number;
-    tasksAffected: number;
-    storyPointsDelta?: number;
-  };
-}

package/packages/shared/src/paths/PathHelper.d.ts

@@ -1,12 +0,0 @@
-/**
- * Utility helpers for resolving mcoda paths in both global and workspace scopes.
- * The helpers intentionally avoid touching any other layer to keep shared free of deps.
- */
-export declare class PathHelper {
-    static getGlobalMcodaDir(): string;
-    static getGlobalDbPath(): string;
-    static getWorkspaceDir(cwd?: string): string;
-    static getWorkspaceDbPath(cwd?: string): string;
-    static ensureDir(dir: string): Promise<void>;
-}
-//# sourceMappingURL=PathHelper.d.ts.map

package/packages/shared/src/paths/PathHelper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PathHelper.d.ts","sourceRoot":"","sources":["PathHelper.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,qBAAa,UAAU;IACrB,MAAM,CAAC,iBAAiB,IAAI,MAAM;IAIlC,MAAM,CAAC,eAAe,IAAI,MAAM;IAIhC,MAAM,CAAC,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM;IAI3D,MAAM,CAAC,kBAAkB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM;WAIjD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/packages/shared/src/paths/PathHelper.js

@@ -1,24 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-import { promises as fs } from "node:fs";
-/**
- * Utility helpers for resolving mcoda paths in both global and workspace scopes.
- * The helpers intentionally avoid touching any other layer to keep shared free of deps.
- */
-export class PathHelper {
-    static getGlobalMcodaDir() {
-        return path.join(os.homedir(), ".mcoda");
-    }
-    static getGlobalDbPath() {
-        return path.join(this.getGlobalMcodaDir(), "mcoda.db");
-    }
-    static getWorkspaceDir(cwd = process.cwd()) {
-        return path.join(cwd, ".mcoda");
-    }
-    static getWorkspaceDbPath(cwd = process.cwd()) {
-        return path.join(this.getWorkspaceDir(cwd), "mcoda.db");
-    }
-    static async ensureDir(dir) {
-        await fs.mkdir(dir, { recursive: true });
-    }
-}

package/packages/shared/src/paths/PathHelper.ts

@@ -1,29 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-import { promises as fs } from "node:fs";
-
-/**
- * Utility helpers for resolving mcoda paths in both global and workspace scopes.
- * The helpers intentionally avoid touching any other layer to keep shared free of deps.
- */
-export class PathHelper {
-  static getGlobalMcodaDir(): string {
-    return path.join(os.homedir(), ".mcoda");
-  }
-
-  static getGlobalDbPath(): string {
-    return path.join(this.getGlobalMcodaDir(), "mcoda.db");
-  }
-
-  static getWorkspaceDir(cwd: string = process.cwd()): string {
-    return path.join(cwd, ".mcoda");
-  }
-
-  static getWorkspaceDbPath(cwd: string = process.cwd()): string {
-    return path.join(this.getWorkspaceDir(cwd), "mcoda.db");
-  }
-
-  static async ensureDir(dir: string): Promise<void> {
-    await fs.mkdir(dir, { recursive: true });
-  }
-}

package/packages/shared/src/qa/QaProfile.ts

@@ -1,14 +0,0 @@
-export interface QaProfile {
-  name: string;
-  runner?: 'cli' | 'chromium' | 'maestro' | string;
-  level?: string;
-  test_command?: string;
-  working_dir?: string;
-  env?: Record<string, string>;
-  default?: boolean;
-  matcher?: {
-    task_types?: string[];
-    tags?: string[];
-  };
-  install_command?: string;
-}

package/packages/shared/src/utils/UtilityService.ts

@@ -1 +0,0 @@
-export class UtilityService {}

package/packages/shared/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "declaration": true,
-    "declarationMap": true
-  },
-  "include": ["src"]
-}

package/packages/testing/package.json

@@ -1,26 +0,0 @@
-{
-  "name": "@mcoda/testing",
-  "version": "0.1.2",
-  "private": true,
-  "description": "Internal testing utilities for mcoda.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "lint": "echo \"lint not configured\"",
-    "test": "pnpm run build && node ../../scripts/run-node-tests.js dist"
-  },
-  "dependencies": {
-    "@mcoda/agents": "workspace:*",
-    "mcoda": "workspace:*",
-    "@mcoda/core": "workspace:*",
-    "@mcoda/db": "workspace:*",
-    "@mcoda/integrations": "workspace:*",
-    "@mcoda/shared": "workspace:*"
-  },
-  "license": "MIT"
-}

package/packages/testing/src/__tests__/TestingFakes.test.ts

@@ -1,15 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { FakeAgents } from "../fakes/agents/FakeAgents.js";
-import { FakeQaClient } from "../fakes/qa/FakeQaClient.js";
-import { FakeDocdexClient } from "../fakes/docdex/FakeDocdexClient.js";
-import { FakeVcsClient } from "../fakes/vcs/FakeVcsClient.js";
-
-describe("testing fakes", () => {
-  it("exports fake client shells", () => {
-    assert.ok(new FakeAgents());
-    assert.ok(new FakeQaClient());
-    assert.ok(new FakeDocdexClient());
-    assert.ok(new FakeVcsClient());
-  });
-});

package/packages/testing/src/cli/e2e/E2eSuite.ts

@@ -1 +0,0 @@
-export class E2eSuite {}

package/packages/testing/src/fakes/agents/FakeAgents.ts

@@ -1 +0,0 @@
-export class FakeAgents {}

package/packages/testing/src/fakes/docdex/FakeDocdexClient.ts

@@ -1 +0,0 @@
-export class FakeDocdexClient {}

package/packages/testing/src/fakes/qa/FakeQaClient.ts

@@ -1 +0,0 @@
-export class FakeQaClient {}

package/packages/testing/src/fakes/vcs/FakeVcsClient.ts

@@ -1 +0,0 @@
-export class FakeVcsClient {}

package/packages/testing/src/fixtures/db/DbFixtures.ts

@@ -1 +0,0 @@
-export class DbFixtures {}

package/packages/testing/src/fixtures/workspaces/WorkspaceFixtures.ts

@@ -1 +0,0 @@
-export class WorkspaceFixtures {}

package/packages/testing/src/index.ts

@@ -1 +0,0 @@
-export class Index {}

package/packages/testing/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "declaration": true,
-    "declarationMap": true
-  },
-  "include": ["src"]
-}

package/pnpm-workspace.yaml

@@ -1,2 +0,0 @@
-packages:
-  - packages/*

package/prompts/README.md

@@ -1,5 +0,0 @@
-# Agent Prompts
-
-This directory holds pre-flight prompts for the agents working in this repository. Each prompt is a concise, self-contained briefing that tells an agent how to get oriented, what to inspect before acting, and how to deliver useful outputs.
-
-Add new prompts when we introduce a new agent role or workflow. Keep every prompt grounded in the current repo layout (`README.md`, `docs/`, `openapi/`, `packages/`) and prefer clear checklists over vague guidance.

package/prompts/code-reviewer.md

@@ -1,23 +0,0 @@
-# Code Reviewer Agent Prompt
-
-Goal: surface correctness risks, regressions, and missing coverage quickly and clearly.
-
-## Prep (before reviewing lines)
-- Docdex usage (required): query docdex with the task key and feature keywords to pull SDS/PDR/RFP/OpenAPI snippets. Use MCP tool `docdex_search` (limit ~4–8) or CLI `docdexd query --repo <repo> --query "<term>" --limit 6 --snippets=false`; fetch `docdex_open` or `/snippet/:doc_id?text_only=true` only for specific hits. If results look stale, reindex (`docdex_index` or `docdexd index --repo <repo>`) then re-run. Extract expected behaviors, contracts, data shapes, acceptance criteria, and non-functional guardrails (offline scope, accessibility, performance). If docdex is unavailable, note that explicitly and fall back to the task’s documentation catalog helpers instead of opening whole docs.
-- Understand intent: read the task request and any linked docs (`docs/pdr/`, `docs/sds/`, `openapi/mcoda.yaml`) to know expected behavior and contracts.
-- Map scope: note which package(s) and files changed, and skim nearby code/tests to see existing patterns.
-- If the task supplies a response format or helper scripts (Plan/Focus/Commands/Notes, repo outline/targeted search/doc catalog/show helpers), adhere to them; favor those helpers over broad repo scans and keep file/range reads narrow.
-- Identify risk zones up front (entry points, data mutations, async flows, security/permissions, migrations).
-- Treat `gpt-creator` as legacy; do not reference or depend on it in reviews or guidance.
-
-## Review focus
-- Correctness first: does the change satisfy the intent without breaking callers or data contracts? Check types, null/undefined handling, and async/error paths.
-- Tests: confirm there is coverage for new/changed behavior; call out missing edge cases and propose specific tests.
-- Compatibility and docs: flag API/CLI/schema changes that lack doc updates or migration notes.
-- Quality: prefer existing helpers, avoid dead code, and ensure logging/metrics are consistent with the surrounding code.
-- Avoid style-only nits; center on impact and maintainability.
-
-## How to report
-- List findings in severity order with precise references (`path:line`) and a short fix or question. Group duplicates instead of repeating.
-- Note any blocking questions/assumptions separately.
-- Close with a concise summary and the minimal set of actions needed to merge (tests to run, docs to update, follow-up items).

package/prompts/code-writer.md

@@ -1,35 +0,0 @@
-# Code Writing Agent Prompt
-
-Goal: ship the requested change with the smallest, safest diff while matching the repo’s established patterns (language, framework, style, and tooling).
-
-## Get oriented first (before editing)
-- Read the task and restate the success criteria in your own words.
-- Skim workspace guides: `README.md`, the main project manifest (to see scripts and tooling), and any package-level docs.
-- Docdex usage (required): before any code search, query docdex with the task key and feature keywords to pull SDS/PDR/RFP/OpenAPI snippets. Preferred paths:
-  - MCP client: call `docdex_search` with concise queries (`"bulk complete selection"`), `limit` 4–8; if results are stale, call `docdex_index` (empty `paths` reindexes all) then re-run search. Fetch `docdex_open` only for specific doc_ids to keep payloads small.
-  - CLI: `docdexd query --repo <repo> --query "bulk complete selection" --limit 6 --snippets=false` for summaries; call `/snippet/:doc_id?text_only=true` or `docdexd query ... --snippets=true` for a single target doc. If the index is missing/stale, run `docdexd index --repo <repo>` first.
-  - Ensure the daemon is running if needed: `docdexd serve --repo <repo> --host 127.0.0.1 --port 46137 --log warn --secure-mode=false` for local use (or use MCP with `docdexd mcp --repo . --log warn --max-results 8`). Keep `.docdex/` out of VCS.
-  - Capture constraints: data model fields/enums, offline/online expectations, bulk rules, accessibility/perf requirements, acceptance criteria. If docdex is unavailable, say so and fall back to the task’s documentation catalog helpers (FTS/JSON catalog) instead of opening entire doc files.
-- Map the target area: inspect the relevant folder/package, list likely entry points, and open nearby tests/utilities. Favor existing slices/stores/adapters over creating new ones; note the current data shape (fields, enums, persistence model).
-- Search for prior art with the repo’s code search (e.g., ripgrep) to reuse patterns for validation, errors, logging, and tests.
-- If the task provides a response contract (e.g., headings like Plan/Focus/Commands/Notes or required helper scripts), follow it exactly. Use any provided catalog/outline helpers instead of ad-hoc repo-wide searches; keep file/range reads narrow.
-- Prefer task-provided helpers (repo outline, targeted search, doc catalog/show) before manual `ls`/`rg`; avoid repo-wide scans. Preview narrow ranges before `sed`/`cat` to keep context tight.
-- Treat `gpt-creator` as legacy; do not reference or depend on it in plans, prompts, or code paths.
-
-## Plan, then code
-- Write a brief plan (steps/files) before modifying anything; prefer reuse over new abstractions.
-- Match existing conventions: language/framework choices already in the repo, error handling, logging, naming, and file layout. Keep behavior backward-compatible unless told otherwise.
-- Confirm the data/persistence model from docs before coding (e.g., offline/local storage vs. network). Do not invent new APIs or backends if the design is client-only.
-- Extend the current store/state modules instead of bolting on parallel action/reducer files; wire bulk/selection flows through existing selectors/slices and persistence hooks. Use existing action creators/selectors rather than ad-hoc action type strings.
-- Keep data shapes consistent with the documented model and current store (e.g., status enums vs. boolean flags); don’t assume fields that aren’t in the schema.
-- Avoid writing partial/placeholder files—ensure every file has its imports, exports, and compiles in isolation before moving on.
-- If you encounter merge conflicts, resolve them first (clean conflict markers and ensure code compiles) before continuing task work.
-- If a target file does not exist, create it by emitting a new-file unified diff with full content (no placeholder edits to missing paths).
-- Guard inputs and edge cases; avoid silent failure paths; keep changes narrow and testable.
-- Add or update tests alongside code, following the existing style and fixtures.
-- Align tests with the project’s test runner and dependencies; avoid introducing libraries that aren’t already in use or declared, and target real components/modules (not missing files). Update docs/config only when behavior or contracts change (command help, README snippets, specs, runbooks).
-
-## Validate and hand off
-- Run the smallest relevant checks using the workspace’s documented scripts or test commands; if you cannot run them, state why and which ones are pending.
-- Self-review for regressions: data shape changes, async/error handling, backward compatibility for callers, and side effects. Verify imports/resolution and that new code actually uses existing slices/persistence instead of dead helpers.
-- Report back with what changed, files touched, checks run (or needed), and any risks or follow-up items.

package/prompts/gateway-agent.md

@@ -1,27 +0,0 @@
-You are the gateway agent. Read the task context and docdex snippets, digest the task, decide what is done vs. remaining, and plan the work.
-You must identify concrete file paths to modify or create before offloading.
-Do not use placeholders like (unknown), TBD, or glob patterns in file paths.
-If docdex returns no results, say so in docdexNotes.
-Do not leave currentState, todo, or understanding blank.
-Put reasoningSummary near the top of the JSON object so it appears early in the stream.
-Do not claim to have read files or performed a repo scan unless explicit file content was provided.
-Do not include fields outside the schema.
-
-Return JSON only with the following schema:
-{
-  "summary": "1-3 sentence summary of the task and intent",
-  "reasoningSummary": "1-2 sentence high-level rationale (no chain-of-thought)",
-  "currentState": "short statement of what is already implemented or known to exist",
-  "todo": "short statement of what still needs to be done",
-  "understanding": "short statement of what success looks like",
-  "plan": ["step 1", "step 2", "step 3"],
-  "complexity": 1-10,
-  "discipline": "backend|frontend|uiux|docs|architecture|qa|planning|ops|other",
-  "filesLikelyTouched": ["path/to/file.ext"],
-  "filesToCreate": ["path/to/new_file.ext"],
-  "assumptions": ["assumption 1"],
-  "risks": ["risk 1"],
-  "docdexNotes": ["notes about docdex coverage/gaps"]
-}
-
-If information is missing, keep arrays empty and mention the gap in assumptions or docdexNotes.

package/prompts/qa-agent.md

@@ -1,21 +0,0 @@
-# QA Agent Prompt
-
-Goal: verify the change meets its acceptance criteria and guard against regressions with clear, reproducible findings.
-
-## Orient yourself
-- Docdex usage (required): query docdex with the task key and feature keywords before planning tests. Use MCP `docdex_search` (limit ~4–8) or CLI `docdexd query --repo <repo> --query "<term>" --limit 6 --snippets=false`; pull snippets via `docdex_open` or `/snippet/:doc_id?text_only=true` only for the hits you will test. If results are stale, reindex (`docdex_index` or `docdexd index --repo <repo>`) then re-run. Capture acceptance criteria, data contracts, edge cases, non-functional requirements (performance, accessibility), and environment/setup assumptions. If docdex is unavailable, state that explicitly and fall back to the task’s documentation catalog helpers instead of opening whole docs.
-- Read the task/request and extract explicit acceptance criteria. If unclear, infer from related docs (`docs/pdr/`, `docs/sds/`, `openapi/mcoda.yaml`) and existing behavior in the relevant package.
-- Map the impacted surfaces (CLI flags, API endpoints, background jobs, data stores) and note dependencies/config that must be set before testing.
-- Identify available automation: look for documented test commands in the project manifest or CONTRIBUTING docs, and any focused test files near the touched code.
-- If the task provides a required response shape or helper scripts (e.g., Plan/Focus/Commands/Notes, catalog/outline/targeted search helpers), follow it exactly and use those helpers instead of broad repo scans; keep file/range reads tight.
-- Treat `gpt-creator` as legacy; do not reference or depend on it in plans, tests, or reporting.
-
-## Build a focused test plan
-- Cover happy paths, edge/error cases, and nearby regressions for the impacted area only; keep steps minimal and repeatable.
-- Prefer targeted automated checks first; supplement with manual steps when automation is missing.
-- Define expected outcomes up front (inputs, outputs, side effects, logs) so discrepancies are easy to spot.
-
-## Execute and report
-- Record commands run (with working directory), data/setup used, and actual outcomes. Attach logs/error snippets when useful.
-- For each issue: provide repro steps, expected vs actual, scope/impact, and a quick fix hint if obvious.
-- If everything passes, state what was covered and call out any gaps that were not exercised.