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

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

implement-plan-preflight

adr-graph-easy-architect

impl-standards

mise-configuration

adr-code-traceability

code-hardcode-audit

semantic-release

pypi-doppler

File Locations

/docs/adr/$ADR_ID.md

/docs/design/$ADR_ID/spec.md

~/.claude/plans/<adj-verb-noun>.md

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

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

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

Arguments

Parse

$ARGUMENTS

slug

clickhouse-aws-ohlcv-ingestion

--branch

-b

{type}/{adr-id}

--continue

-c

--release

-r

--publish

-p

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

completed

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

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

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

6. P.4: Verify checkpoint

WHY P.0 FIRST: Files created before

git checkout -b

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

1. Mark current task as

   in_progress

   in todo list
2. Implement the change
3. Verify it works
4. Update

   spec.md

   to reflect completion
5. Mark task as

   completed

6. Move to next task

1.3 Engineering Standards

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

1. impl-standards

   -- Apply error handling & constants patterns FIRST

2. mise-configuration

   -- Centralize config via mise [env] SECOND

3. adr-code-traceability

   -- Add ADR references to code THIRD

4. code-hardcode-audit

   -- Final audit LAST (before Phase 2)

MANDATORY Skill tool call:

impl-standards

MANDATORY Skill tool call:

mise-configuration

MANDATORY Skill tool call:

adr-code-traceability

MANDATORY Skill tool call:

code-hardcode-audit

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

status

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

--release

MANDATORY Skill tool call:

semantic-release

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

3.3 PyPI Publishing (if -p flag)

Condition: Only execute if

-p

--publish

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

git checkout

/itp:go -r

echo $GITHUB_TOKEN

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.