refactor(skills): convert to canonical Step N — Title headings

.claude/skills/iikit-00-constitution/SKILL.md

@@ -10,6 +10,8 @@ metadata:
 
 # Intent Integrity Kit Constitution
 
+Process steps in order. Do not skip ahead.
+
 Create or update the project constitution at `CONSTITUTION.md` — the governing principles for specification-driven development.
 
 ## Scope
@@ -37,54 +39,116 @@ You **MUST** consider the user input before proceeding (if not empty).
 3. Check if constitution exists: `cat CONSTITUTION.md 2>/dev/null || echo "NO_CONSTITUTION"`
 4. If missing, copy from [constitution-template.md](../iikit-core/templates/constitution-template.md)
 
-## Execution Flow
+## Step 1 — Load Existing Constitution
 
-1. **Load existing constitution** — identify placeholder tokens `[ALL_CAPS_IDENTIFIER]`. Adapt to user's needs (more or fewer principles than template).
+Identify placeholder tokens `[ALL_CAPS_IDENTIFIER]`. Adapt to user's needs (more or fewer principles than template).
 
-2. **Collect values for placeholders**:
-   - From user input, or infer from repo context
-   - `RATIFICATION_DATE`: original adoption date
-   - `LAST_AMENDED_DATE`: today if changes made
-   - `CONSTITUTION_VERSION`: semver (MAJOR: principle removal/redefinition, MINOR: new principle, PATCH: clarifications)
+Proceed immediately to Step 2.
 
-3. **Draft content**: replace all placeholders, preserve heading hierarchy, ensure each principle has name + rules + rationale, governance section covers amendment/versioning/compliance.
 
-4. **Consistency check**: validate against [plan-template.md](../iikit-core/templates/plan-template.md), [spec-template.md](../iikit-core/templates/spec-template.md), [tasks-template.md](../iikit-core/templates/tasks-template.md).
 
-5. **Sync Impact Report** (HTML comment at top): version change, modified principles, added/removed sections, follow-up TODOs.
+## Step 2 — Collect Placeholder Values
 
-6. **Validate**: no remaining bracket tokens, version matches report, dates in ISO format, principles are declarative and testable. Constitution MUST have at least 3 principles — if fewer, add more based on the project context.
+- From user input, or infer from repo context
+- `RATIFICATION_DATE`: original adoption date
+- `LAST_AMENDED_DATE`: today if changes made
+- `CONSTITUTION_VERSION`: semver (MAJOR: principle removal/redefinition, MINOR: new principle, PATCH: clarifications)
 
-7. **Phase separation validation**: scan for technology-specific content per [phase-separation-rules.md](../iikit-core/references/phase-separation-rules.md). Auto-fix violations, re-validate until clean.
+Proceed immediately to Step 3.
 
-8. **Write TWO files** — both are required outputs of this skill:
 
-   **a) Write `CONSTITUTION.md`** with the finalized constitution content.
 
-   **b) Write `.specify/context.json`** with the TDD determination extracted from the constitution you just wrote. All downstream skills (testify, bugfix, implement) read TDD policy from this file. Determine the value from the constitution text:
-   - Constitution contains MUST/REQUIRED + "TDD", "test-first", or "red-green-refactor" → `mandatory`
-   - Constitution contains MUST + "test-driven" or "tests before code" → `mandatory`
-   - Constitution contains MUST + "test-after" or "no unit tests" → `forbidden`
-   - Testing is described as OPTIONAL or SHOULD → `optional`
-   - No testing policy stated → `optional`
+## Step 3 — Draft Content
 
