김경종
174 lines
5.3 KiB
Markdown
174 lines
5.3 KiB
Markdown
---
|
|
name: harness-workflow
|
|
description: 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.
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```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:
|
|
|
|
````markdown
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|