go

⛔ 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

File Locations

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:

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:

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

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

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

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

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.