Workflow Tracking Skill

Purpose

Track active workflows with all related state consolidated in one location. During a workflow, agents ONLY update files within workflow/active/{workflow-name}/. This eliminates state fragmentation and simplifies agent responsibilities.

Token Optimization

Instead of querying Jira for each story status (~5000+ tokens), read workflow files (~800 tokens).

Key Principle: Single Source of Truth

During active workflow:

All state lives in workflow/active/{workflow-name}/
Agents ONLY update files in this folder
context/ folder is READ-ONLY (wiki for reference)

After workflow completes:

Archival skill moves workflow to workflow/archive/
Archival skill updates context/ with learnings
See skills/workflow/workflow-archival/SKILL.md

Folder Structure

During Active Workflow

workflow/
├── active/
│   └── {workflow-type}-{identifier}/    # Folder per workflow
│       ├── workflow.md                   # Manifest: scope, steps, status
│       ├── state.json                    # Gate history, metrics, sync state
│       ├── stories/                      # Story details (for dev workflows)
│       │   ├── PROJECT-123.md            # Story context + iteration history
│       │   └── PROJECT-124.md
│       └── decisions.md                  # Decisions made during workflow
│
└── archive/                              # Completed workflows
    └── {date}-{workflow-type}-{identifier}/
        └── ... (same structure, preserved)

Naming Convention

Workflow Type	Example Folder Name
Development	`development-EPIC-45/`
Development	`development-dark-mode-feature/`
Requirements to Stories	`requirements-to-stories-user-auth/`
Sprint Planning	`sprint-planning-sprint-15/`
Design Review	`design-review-PROJECT-200/`
Bug/Hotfix	`bug-hotfix-PROJECT-301/`
Retrospective	`retrospective-sprint-14/`

File Descriptions

workflow.md (Manifest)

The main tracking file. Contains:

Workflow type, scope, dates, branch
Stories/steps in scope with status
Current focus (step, agent, iteration)
What's next
Blockers

state.json (Consolidated State)

Replaces .ai-dev-team/workflow-state/. Contains:

Current step details
Gate history (all gate attempts with results)
Pending Jira sync items (decisions, blockers, learnings)
Sync history
Metrics

stories/{key}.md (Story Context)

Story-level details for development workflows:

Assignment and task description
Tests to pass, guidance from Senior Dev
Iteration history (What Was Done, Feedback)
Relevant files

decisions.md (Decision Log)

Decisions made during this workflow:

Decision description
Made by, date
Impact and rationale

Workflow Lifecycle

1. Create Workflow

Trigger: Orchestrator initiates a new workflow Agent: Orchestrator

Actions:

Create folder workflow/active/{type}-{identifier}/
Copy templates to create initial files:
- workflow.md from templates/{type}/workflow.template.md
- state.json from templates/state.template.json
- decisions.md from templates/decisions.template.md
- stories/ folder (for dev workflows)
Query Jira once to populate stories in scope
Set initial status and current focus

2. Update During Workflow

Trigger: Agent completes a step or makes progress Agent: The agent that completed the step

What to update:

File	When to Update
`workflow.md`	Step completed, status change, blocker
`state.json`	Gate passed/failed, metrics
`stories/{key}.md`	Iteration progress, feedback
`decisions.md`	Decision made

3. Archive Workflow

Trigger:

Workflow reaches final step, OR
User explicitly says "archive this workflow"

Agent: Orchestrator (via workflow-archival skill)

Actions:

Move folder to workflow/archive/{date}-{type}-{identifier}/
Update context/ wiki with learnings
Batch sync to Jira
See skills/workflow/workflow-archival/SKILL.md

4. Resume Workflow

Trigger: User asks to resume/continue a workflow Agent: Orchestrator

Actions:

Read workflow/active/{name}/workflow.md
Find "Current Focus" section
Read relevant story file if applicable
Spawn appropriate agent for current step
Continue execution

Agent Responsibilities

During Workflow

Agent	Updates
Orchestrator	Creates workflow, updates `workflow.md` (steps, status), `state.json` (gates)
Senior Developer	Creates `stories/{key}.md`, adds feedback after review
Junior Developer	Updates "What Was Done" in `stories/{key}.md`
QA Engineer	Updates test results in `stories/{key}.md`
All Agents	Add to `decisions.md` when decisions made

Key Rule

