Ctrl + K
DocumentationLog inGet started

tessl-labs/intent-integrity-kit

tessl install tessl-labs/intent-integrity-kit@1.0.2

Closing the intent-to-code chasm - specification-driven development with cryptographic verification

SKILL.mdskills/iikit-03-plan/

name:
iikit-03-plan
description:
Create technical implementation plan from feature specification

Intent Integrity Kit Plan

Execute the implementation planning workflow using the plan template to generate design artifacts.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Constitution Loading (REQUIRED)

Before ANY action, load and internalize the project constitution:

  1. Read constitution:

    cat CONSTITUTION.md 2>/dev/null || echo "NO_CONSTITUTION"

  2. If file doesn't exist:

    ERROR: Project constitution not found at CONSTITUTION.md

Cannot proceed without constitution.
Run: /iikit-00-constitution

  3. Parse all principles, constraints, and governance rules.

  4. Extract Enforcement Rules:

    • Find all lines containing "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED", "NON-NEGOTIABLE"
    • Build an enforcement checklist from these rules
    • Example extraction: 
      CONSTITUTION ENFORCEMENT RULES:
[MUST] Use TDD - write tests before implementation
[MUST NOT] Use external dependencies without justification
[REQUIRED] All code must have error handling

  5. Validation commitment: Every output will be validated against each principle before being written.

  6. Hard Gate Declaration: State explicitly:

    CONSTITUTION GATE ACTIVE
Extracted X enforcement rules
ANY violation will HALT planning with explanation

Prerequisites Check

  1. Run setup script (choose based on platform):

    Unix/macOS/Linux:

    bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/bash/setup-plan.sh --json

    Windows (PowerShell):

    pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/setup-plan.ps1 -Json

  2. Parse JSON for:

    • FEATURE_SPEC - path to spec.md
    • IMPL_PLAN - path to plan.md
    • SPECS_DIR - feature directory
    • BRANCH - current branch name

  3. If error or missing spec.md:

    ERROR: spec.md not found in feature directory.

Run: /iikit-01-specify <feature description>

Smart Validation

BEFORE proceeding to planning, perform semantic validation:

Spec Quality Gate

Read the spec.md and validate:

  1. Requirement Count Check:

    • Count functional requirements (FR-XXX patterns)
    • If fewer than 3 requirements: 
      WARNING: Spec may be underspecified (found X requirements, recommend 3+).
    • If 0 requirements: 
      ERROR: Cannot plan without requirements.

The spec.md has no functional requirements (FR-XXX).
Run: /iikit-01-specify to add requirements, or manually add FR-XXX items to spec.md

  2. Measurable Success Criteria Check:

    • Scan Success Criteria section for numeric values, percentages, or time measurements
    • If no measurable criteria found: 
      WARNING: No measurable success criteria found.

Recommendation: Add metrics like "under 3 seconds", "95% uptime", "10,000 users".

  3. Unresolved Clarification Check:

    • Search for [NEEDS CLARIFICATION] markers
    • If found, list each one and ask: "Resolve these before planning, or proceed with assumptions?"
    • If user says proceed, document assumptions explicitly in plan.md

  4. User Story Coverage Check:

    • Verify each user story has at least one acceptance scenario
    • If any story lacks scenarios: 
      WARNING: User Story X has no acceptance criteria.

Recommendation: Add acceptance scenarios to validate the story is complete.

  5. Cross-Reference Validation:

    • Check that requirements reference user stories (or vice versa)
    • If orphan requirements exist: 
      WARNING: Orphan requirement detected (FR-XXX not linked to any user story).

Recommendation: Link requirements to user stories for traceability.

Quality Score Report

Calculate and display:

╭─────────────────────────────────────────────╮
│  SPEC QUALITY REPORT                        │
├─────────────────────────────────────────────┤
│  Requirements:     X found (min: 3)    [✓/✗]│
│  Success Criteria: X found (min: 3)    [✓/✗]│
│  User Stories:     X found (min: 1)    [✓/✗]│
│  Measurable:       X criteria have metrics  │
│  Clarifications:   X unresolved             │
│  Coverage:         X% requirements linked   │
├─────────────────────────────────────────────┤
│  OVERALL SCORE: X/10                        │
│  STATUS: [READY/NEEDS WORK]                 │
╰─────────────────────────────────────────────╯

If score < 6: Recommend running /iikit-02-clarify first If score >= 6: Proceed with planning

Execution Flow

1. Setup

  • Run setup script to get paths and copy plan template
  • Read FEATURE_SPEC and constitution
  • Load IMPL_PLAN template

2. Execute Plan Workflow

Follow the structure in IMPL_PLAN template to:

  1. Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION"):

    • Language/Version
    • Primary Dependencies
    • Storage
    • Testing
    • Target Platform
    • Project Type
    • Performance Goals
    • Constraints
    • Scale/Scope

  2. Fill Constitution Check section from constitution principles

  3. Evaluate gates - ERROR if violations cannot be justified

