{
  "schema_version": "0.1",
  "id": "DEC-001",
  "title": "Downstream system test harness uses opencode CLI-driven agent with pytest",
  "status": "accepted",
  "decided_at": "2026-06-17",
  "decided_by": "AGENT-001",
  "source_request_id": "REQ-028",
  "context": "REQ-028 needs an end-to-end downstream system test for PRD Plugin workflows. The key decision was whether to use a deterministic scripted runner or an opencode CLI-driven simulated agent, and which test framework to use.",
  "options_considered": [
    {
      "id": "DEC-001-OPT-1",
      "name": "Deterministic scripted runner",
      "pros": ["Fast", "Deterministic", "No API cost", "CI reliable"],
      "cons": ["Cannot validate real skill selection", "May give false confidence", "Brittle when skills change"]
    },
    {
      "id": "DEC-001-OPT-2",
      "name": "opencode CLI-driven simulated agent",
      "pros": ["Exercises real skill selection and tool-use paths", "Catches real-world agent behavior", "Scenarios described in natural language"],
      "cons": ["Requires opencode CLI installed", "Non-deterministic", "Requires flakiness controls"]
    },
    {
      "id": "DEC-001-OPT-3",
      "name": "unittest",
      "pros": ["Already used for 213 hub tests", "No extra dependency"],
      "cons": ["No conftest.py/fixtures", "Harder to parametrize", "pytest plugins unavailable"]
    },
    {
      "id": "DEC-001-OPT-4",
      "name": "pytest",
      "pros": ["Fixtures and parametrization", "Mature ecosystem", "Good agent test support", "Can coexist with unittest"],
      "cons": ["Extra dev dependency", "Needs separate test directory to avoid unittest discovery"]
    }
  ],
  "decision": "Use an opencode CLI-driven simulated agent implemented in pytest, with mock-driver smoke tests for CI and optional opencode scenario tests gated by CLI availability.",
  "rationale": "A deterministic runner would not validate the actual skill-selection path that opencode/Codex agents follow. An opencode CLI-driven agent reads the installed skills and emits tool calls, giving confidence that the PRD Plugin method works for real agents. pytest was chosen because its fixture and parametrization model fits the harness architecture; it is kept in a separate system_tests/ directory so the existing unittest suite remains unchanged.",
  "consequences": [
    "System tests live in system_tests/ and are not discovered by python -m unittest discover -s tests.",
    "Mock-driven smoke tests run by default in CI; opencode-driven scenarios require the opencode CLI and are skipped when it is not installed.",
    "Developers must install pytest to run system tests locally; opencode is required only for the optional scenario tests.",
    "The harness must include retries, low temperature, and outcome-focused assertions to manage agent non-determinism."
  ],
  "related_ids": ["REQ-028", "PRD-001", "ARCH-001", "IMP-001", "TRC-001"]
}