Define review-state.json schema and provide workflow integration skills #136

New issue

Closed

opened 2026-01-15 12:02:41 +00:00 by mprihoda · 1 comment

mprihoda commented

2026-01-15 12:02:41 +00:00

(Migrated from github.com)

Context

The review-state.json file is used by workflows (kanon) to communicate state to iw-cli dashboard. Currently, the schema is implicitly defined by what workflows produce. This should be formalized in iw-cli, making iw-cli the owner of the contract.

This establishes a clean relationship:

iw-cli: Defines and owns the schema, provides skills for workflows to use
Workflows (kanon): Consume skills to produce valid state, call iw commands

Proposed Schema Location

iw-cli/
├── schemas/
│   └── review-state.schema.json    # JSON Schema definition
└── skills/
    └── review-state/
        └── SKILL.md                # Skill for writing valid review-state

Schema Should Define

{
  "version": 1,
  "issue_id": "string",
  "status": "enum: implementing | awaiting_review | review_failed | all_complete | ...",
  "phase": "number",
  "step": "string",
  "branch": "string",
  "pr_url": "string | null",
  "git_sha": "string",
  "last_updated": "ISO 8601 timestamp",
  "message": "string",
  "artifacts": [{"label": "string", "path": "string"}],
  "available_actions": [{"id": "string", "label": "string", "skill": "string"}]
}

Skills to Provide

review-state-writer: Skill that workflows invoke to write valid review-state.json
- Takes structured parameters
- Validates against schema before writing
- Handles version migration if schema evolves
review-state-validator: Skill to validate existing review-state.json
- Can be used by workflows to verify their output
- Reports schema violations clearly

Acceptance Criteria

JSON Schema defined in iw-cli repository
iw validate-state <path> command validates against schema
Skills documented for workflow consumption
Dashboard reads available_actions and can invoke them
Migration path documented for schema version changes

## Context The `review-state.json` file is used by workflows (kanon) to communicate state to iw-cli dashboard. Currently, the schema is implicitly defined by what workflows produce. This should be formalized in iw-cli, making iw-cli the owner of the contract. This establishes a clean relationship: - **iw-cli**: Defines and owns the schema, provides skills for workflows to use - **Workflows (kanon)**: Consume skills to produce valid state, call iw commands ## Proposed Schema Location ``` iw-cli/ ├── schemas/ │ └── review-state.schema.json # JSON Schema definition └── skills/ └── review-state/ └── SKILL.md # Skill for writing valid review-state ``` ## Schema Should Define ```json { "version": 1, "issue_id": "string", "status": "enum: implementing | awaiting_review | review_failed | all_complete | ...", "phase": "number", "step": "string", "branch": "string", "pr_url": "string | null", "git_sha": "string", "last_updated": "ISO 8601 timestamp", "message": "string", "artifacts": [{"label": "string", "path": "string"}], "available_actions": [{"id": "string", "label": "string", "skill": "string"}] } ``` ## Skills to Provide 1. **review-state-writer**: Skill that workflows invoke to write valid review-state.json - Takes structured parameters - Validates against schema before writing - Handles version migration if schema evolves 2. **review-state-validator**: Skill to validate existing review-state.json - Can be used by workflows to verify their output - Reports schema violations clearly ## Acceptance Criteria - [ ] JSON Schema defined in iw-cli repository - [ ] `iw validate-state <path>` command validates against schema - [ ] Skills documented for workflow consumption - [ ] Dashboard reads `available_actions` and can invoke them - [ ] Migration path documented for schema version changes

claude commented

2026-10-16 08:41:43 +00:00

Member

Intake: fixed by 0201408fad

PR #187 (merge 0201408f, on main) did this issue as its approved analysis scoped it: schemas/review-state.schema.json, schemas/README.md (versioning policy), and the validate and write commands (now iw review-state validate|write|update). The scope decision is c7a35b26.

project-management/issues/IW-136/analysis.md, "Deferred Work (Future Issues)", moved four items out of scope: dashboard validation UI, dashboard action buttons for available_actions, the skill in the workflows repository, and runtime schema version migration. The dashboard does not read available_actions today, and no open issue tracks the action buttons. If that work is still wanted, open a new issue for it.

Intake: fixed by 0201408fad92640ab5ae187508c8f030dd97f6fd PR #187 (merge 0201408f, on `main`) did this issue as its approved analysis scoped it: `schemas/review-state.schema.json`, `schemas/README.md` (versioning policy), and the validate and write commands (now `iw review-state validate|write|update`). The scope decision is c7a35b26. `project-management/issues/IW-136/analysis.md`, "Deferred Work (Future Issues)", moved four items out of scope: dashboard validation UI, dashboard action buttons for `available_actions`, the skill in the workflows repository, and runtime schema version migration. The dashboard does not read `available_actions` today, and no open issue tracks the action buttons. If that work is still wanted, open a new issue for it.

claude closed this issue

2026-10-16 08:41:43 +00:00