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

1. 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:
8. Update frontmatter: status: specification (or clarification if tags exist)
9. 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:
4. Architecture decisions
5. Components and their purposes
6. Data models
7. API design (if applicable)
8. Integration points
9. Write plan.md
10. Ask user to review plan.md
11. If approved:
12. Update frontmatter: status: planning
13. 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]

1. Tag critical changes: [critical:schema], [critical:api], [critical:types]
2. Write tasks.md
3. Ask user to review tasks.md
4. If approved:
5. Update frontmatter: status: implementation
6. Update progress in frontmatter: tasks_total: {count}
7. 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') != "tr