iikit-03-plan

star 1

Create technical implementation plan from feature specification

MikeCheng1208 By MikeCheng1208 schedule Updated 6/3/2026
play_arrow Run Skill in Manus View GitHub

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)    [Y/N]|
|  Success Criteria: X found (min: 3)    [Y/N]|
|  User Stories:     X found (min: 1)    [Y/N]|
|  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 "
    • 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: /, /, ..."
  • 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 (arch 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:

  1. Recommended: Run /iikit-04-checklist to create domain-specific quality checklists

    • Generates "unit tests for English" to validate requirements quality
    • Helps catch requirement gaps before implementation
    • Required to reach 100% before /iikit-08-implement

  2. If constitution requires TDD: (REQUIRED by constitution) Generate test specifications with /iikit-05-testify

    • If no TDD requirement: (Optional) Generate test specifications for TDD with /iikit-05-testify

  3. Required: Run /iikit-06-tasks to generate the task breakdown

Suggest to user:

Plan complete! Next steps:
- /iikit-04-checklist - (Recommended) Generate quality checklists for requirements validation
- /iikit-05-testify - Generate test specifications (REQUIRED if TDD mandated, otherwise Optional)
- /iikit-06-tasks - Generate task breakdown from plan
Install via CLI
npx skills add https://github.com/MikeCheng1208/BattleTree --skill iikit-03-plan
Repository Details
star Stars 1
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
MikeCheng1208
MikeCheng1208 Explore all skills →