⛔ 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.

⛔ MANDATORY FIRST ACTION: Plan-Aware Todo Integration

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

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

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

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

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

Step 0: TodoWrite initialization (FIRST ACTION - NO EXCEPTIONS)
Preflight: ADR + Design Spec creation
Phase 1: Implementation per spec.md
Phase 2: Format & Push
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

Workflow Preview

Detect branch and show expected workflow before starting. See Workflow Preview 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. 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":

Verify all Preflight: todos show completed
Verify ADR file exists at /docs/adr/$ADR_ID.md
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)

P.0: Create feature branch FIRST (if -b flag) -- MUST happen before ANY file operations
P.1: MANDATORY Skill tool call: implement-plan-preflight -- activate NOW for ADR/spec instructions
P.2: Create ADR file -- path in Quick Reference
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.
P.3: Create design spec -- path in Quick Reference
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

Phase 1: Implementation

1.1 Resumption Protocol

Entry point for both fresh starts and continuations. Full protocol (continuation detection, branch verification, sync checks): Phase 1 Protocols

1.2 Implement the Spec

Execute each task in spec.md:

Mark current task as in_progress in todo list
Implement the change
Verify it works
Update spec.md to reflect completion
Mark task as completed
Move to next task

1.3 Engineering Standards

Skill Execution Order (invoke sequentially, in this order):

impl-standards -- Apply error handling & constants patterns FIRST
mise-configuration -- Centralize config via mise [env] SECOND
adr-code-traceability -- Add ADR references to code THIRD
code-hardcode-audit -- Final audit LAST (before Phase 2)

MANDATORY Skill tool call: impl-standards -- activate NOW for detailed standards.

MANDATORY Skill tool call: mise-configuration -- activate when creating/modifying scripts with configurable values.

MANDATORY Skill tool call: adr-code-traceability -- activate NOW for ADR references in code.

MANDATORY Skill tool call: code-hardcode-audit -- activate NOW before release.

1.4 Decision Capture

When implementation requires a user decision, follow the decision capture protocol: Decision Capture

1.5 Status Synchronization Protocol

Spec implementation-status drives ADR status updates. Full sync table and scripts: Status Sync Protocol

Phase 1 Success Criteria

Implementation complete per spec.md
All artifacts synced (ADR <-> spec <-> todo <-> code)
New files include ADR: {adr-id} in file header
Non-obvious changes have inline ADR: comments

Phase 2: Format & Push

Execute Prettier formatting, git push, and browser open. Full scripts: Phase 2 Scripts

Phase 2 Success Criteria

Markdown formatted with Prettier
Pushed to GitHub
Files viewable in browser

Phase 3: Release & Publish (Requires -r or -p Flag on Main)

Phase 3 requires EXPLICIT flags. It does NOT run automatically.

For entry gate logic and branch-specific messaging, see Phase 3 Gate Logic.

3.1 Pre-Release Verification

Before releasing:

All Success Criteria items in design spec are checked off
Status value in design spec is updated (e.g., Accepted, Implemented)
ADR and spec.md are in sync with final implementation
Version fields use semantic-release patterns (no dynamic versioning)

3.2 Semantic Release (if -r flag)

Condition: Only execute if -r or --release flag was provided.

MANDATORY Skill tool call: semantic-release -- activate NOW for version tagging and release.

Follow the Local Release Workflow
Conventional commits -> tag -> release -> changelog -> push

3.3 PyPI Publishing (if -p flag)

Condition: Only execute if -p or --publish flag was provided.

Only if package pre-exists on PyPI:

MANDATORY Skill tool call: pypi-doppler -- activate NOW to publish

3.4 Earthly Pipeline

Use Earthly as canonical pipeline: non-blocking, observability-first, ensure GitHub Release exists, record stats/errors, Pushover alert, wire into GitHub Actions.

Phase 3 Success Criteria

ADR status updated to accepted or implemented
Release completed via semantic-release
If feature branch: PR created, Phase 3 skipped

Troubleshooting

Issue	Cause	Solution
TodoWrite not found	Skipped mandatory first step	Start from top of file, execute TodoWrite
ADR file not created	Preflight incomplete	Run Skill(itp:implement-plan-preflight)
Branch mismatch	Working on wrong branch	Switch to correct branch with `git checkout`
Phase 3 skipped	Not on main/master	Merge to main first, then run `/itp:go -r`
semantic-release fails	No GITHUB_TOKEN	Check token with `echo $GITHUB_TOKEN`
Diagram missing	graph-easy not invoked	Run Skill(itp:adr-graph-easy-architect)
Spec validation fails	Missing frontmatter fields	Check required fields in Quick Reference