workflow-state

name	workflow-state
description	Shared workflow state persistence for agent-driven development. Defines how to store and resume planning/execution state on disk using .copilot/state JSON files synchronized with manage_todo_list. Triggers on "workflow state", "resume workflow", "persist tasks", "chat state lost", "continue from plan", "state file".
user-invocable	false

Workflow State — Shared Persistence Skill

Use this skill whenever a workflow spans multiple phases and must survive chat/context loss.

CRITICAL RULES

1. Create state file before Phase 1. Do not wait until work is underway.
2. Sync on every todo/phase change. Keep file state aligned with manage_todo_list.
3. Read state first on resume. Never restart from scratch if a state file exists.
4. Store decisions and blockers. Task status alone is insufficient for resumption.
5. Use deterministic paths. Prefer <PROJECT_ROOT>/.copilot/state/<workflow>.json.
6. No state file, no execution. If a multi-phase workflow has started and the state file is missing, pause implementation and create the state file immediately.
7. Every manage_todo_list update requires a matching file sync in the same phase. Treat drift between memory and disk as a defect.
8. Capture lessons learned as you go. When something unexpected happens — a tool limitation, a platform quirk, a pattern that worked well or poorly — append it to lessonsLearned in the active session immediately. These insights improve future agent and skill behavior.
9. Never overwrite previous sessions. State files contain a sessions array. New tasks append a new session — they never replace or delete existing sessions. See resources/state-schema.md for the multi-session schema.

Standard Path

• Preferred: <PROJECT_ROOT>/.copilot/state/<workflow-name>.json
• Fallback: ./.copilot/state/<workflow-name>.json

Workflow

1. Initialize
   • Create .copilot/state/ if missing.
   • If the state file does not exist, create it using resources/state-schema.md with an empty sessions array.
   • Create a new session object with a sequential id (e.g. session-1), a human-readable label, and status: "active". Append it to sessions and set activeSessionId.
   • Seed initial todos inside the active session before first substantive step.
2. New Task (state file already exists)
   • Read the state file.
   • If there is an existing active session, mark it completed or abandoned.
   • Append a new session with the next sequential id and set activeSessionId.
   • Never delete or overwrite previous sessions.
3. Update
   • Update updatedAt, currentPhase, and todos in the active session on each phase/todo change.
   • Append key decisions, blockers, and artifact paths to the active session.
   • Append lessons learned whenever something unexpected happens.
   • Write immediately after each manage_todo_list transition; do not batch.
4. Resume
   • Read state file.
   • Find the session matching activeSessionId.
   • Rebuild manage_todo_list from that session's todos.
   • Review lessonsLearned across all sessions for high-severity entries.
   • Continue from the active session's currentPhase and unresolved blockers.
   • If in-memory plan conflicts with state file, state file is source of truth.

Enforcement Gates

• Gate A — Start: Before first major step, verify .copilot/state/<workflow>.json exists, has a sessions array, and has an active session.
• Gate B — Transition: After every todo status change, persist updated state in the active session immediately.
• Gate C — Handoff/Resume: Before continuing work after interruption, reload state file, locate the active session via activeSessionId, and rehydrate todo statuses. Check for delegations with status: "in-progress" — these indicate incomplete sub-agent work from a crashed session.
• Gate D — New Task: Before starting a new task in an existing state file, verify the previous session was properly closed (completed or abandoned) before creating a new one. Carry forward directives from the most recent completed session.
• Gate E — Completion: Before yielding as "finished", scan all files in .copilot/state/ for sessions with status: "active". If any active sessions exist in any state file, resume them in the most logical order (dependencies first, then independent workstreams) instead of finishing. Only yield as complete when every session across every state file is completed or abandoned.
• Gate F — Pre-Delegation: (Orchestrator agents only) Before every sub-agent spawn, persist a delegations entry with status: "in-progress". If the orchestrator crashes mid-delegation, Gate C can detect and recover incomplete work.
• Gate G — Post-Delegation: (Orchestrator agents only) After every sub-agent return, update the delegation entry with status: "completed" and record the result summary and outputArtifacts.
• Gate H — Cross-Session Directives: (Orchestrator agents only) When starting a new session, carry forward all directives from the most recent completed session. Directives are cumulative until the user explicitly revokes them.

References

• resources/state-schema.md — Canonical schema fields (including orchestration fields)
• resources/resume-playbook.md — Step-by-step recovery flow
• resources/spawn-templates.md — Standard and Lightweight agent spawn prompt templates
• resources/orchestration-patterns.md — Multi-agent orchestration patterns with examples
• resources/after-agent-work.md — Post-completion protocol and consolidation step
• resources/cross-agent-coordination.md — Hub-and-spoke coordination protocol
• Workflow-specific files (if present) can extend this schema

---

Decision Categorization

When logging decisions in the state file, categorize them:

{
  "decisions": [
    {
      "type": "architecture",
      "description": "...",
      "rationale": "...",
      "alternatives_considered": ["..."],
      "workaround": false
    }
  ]
}

Valid type values: architecture, workaround, platform-limitation, user-requirement.

If workaround: true, include:

• What the correct solution would be
• Why it couldn't be implemented
• When to revisit (what would need to change for the correct solution)

This creates an audit trail so workarounds can be systematically replaced later.

Lessons Learned

Capture reusable insights throughout the workflow. These are things that surprised you, caught you out, or worked especially well — knowledge that would help future runs of the same or similar workflows.

{
  "lessonsLearned": [
    {
      "category": "platform-quirk",
      "summary": "Dataverse date-only columns shift by one day when the user's UTC offset is negative",
      "detail": "Always use DateTimeKind.UTC and strip the time component server-side.",
      "appliesTo": ["dataverse-solution-web-api", "ioc-development-pattern"],
      "severity": "high"
    }
  ]
}

Valid category values: platform-quirk, tool-limitation, pattern-that-worked, pattern-to-avoid, performance, security, ux-insight, process.

appliesTo lists skills or agents that should incorporate this lesson. severity: low (nice to know), medium (save time next run), high (would cause bugs or failure if ignored).

When to record:

• A workaround was needed for a platform limitation
• A tool or API behaved differently than expected
• A design pattern proved especially effective or problematic
• A test revealed an edge case that wasn't obvious upfront
• A process step was missing, reordered, or redundant

On workflow completion, review lessonsLearned from the active session and surface high-severity entries to the user with a recommendation for which agents or skills should be updated. Also scan lessonsLearned from prior sessions for recurring themes.