Initial commit: antigravity-ipa-workflow

skills/ipa-start/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: ipa-start
+description: Interactive wizard that guides users through selecting the correct IPA workflow path based on their project situation. Use when starting the IPA process for the first time, when unsure which IPA command to run first, or when onboarding to the workflow. Trigger phrases: "start ipa workflow", "ipa wizard", "help me start ipa".
+---
+
+## Overview
+
+Interactive wizard that detects the user's project situation and provides a tailored workflow path with specific next commands and critical warnings. Retains full wizard behavior with user questions and branching output.
+
+## When to Use
+
+- First time using IPA workflow
+- Unsure which IPA command to run first
+- Onboarding collaborators to the IPA process
+- Need a reminder of the correct path for a specific scenario
+
+## Don't Use When
+
+- Already familiar with IPA and know the next command to run
+- Looking for a command reference (use ipa-help instead)
+
+## Flow
+
+### Step 1: Project Type Detection
+
+Ask user which scenario applies:
+
+```
+What type of project are you starting?
+
+1. New project — Building from scratch
+   → Full workflow: lean → ipa-spec → ipa-design → ipa-detail
+
+2. Existing project (no IPA docs) — Code exists, need docs
+   → Extract docs: ipa-init → lean [feature] → plan
+
+3. Existing project (has IPA docs) — Add feature/improvement
+   → Feature mode: lean [feature] → plan → code
+
+4. Import external SRS — Have requirements document
+   → Import: ipa-import @path/to/srs.md → continue workflow
+```
+
+### Step 2: Workflow Guide
+
+Based on selection, output next steps with warnings.
+
+---
+
+## Output for New Project
+
+```
+## New Project Workflow
+
+Your Path:
+  lean "your idea"           ← Start here
+      ↓ [GATE 1: Scope]
+  ipa-spec                   → SRD.md + UI_SPEC.md
+      ↓ [GATE 2: Spec]
+  ipa-design                 → HTML mockups
+      ↓ [GATE 3: Design]
+  ipa-detail                 → API_SPEC.md + DB_DESIGN.md
+      ↓
+  plan @docs/ @prototypes/   → Implementation plan
+
+IMPORTANT TIPS
+
+1. GATE VALIDATION (Don't skip on first project)
+   - GATE 1: Validate scope with 3+ user interviews
+   - GATE 2: Get stakeholder sign-off on SRD
+   - GATE 3: Test mockups with 5+ users
+
+2. PLANNING WITH CONTEXT
+   Always include design context when planning:
+   CORRECT: plan @docs/ @prototypes/html-mockups/
+   WRONG:   plan "implement feature"
+
+3. DOCS SYNC
+   After coding, run ipa-docs-sync
+   Review changes before accepting
+
+Alternative: Fast Mode
+If experienced: ipa-fast "your idea" (skips all gates)
+
+Next Command:
+  lean "describe your idea here"
+```
+
+---
+
+## Output for Existing Project (No Docs)
+
+```
+## Existing Project (No Docs) Workflow
+
+Your Path:
+  ipa-init                   ← Start here
+      ↓
+  Review generated docs      → Fix inaccuracies
+      ↓
+  lean "feature idea"        → Feature analysis
+      ↓
+  plan @docs/                → Implementation plan
+
+IMPORTANT TIPS
+1. Review generated docs — ipa-init infers from code, may not be 100% accurate
+2. Always include docs in plan: plan [feature] @docs/
+3. Check traceability after changes: ipa-validate
+
+Next Command:
+  ipa-init
+```
+
+---
+
+## Output for Existing Project (Has Docs)
+
+```
+## Existing Project (Has Docs) Workflow
+
+Your Path:
+  lean "feature idea"        ← Start here
+      ↓
+  plan @docs/                → Implementation plan
+      ↓
+  code                       → Implementation
+      ↓
+  ipa-docs-sync              → Update docs
+
+IMPORTANT TIPS
+1. lean auto-detects existing docs and runs in Feature Mode
+2. Always include docs and prototypes in plan command
+3. If adding new screens, run ipa-design first
+
+Next Command:
+  lean "describe your feature idea"
+```
+
+---
+
+## Output for Import External SRS
+
+```
+## Import External SRS Workflow
+
+Your Path:
+  ipa-import @path/to/srs.md  ← Start here
+      ↓
+  Review converted docs        → Fix format issues
+      ↓
+  [GATE 2: Verify conversion]
+      ↓
+  ipa-design                   → Create mockups
+      ↓
+  Continue normal workflow...
+
+SUPPORTED FORMATS: Markdown, PDF, Plain text
+
+REVIEW CONVERSION: External SRS may not map perfectly to IPA format.
+Review FR-xx IDs and S-xx mappings.
+
+Next Command:
+  ipa-import @path/to/your-srs-file.md
+```
+
+---
+
+## Quick Reference Reminder
+
+After completing wizard, suggest:
+```
+Need help anytime? Run ipa-help for quick reference.
+```