go

What this skill does

<!-- ⛔⛔⛔ MANDATORY: READ THIS ENTIRE FILE BEFORE ANY ACTION ⛔⛔⛔ -->

# ⛔ ITP Workflow — STOP AND READ

**DO NOT ACT ON ASSUMPTIONS. Read this file first.**

This is a structured workflow command. Follow the phases in order.

Your FIRST and ONLY action right now: **Execute the TodoWrite below.**

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## ⛔ MANDATORY FIRST ACTION: Plan-Aware Todo Integration

**YOUR FIRST ACTION MUST BE a MERGED TodoWrite that preserves existing todos.**

<!-- ADR: 2025-12-05-itp-todo-insertion-merge -->

DO NOT:

- ❌ Overwrite existing todos from plan files or previous sessions
- ❌ Ignore the plan file at `~/.claude/plans/*.md`
- ❌ Create your own todos without checking for existing ones
- ❌ Jump to coding without completing Step 0
- ❌ Create a branch before TodoWrite

**Follow the full merge strategy (Steps 0.1-0.5) and TodoWrite template**: [Todo Merge Strategy](./references/todo-merge-strategy.md)

**After TodoWrite completes, proceed to Preflight section below.**

---

## Quick Reference

### Skills Invoked

| Skill                      | Phase     | Purpose                         |
| -------------------------- | --------- | ------------------------------- |
| `implement-plan-preflight` | Preflight | ADR + Design Spec creation      |
| `adr-graph-easy-architect` | Preflight | Architecture diagrams           |
| `impl-standards`           | Phase 1   | Error handling, constants       |
| `mise-configuration`       | Phase 1   | Env var centralization patterns |
| `adr-code-traceability`    | Phase 1   | Code-to-ADR references          |
| `code-hardcode-audit`      | Phase 1   | Pre-release validation          |
| `semantic-release`         | Phase 3   | Version tagging + release       |
| `pypi-doppler`             | Phase 3   | PyPI publishing (if applicable) |

### File Locations

| Artifact    | Path                                 | Notes                                |
| ----------- | ------------------------------------ | ------------------------------------ |
| ADR         | `/docs/adr/$ADR_ID.md`               | Permanent                            |
| Design Spec | `/docs/design/$ADR_ID/spec.md`       | Permanent, SSoT after Preflight      |
| Global Plan | `~/.claude/plans/<adj-verb-noun>.md` | **EPHEMERAL** - replaced on new plan |

### Spec YAML Frontmatter

```yaml
---
adr: YYYY-MM-DD-slug # Links to ADR (programmatic)
source: ~/.claude/plans/<adj-verb-noun>.md # Global plan (EPHEMERAL)
implementation-status: in_progress # in_progress | blocked | completed | abandoned
phase: preflight # preflight | phase-1 | phase-2 | phase-3
last-updated: YYYY-MM-DD
---
```

**Note**: The `source` field preserves the global plan filename for traceability, but the file may no longer exist after a new plan is created.

### ADR ID Format

```
ADR_ID="$(date +%Y-%m-%d)-<slug>"
```

Example: `2025-12-01-clickhouse-aws-ohlcv-ingestion`

### Folder Structure

```text
/docs/
  adr/
    YYYY-MM-DD-slug.md          # ADR file
  design/
    YYYY-MM-DD-slug/            # Design folder (1:1 with ADR)
      spec.md                   # Active implementation spec (SSoT)
```

**Naming Rule**: Use exact same `YYYY-MM-DD-slug` for both ADR and Design folder.

---

## CRITICAL: Mandatory Workflow Execution

**THIS WORKFLOW IS NON-NEGOTIABLE. DO NOT SKIP ANY PHASE.**

You MUST execute ALL phases in order, regardless of task complexity:

1. **Step 0**: TodoWrite initialization (FIRST ACTION - NO EXCEPTIONS)
2. **Preflight**: ADR + Design Spec creation
3. **Phase 1**: Implementation per spec.md
4. **Phase 2**: Format & Push
5. **Phase 3**: Release (if on main/master)

**FORBIDDEN BEHAVIORS:**

