@dezycro-ai/agent-plugin 2.0.0

package/skills/import-features/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: import-features
+description: Reverse-engineers a codebase into Dezycro features with user-behavior PRDs and matching TRDs. Use when user asks to import, scan, or analyze a codebase into Dezycro, extract product requirements, or generate PRDs and TRDs from code.
+allowed-tools:
+  - AskUserQuestion
+  - mcp__dezycro__*
+  - Read
+  - Glob
+  - Grep
+  - Agent
+  - TaskCreate
+  - TaskUpdate
+---
+
+# Import Codebase into Dezycro
+
+Analyze this codebase and create **user-facing features** in Dezycro with PRDs describing user behavior and experience. Then generate TRDs describing how those features are implemented technically.
+
+**Your primary role**: You are a product manager documenting what users experience — not a developer documenting how code works.
+
+> **⛔ DUPLICATION GATE — READ THIS FIRST**
+>
+> You MUST call `list_features` and `search` to check for existing features BEFORE calling `create_feature` even once.
+> If you call `create_feature` without first completing Step 3 (deduplication), you are violating this skill.
+> There are NO exceptions — not "the project looks empty", not "the user said create", not "I'll check later."
+> Step 3 is as mandatory as Step 1. You cannot skip it.
+
+## What is a feature?
+
+A product capability that a distinct type of user interacts with. Not an internal service, not infrastructure.
+
+| Good features | Bad features |
+|---|---|
+| Login & Registration | Kafka Consumer |
+| Project Dashboard | Redis Cache |
+| Document Editor | Flyway Migrations |
+| Team Management | Editing Documents (verb) |
+
+---
+
+## Prerequisites
+
+Verify the Dezycro MCP server is connected by calling `list_workspaces`. If it fails, tell the user to run: `npx dezycro-setup`
+
+---
+
+## Process
+
+Follow these steps **in order**. Do NOT skip steps.
+
+### Step 1: Select Workspace and Project
+
+1. Call `list_workspaces`.
+2. Use `AskUserQuestion` with workspace names as `options` to let the user pick.
+   If only one workspace, confirm: question "Use workspace 'X'?", options: ["Yes", "No, cancel"]
+3. Call `list_projects` with the chosen workspaceId.
+4. Use `AskUserQuestion` with project names + "Create new project" as options.
+   If creating: ask for name via `AskUserQuestion`, then call `create_project`.
+5. Store workspaceId and projectId.
+
+**IMPORTANT**: Always use `AskUserQuestion` with `options` — never ask the user to type numbers or text.
+
+---
+
+### Step 2: Discover User Flows
+
+Your goal is to find **what users can do** in this application. Focus on user-facing flows, not internal architecture.
+
+**How to find user flows:**
+
+1. **Start with routes/pages** — entry points to user flows:
+   - Frontend: route definitions, page components, navigation menus
+   - Backend: REST controllers, API route files, GraphQL resolvers
+
+2. **Map each route to a user flow**:
+   - `/login`, `/register` → "Authentication & Onboarding"
+   - `/dashboard` → "Dashboard"
+   - `/settings/team` → "Team Management"
+
+3. **Read actual UI/API code** to understand what users do — don't guess from filenames.
+
+4. **Group related routes into features**:
+   - `/settings/profile`, `/settings/password`, `/settings/notifications` → "User Settings"
+   - `/projects`, `/projects/new`, `/projects/:id` → "Project Management"
+
+**What to SKIP:**
+- Infrastructure: databases, caching, queues, CI/CD, deployment
+- Internal services: background workers, schedulers, migrations
+- Libraries: utility functions, shared components without user-facing purpose
+- Configuration: env files, build config, linters
+
+---
+
+### Step 2.5: Design the Folder Structure
+
+> **Why this matters:** Dezycro uses **folder-scoped knowledge** — features in the same folder share context at full weight when the AI answers chat questions, generates TRDs, detects conflicts, or guides an AI coding agent. Folders outside the current one are deprioritized and drafts outside the folder are excluded entirely. **Bad folder grouping degrades the quality of every AI-assisted action in the product.** Good folder grouping compounds value.
+>
+> Treat folders as **domain boundaries**, not visual categorization. Two features belong in the same folder only if you would want the AI to automatically use one as context when working on the other.
+
+#### Folder design principles
+
+**1. Cohesion over neatness.** Group features that share a domain model, user flow surface, or data. "Cart Management" and "Payment Processing" belong together because editing one affects how you think about the other. "Cart Management" and "User Profile Settings" do not — they live in different mental models.
+
+**2. Use hierarchy when it reflects real containment.** Don't create nested folders just to feel organized. A folder hierarchy is meaningful only when the parent feature governs or scopes its children. For example, `Checkout/Cart Management` is meaningful if there will eventually be a parent-level PRD about checkout policies. Otherwise, flat grouping is better.
+
+**3. Aim for 3–8 features per folder.** Fewer than 3 and the folder adds no value (a lone feature may as well be at root). More than 8 and cohesion breaks down — split it. Hard cap: don't put more than 12 features in one folder.
+
+**4. Folders should be stable, not fashionable.** Name folders after enduring product areas ("Authentication", "Billing", "Project Management"), not current initiatives ("Q4 Revamp", "Phase 2 Features"). The folder tree will outlive any single project timeline.
+
+**5. Deep nesting is mostly unnecessary.** For most projects, 1 or 2 levels of folders are enough. 3 levels is rare and should be justified. Deep nesting fragments the knowledge base without adding real cohesion.
+
+**6. The project root is just another folder.** Features at root are treated as siblings of each other. Cross-cutting features (like "Admin Dashboard" or "System Settings") that touch many domains often belong at root rather than forced into a category.
+
+#### How to derive folders from the codebase
+
+Use the code's structure as a hint, but translate to the product domain:
+
+| Code signal | Folder candidate |
+|---|---|
+| A backend module / microservice boundary (e.g., `payment-service`) | A folder for that domain |
+| A frontend route prefix (e.g., `/admin/*`) | A folder for that area |
+| A natural user journey (e.g., checkout flow across several pages) | A folder containing the flow's features |
+| A permission boundary (e.g., "admin-only" features) | Often a folder |
+
+**Don't mirror the code structure 1:1.** Code organization often reflects technical concerns (one module per team, one service per deployment unit) that don't match product domains. Always ask: "Would a product manager put these together?"
+
+#### Cohesion check before proposing
+
+For each folder you plan to propose, ask:
+
+1. **"If I'm writing the PRD for Feature A in this folder, would knowing about Feature B genuinely help me?"** If no → they don't belong in the same folder.
+2. **"If A and B have conflicting requirements, is that something I'd want flagged?"** If yes → same folder. If no → different folders.
+3. **"Would it make sense for an AI coding agent working on Feature A to automatically read Feature B's docs?"** If yes → same folder.
+
+If you can't answer "yes" to all three for a given pair, they probably belong in separate folders.
+
+#### Edge cases
+
+- **Single-feature folder:** Avoid. If only one feature fits a domain, leave it at root until more join.
+- **Cross-cutting features:** Features that touch multiple domains (e.g., "Search", "Notifications") usually belong at root, not forced into a specific category.
+- **Orphan candidates:** If a feature doesn't fit any natural group, place it at root. Don't invent a "Miscellaneous" folder — it defeats the purpose of folder scoping.
+
+---
+
+### Step 3: Deduplicate Against Existing Features
+
+> **This step is MANDATORY. You must complete 3a and 3b before proposing anything.**
+> Do NOT rationalize skipping it ("project looks empty", "user just wants to create", "I'll check later").
+> The `list_features` and `search` calls are required — no exceptions.
+
+#### 3a: Inventory Existing Features
+
+**Required API calls — you must make these:**
+
+```
+list_features(workspaceId, projectId)                          // root level
+list_features(workspaceId, projectId, parentDirectoryId=X)     // for EACH directory returned
+// repeat recursively until all directories are traversed
+```
+
+Build a complete list of existing features: `id`, `name`, directory path, and whether PRD/TRD have content (from `documentSummaries`).
+
+**If the project has zero existing features:** Say "No existing features found — all proposals will be NEW." then skip to Step 3c.
+
+**If the project has existing features:** You MUST proceed to Step 3b. Do NOT skip it.
+
+#### 3b: Semantic Match Against Existing Features
+
+**Required API calls — you must make at least one `search` call per proposed feature:**
+
+```
+search(workspaceId, projectId, query="<feature's core user flows>", maxResults="5")
+```
+
+For example:
+- Proposed "Document Editor" → `search(... query="document editing creating saving draft")`
+- Proposed "Team Management" → `search(... query="invite team member roles permissions")`
+
+For each proposed feature, combine the name comparison + search results to classify it:
+
+| Classification | Criteria | Action |
+|---|---|---|
+| **🆕 NEW** | No name match AND no meaningful search results | Will be created |
+| **✅ EXACT MATCH** | Existing feature covers the same scope | Skip — do not recreate |
+| **🔄 PARTIAL MATCH** | Existing feature covers some but not all flows | Suggest updating existing feature |
+
+**Matching rules:**
+- A search result is "meaningful" if it describes the same user flows — not just keyword overlap.
+- When in doubt, classify as PARTIAL MATCH rather than NEW.
+- Different names can still be duplicates (e.g., "Authentication" and "Login & Sign Up").
+
+#### 3c: Propose the Feature Structure
+
+Present the full picture — what's new, what already exists, and what needs updating:
+
+```
+📁 Authentication & Onboarding
+  ✅ Login & Registration — ALREADY EXISTS (feature: "User Authentication", has PRD + TRD)
+  🆕 Password Recovery — NEW (flows: forgot password, reset link, new password)
+
+📁 Projects
+  🔄 Project Dashboard — PARTIAL MATCH (existing "Projects" covers create/list but not filtering or stats)
+       → Suggest: update existing "Projects" feature PRD to add filter, sort, stats flows
+  🆕 Project Setup — NEW (flows: create project, edit settings, archive)
+
+📁 Documents
+  🆕 Document Editor — NEW (flows: create, edit, save, AI chat, version history)
+  ✅ Knowledge Base — ALREADY EXISTS (feature: "Knowledge Base", has PRD)
+
+📁 Team
+  🔄 Team Management — PARTIAL MATCH (existing "Team" covers invites but not role changes)
+       → Suggest: update existing "Team" feature PRD to add role management flows
+  🆕 Organization Settings — NEW (flows: rename org, billing, API keys)
+
+Summary: 3 new · 2 already exist · 2 need updates
+```
+
+**Rules:**
+- Every feature must represent something a user DOES
+- Feature names should read like product capabilities, not code modules
+- Group by product area, not by code structure
+- Aim for 8–25 features total (including existing ones) — be selective, not exhaustive
+- For EXACT MATCH features, clearly state which existing feature covers it and whether it has PRD/TRD content
+- For PARTIAL MATCH features, describe specifically what's missing from the existing feature
+
+Use `AskUserQuestion` to confirm:
+question "Does this look right?",
+options: ["Yes, create new and update existing", "Yes, but only create new (skip updates)", "I want to make changes"]
+
+If they want changes, ask what to add/remove/reclassify, iterate, then confirm again.
+
+---
+
+### Step 4: Create and Update in Dezycro
+
+> **⛔ STOP — Before calling `create_feature`, verify ALL of these are true:**
+> 1. You called `list_features` to inventory existing features (Step 3a) — if you didn't, go back and do it NOW
+> 2. You called `search` for at least the first 3 proposed features (Step 3b) — if you didn't, go back and do it NOW
+> 3. You showed the user a proposal with ✅/🆕/🔄 classifications (Step 3c)
+> 4. The user approved the proposal via `AskUserQuestion`
+>
+> If ANY of these are false, STOP and complete the missing step before proceeding.
+
+Once approved, handle each classification differently:
+
+**For NEW features:**
+1. Create directories (top-down, parents first) via `create_directory`
+2. Create features via `create_feature`, then `move_feature` into directories
+3. For EACH feature, call `list_feature_documents` to get the PRD and TRD docIds
+4. Track all featureIds and their PRD docIds — you need them for Step 5
+
+**For EXACT MATCH features:**
+- Do nothing. Do NOT recreate them.
+- If a PRD/TRD exists but is empty (check `documentSummaries`), note it for Step 5 — the user may want to write/rewrite the content.
+
+**For PARTIAL MATCH features (if user chose to update):**
+1. Retrieve the existing feature's `featureId` from the inventory in Step 3a.
+2. Call `list_feature_documents` to get the existing PRD/TRD docIds.
+3. Track these for Step 5 — the PRD will be updated (not replaced) to cover the missing flows.
+4. Do NOT create a new feature or move anything.
+
+Report progress: "Created 3/8 new features... Queued 2 existing features for update..."
+
+---
+
+### Step 5: Write PRDs
+
+For each feature (both NEW and PARTIAL MATCH), read the relevant code and write or update a PRD.
+
+**For NEW features:** Write a full PRD covering all user flows within the feature.
+
+**For PARTIAL MATCH features (updating existing PRDs):**
+1. First, read the existing PRD content by calling `list_feature_documents` then reading the document.
+2. Identify which flows are already documented and which are missing.
+3. Write an updated PRD that **preserves all existing content** and **adds the missing flows**.
+4. Do NOT rewrite or rephrase existing sections unless they are factually wrong — only add what's missing.
+5. If the existing PRD uses a different structure than the template below, follow the existing structure for consistency.
+
+**For EXACT MATCH features:** Skip unless the PRD is empty (no content). If empty, write a full PRD as if it were new.
+
+#### Your mindset while writing PRDs
+
+You are a product manager who has watched users interact with the product. You are describing what users see, click, enter, and experience. You have no idea how the backend works — and that's intentional.
+
+**Before writing each PRD, ask yourself:**
+> "Would a product manager say this? Or is this something only a developer would know?"
+
+If only a developer would say it — leave it out of the PRD. It belongs in the TRD.
+
+#### PRD Structure
+
+Each PRD must contain these sections:
+
+**Overview**
+- What is this feature?
+- Why does it exist? What user problem does it solve?
+- Who uses it?
+
+**User Flows**
+For each flow within this feature:
+- Flow name (e.g., "Create New Document")
+- Step-by-step from the USER's perspective
+- Include: happy path + key error/edge cases
+
+**Business Rules**
+- Validation rules the user encounters (e.g., "email must be unique")
+- Permission constraints (e.g., "only admins can delete")
+- Tier/plan limits (e.g., "free tier limited to 3 projects")
+- Character limits, file size limits, etc.
+
+**Dependencies**
+- Which other features does this connect to? (user-facing connections only)
+
+---
+
+#### PRD Quality Rules — CRITICAL
+
+**INCLUDE in PRDs:**
+- What the user sees on screen
+- What the user clicks, types, selects
+- What happens after each action
+- What errors or messages the user sees
+- What permissions control who can do what
+- What limits or constraints the user encounters
+
+**NEVER include in PRDs:**
+- API endpoints or HTTP methods
+- Database table or column names
+- Class names, file paths, or component names
+- Request/response JSON formats
+- Backend validation logic or algorithms
+- Service names, repository names, or method calls
+- Infrastructure or architecture details
+
+---
+
+#### PRD — Good vs. Bad Examples
+
+**❌ BAD PRD paragraph** (technical contamination):
+> When the user submits the login form, the frontend calls `POST /api/v1/auth/login` with `{email, password}`. The `AuthController` validates credentials against the `users` table using bcrypt comparison. On success, a JWT is issued and stored in `localStorage`.
+
+**✅ GOOD PRD paragraph** (user behavior only):
+> The user enters their email address and password on the Login screen, then clicks "Sign In." If the credentials are correct, they are taken to their Dashboard. If not, they see an error message: "Invalid email or password." After 5 failed attempts, the account is temporarily locked and the user is shown instructions to reset their password.
+
+---
+
+**❌ BAD PRD paragraph** (technical contamination):
+> The `DocumentService.create()` method creates a new `Document` entity in PostgreSQL with `status=DRAFT`. The S3 key is generated from the workspace UUID.
+
+**✅ GOOD PRD paragraph** (user behavior only):
+> When the user clicks "New Document," a blank document is created and they are taken to the editor. The document is saved automatically as a draft every 30 seconds. A "Saving..." indicator appears in the top bar while saving is in progress.
+
+---
+
+#### PRD Writing Process (Per Feature)
+
+Follow this chain of thought before writing:
+
+1. **Identify users**: Who interacts with this feature? (admin, member, guest, etc.)
+2. **List flows**: What distinct tasks can each user type perform?
+3. **Walk each flow as a user**: Step through it as if you're clicking through the UI
+4. **Extract business rules**: What limits, permissions, or validations does the user encounter?
+5. **Write the PRD**: Use the structure above, user language only
+6. **Self-check**: Read each sentence and ask "Does this describe what a user sees/does, or what code does?" — remove any sentence that describes code
+
+**Target length**: 500–2000 words per PRD depending on feature complexity.
+
+Upload each PRD via `update_document(workspaceId, featureId, prdDocId, content)`, then immediately mark it complete via `change_document_status(workspaceId, featureId, prdDocId, status="COMPLETE")`.
+
+Report progress: "Writing PRD 3/15: Document Editor..."
+
+---
+
+### Step 6: Write TRDs
+
+After ALL PRDs are written, use `AskUserQuestion`:
+question "All PRDs written. Write TRDs from the code?",
+options: ["Yes, write TRDs from code", "No, I'm done for now"]
+
+**If "Write TRDs from code"** (the only auto path now — guided per-feature TRD authoring is done via `/dezycro:author --doc trd` after import):
+
+For each feature (NEW, PARTIAL MATCH, and EXACT MATCH with empty TRDs), read the backend code and write or update a TRD.
+
+**For PARTIAL MATCH features:** Read the existing TRD first. Preserve existing content and add sections covering the newly documented flows. Do NOT rewrite existing sections unless factually wrong.
+
+The TRD is the technical complement to the PRD. Where the PRD says "user sees an error", the TRD says "the endpoint returns HTTP 401 with `{error: 'INVALID_CREDENTIALS'}` and the frontend renders the error message from `auth/errors.ts`."
+
+#### TRD Structure
+
+- **Architecture Overview**: How this feature is structured technically
+- **Components**: Services, controllers, repositories, entities involved (with file paths)
+- **API Contracts**: Request/response shapes, status codes, auth requirements
+- **Data Model**: Database tables, columns, relationships, migrations
+- **Business Logic**: Core algorithms, validation rules, state machines in the code
+- **External Dependencies**: Third-party services, queues, caches, gRPC calls
+- **Error Handling**: How failures are handled, retry strategies, fallbacks
+- **Security**: Auth checks, tenant scoping, permission enforcement
+
+#### TRD Quality Rules
+
+- Write from the DEVELOPER's perspective — this is for engineers
+- Reference specific classes, methods, SQL, and config
+- Include actual API request/response examples from the code
+- Document the implementation as-is, not as it should be
+- 800–3000 words per TRD depending on complexity
+
+Get the TRD docId via `list_feature_documents` (type "TRD"). If no TRD document exists, create one first with `create_document(workspaceId, featureId, "TRD")`. Then upload content via `update_document`, then mark it complete via `change_document_status(workspaceId, featureId, trdDocId, status="COMPLETE")`.
+
+Report progress: "Writing TRD 3/15: Document Editor..."
+
+---
+
+## Rules
+
+- **Never create duplicates** — always inventory existing features and deduplicate before creating
+- **Prefer updating over recreating** — if a feature partially exists, update it rather than making a new one
+- **Preserve existing content** — when updating PRDs/TRDs, add missing flows without rewriting existing sections
+- **Folders are domain boundaries, not categorization** — features in the same folder must share a domain model, user flow surface, or data; bad folder grouping degrades every AI-assisted action in the product
+- **Apply the cohesion check** — for every folder, verify you'd want the AI to use one feature as context when working on another
+- **Avoid single-feature folders and deep nesting** — a folder with one feature adds nothing; more than 2 levels of nesting is rarely justified
+- **Don't mirror code structure** — code organization reflects technical concerns that often don't match product domains
+- **User flows only in PRDs** — skip infrastructure, internal services, background jobs
+- **Technical details only in TRDs** — endpoints, schemas, components, algorithms
+- **Always use AskUserQuestion** with options for any user choice
+- **Always wait for approval** before creating anything
+- **Write from code** — read the actual source, don't invent
+- **Handle errors gracefully** — log and continue
+- **Report progress** at each step

