Managing workflow

Orbit Workflow

Single skill for specification-driven development. Artifacts are the source of truth.

Initialization

<context-loading> Before any workflow action, load full context with a single Bash call:

node plugins/spec/skills/managing-workflow/scripts/context-loader.js

This returns JSON with:

• suggestion: Recommended next action
• current: Active feature state and artifacts
• features.active: All features with frontmatter state
• features.in_progress: Features needing attention
• architecture_files: Available architecture docs

Use this context for all decisions. Avoid additional Read calls for state detection. </context-loading>

Phase Detection

Phase is stored in spec.md frontmatter status field:

Status	Artifacts	Next Action
initialize	None	Create spec.md
specification	spec.md (no [CLARIFY])	Create plan.md
clarification	spec.md with [CLARIFY]	Resolve questions
planning	spec.md + plan.md	Create tasks.md
implementation	tasks.md has - [ ]	Execute tasks
complete	All tasks - [x]	Archive or new feature

Frontmatter Schema

spec.md Frontmatter

---
id: 001-feature-name
title: Human Readable Title
status: specification  # initialize|specification|clarification|planning|implementation|complete
priority: P1           # P1|P2|P3
created: 2025-11-27
updated: 2025-11-27
progress:
  tasks_total: 0
  tasks_done: 0
owner: team-name
tags:
  - api
  - auth
---

Updating Frontmatter

On every phase transition, use the skill's built-in scripts:

# Update status and timestamp
node plugins/spec/skills/managing-workflow/scripts/update-status.js \
  ".spec/features/{feature}/spec.md" "planning"

# Log activity with ISO timestamp
node plugins/spec/skills/managing-workflow/scripts/log-activity.js \
  ".spec/features/{feature}/metrics.md" "Plan created"

Or with Edit tool - update the status line in frontmatter.

Phase Gates (MANDATORY)

You MUST validate before ANY phase transition. This is NOT optional.

# REQUIRED before every phase change
RESULT=$(node plugins/spec/skills/managing-workflow/scripts/validate-phase.js \
  ".spec/features/{feature}" "{target-phase}")

# Check result - DO NOT PROCEED if invalid
if [[ $(echo "$RESULT" | jq -r '.valid') != "true" ]]; then
  echo "BLOCKED: $(echo "$RESULT" | jq -r '.suggestion')"
  # Create the missing artifact before continuing
fi

Phase Prerequisites

Target Phase	Required Artifacts	If Missing
specification	None	-
clarification	spec.md	Create spec first
planning	spec.md (no [CLARIFY])	Resolve clarifications
implementation	spec.md, plan.md, tasks.md	Create missing artifacts
complete	All tasks [x]	Complete remaining tasks

Enforcement Rules

1. NEVER skip directly to implementation - plan.md and tasks.md MUST exist
2. NEVER mark complete with unchecked tasks - all [ ] must be [x]
3. If validation fails: Create the missing artifact, don't proceed
4. For simple features: Use quick-plan template (see plugins/spec/skills/managing-workflow/templates/quick-plan.md)

Quick Planning Option

For simple features (bug fixes, < 3 files), use streamlined templates:

• plugins/spec/skills/managing-workflow/templates/quick-plan.md - Combined plan with inline tasks
• plugins/spec/skills/managing-workflow/templates/quick-tasks.md - Minimal task list

This ensures artifacts exist while reducing overhead for small changes.

Workflow Actions

Initialize New Feature

1. Ask user for feature name and description
2. Generate feature ID: {NNN}-{kebab-name}
3. Create directory and files in parallel:

mkdir -p .spec/features/{id}

Create these files simultaneously:

• spec.md with frontmatter
• metrics.md with tracking template

4. Set session: set_feature "{id}"

spec.md Template

---
id: {id}
title: {title}
status: specification
priority: P2
created: {date}
updated: {date}
progress:
  tasks_total: 0
  tasks_done: 0
---

# Feature: {title}

## Overview

{description}

## User Stories

### US1: {story title}

As a {role}, I want {goal} so that {benefit}.

**Acceptance Criteria:**
- [ ] AC1.1: {criterion}
- [ ] AC1.2: {criterion}

## Technical Constraints

- {constraint}

## Out of Scope

- {exclusion}

metrics.md Template

# Metrics: {title}

## Progress

| Phase | Status | Updated |
|-------|--------|---------|
| Specification | pending | |
| Clarification | pending | |
| Planning | pending | |
| Implementation | 0/0 | |

## Activity

| Timestamp | Event |
|-----------|-------|

Note: All timestamps use ISO 8601 format: 2025-11-27T10:30:00Z

Define Specification

1. Load context to check for related archived features
2. If related found, ask: "Found similar feature '{name}'. Reference it?"
3. Ask user for feature requirements (use AskUserQuestion for scope/priority)
4. Generate user stories with acceptance criteria
5. Mark unclear items with [CLARIFY]
6. Ask user to review spec.md
7. If approved:
   • Update frontmatter: status: specification (or clarification if tags exist)
   • Update metrics.md

Clarify

1. Find all [CLARIFY] tags in spec.md
2. Batch into groups of max 4 questions
3. Use AskUserQuestion to resolve each batch
4. Update spec.md with answers, remove [CLARIFY] tags
5. Ask user to review changes
6. When all resolved and approved, update frontmatter: status: specification

Create Plan

1. Validate spec completeness (no [CLARIFY] tags)
2. Read spec.md
3. Generate technical plan with:
   • Architecture decisions
   • Components and their purposes
   • Data models
   • API design (if applicable)
   • Integration points
