artifact-standards

name	artifact-standards
description	Artifact file paths, naming conventions, directory structure, and JSON output schemas for QA agents. Use when writing test case files, review reports, coverage reports, or generating execution metrics JSON. Covers the complete workflow artifact directory structure and versioning rules.
user-invocable	false

Artifact & Output Standards

Directory Structure

.github/agent-workflow-artifacts/<STORY-ID>/
├── manual-testcases/
│   ├── <STORY-ID>_testcases.txt              ← Generated test cases (Generator)
│   ├── test_creation_summary.json            ← Generator execution metrics
│   ├── <STORY-ID>_review_report.txt          ← Review output (Reviewer)
│   └── test_review_summary.json             ← Reviewer execution metrics
└── analysis/
    ├── <STORY-ID>_coverage_report.json       ← Coverage analysis (Analyzer)
    └── <STORY-ID>_coverage_recommendations.txt ← Shift-left action plan

File Naming Conventions

Artifact	File Name Pattern
Test cases	<STORY-ID>_testcases.txt
Review report	<STORY-ID>_review_report.txt
Coverage report	<STORY-ID>_coverage_report.json
Recommendations	<STORY-ID>_coverage_recommendations.txt
Generator summary	test_creation_summary.json
Reviewer summary	test_review_summary.json

Versioning: If file already exists → append _v2, _v3 (applies to both .txt and .json files).

Timestamp Capture (All Agents)

Every agent execution MUST capture:

Field	Format	Capture Point
startedAt	ISO 8601 (2025-01-15T10:30:00.000Z)	When execution begins
completedAt	ISO 8601	When execution ends
duration	Human-readable (2m 34s)	Calculated from start/end

JSON Response Schemas

Generator — test_creation_summary.json

{
  "status": "success",
  "storyId": "<STORY-ID>",
  "executionMetrics": {
    "startedAt": "{{ISO_TIMESTAMP}}",
    "completedAt": "{{ISO_TIMESTAMP}}",
    "duration": "{{CALCULATED_DURATION}}",
    "testCaseCount": 21,
    "acCovered": 6
  },
  "artifacts": {
    "filePath": ".github/agent-workflow-artifacts/<STORY-ID>/manual-testcases/<STORY-ID>_testcases.txt",
    "fileSize": "45KB"
  },
  "coverage": {
    "totalACs": 6,
    "coveredACs": 6,
    "coveragePercentage": 100
  }
}

Reviewer — test_review_summary.json

{
  "status": "success",
  "storyId": "<STORY-ID>",
  "reviewMetrics": {
    "reviewStartedAt": "{{ISO_TIMESTAMP}}",
    "reviewCompletedAt": "{{ISO_TIMESTAMP}}",
    "reviewDuration": "{{CALCULATED_DURATION}}",
    "qualityScore": 94,
    "totalTestCases": 25
  },
  "reviewArtifacts": {
    "reviewReportPath": ".github/agent-workflow-artifacts/<STORY-ID>/manual-testcases/<STORY-ID>_review_report.txt"
  }
}

Analyzer — <STORY-ID>_coverage_report.json

{
  "status": "success",
  "storyId": "<STORY-ID>",
  "analysisMetrics": {
    "analysisStartedAt": "{{ISO_TIMESTAMP}}",
    "analysisCompletedAt": "{{ISO_TIMESTAMP}}",
    "analysisDuration": "{{CALCULATED_DURATION}}",
    "coverageScore": 78,
    "totalTestCases": 45,
    "automationGaps": 12
  },
  "analysisArtifacts": {
    "coverageReportPath": ".github/agent-workflow-artifacts/<STORY-ID>/analysis/<STORY-ID>_coverage_report.json",
    "recommendationsPath": ".github/agent-workflow-artifacts/<STORY-ID>/analysis/<STORY-ID>_coverage_recommendations.txt"
  }
}

File Generation Rules

1. Validate Jira data before generating any file
2. Do NOT generate output without a valid Story ID and ≥1 active AC
3. Create parent directories if they do not already exist
4. Confirm file written successfully before returning the JSON response
5. All artifact files MUST be within .github/agent-workflow-artifacts/
6. Apply _v2, _v3 versioning if the file already exists — never overwrite silently