package/skills/init/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: init
+description: Set up a repository for Dezycro — connects to workspace/project, detects environment, writes .dezycro/config.json. Run once per repo.
+---
+
+# Dezycro Repository Setup
+
+You are setting up this repository to work with Dezycro. This is a one-time setup that creates `.dezycro/config.json`.
+
+## Prerequisites
+
+Before starting, verify the Dezycro MCP server is connected by calling `list_workspaces`. If it fails, tell the user:
+
+> The Dezycro MCP server is not configured. Add it to your Claude Code MCP settings:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "dezycro": {
+>       "url": "https://mcp.dezycro.ai/mcp",
+>       "headers": {
+>         "Authorization": "Bearer dzy_YOUR_API_KEY"
+>       }
+>     }
+>   }
+> }
+> ```
+>
+> Get your API key from **Dezycro > Settings > API Keys**.
+
+Then stop. Do not proceed without a working MCP connection.
+
+## Step 1: Select Workspace
+
+1. Call `list_workspaces`.
+2. If only one workspace, auto-select it and confirm with the user.
+3. If multiple, list them and ask the user to pick.
+4. Store the `workspaceId`.
+
+## Step 2: Select Project
+
+1. Call `list_projects` with the chosen `workspaceId`.
+2. If the user wants an existing project, list them and ask to pick.
+3. If the user wants a new project, ask for a name and call `create_project`.
+4. Store the `projectId`.
+
+## Step 3: Detect Environment Setup
+
+Scan the repository root for common patterns. Use the Glob tool to check for these files:
+
+1. **docker-compose.yml** or **docker-compose.yaml** — suggest `docker-compose up -d` as setup command
+2. **package.json** — read it, check for `dev` or `start` scripts. If found, suggest `npm run dev` or `yarn dev`.
+3. **Makefile** — read it, check for `run`, `dev`, or `serve` targets.
+
+Present what you found to the user:
+
+> I detected the following in your repo:
+> - `docker-compose.yml` found — setup: `docker-compose up -d`, teardown: `docker-compose down`
+>
+> Does this look right? You can also enter a custom command or skip environment setup.
+
+If nothing detected, ask:
+
+> How do you start your local dev environment? Enter a command (e.g., `docker-compose up -d`) or type "skip" to configure later.
+
+## Step 4: API URL and Health Check
+
+Ask the user:
+
+> What is your local API URL? (default: `http://localhost:3000`)
+
+Then:
+
+> Health check endpoint? (default: `/health`)
+
+Combine the API URL + health check path into a full health check command: `curl -sf {apiUrl}{healthPath}`
+
+## Step 5: Remote Environment (Optional)
+
+Ask:
+
+> Do you want to configure a remote dev environment too? (e.g., a shared dev/staging server)
+
+If yes, ask for:
+- Environment name (e.g., `dev`, `staging`)
+- API URL (e.g., `https://api.dev.example.com`)
+- Health check endpoint (default: same as local)
+
+## Step 6: Write Config
+
+Create the `.dezycro/` directory and write `.dezycro/config.json`:
+
+```json
+{
+  "version": 1,
+  "projectId": "<selected projectId>",
+  "workspaceId": "<selected workspaceId>",
+  "environments": {
+    "local": {
+      "setup": "<detected or entered setup command>",
+      "apiUrl": "<entered API URL>",
+      "teardown": "<detected or entered teardown command>",
+      "healthCheck": "curl -sf <apiUrl><healthPath>",
+      "default": true
+    }
+  }
+}
+```
+
+Omit `setup` and `teardown` keys if the user skipped environment setup. Include remote environments if configured (without `default: true`).
+
+Use the Bash tool to create the directory: `mkdir -p .dezycro`
+Use the Write tool to write the config file.
+
+## Step 7: Gitignore Check
+
+Read `.gitignore` (if it exists) and check if it already covers `.dezycro/`. If not, suggest adding:
+
+```
+# Dezycro local state
+.dezycro/active-feature.json
+.dezycro/bin/
+```
+
+Ask the user if they want `.dezycro/config.json` committed (recommended) or gitignored too. If they want it gitignored, add `.dezycro/` instead.
+
+## Done
+
+Tell the user:
+
+> Dezycro setup complete! Your config is at `.dezycro/config.json`.
+>
+> Next: run `/dezycro:work <feature-name>` to start working on a feature.

