Stage skill catalog and per-stage artifact contracts

[savitharaghunathan]

Stage skill catalog and per-stage artifact contracts

Related to #46.

Define the full set of stage skills for the migration pipeline and the artifacts each stage produces and consumes.

Pipeline

Questionnaire → Plan → Execute → Verify → Eval → Report

The harness supports two modes:

• Interactive — human answers questionnaire, approves spec, inspects report
• Non-interactive — LLM picks best answers autonomously and records its reasoning. Eval stage scores those choices so future runs can learn what worked.

Artifact contract summary

Every stage appends an entry to .konveyor/results.json. Missing results.json = stage failure (ADR 0006).

Stage	Consumes	Produces
Questionnaire	source repo	.konveyor/questionnaire.json (tech summary, arch summary, dependencies, migration choices)
Plan	repo, questionnaire.json, domain skill refs	SPEC.md (for approval), PLAN.md, graph.json
Execute	PLAN.md, domain skill refs	migrated source files (parallel sub-agents per plan step)
Verify	migrated source, PLAN.md, domain skill refs	fix patches, build/test summary
Eval	migrated source, PLAN.md, questionnaire.json, all results.json entries	.konveyor/eval.json (quality scores, learned patterns)
Report	results.json, eval.json, PLAN.md, git diff	.konveyor/report.md

Questionnaire: detect + gather in one stage

The questionnaire stage combines automated detection with decision gathering:

1. Detect — tech summary (languages, frameworks, build tools, app servers), architecture summary (layers, complexity), dependency capture
2. Gather — migration target, scope constraints, priorities

In interactive mode, the agent presents detection results and asks the human for decisions. In non-interactive mode, the LLM picks the best answers based on detection results and records its reasoning in questionnaire.json. The eval stage later scores whether those autonomous choices led to a good migration, building a feedback loop for future runs.

Domain skills

Domain skills provide migration-specific knowledge. Stage skills reference them via /opt/skills/*/references/. Migration intelligence (rules, extracted patterns, solution server) enters the pipeline through these references. Learned patterns from eval feed back for future runs.

Sub-issues

• Questionnaire stage skill (detect + gather) #55 — Questionnaire skill (detect + gather)
• Plan stage skill #56 — Plan skill (spec + implementation plan)
• Execute stage skill #57 — Execute skill (parallel sub-agents per plan step)
• Verify stage skill #58 — Verify skill
• Eval stage skill #59 — Eval skill (quality scores, learned patterns feedback loop)
• Report stage skill #60 — Report skill

[savitharaghunathan]

Note: file contract philosophy (2026-07-22)

Per discussion with @djzager: git commits should be the primary cross-stage context — self-documenting changes. Don't create .konveyor/ files unless there's a proven consumer.

For new stages (questionnaire, eval, report): design the stage first, see what context the next stage actually needs, and only then decide whether a file is warranted. The artifact contracts in the sub-issues (#55–#60) are starting points, not commitments — validate each one against a real consumer before implementing.

See #43 for full context on results.json and handoff.md direction.