-   Create the file:
-   ```bash
-   mkdir -p .specify
-   ```
-   Write `.specify/context.json` containing at minimum:
-   ```json
-   {
-     "tdd_determination": "<mandatory|optional|forbidden>"
-   }
-   ```
-   If `.specify/context.json` already exists, merge (don't overwrite other fields). You can use `jq` if available, or write the file directly.
+Replace all placeholders, preserve heading hierarchy, ensure each principle has name + rules + rationale, governance section covers amendment/versioning/compliance.
+
+Proceed immediately to Step 4.
+
+
+
+## Step 4 — Consistency Check
+
+Validate against [plan-template.md](../iikit-core/templates/plan-template.md), [spec-template.md](../iikit-core/templates/spec-template.md), [tasks-template.md](../iikit-core/templates/tasks-template.md).
+
+Proceed immediately to Step 5.
+
+
+
+## Step 5 — Sync Impact Report
+
+HTML comment at top: version change, modified principles, added/removed sections, follow-up TODOs.
+
+Proceed immediately to Step 6.
+
+
+
+## Step 6 — Validate
+
+No remaining bracket tokens, version matches report, dates in ISO format, principles are declarative and testable. Constitution MUST have at least 3 principles — if fewer, add more based on the project context.
+
+Proceed immediately to Step 7.
+
+
+
+## Step 7 — Phase Separation Validation
+
+Scan for technology-specific content per [phase-separation-rules.md](../iikit-core/references/phase-separation-rules.md). Auto-fix violations, re-validate until clean.
+
+Proceed immediately to Step 8.
+
+
+
+## Step 8 — Write Outputs
+
+Both files are required outputs of this skill:
+
+**Write `CONSTITUTION.md`** with the finalized constitution content.
+
+**Write `.specify/context.json`** with the TDD determination extracted from the constitution you just wrote. All downstream skills (testify, bugfix, implement) read TDD policy from this file. Determine the value from the constitution text:
+
+- Constitution contains MUST/REQUIRED + "TDD", "test-first", or "red-green-refactor" → `mandatory`
+- Constitution contains MUST + "test-driven" or "tests before code" → `mandatory`
+- Constitution contains MUST + "test-after" or "no unit tests" → `forbidden`
+- Testing is described as OPTIONAL or SHOULD → `optional`
+- No testing policy stated → `optional`
+
+Create the file:
+
+```bash
+mkdir -p .specify
+```
+
+Write `.specify/context.json` containing at minimum:
+
+```json
+{
+  "tdd_determination": "<mandatory|optional|forbidden>"
+}
+```
+
+If `.specify/context.json` already exists, merge (don't overwrite other fields). You can use `jq` if available, or write the file directly.
+
+**Verify**: confirm `.specify/context.json` exists and contains `tdd_determination`.
+
+Proceed immediately to Step 9.
+
+
+
+## Step 9 — Git Init
+
+If needed, run `git init` to ensure project isolation.
+
+Proceed immediately to Step 10.
+
+
+
+## Step 10 — Report
+
+Report version, bump rationale, TDD determination, git status.
 
-   **Verify**: confirm `.specify/context.json` exists and contains `tdd_determination`.
+Finish here.
 
-9. **Git init** (if needed): `git init` to ensure project isolation
 
-10. **Report**: version, bump rationale, TDD determination, git status
 
 ## Formatting
 

.claude/skills/iikit-01-specify/SKILL.md

@@ -10,6 +10,8 @@ metadata:
 
 # Intent Integrity Kit Specify
 
+Process steps in order. Do not skip ahead.
+
 Create or update a feature specification from a natural language description.
 
 ## User Input
@@ -24,11 +26,9 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 Load constitution per [constitution-loading.md](../iikit-core/references/constitution-loading.md) (soft mode — warn if missing, proceed without).
 
-## Execution Flow
-
 The text after `/iikit-01-specify` **is** the feature description.
 
-### 0. Bug-Fix Intent Detection
+## Step 1 — Bug-Fix Intent Detection
 
 Analyze the description using **contextual analysis** (not keyword-only) to determine primary intent: **fix existing broken behavior** vs. **add new capability**.
 
@@ -39,15 +39,23 @@ If bug-fix intent is detected:
 1. Display: "This sounds like a bug fix. Consider using `/iikit-bugfix` instead."
 2. Show example: `/iikit-bugfix '<the user description>'`
 3. Ask the user to confirm: proceed with specification (genuinely a new feature) or switch to `/iikit-bugfix`
-4. User confirms new feature → proceed to Step 1; user wants bugfix → stop.
+4. User confirms new feature → proceed to Step 2; user wants bugfix → stop.
+
+If bug-fix intent was NOT detected, or the user confirmed this is a new feature, proceed immediately to Step 2. If the user switched to `/iikit-bugfix`, finish here.
+
 
-### 1. Generate Branch Name
+
+## Step 2 — Generate Branch Name
 
 Create 2-4 word action-noun name from description:
 - "I want to add user authentication" -> "user-auth"
 - "Implement OAuth2 integration for the API" -> "oauth2-api-integration"
 
-### 2. Create Feature Branch and Directory
+Proceed immediately to Step 3.
+
+
+
+## Step 3 — Create Feature Branch and Directory
 
 Check current branch. If on main/master/develop, suggest creating feature branch (default). If already on feature branch, suggest skipping.
 
@@ -64,7 +72,11 @@ pwsh .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/po
 
 Parse JSON for `BRANCH_NAME`, `SPEC_FILE`, `FEATURE_NUM`. Only run ONCE per feature.
 
-### 3. Generate Specification
+Proceed immediately to Step 4.
+
+
+
+## Step 4 — Generate Specification
 
 1. Parse user description — if empty: ERROR with usage example
 2. Extract key concepts: actors, actions, data, constraints
@@ -76,22 +88,42 @@ Parse JSON for `BRANCH_NAME`, `SPEC_FILE`, `FEATURE_NUM`. Only run ONCE per feat
 
 Write to `SPEC_FILE` using [spec-template.md](../iikit-core/templates/spec-template.md) structure.
 
-### 4. Phase Separation Validation
+Proceed immediately to Step 5.
+
+
+
+## Step 5 — Phase Separation Validation
 
 Scan for implementation details per [phase-separation-rules.md](../iikit-core/references/phase-separation-rules.md) (Specification section). Auto-fix violations, re-validate until clean.
 
-### 5. Create Spec Quality Checklist
+Proceed immediately to Step 6.
+
+
+
+## Step 6 — Create Spec Quality Checklist
 
 Generate `FEATURE_DIR/checklists/requirements.md` covering: content quality (no implementation details), requirement completeness, feature readiness.
 
-### 6. Handle Clarifications
+Proceed immediately to Step 7.
+
+
+
+## Step 7 — Handle Clarifications
 
 If `[NEEDS CLARIFICATION]` markers remain, present each as a question with options table and wait for user response.
 
-### 7. Report
+Proceed immediately to Step 8.
+
+
+
+## Step 8 — Report
 
 Output: branch name, spec file path, checklist results, readiness for next phase.
 
+Finish here.
+
+
+
 ## Guidelines
 
 - Focus on **WHAT** users need and **WHY** — avoid HOW

.claude/skills/iikit-02-plan/SKILL.md

@@ -10,6 +10,8 @@ metadata:
 
 # Intent Integrity Kit Plan
 
+Process steps in order. Do not skip ahead.
+
 Generate design artifacts from the feature specification using the plan template.
 
 ## User Input
@@ -39,7 +41,7 @@ Load constitution per [constitution-loading.md](../iikit-core/references/constit
    ```
    Windows: `pwsh .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/set-active-feature.ps1 -Json <selection>`
 
-   Then re-run the prerequisites check from step 1.
+   Then re-run the prerequisites check (item 1 of this section).
 
 ## Spec Quality Gate
 
@@ -65,23 +67,33 @@ Spec Quality: X/10
 
 If score < 6: recommend `/iikit-clarify` first.
 
-## Execution Flow
-
-### 1. Fill Technical Context
+## Step 1 — Fill Technical Context
 
 Using the plan template, define: Language/Version, Primary Dependencies, Storage, Testing, Target Platform, Project Type, Performance Goals, Constraints, Scale/Scope. Mark unknowns as "NEEDS CLARIFICATION".
 
 When Tessl eval results are available for candidate technologies, include eval scores in the decision rationale in research.md. Higher eval scores indicate better-validated tiles and should factor into technology selection when choosing between alternatives.
 
-### 2. Tessl Tile Discovery
+Proceed immediately to Step 2.
+
+
+
+## Step 2 — Tessl Tile Discovery
 
 If Tessl is installed, discover and install tiles for all technologies. See [tessl-tile-discovery.md](references/tessl-tile-discovery.md) for the full procedure.
 
-### 3. Research & Resolve Unknowns
+Proceed immediately to Step 3.
+
+
+
+## Step 3 — Resolve Unknowns
 
 For each NEEDS CLARIFICATION item and dependency: research, document findings in `research.md` with decision, rationale, and alternatives considered. Include Tessl Tiles section if applicable.
 
-### 4. Design & Contracts
+Proceed immediately to Step 4.
+
+
+
+## Step 4 — Design & Contracts
 
 **Prerequisites**: research.md complete
 
@@ -94,7 +106,11 @@ For each NEEDS CLARIFICATION item and dependency: research, document findings in
    ```
    Windows: `pwsh .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/update-agent-context.ps1 -AgentType claude`
 
-### 5. Update context.json with Dashboard Data
+Proceed immediately to Step 5.
+
+
+
+## Step 5 — Update context.json with Dashboard Data
 
 **MANDATORY** — you MUST update `.specify/context.json` after the plan is complete. Use `jq` to merge into the existing file (create if missing). Do NOT overwrite existing fields.
 
@@ -124,14 +140,26 @@ jq --argjson evals '{
 }' '.planview.evalScores = $evals' "$CONTEXT_FILE" > "$CONTEXT_FILE.tmp" && mv "$CONTEXT_FILE.tmp" "$CONTEXT_FILE"
 ```
 
-### 6. Constitution Check (Post-Design)
+Proceed immediately to Step 6.
+
+
+
+## Step 6 — Constitution Check (Post-Design)
 
 Re-validate all technical decisions against constitutional principles. On violation: STOP, state violation, suggest compliant alternative.
 
-### 7. Phase Separation Validation
+Proceed immediately to Step 7.
+
+
+
+## Step 7 — Phase Separation Validation
 
 Scan plan for governance content per [phase-separation-rules.md](../iikit-core/references/phase-separation-rules.md) (Plan section). Auto-fix by replacing with constitution references, re-validate.
 
+Finish here.
+
+
+
 ## Output Validation
 
 Before writing any artifact: review against each constitutional principle. On violation: STOP with explanation and alternative.