Change Workflow Hub

Change Workflow Hub

Purpose

Create a single durable workflow for a complex change and keep all stage documents synchronized.

This skill is the entry point and orchestration layer for these specialized skills:

• research-deep-dive
• architecture-options-analysis
• architecture-spec-writer
• module-boundary-design
• post-research-to-plan
• implementation-plan

It should not duplicate their deep analysis. It should decide which one comes next, initialize the document structure, and maintain handoff state.

Use when

Use this skill when:

• the user wants a unified workflow for a complex change
• multiple research, architecture, or planning skills may be needed
• the user wants a dossier, folder, or linked documents for the whole change
• the user wants to continue a previously started change and recover state

Typical trigger phrases:

• "собери workflow"
• "свяжи эти skills в один pipeline"
• "создай dossier под изменение"
• "давай вести это как единый change workflow"
• "start a change dossier"
• "continue this architecture/research workflow"

Do not use when

Do not use this skill for:

• direct implementation work
• deep single-stage analysis that clearly belongs to one specialized skill
• bug fixing
• simple one-off local changes
• personal planning

If the user clearly asks for a single stage only, route directly to the relevant specialized skill instead of creating unnecessary workflow overhead.

Inputs

Expected inputs:

• change goal or target change
• current repository or system context
• any existing stage documents or partial analysis

Optional inputs:

• preferred slug or naming
• known current stage
• prior research/spec/plan docs
• explicit constraints that affect routing

Outputs

Always produce:

1. a dossier folder for the change when the task is substantial
2. an INDEX.md manifest for workflow state
3. a clear current stage
4. a recommended next skill
5. linked stage documents
6. missing-document / missing-information notes

Core principles

• The hub is a router and dossier manager, not a mega-analysis skill.
• The durable source of truth is the dossier, not the chat.
• Each stage skill owns its own document and stop condition.
• The hub should make stage transitions explicit and predictable.

Constraints

• Prefer an existing repository docs convention if one already exists.
• If no strong convention exists, use docs/changes/<slug>/.
• INDEX.md must always reflect current stage and recommended next skill.
• Do not silently skip upstream stage documents when they are needed for the next step.
• Once 60-implementation-plan.md exists, treat it as the execution source of truth for that change.

Required folder structure

For a substantial change, create or maintain:

docs/changes/<slug>/

with:

• INDEX.md
• 10-research.md
• 20-options.md
• 30-spec.md
• 40-module-boundaries.md
• 50-adoption-plan.md
• 60-implementation-plan.md
• artifacts/

If the repository already has a strong planning/docs convention, adapt to it instead of forcing a parallel structure.

INDEX.md responsibilities

INDEX.md is the workflow source of truth before execution starts. It must contain:

• Goal
• Current stage
• Recommended next skill
• Current recommendation
• Proven conclusions
• Hypotheses / unresolved assumptions
• Rejected options
• Active module decisions
• Validation posture
• Linked documents
• Open questions
• Invalidated by

Routing rules

Determine the starting stage like this:

• If the main question is "what actually works / what does the paper or direction really imply": use research-deep-dive

• If the main question is "what architecture options do we have and which one should we choose": use architecture-options-analysis

• If the architecture is chosen and needs a concrete design/spec document: use architecture-spec-writer

• If the main issue is carving out or defining a module boundary: use module-boundary-design

• If the research/architecture is done but uncertainty remains before implementation: use post-research-to-plan

• If the direction is already chosen and the user needs an execution breakdown: use implementation-plan

Orchestration procedure

1. Inspect whether a dossier already exists.

   • If yes, read INDEX.md first.
   • Reconstruct current stage and linked docs.
   • Do not restart analysis from scratch.

2. If no dossier exists:

   • create docs/changes/<slug>/
   • create INDEX.md
   • create empty stage docs only as needed
   • write Goal, Current stage, and Recommended next skill

3. Route explicitly. In your reasoning and working instructions, explicitly use the relevant specialized skill by name. Prefer deterministic routing over fuzzy implicit switching.

4. Before handing off, ensure INDEX.md is updated with:

   • current stage
   • next skill
   • linked documents
   • current recommendation
   • unresolved questions
   • validation posture

5. After a specialized stage completes:

   • update or create its stage file
   • update INDEX.md
   • decide whether another stage is required
   • if yes, recommend the next specialized skill explicitly
   • if no, stop and state the current terminal artifact

Handoff contract

Each specialized skill writes to one stage file and must update INDEX.md.

• research-deep-dive -> 10-research.md
• architecture-options-analysis -> 20-options.md
• architecture-spec-writer -> 30-spec.md
• module-boundary-design -> 40-module-boundaries.md
• post-research-to-plan -> 50-adoption-plan.md
• implementation-plan -> 60-implementation-plan.md

Stopping rules

Stop orchestration when:

• the user only wanted dossier initialization
• the current stage output is complete and the next stage is not yet requested
• 60-implementation-plan.md exists and the user wants to execute from that plan

Once 60-implementation-plan.md exists, treat it as the execution source of truth.

References

Use the supporting references when needed:

• references/dossier-structure.md
• references/index-template.md
• references/stage-routing-matrix.md
• references/stage-handoff-contracts.md

Definition of done

• The dossier exists or is updated in a stable location.
• INDEX.md is present and synchronized.
• Current stage and next recommended skill are explicit.
• Existing stage documents are linked.
• Missing stage docs or missing information are visible.
• The hub stops after routing and dossier maintenance instead of duplicating deep stage work.

Final response format

Return:

• Dossier path
• Current stage
• Recommended next skill
• Existing docs
• Missing docs
• Current recommendation
• Open questions