- ❌ Deciding "this is simple, skip the workflow"
- ❌ Jumping directly to implementation without TodoWrite
- ❌ Skipping ADR/Design Spec for "document fixes" or "small changes"
- ❌ Making autonomous judgments to bypass phases

**If the task seems too simple for this workflow**: Stop and ask the user if they want to proceed without `/itp:go`. Do NOT silently skip phases.

---

## Arguments

Parse `$ARGUMENTS` for:

| Argument     | Short | Description                                                       | Default                         |
| ------------ | ----- | ----------------------------------------------------------------- | ------------------------------- |
| `slug`       | -     | Feature name for ADR ID (e.g., `clickhouse-aws-ohlcv-ingestion`)  | Derive from Global Plan context |
| `--branch`   | `-b`  | Create branch `{type}/{adr-id}` from main/master                  | Work on current branch          |
| `--continue` | `-c`  | Continue in-progress work; optionally provide decision            | Last "Recommended Next Steps"   |
| `--release`  | `-r`  | Enable semantic-release in Phase 3 (required on main for release) | Skip Phase 3 release            |
| `--publish`  | `-p`  | Enable PyPI publishing in Phase 3 (required on main for publish)  | Skip Phase 3 publish            |

**Detailed usage examples, branch types, and slug derivation rules**: [Arguments Reference](./references/arguments-reference.md)

---

## Workflow Preview

**Detect branch and show expected workflow before starting.** See [Workflow Preview](./references/workflow-preview.md) for the branch detection script and condition table.

---

## Step 0: Initialize Todo List (ALREADY DONE)

**If you followed the STOP instruction at the top, this step is complete.**

The TodoWrite template is in the [Todo Merge Strategy](./references/todo-merge-strategy.md). If you haven't executed it yet, **STOP and go back to the top**.

**Mark each todo `in_progress` before starting, `completed` when done.**

### Preflight Gate (MANDATORY)

**You CANNOT proceed to Phase 1 until ALL Preflight todos are marked `completed`.**

Before starting "Phase 1: Execute implementation tasks":

1. Verify all `Preflight:` todos show `completed`
2. Verify ADR file exists at `/docs/adr/$ADR_ID.md`
3. Verify design spec exists at `/docs/design/$ADR_ID/spec.md`

If any Preflight item is not complete, **STOP** and complete it first. Do NOT skip ahead.

---

## Preflight: Artifact Setup

**MANDATORY Skill tool call: `implement-plan-preflight`** -- activate NOW before proceeding.

This skill provides detailed ADR and Design Spec creation instructions (MADR 4.0 frontmatter, perspectives taxonomy, validation).

### Preflight Steps (via skill)

1. **P.0**: **Create feature branch FIRST** (if `-b` flag) -- MUST happen before ANY file operations
2. **P.1**: **MANDATORY Skill tool call: `implement-plan-preflight`** -- activate NOW for ADR/spec instructions
3. **P.2**: Create ADR file -- path in [Quick Reference](#file-locations)
4. **P.2.1**: **ADR Diagram Creation (MANDATORY for ALL ADRs)**

   **ALL ADRs require BOTH diagrams -- NO EXCEPTIONS, regardless of task complexity.**
   - INVOKE: **Skill tool call with `adr-graph-easy-architect`** -- triggers diagram workflow
   - CREATE: **Before/After diagram** -- visualizes state change in Context section
   - CREATE: **Architecture diagram** -- visualizes component relationships in Architecture section
   - VERIFY: Confirm BOTH diagrams embedded in ADR before proceeding

   **BLOCKING GATE**: Do NOT proceed to P.3 until BOTH diagrams are verified in ADR.

5. **P.3**: Create design spec -- path in [Quick Reference](#file-locations)
6. **P.4**: Verify checkpoint

**WHY P.0 FIRST**: Files created before `git checkout -b` stay on main/master. Branch must exist before ADR/spec creation.

### Preflight Checkpoint (MANDATORY)

**STOP. Verify artifacts exist before proceeding to Phase 1.** Full checklist and validator script: [Preflight Checkpoint](./references/preflight-checkpoint.md)

---

## Phase 1: Implementation

### 1.1 Resumption Protocol

**Entry point for both fresh starts and continuations.** Full protocol