3. Tessl Tile Discovery (MANDATORY if Tessl installed)

Purpose: Discover, install, and catalog Tessl tiles for all technologies in the Technical Context. Tiles provide documentation, rules, and skills that improve implementation quality.

3.1 Check Tessl Availability

Platform Detection:

  • Unix/Linux/macOS: command -v tessl >/dev/null 2>&1
  • Windows PowerShell: Get-Command tessl -ErrorAction SilentlyContinue

If Tessl NOT Available: Display once and continue without tile operations:

ℹ️ Tessl not installed. Tile-based documentation unavailable.
   Install Tessl for enhanced library documentation: https://tessl.io

If Tessl Available: Proceed with tile discovery.

3.2 Check Tessl Status

mcp__tessl__status()

This shows authentication status and any existing tiles.

3.3 Extract Technologies from Technical Context

From the drafted Technical Context, extract:

  • Language/Version (e.g., "Python 3.12", "TypeScript 5.x")
  • Primary Dependencies (e.g., "Click", "Express", "React")
  • Storage (e.g., "SQLite", "PostgreSQL", "MongoDB")
  • Testing (e.g., "pytest", "Jest", "Vitest")
  • Any other frameworks/libraries mentioned

3.4 Search and Install Tiles for Each Technology

For each technology identified:

  1. Search for tiles:

    mcp__tessl__search(query="<technology>")

  2. For each tile found, identify type:

    • Documentation tile: Contains library usage specs (has describes field)
    • Rules tile: Contains behavioral guidelines (has rules section)
    • Skills tile: Contains invocable AI commands (has skill section)

  3. Install relevant tiles:

    mcp__tessl__install(packageName="<workspace/tile-name>")

  4. Document in research.md (Tessl Tiles section):

    ## Tessl Tiles

### Installed Tiles

| Technology | Tile | Type | Version |
|------------|------|------|---------|
| Python | tessl/python | Documentation | 1.2.0 |
| Click | tessl/click | Documentation | 0.8.0 |
| pytest | tessl/pytest | Documentation + Rules | 1.0.0 |

### Available Skills

The following skills are available from installed tiles:
- `/<skill-name>` - Description of what the skill does

### Technologies Without Tiles

- <technology>: No tile found in registry

  5. If no tiles found for a technology:

    • Note in research.md: "No Tessl tile available for <technology>"
    • Continue without tile for that technology

3.5 Query Installed Documentation Tiles for Best Practices

For each installed documentation tile, query for best practices:

mcp__tessl__query_library_docs(query="best practices for <library>")

Incorporate findings into research.md decisions section.

3.6 Catalog Installed Skill Tiles

List all available skills from installed tiles:

  • Record skill name and purpose
  • Note in research.md: "Available skills: /<skill-1>, /<skill-2>, ..."
  • Skills become available for use in subsequent phases (especially /iikit-08-implement)

3.7 Handle Failures Gracefully

  • Network issues: Log warning, continue without affected tiles
  • Registry unavailable: Log warning, continue without tiles
  • Authentication required: Prompt user to run tessl login, continue without tiles
  • Search returns no results: Note in research.md, continue

4. Phase 0: Outline & Research (includes Tessl findings)

  1. Extract unknowns from Technical Context:

    • For each NEEDS CLARIFICATION -> research task
    • For each dependency -> best practices task
    • For each integration -> patterns task

  2. Research each unknown and document findings

  3. Consolidate findings in research.md:

    • Decision: [what was chosen]
    • Rationale: [why chosen]
    • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved (includes Tessl Tiles section if Tessl available)

5. Phase 1: Design & Contracts

Prerequisites: research.md complete

  1. Extract entities from feature spec -> data-model.md:

    • Entity name, fields, relationships
    • Validation rules from requirements
    • State transitions if applicable

  2. Generate API contracts from functional requirements:

    • For each user action -> endpoint
    • Use standard REST/GraphQL patterns
    • Output OpenAPI/GraphQL schema to /contracts/

  3. Create quickstart.md with test scenarios

  4. Agent context update (choose based on platform):

    Unix/macOS/Linux:

    bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/bash/update-agent-context.sh claude

    Windows (PowerShell):

    pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/update-agent-context.ps1 -AgentType claude

    This updates CLAUDE.md with the new technology stack using the agent-file-template.md.