package/skills/publish-spec/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: publish-spec
+description: Auto-detect and upload an OpenAPI spec for the active feature. Triggers JEP generation. Requires an active feature (run /dezycro:work first).
+---
+
+# Publish Feature API Spec
+
+You are detecting the project's OpenAPI spec, optionally filtering it to feature-relevant endpoints, and uploading it to trigger JEP generation.
+
+## Step 1: Read Active Feature
+
+Read `.dezycro/active-feature.json` using the Read tool. If the file does not exist, tell the user:
+
+> No active feature. Run `/dezycro:work <feature-name>` first to select a feature.
+
+Then stop.
+
+Extract `featureId`, `featureName`.
+
+## Step 2: Read Config
+
+Read `.dezycro/config.json` to get `workspaceId`.
+
+## Step 3: Auto-Detect OpenAPI Spec
+
+Search for OpenAPI spec files in this order. Use Glob to find files, then Read to check their content:
+
+1. **Spring Boot / Java / Kotlin**:
+   - Glob: `**/build/generated/openapi/*.json`
+   - Glob: `**/target/generated-docs/openapi*.json`
+   - Glob: `**/src/main/resources/openapi*.json`
+   - Glob: `**/src/main/resources/openapi*.yaml`
+
+2. **Express / Node.js**:
+   - Glob: `**/swagger-output.json`
+   - Glob: `**/openapi.json`
+   - Glob: `**/openapi.yaml`
+   - Glob: `**/docs/openapi*.{json,yaml}`
+
+3. **Go**:
+   - Glob: `**/docs/swagger.json`
+   - Glob: `**/api/openapi*.{json,yaml}`
+
+4. **Generic**:
+   - Glob: `**/*openapi*.{json,yaml,yml}`
+   - Glob: `**/*swagger*.{json,yaml,yml}`
+
+5. **Live endpoint** (if an environment is running):
+   - Read `.dezycro/config.json` for the default environment's `apiUrl`
+   - Try: `curl -sf <apiUrl>/v3/api-docs` via Bash
+   - Try: `curl -sf <apiUrl>/swagger.json` via Bash
+
+If **multiple files found**, list them and ask the user to pick.
+
+If **no files found**, tell the user:
+> No OpenAPI spec detected. You can:
+> 1. Provide a file path to your spec
+> 2. Provide a URL to fetch the spec from
+> 3. Start your server and I'll try to fetch it from `/v3/api-docs`
+
+## Step 4: Validate Spec
+
+Read the selected file. Check that it contains either:
+- `"openapi"` key (OpenAPI 3.x)
+- `"swagger"` key (Swagger 2.x)
+
+If it's YAML, note that `publish_feature_spec` expects JSON — you will need to mention this to the user if conversion is needed.
+
+If invalid, tell the user:
+> This doesn't look like a valid OpenAPI spec (no `openapi` or `swagger` key found). Please check the file.
+
+## Step 5: Filter (Optional)
+
+Ask the user:
+
+> The spec contains N endpoints. Want to:
+> 1. Upload the full spec (recommended for most cases)
+> 2. Filter to specific path prefixes (e.g., `/api/otp/*`)
+> 3. Filter by tag
+
+If they choose to filter, extract only the matching paths and their referenced schemas. Construct a valid OpenAPI document with just the filtered content.
+
+## Step 6: Upload
+
+Upload via the MCP tool. The tool handles multipart upload internally:
+
+```
+publish_feature_spec(workspaceId, featureId, openApiFragment)
+```
+
+Where `openApiFragment` is the JSON string of the spec. The MCP tool uploads it as a multipart file to the backend (max 5 MB).
+
+## Step 7: Report
+
+Tell the user:
+
+> Spec published for "<featureName>". JEP generation workflow has been triggered — this typically takes 2-5 minutes.
+>
+> Once complete, run `/dezycro:verify` to pull the verifier binary and test your implementation.
+>
+> You can check generation status by running `/dezycro:status`.