4. Write plan.md
5. Ask user to review plan.md
6. If approved:
   • Update frontmatter: status: planning
   • Update metrics.md

plan.md Template

# Technical Plan: {title}

## Architecture

{architecture decisions and rationale}

## Components

| Component | Purpose | Dependencies |
|-----------|---------|--------------|
| {name} | {purpose} | {deps} |

## Data Models

{model definitions}

## API Design

{endpoints if applicable}

## Implementation Phases

1. **Phase 1**: {description}
2. **Phase 2**: {description}

## Risks

| Risk | Impact | Mitigation |
|------|--------|------------|
| {risk} | {impact} | {mitigation} |

Create Tasks

1. Read spec.md + plan.md
2. Break into tasks with parallel groups and dependencies:

## Parallel Group A
- [ ] T001: {task} [P1]
- [ ] T002: {task} [P1]

## Parallel Group B [depends:A]
- [ ] T003: {task} [P1] [depends:T001,T002]

3. Tag critical changes: [critical:schema], [critical:api], [critical:types]
4. Write tasks.md
5. Ask user to review tasks.md
6. If approved:
   • Update frontmatter: status: implementation
   • Update progress in frontmatter: tasks_total: {count}
   • Update metrics.md

tasks.md Template

# Tasks: {title}

## Parallel Group A

- [ ] T001: {description} [P1]
- [ ] T002: {description} [P1]

## Parallel Group B [depends:A]

- [ ] T003: {description} [P1] [depends:T001,T002]
- [ ] T004: {description} [P2] [depends:T001]

## Sequential

- [ ] T005: {description} [P1] [critical:api] [depends:T003,T004]

---

## Legend

- `[P1/P2/P3]` - Priority level
- `[depends:X,Y]` - Task dependencies
- `[critical:type]` - Requires extra review (schema, api, types, auth)
- `[estimate:S/M/L]` - Size estimate

Implement

GATE CHECK REQUIRED - Before implementing, MUST validate:

# MANDATORY: Run this before any implementation
RESULT=$(node plugins/spec/skills/managing-workflow/scripts/validate-phase.js \
  ".spec/features/{feature}" "implementation")

# If not valid, STOP and create missing artifacts
if [[ $(echo "$RESULT" | jq -r '.valid') != "true" ]]; then
  MISSING=$(echo "$RESULT" | jq -r '.missing')
  echo "Cannot implement: missing $MISSING"
  # Go back and create: plan.md or tasks.md
fi

Only after validation passes, delegate to task-implementer agent:

Task: task-implementer agent

Feature: {feature-path}
Tasks file: .spec/features/{feature}/tasks.md

Execute tasks in parallel groups where possible.
Update task checkboxes as completed.
Report any blockers.

After implementation:

• Update frontmatter progress: tasks_done: {count}
• If all complete, update: status: complete

Validate

Delegate to artifact-validator agent:

Task: artifact-validator agent

Feature: {feature-path}

Validate:
1. Spec completeness (all AC have tasks)
2. Plan coverage (all US have implementation)
3. Task consistency (dependencies valid)

Archive Feature

When feature is complete:

1. Ask user: "Archive this feature?"
2. If yes: a. Check for repeatable patterns in completed work b. If patterns detected (2+ similar files/tasks), offer tooling suggestions
3. Run archive_feature

node plugins/spec/skills/managing-workflow/scripts/archive-feature.js "{feature-id}"

3. If new skills/agents were created during the feature:
   • Inform user: "New tooling was created. Restart Claude to use it."
   • Suggest: claude --continue to resume after restart
4. Suggest next action from context loader

Tooling Check on Archive

Before archiving, analyze the completed feature for automation opportunities:

Pattern Detection (only for repeatable tasks):
- Created 3+ similar files? → Suggest generator skill
- Wrote 3+ test files? → Suggest testing-code skill
- Added 3+ API endpoints? → Suggest api-testing agent
- Similar task structure repeated? → Suggest workflow skill

Skip tooling suggestions if:

• Feature was one-off (migration, unique integration)
• Pattern count < 2
• Similar tooling already exists

If tooling is created:

## New Tooling Created

| Type | Name | Location |
|------|------|----------|
| Skill | {name} | .claude/skills/{name}/ |
| Agent | {name} | .claude/agents/{name}.md |

**Restart Required**: Run `claude --continue` to use new tooling.

User Questions

Use AskUserQuestion strategically:

On Initialize

questions:
  - header: "Project Type"
    question: "What type of project is this?"
    options:
      - label: "Greenfield"
        description: "New project from scratch"
      - label: "Brownfield"
        description: "Existing codebase"

On Feature Selection (multiple features)

questions:
  - header: "Feature"
    question: "Which feature to work on?"
    options:
      - label: "{feature-1}"
        description: "{status} - {progress}"
      - label: "{feature-2}"
        description: "{status}"
      - label: "New Feature"
        description: "Start fresh"

On Implementation Start

questions:
  - header: "Execution"
    question: "How to execute tasks?"
    options:
      - label: "Guided"
        description: "Confirm each task"
      - label: "Autonomous"
        description: "Execute all, report at end"

Error Handling

• Missing artifact → Start from that phase
• Validation fails → Show gaps, offer to fix
• Task blocked → Log blocker, skip to next, report at end
• Frontmatter missing → Add it on next update

Parallel Execution Guidelines

Execute in parallel when independent:

• File creation (spec.md + metrics.md)
• Multiple validations
• Independent task groups

Execute sequentially when dependent:

• Spec → Plan → Tasks
• Dependent task groups