From bad4526f9fae9e5c2b581882ef3958536d38e86a Mon Sep 17 00:00:00 2001 From: Baruch Sadogursky Date: Tue, 2 Jun 2026 22:39:23 +0100 Subject: [PATCH 01/10] =?UTF-8?q?refactor:=20convert=20iikit=20skills=20to?= =?UTF-8?q?=20canonical=20Step=20N=20=E2=80=94=20Title=20headings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per jbaruch/coding-policy: skill-authoring — every skill must use flat ## Step N — Descriptive Title headings (em dash), declare an execution- mode preamble after its H1, and avoid decimal sub-step headings. The existing iikit-*/SKILL.md form (### N. Title under ## Execution Flow, no preamble, ad-hoc sub-step decimals) failed all three. Changes by skill: - Sequential skills (10): add 'Process steps in order. Do not skip ahead.' preamble; remove '## Execution Flow' / '## Execution Steps' parent heading; convert each '### N. Title' to '## Step N — Title' - iikit-core (action router): add the router preamble; restructure the 5 subcommands (init, status, use, uninit, help) as 5 flat Step headings; inline each subcommand's internal procedure as numbered body bullets instead of '#### Step N — ...' sub-headings - iikit-00-constitution: convert the 10-item numbered list under '## Execution Flow' into 10 flat Step headings - iikit-04-testify: '#### 2.1 Gherkin Tag Conventions' / '#### 2.2 Transformation Rules' become bold paragraph labels under Step 2 (reference material, not separate actions) - iikit-06-analyze: '### 5b. Score History' promoted to its own Step 6 (Persist Health Score); existing Step 6/7 renumbered to 7/8 - iikit-07-implement: '### 2.1–2.4' constraints absorbed into Step 3 (Execute BDD Verification Chain) body as bold paragraphs; the pre-existing Step 3→6 numbering gap closed (now Steps 1–9); '6.x' body labels renumbered to '5.x' and section cross-references updated (§2.1 → Step 3, §6.5/§6.6 → §5.5/§5.6) - iikit-bugfix: '### 2a/2b' GitHub/text branches merged into one Step 2 (Resolve Bug Source) with bold branch labels 88 step headings across 12 skills. No behavioral change. Source/tile test labels updated to match new section numbers (114/123 pass). Closes #86 Co-Authored-By: Claude Opus 4.7 --- .claude/skills/iikit-00-constitution/SKILL.md | 92 +++++++----- .claude/skills/iikit-01-specify/SKILL.md | 20 +-- .claude/skills/iikit-02-plan/SKILL.md | 18 +-- .claude/skills/iikit-03-checklist/SKILL.md | 16 +- .claude/skills/iikit-04-testify/SKILL.md | 20 +-- .claude/skills/iikit-05-tasks/SKILL.md | 20 +-- .claude/skills/iikit-06-analyze/SKILL.md | 22 +-- .claude/skills/iikit-07-implement/SKILL.md | 57 ++++--- .../skills/iikit-08-taskstoissues/SKILL.md | 12 +- .claude/skills/iikit-bugfix/SKILL.md | 38 ++--- .claude/skills/iikit-clarify/SKILL.md | 18 +-- .claude/skills/iikit-core/SKILL.md | 140 ++++++++---------- CHANGELOG.md | 1 + tests/run-source-tests.sh | 14 +- 14 files changed, 245 insertions(+), 243 deletions(-) diff --git a/.claude/skills/iikit-00-constitution/SKILL.md b/.claude/skills/iikit-00-constitution/SKILL.md index 8e8b8a5..bc94d9f 100644 --- a/.claude/skills/iikit-00-constitution/SKILL.md +++ b/.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,76 @@ 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) +## Step 2 — Collect Placeholder Values -3. **Draft content**: replace all placeholders, preserve heading hierarchy, ensure each principle has name + rules + rationale, governance section covers amendment/versioning/compliance. +- 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) -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). +## Step 3 — Draft Content -5. **Sync Impact Report** (HTML comment at top): version change, modified principles, added/removed sections, follow-up TODOs. +Replace all placeholders, preserve heading hierarchy, ensure each principle has name + rules + rationale, governance section covers amendment/versioning/compliance. -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. +## Step 4 — Consistency Check -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. +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). -8. **Write TWO files** — both are required outputs of this skill: +## Step 5 — Sync Impact Report - **a) Write `CONSTITUTION.md`** with the finalized constitution content. +HTML comment at top: version change, modified principles, added/removed sections, follow-up TODOs. - **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 6 — Validate - Create the file: - ```bash - mkdir -p .specify - ``` - Write `.specify/context.json` containing at minimum: - ```json - { - "tdd_determination": "" - } - ``` - If `.specify/context.json` already exists, merge (don't overwrite other fields). You can use `jq` if available, or write the file directly. +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. + +## 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. + +## 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": "" +} +``` + +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`. + +## Step 9 — Git Init - **Verify**: confirm `.specify/context.json` exists and contains `tdd_determination`. +If needed, run `git init` to ensure project isolation. -9. **Git init** (if needed): `git init` to ensure project isolation +## Step 10 — Report -10. **Report**: version, bump rationale, TDD determination, git status +Report version, bump rationale, TDD determination, git status. ## Formatting diff --git a/.claude/skills/iikit-01-specify/SKILL.md b/.claude/skills/iikit-01-specify/SKILL.md index 8cd5bf4..2fe6328 100644 --- a/.claude/skills/iikit-01-specify/SKILL.md +++ b/.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 0 — 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**. @@ -41,13 +41,13 @@ If bug-fix intent is detected: 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. -### 1. Generate Branch Name +## Step 1 — 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 +## Step 2 — 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 +64,7 @@ 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 +## Step 3 — Generate Specification 1. Parse user description — if empty: ERROR with usage example 2. Extract key concepts: actors, actions, data, constraints @@ -76,19 +76,19 @@ 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 +## Step 4 — 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 +## Step 5 — Create Spec Quality Checklist Generate `FEATURE_DIR/checklists/requirements.md` covering: content quality (no implementation details), requirement completeness, feature readiness. -### 6. Handle Clarifications +## Step 6 — Handle Clarifications If `[NEEDS CLARIFICATION]` markers remain, present each as a question with options table and wait for user response. -### 7. Report +## Step 7 — Report Output: branch name, spec file path, checklist results, readiness for next phase. diff --git a/.claude/skills/iikit-02-plan/SKILL.md b/.claude/skills/iikit-02-plan/SKILL.md index 910bf85..88751df 100644 --- a/.claude/skills/iikit-02-plan/SKILL.md +++ b/.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 @@ -65,23 +67,21 @@ 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 +## 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 +## Step 3 — Research & 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 +## Step 4 — Design & Contracts **Prerequisites**: research.md complete @@ -94,7 +94,7 @@ 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 +## 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,11 +124,11 @@ jq --argjson evals '{ }' '.planview.evalScores = $evals' "$CONTEXT_FILE" > "$CONTEXT_FILE.tmp" && mv "$CONTEXT_FILE.tmp" "$CONTEXT_FILE" ``` -### 6. Constitution Check (Post-Design) +## 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 +## 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. diff --git a/.claude/skills/iikit-03-checklist/SKILL.md b/.claude/skills/iikit-03-checklist/SKILL.md index 1e19e14..d38a55f 100644 --- a/.claude/skills/iikit-03-checklist/SKILL.md +++ b/.claude/skills/iikit-03-checklist/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Checklist +Process steps in order. Do not skip ahead. + Generate checklists that validate REQUIREMENTS quality, not implementation. ## User Input @@ -37,9 +39,7 @@ Load constitution per [constitution-loading.md](../iikit-core/references/constit Then re-run the prerequisites check from step 1. -## Execution Steps - -### 1. Clarify Intent +## Step 1 — Clarify Intent Derive up to THREE contextual questions (skip if unambiguous from `$ARGUMENTS`): - Scope: include integration touchpoints? @@ -47,11 +47,11 @@ Derive up to THREE contextual questions (skip if unambiguous from `$ARGUMENTS`): - Depth: lightweight sanity list or formal release gate? - Audience: author-only or peer PR review? -### 2. Load Feature Context +## Step 2 — Load Feature Context Read from FEATURE_DIR: `spec.md` (required), `plan.md` (optional), `tasks.md` (optional). -### 3. Generate Checklist +## Step 3 — Generate Checklist **Starting point**: `FEATURE_DIR/checklists/requirements.md` already exists (created by `/iikit-01-specify`). Review it, extend it with additional items, and resolve gaps. Do NOT create a duplicate — work with the existing file. @@ -70,11 +70,11 @@ See [checklist-examples.md](references/checklist-examples.md) for correct/wrong Use [checklist-template.md](../iikit-core/templates/checklist-template.md) for format structure. -### 4. Gap Resolution (Interactive) +## Step 4 — Gap Resolution (Interactive) For each `[Gap]` item: follow the gap resolution pattern in [conversation-guide.md](../iikit-core/references/conversation-guide.md). Present missing requirement, explain risk, offer options. On resolution: update spec.md and check item off. Skip if `--no-interactive` or no gaps. -### 5. Remaining Item Validation +## Step 5 — Remaining Item Validation After gap resolution, validate ALL unchecked `[ ]` items against spec/plan/constitution: - If covered: check off with justification @@ -84,7 +84,7 @@ Continue until all items are `[x]` or explicitly deferred. **IMPORTANT**: Checklists are optional — not creating one is fine. But once created, they MUST reach 100% before the skill reports success. -### 6. Report +## Step 6 — Report Output: checklist path, item counts (total/checked/deferred), gap resolution summary, completion percentage. diff --git a/.claude/skills/iikit-04-testify/SKILL.md b/.claude/skills/iikit-04-testify/SKILL.md index ec7e060..491df13 100644 --- a/.claude/skills/iikit-04-testify/SKILL.md +++ b/.claude/skills/iikit-04-testify/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Testify +Process steps in order. Do not skip ahead. + Generate executable Gherkin `.feature` files from requirement artifacts before implementation. Enables TDD by creating hash-locked BDD scenarios that serve as acceptance criteria. > **OS convention**: All commands are shown in bash. PowerShell equivalents exist at the same path with a `.ps1` extension (e.g., `scripts/powershell/check-prerequisites.ps1`) and accept the same flags in PascalCase (e.g., `-Phase 04 -Json`). @@ -49,14 +51,12 @@ Report per [formatting-guide.md](../iikit-core/references/formatting-guide.md) ( Search spec.md for Given/When/Then patterns. If none found: ERROR with `Run: /iikit-clarify`. -## Execution Flow - -### 1. Load Artifacts +## Step 1 — Load Artifacts - **Required**: `spec.md` (acceptance scenarios), `plan.md` (API contracts, tech stack) - **Optional**: `data-model.md` (validation rules) -### 2. Generate Gherkin Feature Files +## Step 2 — Generate Gherkin Feature Files Create `.feature` files in `FEATURE_DIR/tests/features/`: @@ -64,7 +64,7 @@ Create `.feature` files in `FEATURE_DIR/tests/features/`: **File organization**: Generate one `.feature` file per user story or logical grouping. Use descriptive filenames (e.g., `login.feature`, `user-management.feature`). -#### 2.1 Gherkin Tag Conventions +**Gherkin Tag Conventions** Every scenario MUST include traceability tags: - `@TS-XXX` — test spec ID (sequential, unique across all .feature files) @@ -79,13 +79,13 @@ Every scenario MUST include traceability tags: Feature-level tags for shared metadata: - `@US-XXX` on the Feature line for the parent user story -#### 2.2 Transformation Rules +**Transformation Rules** **From spec.md — Acceptance Tests**: For each Given/When/Then scenario, generate a Gherkin scenario. Use [testspec-template.md](../iikit-core/templates/testspec-template.md) as the Gherkin file template. For transformation examples, advanced constructs (Background, Scenario Outline, Rule), and syntax validation rules, see [gherkin-reference.md](references/gherkin-reference.md). -### 3. Add DO NOT MODIFY Markers +## Step 3 — Add DO NOT MODIFY Markers Add an HTML comment at the top of each `.feature` file: ```gherkin @@ -93,7 +93,7 @@ Add an HTML comment at the top of each `.feature` file: # Derived from requirements. Fix code to pass tests; re-run /iikit-04-testify if requirements change. ``` -### 4. Idempotency +## Step 4 — Idempotency If `tests/features/` already contains `.feature` files: - Preserve existing scenario tags (TS-XXX) where the source scenario is unchanged @@ -101,7 +101,7 @@ If `tests/features/` already contains `.feature` files: - Mark removed scenarios as deprecated (comment out with `# DEPRECATED:`) - Show diff summary of changes -### 5. Store Assertion Integrity Hash +## Step 5 — Store Assertion Integrity Hash **CRITICAL**: Store SHA256 hash in both context.json and git note in a single call: @@ -111,7 +111,7 @@ bash .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/ba Returns JSON with `hash` and `git_note` status. The implement skill verifies this hash before proceeding. -### 6. Report +## Step 6 — Report Output: TDD determination, scenario counts by source (acceptance/contract/validation), output directory path, number of `.feature` files generated, hash status (LOCKED). diff --git a/.claude/skills/iikit-05-tasks/SKILL.md b/.claude/skills/iikit-05-tasks/SKILL.md index f1d1cd4..f8d46ca 100644 --- a/.claude/skills/iikit-05-tasks/SKILL.md +++ b/.claude/skills/iikit-05-tasks/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Tasks +Process steps in order. Do not skip ahead. + Generate an actionable, dependency-ordered tasks.md for the feature. ## User Input @@ -46,24 +48,22 @@ Load constitution per [constitution-loading.md](../iikit-core/references/constit Report readiness per [formatting-guide.md](../iikit-core/references/formatting-guide.md) (Plan Readiness section). -## Execution Flow - -### 1. Load Documents +## Step 1 — Load Documents - **Required**: `plan.md`, `spec.md` - **Optional**: `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tests/features/` (.feature files) If .feature files exist (or legacy test-specs.md), tasks reference specific test IDs (e.g., "T012 [US1] Implement to pass TS-001"). -### 2. Tessl Convention Consultation +## Step 2 — Tessl Convention Consultation If Tessl installed: query primary framework tile for project structure conventions and testing framework tile for test organization. Apply to file paths and task ordering. If not available: skip silently. -### 3. Generate Tasks +## Step 3 — Generate Tasks Extract tech stack from plan.md, user stories from spec.md, entities from data-model.md, endpoints from contracts/, decisions from research.md. Organize by user story with dependency graph and parallel markers. -### 4. Task Format (REQUIRED) +## Step 4 — Task Format (REQUIRED) ```text - [ ] [TaskID] [P?] [Story?] Description with file path @@ -91,18 +91,18 @@ Extract tech stack from plan.md, user stories from spec.md, entities from data-m **Correct**: `[TS-005, TS-006, TS-007, TS-008, TS-009, TS-010]` **Wrong**: `TS-005 through TS-010` -### 5. Phase Structure +## Step 5 — Phase Structure - **Phase 1**: Setup (project initialization) - **Phase 2**: Foundational (blocking prerequisites, complete before stories) - **Phase 3+**: User Stories in priority order (P1, P2, P3...) — tests -> models -> services -> endpoints -> integration - **Final**: Polish & Cross-Cutting Concerns -### 6. Task Organization +## Step 6 — Task Organization Map each component to its user story. Shared entities serving multiple stories go in Setup/Foundational. Each contract gets a contract test task. Story dependencies marked explicitly. -### 7. Dependency Graph Validation +## Step 7 — Dependency Graph Validation After generating, validate: 1. **Circular dependencies**: detect cycles, ERROR if found with resolution options @@ -111,7 +111,7 @@ After generating, validate: 4. **Phase boundaries**: no backward cross-phase dependencies 5. **Story independence**: warn on priority inversions (higher-priority depending on lower) -### 8. Write tasks.md +## Step 8 — Write tasks.md Use [tasks-template.md](../iikit-core/templates/tasks-template.md) with phases, dependencies, parallel examples, and implementation strategy. diff --git a/.claude/skills/iikit-06-analyze/SKILL.md b/.claude/skills/iikit-06-analyze/SKILL.md index e51eee3..be54f7d 100644 --- a/.claude/skills/iikit-06-analyze/SKILL.md +++ b/.claude/skills/iikit-06-analyze/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Analyze +Process steps in order. Do not skip ahead. + Non-destructive cross-artifact consistency analysis across spec.md, plan.md, and tasks.md. ## Operating Constraints @@ -42,15 +44,13 @@ Load constitution per [constitution-loading.md](../iikit-core/references/constit Then re-run the prerequisites check from step 1. 4. Checklist gate per [checklist-gate.md](../iikit-core/references/checklist-gate.md). -## Execution Steps - -### 1. Load Artifacts (Progressive) +## Step 1 — Load Artifacts (Progressive) From spec.md: overview, requirements, user stories, edge cases. From plan.md: architecture, data model refs, phases, constraints. From tasks.md: task IDs, descriptions, phases, [P] markers, file paths. -### 2. Build Semantic Models +## Step 2 — Build Semantic Models - Requirements inventory (functional + non-functional) - User story/action inventory with acceptance criteria @@ -58,7 +58,7 @@ From tasks.md: task IDs, descriptions, phases, [P] markers, file paths. - Plan coverage mapping (requirement ID → plan.md sections where referenced) - Constitution rule set -### 3. Detection Passes (limit 50 findings) +## Step 3 — Detection Passes (limit 50 findings) | Pass | Category | What to detect | |------|----------|----------------| @@ -81,14 +81,14 @@ From tasks.md: task IDs, descriptions, phases, [P] markers, file paths. `BLOCKED` → report undefined steps (HIGH). `DEGRADED` → note in report only. -### 4. Severity +## Step 4 — Severity - **CRITICAL**: constitution MUST violations, phase separation, missing core artifact, zero-coverage blocking requirement - **HIGH**: duplicates, conflicting requirements, ambiguous security/performance, untestable criteria - **MEDIUM**: terminology drift, missing non-functional coverage, underspecified edge cases - **LOW**: style/wording, minor redundancy -### 5. Analysis Report +## Step 5 — Analysis Report Output to console AND write to `FEATURE_DIR/analysis.md`: @@ -112,9 +112,9 @@ Output to console AND write to `FEATURE_DIR/analysis.md`: | | | % | | | | | | ``` -### 5b. Score History +## Step 6 — Persist Health Score -After computing **Metrics** in step 5, persist the health score: +After computing **Metrics** in Step 5, persist the health score: 1. **Compute**: `score = max(0, round(100 - (critical×20 + high×5 + medium×2 + low×0.5)))`. 2. **Read** `.specify/score-history.json` (initialize `{}` if missing). @@ -125,12 +125,12 @@ After computing **Metrics** in step 5, persist the health score: 6. **Display**: `Health Score: /100 ()` in console and `analysis.md`. 7. **Include** full `score_history` array for the current feature under the **Score History** table in `analysis.md`. -### 6. Next Actions +## Step 7 — Next Actions - CRITICAL issues: recommend resolving before `/iikit-07-implement` - LOW/MEDIUM only: may proceed with improvement suggestions -### 7. Offer Remediation +## Step 8 — Offer Remediation Ask: "Suggest concrete remediation edits for the top N issues?" Do NOT apply automatically. diff --git a/.claude/skills/iikit-07-implement/SKILL.md b/.claude/skills/iikit-07-implement/SKILL.md index ad136f2..4e2b83c 100644 --- a/.claude/skills/iikit-07-implement/SKILL.md +++ b/.claude/skills/iikit-07-implement/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Implement +Process steps in order. Do not skip ahead. + Execute the implementation plan by processing all tasks in tasks.md. ## User Input @@ -53,7 +55,7 @@ Default to A if user doesn't respond. Apply the chosen strategy throughout. **Standard mode**: Verify artifact completeness (constitution, spec, plan, tasks, checklists), cross-artifact consistency (FR-XXX → tasks, tech stack → file paths), and checklist completion (all 100% or ask user). Report READY or BLOCKED. -**Bugfix mode**: Only require tasks.md (T-B tasks) and bugs.md (matching BUG-NNN). Skip spec/plan/checklist gates. BDD chain (§2.1–2.4) still applies if `.feature` files exist. +**Bugfix mode**: Only require tasks.md (T-B tasks) and bugs.md (matching BUG-NNN). Skip spec/plan/checklist gates. BDD chain (Step 3) still applies if `.feature` files exist. ## Dashboard @@ -62,13 +64,11 @@ Suggest the user open the dashboard to watch implementation progress in real tim Dashboard: file://$(pwd)/.specify/dashboard.html (resolve the path) — updates live as tasks complete ``` -## Execution Flow - -### 1. Load Context +## Step 1 — Load Context Read `tasks.md` + `plan.md` (standard) or `tasks.md` + `bugs.md` (bugfix). Optional: `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tests/features/`. -### 2. TDD Support Check +## Step 2 — TDD Support Check If `tests/features/` directory exists (contains `.feature` files), verify assertion integrity: @@ -80,7 +80,7 @@ Parse JSON response: `PASS` (proceed), `BLOCKED` (halt, show remediation), `WARN If TDD **mandatory** but `tests/features/` missing or empty: ERROR with `Run: /iikit-04-testify`. -### 2.1 BDD Verification Chain Enforcement +## Step 3 — Execute BDD Verification Chain When `.feature` files exist, apply this chain to each implementation task: @@ -94,13 +94,9 @@ When `.feature` files exist, apply this chain to each implementation task: ``` Parse JSON for `steps.status` (coverage) and `quality.status` (assertions). Both must be `PASS` before marking task complete. If `BLOCKED`: fix the flagged step definitions. -### 2.2 Feature File Immutability - -**CRITICAL**: `.feature` files MUST NOT be modified during implementation. They are generated by `/iikit-04-testify` and hash-locked. Only step definitions and production code may be modified. If a `.feature` file needs changes, re-run `/iikit-04-testify`. - -### 2.3 Test Execution Enforcement +**Feature File Immutability** — `.feature` files MUST NOT be modified during implementation. They are generated by `/iikit-04-testify` and hash-locked. Only step definitions and production code may be modified. If a `.feature` file needs changes, re-run `/iikit-04-testify`. -Tests **MUST** be run, not just written. Run immediately after writing (expect red); run again after implementing (expect green). Fix code, not tests. Never mark a test task `[x]` without execution output. +**Test Execution Enforcement** — Tests MUST be run, not just written. Run immediately after writing (expect red); run again after implementing (expect green). Fix code, not tests. Never mark a test task `[x]` without execution output. ```bash bash .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/bash/verify-test-execution.sh verify "FEATURE_DIR/tests/features" "$(cat test-output.log)" @@ -108,43 +104,42 @@ bash .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/ba Block on any status other than `PASS`. -### 2.4 Task Completion Gate +**Task Completion Gate** — A task is NOT complete until: -A task is NOT complete until: 1. `verify-steps.sh` returns `PASS` (all steps defined) 2. BDD tests pass (GREEN phase confirmed) 3. `verify-step-quality.sh` returns `PASS` (no empty/trivial assertions) Do NOT mark `[x]` in tasks.md until all three gates pass. -### 3. Setup (Dependencies, Tiles, Scaffolding) +## Step 4 — Setup (Dependencies, Tiles, Scaffolding) Before writing source code: 1. **Install dependencies** from plan.md Technical Context (detect package manager, add runtime + dev deps, commit manifest + lockfile) 2. **Install Tessl tiles** for each major dependency: `tessl search ` then `tessl install `. Query tile docs before writing library code. See [tessl-integration.md](references/tessl-integration.md). 3. **Scaffold project** if needed. For existing directories, use force/overwrite flags. See [ignore-patterns.md](references/ignore-patterns.md) for gitignore patterns. -### 6. Parse and Execute Tasks +## Step 5 — Parse and Execute Tasks -**6.1 Task extraction**: parse tasks.md for phase, completion status (`[x]` = skip), dependencies, [P] markers, [USn] labels. Build in-memory task graph. +**5.1 Task extraction**: parse tasks.md for phase, completion status (`[x]` = skip), dependencies, [P] markers, [USn] labels. Build in-memory task graph. -**6.2 Execution strategy — read [parallel-execution.md](references/parallel-execution.md) BEFORE proceeding**: +**5.2 Execution strategy — read [parallel-execution.md](references/parallel-execution.md) BEFORE proceeding**: If tasks.md contains `[P]` markers, you **MUST** use the `Task` tool to dispatch parallel batches as concurrent subagents (one worker per task). Only fall back to sequential execution if the runtime has no subagent dispatch mechanism. Report mode per [formatting-guide.md](../iikit-core/references/formatting-guide.md) (Execution Mode Header). -**6.3 Phase-by-phase**: +**5.3 Phase-by-phase**: 1. Collect eligible tasks (dependencies satisfied) 2. Build parallel batches from [P] tasks with no mutual dependencies 3. Dispatch — parallel: launch one `Task` tool subagent per `[P]` task in the batch; sequential: one at a time -4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§6.6) +4. Collect results, checkpoint `[x]` in tasks.md per batch, then commit per chosen strategy (§5.6) 5. Repeat until phase complete Cross-story parallelism: independent stories can run as parallel workstreams after Phase 2 (verify no shared file modifications). -**6.4 Rules**: install dependencies (§3) and Tessl tiles (§4) before writing code, query tiles before library code, tests before code if TDD, run tests after writing them, only orchestrator updates tasks.md. +**5.4 Rules**: install dependencies (Step 4) and Tessl tiles (Step 4) before writing code, query tiles before library code, tests before code if TDD, run tests after writing them, only orchestrator updates tasks.md. -**6.5 Failure handling**: let in-flight siblings finish, mark successes, report failures, halt phase. Constitutional violations in workers: worker stops, reports to orchestrator, treated as task failure. +**5.5 Failure handling**: let in-flight siblings finish, mark successes, report failures, halt phase. Constitutional violations in workers: worker stops, reports to orchestrator, treated as task failure. -**6.6 Task Commits**: Apply the user's chosen commit strategy. +**5.6 Task Commits**: Apply the user's chosen commit strategy. **Per-task** (strategy A): After each task is marked `[x]`, stage its changed files (`git add` specific files, NOT `-A`) and commit: @@ -175,15 +170,15 @@ For both strategies, regenerate the dashboard after commits: bash .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/bash/generate-dashboard-safe.sh ``` -### 7. Output Validation +## Step 6 — Output Validation Before writing ANY file: review against constitutional principles. On violation: STOP, explain, suggest alternative. -### 8. Progress Tracking +## Step 7 — Progress Tracking Report after each task/batch. Mark completed `[x]` in tasks.md. Halt on failure. -### 9. Post-Fix GitHub Integration (Bug Fix Tasks) +## Step 8 — Post-Fix GitHub Integration (Bug Fix Tasks) After completing bug fix tasks (tasks with `T-B` prefix pattern): @@ -191,17 +186,17 @@ After completing bug fix tasks (tasks with `T-B` prefix pattern): 2. For each completed bug (all T-BNNN tasks for a BUG-NNN marked `[x]`): - Read the `GitHub Issue` field from the bug's entry in bugs.md - If a GitHub issue is linked (e.g., `#42`): - - **Close via commit**: include `Fixes #` in the last task's commit message (§6.6) + - **Close via commit**: include `Fixes #` in the last task's commit message (§5.6) - **Post a comment**: use `gh issue comment` if available, otherwise `curl` the GitHub API (`POST /repos/{owner}/{repo}/issues/{number}/comments`). Comment content: root cause from bugs.md, completed fix tasks, and fix reference - If no GitHub issue is linked: skip silently -### 10. Completion +## Step 9 — Completion -All tasks `[x]`, features validated against spec, test execution enforcement (§2.1) satisfied, Tessl usage reported. +All tasks `[x]`, features validated against spec, test execution enforcement (Step 3) satisfied, Tessl usage reported. ## Error Handling -Missing artifacts: STOP with run instructions. Constitution violations: STOP, explain, suggest alternative. Checklist incomplete: ask user. Task/parallel failure: report + halt (§6.5). Tests not run: STOP. Tests failing: fix code, re-run. +Missing artifacts: STOP with run instructions. Constitution violations: STOP, explain, suggest alternative. Checklist incomplete: ask user. Task/parallel failure: report + halt (§5.5). Tests not run: STOP. Tests failing: fix code, re-run. ## Dashboard & Next Steps @@ -212,7 +207,7 @@ bash .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/ba ``` Windows: `pwsh .tessl/plugins/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/post-phase.ps1 -Phase 07` -Note: implement handles its own git commits per the chosen strategy (§6.6), so post-phase is called without `--commit-files`. +Note: implement handles its own git commits per the chosen strategy (§5.6), so post-phase is called without `--commit-files`. Parse `next_step` from JSON: - If `next_step` is `/iikit-07-implement` (feature incomplete): suggest resuming diff --git a/.claude/skills/iikit-08-taskstoissues/SKILL.md b/.claude/skills/iikit-08-taskstoissues/SKILL.md index 72ad11f..41c21b9 100644 --- a/.claude/skills/iikit-08-taskstoissues/SKILL.md +++ b/.claude/skills/iikit-08-taskstoissues/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Tasks to Issues +Process steps in order. Do not skip ahead. + Convert existing tasks into dependency-ordered GitHub issues for project tracking. ## User Input @@ -45,19 +47,17 @@ git config --get remote.origin.url **CRITICAL**: Only proceed if remote is a GitHub URL (`git@github.com:` or `https://github.com/`). Otherwise ERROR. -## Execution Flow - -### 1. Parse tasks.md +## Step 1 — Parse tasks.md Extract: Task IDs, descriptions, phase groupings, parallel markers [P], user story labels [USn], dependencies. -### 2. Prepare Labels and Title Format +## Step 2 — Prepare Labels and Title Format **Title format**: `[FeatureID/TaskID] [Story] Description` — feature-id extracted from `FEATURE_DIR` (e.g. `001-user-auth`). **Body**: use template from [issue-body-template.md](references/issue-body-template.md). **Labels** (create if needed): `iikit`, `phase-N`, `us-N`, `parallel`. -### 3. Create Issues (parallel) +## Step 3 — Create Issues (parallel) Use the `Task` tool to dispatch issue creation in parallel — one subagent per chunk of tasks (split by phase or user story). Each subagent receives: - The chunk of tasks to create issues for @@ -73,7 +73,7 @@ gh issue create --title "[001-user-auth/T012] [US1] Create User model" --body ". Collect all created issue numbers from subagents. Verify all returned successfully before proceeding. If some failed: report failures, continue with successful issues only. -### 4. Link Dependencies +## Step 4 — Link Dependencies After all issues exist, edit bodies to add cross-references using `#NNN` syntax. Skip dependency links for any issues that failed to create. diff --git a/.claude/skills/iikit-bugfix/SKILL.md b/.claude/skills/iikit-bugfix/SKILL.md index 45b709f..c9c4c59 100644 --- a/.claude/skills/iikit-bugfix/SKILL.md +++ b/.claude/skills/iikit-bugfix/SKILL.md @@ -10,6 +10,8 @@ metadata: # Intent Integrity Kit Bugfix +Process steps in order. Do not skip ahead. + Report a bug against an existing feature, create a structured `bugs.md` record, and generate fix tasks in `tasks.md`. ## User Input @@ -24,21 +26,23 @@ 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-bugfix` is either a `#number` (GitHub issue) or a text bug description. -### 1. Parse Input +## Step 1 — Parse Input Determine the input type: -- **`#number` pattern** (e.g., `#42`): GitHub inbound flow (Step 2a) -- **Text description**: Text description flow (Step 2b) +- **`#number` pattern** (e.g., `#42`): GitHub inbound flow +- **Text description**: Text description flow - **Empty**: ERROR with usage example: `/iikit-bugfix 'Login fails when email contains plus sign'` or `/iikit-bugfix #42` If input contains BOTH `#number` and text, prioritize the `#number` and warn that text is ignored. -### 2a. GitHub Inbound Flow +## Step 2 — Resolve Bug Source + +Take exactly one branch based on the input type from Step 1. + +**GitHub Inbound Flow** (when input matches `#number`): 1. Fetch issue: use `gh issue view --json title,body,labels` if available, otherwise `curl` the GitHub API (`GET /repos/{owner}/{repo}/issues/{number}`) 2. If fetch fails (issue not found, auth error, or no GitHub remote configured): ERROR with clear message and remediation; suggest using text description instead. @@ -47,14 +51,14 @@ If input contains BOTH `#number` and text, prioritize the `#number` and warn tha - `body` → reproduction steps - `labels` → severity: "critical" → critical, "high"/"priority" → high, "bug" → medium (default), otherwise → medium 4. Store issue number for GitHub Issue field in bugs.md -5. Continue to Step 3 -### 2b. Text Description Flow +**Text Description Flow** (when input is free-form text): 1. Store the text as the bug description -2. Continue to Step 3 -### 3. Select Feature & Full Setup +Both flows converge at Step 3. + +## Step 3 — Select Feature & Full Setup Run full setup to list features, validate, and get bug ID and task IDs. First, present feature list to user. After selection: @@ -73,7 +77,7 @@ Parse JSON for: `features` (list for display), `validation` (check `valid`), `bu If `validation.valid` is false: ERROR with the message. If `features` is empty: ERROR with "No features found." -### 4. Gather Bug Details +## Step 4 — Gather Bug Details **For text input (2b):** - Prompt user for **severity**: present options (critical, high, medium, low) with descriptions @@ -83,7 +87,7 @@ If `validation.valid` is false: ERROR with the message. If `features` is empty: - Severity is pre-filled from labels (confirm with user if mapping is ambiguous) - Reproduction steps are pre-filled from issue body (confirm with user) -### 5. Write bugs.md +## Step 5 — Write bugs.md Create or append to `/bugs.md` using the template at [bugs-template.md](references/bugs-template.md). @@ -102,7 +106,7 @@ If `bugs.md` already exists, append with `---` separator before the new entry. D If `bugs.md` does not exist, create it with the header `# Bug Reports: ` followed by the entry. -### 6. Outbound GitHub Issue (Text Input Only) +## Step 6 — Outbound GitHub Issue (Text Input Only) For text-input bugs only (NOT for GitHub inbound — issue already exists): @@ -110,11 +114,11 @@ For text-input bugs only (NOT for GitHub inbound — issue already exists): 2. Store returned issue number in the bugs.md GitHub Issue field 3. If no GitHub remote configured: warn that GitHub issue creation was skipped, proceed with local workflow -### 7. TDD & Task Generation +## Step 7 — TDD & Task Generation Use `tdd_determination` and `task_ids` from Step 3. Use `bug_id` from Step 3. -### 8. BDD/TDD Flow (If Mandatory) +## Step 8 — BDD/TDD Flow (If Mandatory) If TDD is mandatory (`determination` = `mandatory`): @@ -138,7 +142,7 @@ If TDD is mandatory (`determination` = `mandatory`): ``` 5. Continue to Step 9 with TDD task variant -### 9. Generate Bug Fix Tasks +## Step 9 — Generate Bug Fix Tasks Use `task_ids` from Step 3. Task IDs use `T-B` prefix — parsers and dashboard rely on this. @@ -172,7 +176,7 @@ Append to existing `/tasks.md`. If tasks.md does not exist, create Do NOT modify existing entries or task IDs in tasks.md. -### 10. Commit, Dashboard & Next Steps +## Step 10 — Commit, Dashboard & Next Steps **Unix/macOS/Linux:** ```bash diff --git a/.claude/skills/iikit-clarify/SKILL.md b/.claude/skills/iikit-clarify/SKILL.md index 910c0cf..b803bac 100644 --- a/.claude/skills/iikit-clarify/SKILL.md +++ b/.claude/skills/iikit-clarify/SKILL.md @@ -12,6 +12,8 @@ metadata: # Intent Integrity Kit Clarify (Generic Utility) +Process steps in order. Do not skip ahead. + Ask targeted clarification questions to reduce ambiguity in the detected (or user-specified) artifact, then encode answers back into it. ## User Input @@ -65,13 +67,11 @@ If no argument, auto-detect by checking artifacts in reverse phase order. Pick t If no clarifiable artifact exists: ERROR with `No artifacts to clarify. Run /iikit-01-specify first or /iikit-00-constitution.` -## Execution Steps - -### 1. Scan for Ambiguities +## Step 1 — Scan for Ambiguities Load the target artifact and perform a structured scan using the taxonomy for that artifact type from [ambiguity-taxonomies.md](../iikit-core/references/ambiguity-taxonomies.md). Mark each area: Clear / Partial / Missing. -### 2. Generate Question Queue +## Step 2 — Generate Question Queue **Constraints**: - Each answerable with multiple-choice (2-5 options) OR short phrase (<=5 words) @@ -85,7 +85,7 @@ Load the target artifact and perform a structured scan using the taxonomy for th - Only include questions that materially impact downstream phases - Balance category coverage, exclude already-answered, favor downstream rework reduction -### 3. Sequential Questioning +## Step 3 — Sequential Questioning Present ONE question at a time. @@ -95,7 +95,7 @@ Present ONE question at a time. **Stop when**: all critical ambiguities resolved or user signals done. -### 4. Integration After Each Answer +## Step 4 — Integration After Each Answer 1. Ensure `## Clarifications` section exists in the target artifact with `### Session YYYY-MM-DD` subheading 2. Append: `- Q: -> A: []` @@ -111,7 +111,7 @@ Present ONE question at a time. See [clarification-format.md](references/clarification-format.md) for format details. -### 5. Re-validate Affected Checklists +## Step 5 — Re-validate Affected Checklists If the clarified target was `spec.md` AND one or more `{FEATURE_DIR}/checklists/*.md` files are present, re-evaluate each checklist file against the updated spec: @@ -130,14 +130,14 @@ Append a **Checklist re-validation** entry under the active session in `spec.md` Skip this step when the target was not `spec.md` (plan, tasks, testify, checklist, constitution). Skip when no checklist files exist. -### 6. Validation +## Step 6 — Validation After each write and final pass: - Every Q&A bullet ends with `[refs]` (the optional Checklist re-validation entry from step 5 is exempt) - All referenced IDs exist in the artifact - No vague placeholders or contradictions remain -### 7. Report +## Step 7 — Report Output: questions asked/answered, target artifact and path, sections touched, traceability summary table (clarification -> referenced items), coverage summary (category -> status), checklist re-validation diff (when step 5 ran), suggested next command. diff --git a/.claude/skills/iikit-core/SKILL.md b/.claude/skills/iikit-core/SKILL.md index 9c4f4bc..4cdf363 100644 --- a/.claude/skills/iikit-core/SKILL.md +++ b/.claude/skills/iikit-core/SKILL.md @@ -10,7 +10,9 @@ metadata: # Intent Integrity Kit Core -Core skill providing project initialization, status checking, and workflow help. +This skill is an action router — pick the step that matches the user's intent and execute only that step. Do not run other steps; do not parallelize. + +Core skill providing project initialization, status checking, feature selection, scaffolding removal, and workflow help. ## User Input @@ -18,96 +20,68 @@ Core skill providing project initialization, status checking, and workflow help. $ARGUMENTS ``` -Parse the user input to determine which subcommand to execute. - -## Subcommands - -1. **init** - Initialize intent-integrity-kit in a new or existing project -2. **status** - Show current project and feature status -3. **use** - Select the active feature for multi-feature projects -4. **uninit** - Remove iikit scaffolding before `tessl uninstall` -5. **help** - Display workflow phases and command reference - -If no subcommand is provided, show help. - -## Subcommand: init - -Initialize intent-integrity-kit in the current directory. Handles the full project bootstrap: git init, optional GitHub repo creation, or cloning an existing repo. Optionally seeds the project backlog from an existing PRD/SDD document. - -### Argument Parsing - -The `$ARGUMENTS` after `init` may include an optional path or URL to a PRD/SDD document (e.g., `/iikit-core init ./docs/prd.md` or `/iikit-core init https://example.com/prd.md`). If present, store it as `prd_source` for use in Step 6. - -### Execution Flow +Parse the user input to determine which subcommand to execute. Available subcommands map to steps below: `init` (Step 1), `status` (Step 2), `use` (Step 3), `uninit` (Step 4), `help` (Step 5). If no subcommand is provided, execute Step 5 (help). > **Working directory**: All script paths are relative to the project root (the directory containing `tessl.json` or `.tessl/`). If a script path doesn't resolve, search with: `find . -path "*/iikit-core/scripts/bash/