Output: data-model.md, /contracts/*, quickstart.md, updated agent file

6. Constitution Check (Post-Design)

Re-evaluate the Constitution Check after design phase:

  • Verify all technical decisions align with principles
  • If ANY violation detected:
    • STOP immediately
    • State: "CONSTITUTION VIOLATION: [Principle Name]"
    • Explain what specifically violates the principle
    • Suggest compliant alternative approach
    • DO NOT proceed with "best effort" or workarounds

7. Phase Separation Validation (REQUIRED)

Before finalizing, scan the draft plan for governance content that belongs in /iikit-00-constitution:

Check for violations - plan MUST NOT contain:

  • Project governance principles or "laws"
  • Non-negotiable development rules (e.g., "always use TDD", "code review required")
  • Quality standards that apply project-wide (e.g., "100% test coverage")
  • Amendment procedures or versioning policies
  • Compliance or audit requirements
  • Team workflow rules (e.g., "PRs must be approved by 2 reviewers")
  • Coding standards that aren't technology-specific

Plan SHOULD contain (these are appropriate here):

  • Technology stack decisions (languages, frameworks, databases)
  • Architecture patterns for THIS feature
  • Implementation approach and rationale
  • Data models and API contracts
  • Performance targets for THIS feature
  • Technology-specific best practices

If violations found:

╭─────────────────────────────────────────────────────────────────╮
│  PHASE SEPARATION VIOLATION DETECTED                           │
├─────────────────────────────────────────────────────────────────┤
│  Plan contains governance content:                             │
│  - [list each violation]                                       │
│                                                                 │
│  Governance principles belong in /iikit-00-constitution.     │
│  Plan defines HOW to implement THIS feature, not project laws. │
├─────────────────────────────────────────────────────────────────┤
│  ACTION: Moving governance content to constitution reference...│
╰─────────────────────────────────────────────────────────────────╯

Auto-fix: Replace governance statements with constitution references:

  • "Always use TDD" → "Per constitution: [reference TDD principle]"
  • "Code must have 100% coverage" → "Coverage target per constitution"
  • "All PRs require review" → (remove - this is workflow, not implementation)

Re-validate after fixes until no violations remain.

Output Validation (REQUIRED)

Before writing ANY artifact:

  1. Review output against EACH constitutional principle
  2. If ANY violation detected:
    • STOP immediately
    • State: "CONSTITUTION VIOLATION: [Principle Name]"
    • Explain: What specifically violates the principle
    • Suggest: Compliant alternative approach
  3. If compliant, proceed and note: "Validated against constitution v[VERSION]"

Key Rules

  • Use absolute paths
  • ERROR on gate failures or unresolved clarifications
  • Command ends after Phase 1 design is complete

Report

Output:

  • Branch name
  • IMPL_PLAN path
  • Generated artifacts list:
    • research.md (includes Tessl Tiles section if Tessl available)
    • data-model.md
    • contracts/*
    • quickstart.md
  • Agent file update status
  • Tessl integration status:
    • Tiles installed (with versions)
    • Skills available for implementation phase
    • Technologies without tiles

Semantic Diff on Re-run

If plan.md already exists with content, perform semantic diff before overwriting:

1. Detect and Parse Existing Plan

If plan.md exists and has Technical Context filled in:

  1. Extract semantic elements:

    • Language/Version
    • Primary Dependencies
    • Storage choice
    • Project structure decisions

  2. Compare with new content:

    ╭─────────────────────────────────────────────────────╮
│  SEMANTIC DIFF: plan.md                             │
├─────────────────────────────────────────────────────┤
│  Tech Stack:                                        │
│    ~ Language: Python 3.11 → Python 3.12            │
│    + Added: Redis for caching                       │
│    - Removed: None                                  │
│                                                     │
│  Architecture:                                      │
│    ~ Changed: Switched from REST to GraphQL         │
│    + Added: Event sourcing pattern                  │
├─────────────────────────────────────────────────────┤
│  DOWNSTREAM IMPACT:                                 │
│  ⚠ tasks.md MUST be regenerated (architecture change)│
│  ⚠ contracts/ need updates (API change)            │
│  ⚠ data-model.md may need updates                  │
╰─────────────────────────────────────────────────────╯

  3. Flag breaking changes:

    • Language change → ALL tasks affected
    • Framework change → Most tasks affected
    • Storage change → Data layer tasks affected

2. Automatic Downstream Invalidation

If significant changes detected:

WARNING: Plan changes detected that invalidate downstream artifacts.
Recommend re-running:
- /iikit-06-tasks (REQUIRED - architecture changed)
- /iikit-07-analyze (RECOMMENDED - verify consistency)

Next Steps

After completing the plan, determine next step based on constitution:

If TDD is MANDATORY in constitution:

Plan complete! Next steps:
1. /iikit-04-checklist - (Recommended) Generate quality checklists
2. /iikit-05-testify - (REQUIRED by constitution) Generate test specifications
3. /iikit-06-tasks - Generate task breakdown

If TDD is optional or not mentioned:

Plan complete! Next steps:
1. /iikit-04-checklist - (Recommended) Generate quality checklists
2. /iikit-05-testify - (Optional) Generate test specifications for TDD
3. /iikit-06-tasks - Generate task breakdown

IMPORTANT: Do NOT suggest /iikit-08-implement here - it requires tasks.md to exist first.

Version

Workspace
tessl-labs
Visibility
Public
Created
Last updated

skills

iikit-03-plan

SKILL.md
index.mdtile.json