Initial commit: antigravity-ipa-workflow

skills/ipa-detail/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ipa-detail
+description: Generate API_SPEC.md and DB_DESIGN.md from SRD and UI_SPEC — Stage 3 of the IPA pipeline. Use when SRD and UI_SPEC are complete and interface contracts plus database schema need to be defined, when designing API endpoints from screen requirements, or when creating language-agnostic data models from entity lists. Trigger phrases: "generate api spec and db design", "ipa detail design", "stage 3 ipa".
+---
+
+<HARD-GATE>Do NOT generate API_SPEC/DB_DESIGN until UI_SPEC.md exists. Run ipa-design first.</HARD-GATE>
+
+## Overview
+
+Generate Stage 3 Detail Design documents following IPA standard. Platform agnostic — works with any project type.
+
+Output:
+- `docs/API_SPEC.md` — Interface specifications (API/CLI/MCP/Chat)
+- `docs/DB_DESIGN.md` — Data design (SQL/NoSQL/Vector/File)
+
+## When to Use
+
+- docs/SRD.md and docs/UI_SPEC.md both exist and are reviewed
+- Ready to define API contracts and database schema
+- Completing Stage 3 of the IPA pipeline before planning
+
+## Don't Use When
+
+- UI_SPEC.md does not exist (run ipa-design first)
+- SRD.md is missing (run ipa-spec first)
+- Only UI changes are needed with no API/DB impact
+
+## Project Type Handling
+
+| Project Type | Interface Spec | Data Design |
+|--------------|----------------|-------------|
+| Web App | REST/GraphQL API | SQL/NoSQL |
+| Desktop App | IPC/Native API | SQLite/Local |
+| CLI Tool | Commands/Args/Flags | Config files |
+| MCP Server | Tools/Resources/Prompts | — |
+| Chatbot/RAG | Conversation flows | Vector DB |
+| Library/SDK | Public API/Methods | — |
+
+## Language-Agnostic Principle
+
+API_SPEC.md uses:
+- OpenAPI 3.x standard (YAML/JSON)
+- Standard HTTP methods
+- JSON Schema for request/response
+- No framework-specific code
+
+DB_DESIGN.md uses:
+- Standard SQL (DDL)
+- ER Diagram (Mermaid)
+- Portable data types
+- No ORM-specific syntax
+
+## Workflow
+
+1. Read `docs/SRD.md` for entities (E-xx) and features (FR-xx)
+2. Read `docs/UI_SPEC.md` for screen → API mapping (S-xx)
+3. Read prototypes if available for data flow visualization
+4. Generate `docs/DB_DESIGN.md` (schema based on E-xx, 3NF, ER diagram)
+5. Generate `docs/API_SPEC.md` (endpoints supporting all FR-xx and S-xx)
+6. Verify traceability: API ↔ Screen ↔ Feature ↔ Entity
+7. Ask user to review
+
+## Required Output Structure
+
+### docs/DB_DESIGN.md
+
+```markdown
+# Database Detailed Design
+
+## 1. ER Diagram
+[Mermaid ERD]
+
+## 2. Table Definitions
+
+### E-01: Users (users)
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | uuid | PK | Unique ID |
+| email | varchar | Unique, Not Null | User email |
+```
+
+### docs/API_SPEC.md
+
+```markdown
+# Interface Specification (API)
+
+## 1. Endpoint Matrix
+| Method | URL | Feature (FR-xx) | Screen (S-xx) |
+|--------|-----|-----------------|---------------|
+| POST | /auth/login | FR-01 | S-01 |
+
+## 2. Endpoint Details
+
+### POST /auth/login
+- **Description**: Authenticate user
+- **Request**: { "email": "...", "password": "..." }
+- **Response**: { "token": "..." }
+```
+
+## Traceability Check
+
+- Every table corresponds to an E-xx
+- Every endpoint links to an FR-xx
+
+## Next Steps
+
+After generation: run plan to create implementation tasks.
+
+Does not implement code — only generates documentation.