managing-workflow

What this skill does

# 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:

```bash
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

```yaml
---
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:

```bash
# 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.**

```bash
# 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:

```bash
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

```markdown
---
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

```markdown
# 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

```markdown
# 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:

```markdown
## 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

```markdown
# 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:

```bash
# 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') != "t