@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/skills/app-compose-4-design-mock/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: app-compose-4-design-mock
+description: Create design mockups from screen specifications using .pen files. Use after completing documentation review with app-compose-3-doc-review. Generates visual UI mockups with shadcn components.
+---
+
+# Design Mockup Workflow
+
+Create visual UI mockups from Tier 3 screen documentation using .pen design files and shadcn components.
+
+## Prerequisites
+
+Tier 3 documentation must exist:
+
+- `docs/screen/*.md` (screen specifications)
+- Design system source file (contains reusable shadcn components)
+
+## Workflow Phases
+
+```
+SETUP → ANALYZE → DESIGN → VALIDATE
+```
+
+### Phase 1: Setup
+
+Ensure the design system file exists at the application's `docs/design.pen`.
+
+This provides access to 87+ shadcn reusable components including:
+
+- **Layout**: Sidebar, Card, Table, Data Table
+- **Form**: Input, Textarea, Select, Checkbox, Radio
+- **Navigation**: Breadcrumb, Pagination, Tabs
+- **Feedback**: Badge, Alert, Dialog
+- **Actions**: Button (Default, Secondary, Outline, Ghost, Destructive)
+
+### Phase 2: Analyze
+
+1. **Read** all screen documentation in `docs/screen/*.md`
+2. **Identify** screen types: ListView, DetailView, Form
+3. **Map** UI requirements to available components
+4. **Plan** layout hierarchy based on sidebar navigation
+
+### Phase 3: Design
+
+Create mockups using Pencil MCP tools.
+
+#### 3.1 Get Editor State
+
+```
+mcp__pencil__get_editor_state(include_schema: true)
+mcp__pencil__open_document(filePathOrTemplate: "docs/design.pen")
+```
+
+#### 3.2 Discover Components
+
+Search for reusable components:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  patterns: [{ "reusable": true }],
+  searchDepth: 3
+)
+```
+
+Key component patterns to search:
+
+| Component Type | Search Pattern          |
+| -------------- | ----------------------- |
+| Sidebar        | `{ "name": "Sidebar" }` |
+| Card           | `{ "name": "Card" }`    |
+| Table          | `{ "name": "Table" }`   |
+| Input          | `{ "name": "Input" }`   |
+| Button         | `{ "name": "Button" }`  |
+| Badge          | `{ "name": "Badge" }`   |
+
+#### 3.3 Create Screen Frames
+
+Use `batch_design` to create screens. Standard pattern:
+
+```javascript
+// Create screen frame
+screen = I("document", {
+  type: "frame",
+  name: "{screen-name}",
+  x: { x },
+  y: { y },
+  width: 1280,
+  height: 800,
+  fill: "$--background",
+  layout: "horizontal",
+});
+
+// Add sidebar
+sidebar = I(screen, {
+  type: "ref",
+  ref: "{sidebar-component-id}",
+  height: "fill_container",
+});
+U(sidebar + "/{title-id}", { content: "{app-name}" });
+
+// Add main content area
+mainContent = I(screen, {
+  type: "frame",
+  layout: "vertical",
+  gap: 24,
+  padding: 32,
+  width: "fill_container",
+  height: "fill_container",
+});
+```
+
+#### 3.4 Layout Organization
+
+Arrange screens by navigation hierarchy:
+
+| Row | Y Position | Screens                   |
+| --- | ---------- | ------------------------- |
+| 0   | 0          | Dashboard (Home)          |
+| 1   | 1000       | Primary feature screens   |
+| 2   | 2000       | Secondary feature screens |
+| 3   | 3000       | Tertiary feature screens  |
+| N   | N\*1000    | Settings/Admin screens    |
+
+Flow within rows: List → Detail → Create/Edit Form
+
+#### 3.5 Component Patterns by Screen Type
+
+**ListView Pattern:**
+
+```javascript
+// Header with title and action button
+header = I(mainContent, {
+  type: "frame",
+  justifyContent: "space_between",
+  alignItems: "center",
+  width: "fill_container",
+});
+title = I(header, {
+  type: "text",
+  content: "{page-title}",
+  fontSize: 24,
+  fontWeight: "600",
+  fill: "$--foreground",
+});
+actionBtn = I(header, { type: "ref", ref: "{button-component-id}" });
+
+// Filter row
+filterRow = I(mainContent, { type: "frame", gap: 12, alignItems: "center" });
+
+// Data table in card
+tableCard = I(mainContent, {
+  type: "ref",
+  ref: "{card-component-id}",
+  width: "fill_container",
+});
+```
+
+**Form Pattern:**
+
+```javascript
+// Card with header
+formCard = I(mainContent, {
+  type: "ref",
+  ref: "{card-component-id}",
+  width: "fill_container",
+});
+cardTitle = I(formCard + "/{header-slot-id}", {
+  type: "text",
+  content: "{form-title}",
+  fontSize: 18,
+  fontWeight: "600",
+});
+
+// Form fields in content slot
+formContent = I(formCard + "/{content-slot-id}", {
+  type: "frame",
+  layout: "vertical",
+  gap: 16,
+  width: "fill_container",
+});
+inputField = I(formContent, {
+  type: "ref",
+  ref: "{input-component-id}",
+  width: "fill_container",
+});
+U(inputField + "/{label-id}", { content: "{field-label}" });
+
+// Action buttons in footer slot
+btnRow = I(formCard + "/{footer-slot-id}", {
+  type: "frame",
+  gap: 12,
+  justifyContent: "flex_end",
+});
+```
+
+**DetailView Pattern:**
+
+```javascript
+// Breadcrumb navigation
+bcRow = I(mainContent, { type: "frame", gap: 4, alignItems: "center" });
+
+// Info cards
+infoCard = I(mainContent, {
+  type: "ref",
+  ref: "{card-component-id}",
+  width: "fill_container",
+});
+
+// Action section
+actionRow = I(mainContent, { type: "frame", gap: 12 });
+```
+
+### Phase 4: Validate
+
+Take screenshots to verify each screen:
+
+```
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+Check for:
+
+- Consistent sidebar navigation across screens
+- Proper alignment and spacing
+- Correct component usage
+- Readable text and labels
+
+## Tips
+
+- Always check component structure with `batch_get` before using `U()` updates
+- Use `find_empty_space_on_canvas` for positioning new screens
+- Sidebar navigation should highlight the current screen's menu item
+- Keep operations under 25 per `batch_design` call
+- Use consistent user profile in sidebar footer across all screens
+
+## Validation Commands
+
+```
+# Check layout structure
+mcp__pencil__snapshot_layout(filePath: "docs/design.pen", maxDepth: 0)
+
+# Verify screen screenshot
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+## Next Step
+
+After completing design mockups, use `/app-compose-5-design-mock-review` to review and validate the mockups against screen specifications.

package/skills/app-compose-5-design-mock-review/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: app-compose-5-design-mock-review
+description: Review design mockups (.pen files) against screen specifications. Use after completing design mockups with app-compose-4-design-mock. Validates visual consistency, detects regressions, and fixes layout issues.
+---
+
+# Design Mockup Review Workflow
+
+Review visual design mockups against Tier 3 screen documentation. Detect and fix regressions, layout issues, and specification mismatches.
+
+## Prerequisites
+
+- `docs/screen/*.md` (screen specifications)
+- `docs/design.pen` (design mockups from app-compose-4-design-mock)
+
+## Workflow Phases
+
+```
+INVENTORY → PARITY CHECK → VISUAL REVIEW → REGRESSION FIX → VALIDATE
+```
+
+### Phase 1: Inventory
+
+#### 1.1 Open Design File
+
+```
+mcp__pencil__get_editor_state(include_schema: false)
+mcp__pencil__open_document(filePathOrTemplate: "docs/design.pen")
+```
+
+#### 1.2 List Design Screens
+
+Extract top-level frames (screens) from design.pen:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  readDepth: 1
+)
+```
+
+Filter for screen frames (exclude design system components frame).
+
+#### 1.3 List Screen Specifications
+
+```bash
+ls docs/screen/*.md
+```
+
+### Phase 2: Parity Check
+
+#### Screen Count Validation
+
+| Check           | Question                                                     |
+| --------------- | ------------------------------------------------------------ |
+| Count match     | Does design.pen have same number of screens as screen/\*.md? |
+| Name match      | Does each screen in design.pen correspond to a spec file?    |
+| Missing screens | Any spec files without corresponding design frames?          |
+
+Create mapping table:
+
+```markdown
+| Screen Spec      | Design Frame               | Status     |
+| ---------------- | -------------------------- | ---------- |
+| {screen-name}.md | {Screen Name} ({frame-id}) | ✅         |
+| {screen-name}.md | -                          | ❌ Missing |
+```
+
+### Phase 3: Visual Review
+
+For each screen, perform detailed review:
+
+#### 3.1 Screenshot Capture
+
+```
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+#### 3.2 Specification Comparison
+
+**For ListView screens:**
+
+| Check                  | How to Verify                                        |
+| ---------------------- | ---------------------------------------------------- |
+| Required columns exist | Compare spec table columns with design table headers |
+| Column properties      | Sortable/Filterable indicators if applicable         |
+| Action buttons         | Create/Edit/Delete buttons per spec                  |
+| Pagination             | Present if list can be long                          |
+
+**For Form screens:**
+
+| Check                  | How to Verify                                    |
+| ---------------------- | ------------------------------------------------ |
+| All input fields exist | Match spec field list with form fields           |
+| Field types correct    | Text/Dropdown/Radio/Checkbox/FileUpload per spec |
+| Required indicators    | Required fields marked appropriately             |
+| Action buttons         | Submit/Cancel buttons present                    |
+
+**For DetailView screens:**
+
+| Check             | How to Verify                |
+| ----------------- | ---------------------------- |
+| Displayed fields  | All spec fields visible      |
+| Action buttons    | Available actions per spec   |
+| Status indicators | Badges/Timeline if specified |
+
+#### 3.3 Layout Problem Detection
+
+```
+mcp__pencil__snapshot_layout(
+  filePath: "docs/design.pen",
+  parentId: "{frame-id}",
+  problemsOnly: true,
+  maxDepth: 10
+)
+```
+
+Common problems:
+
+- `partially clipped` - Content overflows container
+- `fully clipped` - Element completely hidden
+- Negative coordinates - Mispositioned elements
+
+### Phase 4: Regression Fix
+
+#### 4.1 Layout Issues
+
+**Fixed height causing overflow:**
+
+```javascript
+// Change fixed height to fit_content
+U("{container-id}", { height: "fit_content", justifyContent: "start" });
+```
+
+**Element positioning:**
+
+```javascript
+// Reset position
+U("{element-id}", { x: 0, y: 0 });
+```
+
+#### 4.2 Style Inconsistencies
+
+**Background color mismatch:**
+
+```javascript
+// Use design token instead of hardcoded color
+U("{frame-id}", { fill: "$--background" });
+```
+
+**Missing icon:**
+
+```javascript
+// Add icon to sidebar item
+U("{frame-id}/{sidebar-id}/{menu-item-id}/{icon-id}", { iconFontName: "{icon-name}" });
+```
+
+**Text not visible (missing fill):**
+
+```javascript
+// Add fill color to text
+U("{text-id}", { fill: "$--foreground" });
+```
+
+#### 4.3 Missing Fields
+
+**Add missing form field:**
+
+```javascript
+newField = I("{form-container-id}", {
+  type: "ref",
+  ref: "{input-component-id}",
+  width: "fill_container",
+  descendants: {
+    "{label-id}": { content: "{field-label}" },
+    "{input-id}": { content: "{placeholder}" },
+  },
+});
+```
+
+#### 4.4 Common Component Fixes
+
+| Issue                   | Fix Pattern                                      |
+| ----------------------- | ------------------------------------------------ |
+| Card content overflow   | Set `height: "fit_content"` on Card Content slot |
+| Sidebar icons missing   | Update `iconFontName` on menu item icon element  |
+| Text invisible          | Add `fill: "$--foreground"` to text element      |
+| Inconsistent background | Use `$--background` instead of hex colors        |
+
+### Phase 5: Validate
+
+After fixes, re-verify each screen:
+
+```
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+Check:
+
+- Layout renders correctly
+- All text visible
+- Consistent styling
+- No clipped elements
+
+## Review Report Template
+
+```markdown
+## Design Mockup Review Report
+
+**Application:** {app-name}
+**Design File:** docs/design.pen
+
+### Screen Inventory
+
+| Screen        | Spec File        | Design Frame | Status |
+| ------------- | ---------------- | ------------ | ------ |
+| {screen-name} | {screen-name}.md | {frame-id}   | ✅     |
+
+### Issues Found & Fixed
+
+#### 1. [{screen-name}] - {issue-description}
+
+- **Problem:** {description}
+- **Root Cause:** {cause}
+- **Fix Applied:** {fix}
+
+### Remaining Issues
+
+- [ ] {issue-description}
+
+### Summary
+
+| Category         | Count   |
+| ---------------- | ------- |
+| Screens Reviewed | {count} |
+| Issues Found     | {count} |
+| Issues Fixed     | {count} |
+| Remaining        | {count} |
+```
+
+## Design Token Reference
+
+Retrieve available design tokens dynamically:
+
+```
+mcp__pencil__get_variables(filePath: "docs/design.pen")
+```
+
+Common token patterns:
+
+- `$--background` / `$--foreground` - Base colors
+- `$--card` / `$--border` - Card styling
+- `$--primary` / `$--secondary` - Action colors
+- `$--sidebar-*` - Sidebar-specific tokens
+- `$--muted-*` - Subdued variants
+
+## Sidebar Component Reference
+
+Retrieve sidebar component structure to find icon element paths:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  patterns: [{"reusable": true, "name": "Sidebar"}],
+  readDepth: 4
+)
+```
+
+To find icon names used in an existing screen's sidebar:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  nodeIds: ["{frame-id}/{sidebar-id}"],
+  readDepth: 5,
+  resolveInstances: true
+)
+```
+
+Look for `iconFontName` property in sidebar menu items. Icons use Lucide icon font family.
+
+## Next Step
+
+After completing design review, use `/app-compose-6-implementation-spec` to create Tier 4 documentation (resolvers).

package/skills/app-compose-6-implementation-spec/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: app-compose-6-implementation-spec
+description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing design review with app-compose-5-design-mock-review.
+---
+
+# Implementation Spec Workflow
+
+Create Tier 4 documentation: GraphQL Resolvers (mutations and queries).
+
+## Prerequisites
+
+Tier 1-3 documentation and design mockups must exist:
+
+- `README.md` (requirements)
+- `docs/actors/*.md` (actors)
+- `docs/business-flow/*/README.md` (flows)
+- `docs/business-flow/*/story/*.md` (stories)
+- `docs/screen/*.md` (screens)
+- `docs/design.pen` (UI mockups)
+
+## Workflow Phases
+
+```
+ANALYZE → IDENTIFY → CHECK MODULES → CREATE → VALIDATE
+```
+
+### Phase 1: Analyze
+
+Read all story files and identify:
+
+1. **Operations** that modify data → mutations
+2. **Operations** that retrieve data → queries
+3. **Error scenarios** for each operation
+
+### Phase 2: Identify
+
+Map stories to resolvers:
+
+| Story Element        | Resolver Type |
+| -------------------- | ------------- |
+| Create/Update/Delete | Mutation      |
+| View/List/Search     | Query         |
+| Real-time updates    | Subscription  |
+
+**Naming:** Use action-verb names: `create-`, `update-`, `delete-`, `submit-`, `approve-`
+
+### Phase 3: Check Module Dependencies
+
+Resolvers reference module commands. Before creating resolver docs, verify required modules exist.
+
+**Check existing modules:**
+
+```bash
+ls modules/
+```
+
+**Check module commands:**
+
+```bash
+ls modules/<module-name>/docs/commands/
+```
+
+**Map resolvers to modules:**
+
+| Resolver Operation | Typical Module        |
+| ------------------ | --------------------- |
+| User invite/roles  | `user-management`     |
+| Supplier CRUD      | `supplier-management` |
+| Document handling  | `document-management` |
+| Task workflows     | `task-management`     |
+
+**If modules don't exist:**
+
+1. **Identify needed modules** - Group resolver operations by domain
+2. **Create module docs first** - Use `1-module-docs` skill
+3. **Return to Tier 4** - After modules have documented commands
+
+```
+Tier 4 blocked → Create modules → Return to Tier 4
+```
+
+**Only reference existing module commands** in resolver documentation. Never reference modules or commands that don't exist.
+
+### Phase 4: Create
+
+Generate documentation using `erp-kit` CLI:
+
+```bash
+erp-kit scaffold --app-root examples resolver <app> <resolver-name>
+```
+
+**Naming conventions:**
+
+- Filename must match H1 heading exactly (kebab-case)
+- Action-focused names: `create-supplier-invitation.md`
+
+### Phase 5: Validate
+
+```bash
+pnpm run app:doc:check
+```
+
+## Schema Reference
+
+| Schema         | Tier | Output Path               |
+| -------------- | ---- | ------------------------- |
+| `resolver.yml` | 4    | `docs/resolver/<name>.md` |
+
+## Tips
+
+- One story may require 1-3 resolvers
+- Group related operations logically
+- Document all error scenarios
+
+## Completion
+
+After Tier 4, the application specification is complete:
+
+- **Tier 1**: Application overview
+- **Tier 2**: Actors and business workflows
+- **Tier 3**: User stories and screens
+- **Tier 4**: Implementation specifications