Agentic-AI-Template/Document/.agents/skills/harness-workflow/SKILL.md

name, description

name	description
harness-workflow	Plan and run the Report Harness workflow for this repository. Use when Codex needs to read `AGENTS.md` and `docs/*.md`, discuss report scope, draft research/drafting/revision phase plans, or create/update `phases/index.json`, `phases/{phase}/index.json`, and `phases/{phase}/stepN.md` files for staged execution.

Report Harness Workflow

Use this skill when the user is working in the report-generation Harness template and wants structured planning or phase-file generation.

Workflow

1. Explore first

Read these files before proposing steps:

• /AGENTS.md
• /docs/PRD.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/UI_GUIDE.md
• /docs/RESEARCH_LOG.md
• /docs/REPORT_DRAFT.md
• /docs/FEEDBACK.md

If the user explicitly asks for parallel exploration, use built-in Codex subagents such as explorer, or the repo-scoped custom agent phase_planner.

2. Confirm report inputs before locking the plan

Check that docs/PRD.md has enough information for:

1. Report topic.
2. Purpose and target reader.
3. Required keywords.
4. Direction or stance.
5. Output format and success criteria.

If any of these are missing and cannot be reasonably inferred, create a short blocked step or ask the user for the missing input instead of fabricating intent.

3. Design steps with strict boundaries

When drafting a report phase plan:

1. Keep each step focused on one research question, source-review pass, outline pass, draft pass, or feedback pass.
2. Make each stepN.md self-contained so it can run in an isolated Codex session.
3. List prerequisite files explicitly. Never rely on "as discussed above".
4. Specify report artifacts and invariants, not line-by-line prose.
5. Use executable acceptance commands, not vague success criteria.
6. Write concrete warnings in "do not do X because Y" form.
7. Use kebab-case step names.
8. Require web search for facts, current information, market data, policy/law, statistics, or recommendations.
9. Require source notes in docs/RESEARCH_LOG.md before adding claims to docs/REPORT_DRAFT.md.

Recommended step sequence:

1. brief-audit: validate the report brief and derive research questions.
2. source-discovery: perform broad web search and record candidate sources.
3. deep-research-{topic}: research one specific keyword, stakeholder, region, or issue.
4. source-review: check source quality, conflicts, freshness, and missing evidence.
5. outline: design the report structure from the evidence.
6. draft-report: write or revise docs/REPORT_DRAFT.md.
7. feedback-questions: add targeted questions for the user and update docs/FEEDBACK.md.

Files to generate

phases/index.json

Top-level phase registry. Append to phases[] when the file already exists.

{
  "phases": [
    {
      "dir": "0-research",
      "status": "pending"
    }
  ]
}

• dir: phase directory name.
• status: pending, completed, error, or blocked.
• Timestamp fields are written by scripts/execute.py; do not seed them during planning.

phases/{phase}/index.json

{
  "project": "<report-project-name>",
  "phase": "<phase-name>",
  "steps": [
    { "step": 0, "name": "brief-audit", "status": "pending" },
    { "step": 1, "name": "source-discovery", "status": "pending" },
    { "step": 2, "name": "draft-outline", "status": "pending" }
  ]
}

• project: from AGENTS.md or docs/PRD.md.
• phase: directory name.
• steps[].step: zero-based integer.
• steps[].name: kebab-case slug.
• steps[].status: initialize to pending.

phases/{phase}/stepN.md

Each step file should contain:

1. A title.
2. A "read these files first" section.
3. A concrete task section.
4. Executable acceptance criteria.
5. Verification instructions.
6. Explicit prohibitions.

Recommended structure:

# Step {N}: {name}

## Read First
- /AGENTS.md
- /docs/PRD.md
- /docs/ARCHITECTURE.md
- /docs/ADR.md
- /docs/UI_GUIDE.md
- /docs/RESEARCH_LOG.md
- /docs/REPORT_DRAFT.md
- /docs/FEEDBACK.md
- {files from previous steps}

## Task
{specific report research, source review, drafting, or feedback instructions}

## Acceptance Criteria
```bash
python scripts/validate_workspace.py
```

## Verification
1. Run the acceptance commands.
2. Check `AGENTS.md` and `docs/*.md` for report-rule drift.
3. Confirm every new factual claim has a source or is listed under `검증 필요`.
4. Update the matching step in `phases/{phase}/index.json`:
   - completed + summary
   - error + error_message
   - blocked + blocked_reason

## Do Not
- {concrete prohibition}

Execution

Run the generated phase with:

python scripts/execute.py <phase-name>
python scripts/execute.py <phase-name> --push

scripts/execute.py handles:

• report-{phase} branch checkout/creation when the directory is a git repository
• guardrail injection from AGENTS.md and docs/*.md
• accumulation of completed-step summaries into later prompts
• up to 3 retries with prior error feedback
• two-phase commit of report artifact changes and metadata updates
• timestamps such as created_at, started_at, completed_at, failed_at, and blocked_at

Recovery rules

• If a step is error, reset its status to pending, remove error_message, then rerun.
• If a step is blocked, resolve the blocker, reset to pending, remove blocked_reason, then rerun.