IIKit Lite Mode: collapsed phases for small features

[jbaruch]

Summary

Introduce an /iikit-lite mode that collapses multiple IIKit phases into a single interaction with lighter artifacts, making the framework practical for small features where 90 minutes of ceremony is overkill.

Motivation

• Current minimum path from idea to code: 8 skill invocations, ~90 minutes of non-implementation overhead, 5-8 generated files
• Many features ("add a logout button", "fix pagination", "add a config option") don't warrant full ceremony
• Cavekit demonstrates that sketch → map → make can collapse into a single /ck:ship command
• Users abandon structured workflows when the cost exceeds the perceived value — lite mode keeps them in the framework

Scope

Single-Command Workflow

• /iikit-lite "feature description" runs specify → plan → tasks in one shot
• Produces the same artifact files (spec.md, plan.md, tasks.md) but with lighter content
• User reviews the combined output once, then proceeds to implement
• Falls back to full mode if the feature grows complex mid-flight

Lighter Artifacts

Artifact	Full Mode	Lite Mode
spec.md	User stories + FR-XXX + SC-XXX + edge cases + NFRs	User stories with inline acceptance criteria
plan.md	Architecture + research.md + data-model.md + contracts/ + quickstart.md	Tech stack + key decisions (single file, no satellite artifacts)
tasks.md	Dependency graph + parallel markers + phases	Flat numbered list
checklists/	Quality gate (blocks implementation)	Skipped or advisory-only warning
analysis.md	Cross-artifact consistency report	Skipped

Constitution Handling

• If CONSTITUTION.md exists, lite mode respects it (reduced validation, not zero)
• If no constitution exists, lite mode uses sensible defaults instead of blocking
• No phase 0 requirement for lite mode

Gate Relaxation

• Checklist gate (/iikit-03-checklist): advisory only (warning, not blocker)
• Analyze gate (/iikit-06-analyze): skipped entirely
• Implement gate: requires only spec.md + tasks.md (plan.md optional)

State Management

• context.json gets a "mode": "lite" flag
• /iikit-07-implement reads this flag and relaxes its prerequisite checks accordingly
• User can "upgrade" from lite to full mode at any point by running individual skills

Design Decisions to Resolve

1. Phase Separation in Lite Mode

FRAMEWORK-PRINCIPLES.md Principle IV (Phase Separation) is NON-NEGOTIABLE. Options:

• A) Amend principles to add "lite mode" exemption — phases still exist but with reduced requirements
• B) Reframe as "all phases execute internally, user interacts once" — the orchestrator runs specify, plan, tasks as sub-steps
• C) Keep spec.md/plan.md/tasks.md as separate files but allow lighter content within each

Recommendation: Option B — the phases still happen, they're just orchestrated. Artifacts remain separate files, preserving traceability.

2. When to Recommend Lite vs. Full

• Heuristic: if the feature description is < 2 sentences and touches < 5 files, suggest lite mode
• User can always override: /iikit-lite --full to upgrade, /iikit-01-specify --lite to downgrade
• Lite mode should warn when it detects complexity (multiple domains, data model changes, API contracts)

3. Upgrade Path

• Running any full-mode skill (e.g., /iikit-02-plan) on a lite-mode feature should work — it reads existing artifacts and expands them
• The mode flag in context.json switches from lite to full on upgrade
• No downgrade path (full → lite) — once expanded, stay expanded

Non-Goals

• NOT a different framework — same IIKit, same artifact structure, less ceremony
• NOT a replacement for full mode — lite is for small features, full is for complex ones
• NOT removing phase separation — phases still execute, just faster and lighter
• NOT a cavekit clone — no tiered build sites, no parallel subagent dispatch

Success Criteria

• Time from idea to first implement task: < 10 minutes (vs. ~90 for full mode)
• Artifacts produced are valid IIKit artifacts (implement skill can consume them)
• Upgrade from lite to full mode works without data loss
• Users with existing constitutions see their principles respected

Prior Art

• Cavekit /ck:ship — single command end-to-end
• Rails scaffolding — generates working structure with minimal input, user refines later
• GitHub issue templates — structured but lightweight