┌─────────────────────────────────────────────────────────────────┐
│  AGENTS ONLY UPDATE: workflow/active/{workflow-name}/*          │
│                                                                  │
│  AGENTS DO NOT UPDATE:                                           │
│  - context/  (read-only during workflow)                        │
│  - .ai-dev-team/  (deprecated, use state.json instead)          │
└─────────────────────────────────────────────────────────────────┘

Integration with Context (Read-Only)

During workflow, agents may READ from context/ for reference:

context/                          # READ-ONLY during workflow
├── solution-summary.md           # Codebase overview
├── project/                      # Module documentation
│   └── *.md
└── stories/                      # Historical stories (from past workflows)
    └── *.md

The context/ folder serves as a wiki - updated only by the archival skill after workflows complete.

State.json Schema

{
  "workflow_id": "development-EPIC-45",
  "workflow_type": "development",
  "created": "2026-01-09T14:30:00Z",
  "last_updated": "2026-01-09T16:45:00Z",

  "current_step": {
    "step_number": 3,
    "step_name": "Implementation (TDD Green)",
    "agent": "Junior Developer",
    "started": "2026-01-09T15:30:00Z"
  },

  "gate_history": [
    {
      "gate_id": "tests-ready-gate",
      "step": 2,
      "agent": "Senior Developer",
      "result": "passed",
      "timestamp": "2026-01-09T15:15:00Z",
      "details": { "unit_tests": 12, "coverage": "85%" }
    }
  ],

  "pending_sync": {
    "decisions": [],
    "blockers": [],
    "learnings": [],
    "comments": []
  },

  "sync_history": [
    {
      "timestamp": "2026-01-09T15:00:00Z",
      "trigger": "step_completion",
      "items_synced": ["story_status", "comments"]
    }
  ],

  "metrics": {
    "total_iterations": 2,
    "gates_passed": 1,
    "gates_failed": 0,
    "time_in_workflow": "2h15m"
  }
}

Templates

Templates are provided for each workflow type:

templates/
├── development/
│   ├── workflow.template.md
│   └── story.template.md
├── requirements-to-stories/
│   └── workflow.template.md
├── sprint-planning/
│   └── workflow.template.md
├── design-review/
│   └── workflow.template.md
├── bug-hotfix/
│   ├── workflow.template.md
│   └── investigation.template.md
├── retrospective/
│   └── workflow.template.md
├── state.template.json
└── decisions.template.md

Example: Development Workflow

Orchestrator Creates Workflow

workflow/active/development-EPIC-45/
├── workflow.md          # Scope: EPIC-45, Stories: 123, 124, 125
├── state.json           # Current step: 1, Status: started
├── stories/
│   ├── PROJECT-123.md   # First story details
│   ├── PROJECT-124.md   # Second story
│   └── PROJECT-125.md   # Third story
└── decisions.md         # Empty initially

Senior Dev Creates Tests (Step 2)

Updates:

workflow.md → Step 2 complete, move to Step 3
state.json → Add gate result for tests-ready-gate
stories/PROJECT-123.md → Add tests to pass, guidance

Junior Dev Implements (Step 3)

Updates:

stories/PROJECT-123.md → "What Was Done" section
workflow.md → Current iteration progress

Workflow Completes

Orchestrator triggers archival:

workflow/active/development-EPIC-45/
    ↓ (archival skill)
workflow/archive/2026-01-09-development-EPIC-45/

Context folder updated with learnings.

Example: Bug/Hotfix Workflow (P1/P2)

Bug-hotfix workflow uses tiered tracking based on severity.

Tiered Tracking

Severity	Tracking Level	Folder Created
P1/P2	Full tracking (mandatory)	`workflow/active/bugfix-PROJECT-301/`
P3/P4	Lightweight (optional)	Jira ticket only

Orchestrator Creates Workflow (P1/P2)

workflow/active/bugfix-PROJECT-301/
├── workflow.md          # Bug manifest, step status, status updates log
├── state.json           # Gate history, MTTR tracking, sync state
├── investigation.md     # Root cause analysis, fix attempts
└── decisions.md         # Technical debt, shortcuts taken

P1 Status Updates

For P1 incidents, all stakeholder communications are tracked in state.json:

{
  "status_updates": [
    { "timestamp": "...", "type": "kickoff", "summary": "..." },
    { "timestamp": "...", "type": "progress", "status": "Investigating", "summary": "..." }
  ]
}

This ensures handoff includes full communication history and provides audit trail for post-mortem.

Timeline Tracking

The workflow.md file tracks resolution timeline for MTTR calculations:

Reported → Investigation Started → Root Cause Found → Fix Deployed → Verified

Workflow Completes

After bug is resolved:

MTTR calculated from timestamps
Archival skill moves to workflow/archive/
Learnings captured for retrospective
Incident report data available for post-mortem

Workflow Tracking Skill

Workflow Tracking Skill

Purpose

Token Optimization

Key Principle: Single Source of Truth

Folder Structure

During Active Workflow

Naming Convention

File Descriptions

workflow.md (Manifest)

state.json (Consolidated State)

stories/{key}.md (Story Context)

decisions.md (Decision Log)

Workflow Lifecycle

1. Create Workflow

2. Update During Workflow

3. Archive Workflow

4. Resume Workflow

Agent Responsibilities

During Workflow

Key Rule

Integration with Context (Read-Only)

State.json Schema

Templates

Example: Development Workflow

Orchestrator Creates Workflow

Senior Dev Creates Tests (Step 2)

Junior Dev Implements (Step 3)

Workflow Completes

Example: Bug/Hotfix Workflow (P1/P2)

Tiered Tracking

Orchestrator Creates Workflow (P1/P2)

P1 Status Updates

Timeline Tracking

Workflow Completes

Similar Skills