Clavix Plan Skill

Transform PRD documents into structured, actionable task lists with proper sequencing.

State Assertion (REQUIRED)

Before starting task breakdown, output:

**CLAVIX MODE: Technical Planning**
Mode: planning
Purpose: Generating low-level engineering tasks from PRD & Codebase
Implementation: BLOCKED - I will create the plan, not the code

Self-Correction Protocol

DETECT: If you find yourself doing any of these mistake types:

| Type | What It Looks Like | |------|--------------------| | 1. Generic Tasks | "Create login page" (without specifying file path, library, or pattern) | | 2. Ignoring Context | Planning a Redux store when the project uses Zustand, or creating new CSS files when Tailwind is configured | | 3. Implementation Code | Writing full function bodies or components during the planning phase | | 4. Missing Task IDs | Not assigning proper task IDs for tracking | | 5. Capability Hallucination | Claiming features Clavix doesn't have |

STOP: Immediately halt the incorrect action.

CORRECT: Output:

"I apologize - I was [describe mistake]. Let me return to generating specific technical tasks based on the codebase."

RESUME: Return to the workflow with correct context-aware approach.

Workflow

Phase 1: Context Analysis (CRITICAL)

Before reading the PRD, understand the codebase patterns.

Scan Directory Structure:
- Run ls -R src (or relevant folders) to see the file layout
- Identify folder conventions (features/, components/, services/)
Read Configuration:
- Read package.json to identify dependencies (React? Vue? Express? Tailwind? Prisma?)
- Read tsconfig.json or similar to understand aliases and strictness
- Check for .eslintrc, prettier.config, etc.
Identify Patterns:
- Open 1-2 representative files (e.g., a component, a service, a route)
- Determine:
  - How is state managed? (Context, Redux, Zustand?)
  - How is styling done? (CSS Modules, Tailwind, SCSS?)
  - How are API calls made? (fetch, axios, custom hooks?)
  - Where are types defined?

Output Summary:

Detected Stack Summary:
- Framework: [e.g., Next.js 14 App Router]
- Styling: [e.g., Tailwind CSS + shadcn/ui]
- State: [e.g., Zustand (stores in /src/store)]
- API: [e.g., Server Actions + Prisma]
- Conventions: [e.g., kebab-case files, Zod for validation]

Phase 2: PRD Ingestion

Locate PRD:
- Check .clavix/outputs/<project-name>/ for full-prd.md, quick-prd.md
- If missing, check legacy .clavix/outputs/summarize/
Read PRD: Ingest all requirements
Extract Architecture Section:
- Look for "Architecture & Design" section
- Note any specific patterns (Clean Architecture, Feature-Sliced Design)
- Identify structural decisions from PRD

If no PRD found:

"I don't see a PRD for this project. Please run /clavix-prd first to generate requirements, or provide them directly."

Phase 3: Task Generation

Architecture First Principle:
- If the PRD specifies a pattern (e.g., Repository), the first tasks MUST set up that structure
- Bad: "Implement user feature"
- Good: "Create src/repositories/UserRepository.ts interface first, then implementation"
Specific File Paths Required:
- Bad: "Create a user profile component"
- Good: "Create src/components/user/UserProfile.tsx. Export as default"
Technical Constraints:
- Bad: "Add validation"
- Good: "Use zod schema in src/schemas/user.ts. Integrate with react-hook-form"
Respect Existing Architecture:
- If project uses services/ folder for API calls, don't put fetch calls in components
- If project uses shadcn/ui, instruct to use those primitives, not raw HTML
Draft Tasks: Create tasks using the Task Format Reference below
Save to: .clavix/outputs/{project-name}/tasks.md

Task Format Reference

You must generate tasks.md using this exact format:

# Implementation Plan

**Project**: {project-name}
**Generated**: {ISO timestamp}

## Technical Context & Standards

*Detected Stack & Patterns*
- **Architecture**: {e.g., Feature-Sliced Design, Monolith}
- **Framework**: {e.g., Next.js 14 App Router}
- **Styling**: {e.g., Tailwind CSS + shadcn/ui}
- **State**: {e.g., Zustand (stores in /src/store)}
- **API**: {e.g., Server Actions + Prisma}
- **Conventions**: {e.g., "kebab-case files", "Zod for validation"}

---

## Phase 1: {Phase Name}

- [ ] **{Task Title}** (ref: {PRD Section})
  Task ID: phase-1-{name}-01
  > **Implementation**: Create/Edit `{file/path}`.
  > **Details**: {Technical instruction with specifics}

- [ ] **{Next Task Title}**
  Task ID: phase-1-{name}-02
  > **Implementation**: Modify `{file/path}`.
  > **Details**: {Specific logic requirements}

## Phase 2: {Phase Name}

- [ ] **{Task Title}** (ref: {PRD Section})
  Task ID: phase-2-{name}-01
  > **Implementation**: Create `{file/path}`.
  > **Details**: {Technical instruction}

---

*Generated by Clavix /clavix-plan*

Task ID Format

Pattern: phase-{phase-number}-{sanitized-phase-name}-{task-counter}

Examples:

phase-1-setup-01
phase-2-auth-03
phase-3-testing-02

Checklist Rules

Use - [ ] for pending tasks
Use - [x] for completed tasks
Implementation Note: The > **Implementation** block is REQUIRED for every task

Granularity Guidelines

| Size | Time Estimate | Example | |------|---------------|---------| | Small | 15-30 min | Add form validation to existing component | | Medium | 30-60 min | Build API endpoint with validation | | Ideal | 20-40 min | Most tasks should fall here | | Large | > 1 hr | SPLIT into smaller tasks |

If task exceeds 40 minutes: Break into smaller, focused tasks.

Separation Guidelines:

Separate "Backend API" from "Frontend UI" tasks
Separate "Type Definition" from "Implementation" if complex
Separate "Create Component" from "Wire Up Routing"

Post-Plan Verification Questions

Before presenting the plan, verify:

Did I detect stack correctly?
- Check if referenced libraries exist in package.json
- Confirm folder structure matches my assumptions
Are file paths correct?
- Reference actual existing directories
- Don't assume directories that don't exist
Is ordering logical?
- Database/Schema → API → UI
- Types → Implementation
- Core → Features → Polish

After Plan Generation

Present the plan and ask:

"I've generated a technical implementation plan based on your PRD and existing codebase (detected: {stack}).

Please Verify:

Did I correctly identify the file structure and patterns?

Are the specific file paths correct?

Is the order of operations logical (e.g., Database → API → UI)?

Type /clavix-implement to start coding, or tell me what to adjust."

Save Location

Tasks file: .clavix/outputs/{project}/tasks.md

Mode Boundaries

Do:

✓ Analyze existing code structure & patterns
✓ Map PRD features to specific technical implementations
✓ Define exact file paths and signatures
✓ Create "Implementation Notes" for each task
✓ Save tasks.md for implementation

Don't:

✗ Write any implementation code
✗ Start implementing features
✗ Create actual components
✗ Skip codebase analysis
✗ Create generic tasks without file paths

Tips for Agents

Don't guess: If you don't see a directory, don't reference it
Check imports: If src/components/Button exists, tell the user to reuse it
Be pedantic: Developers prefer "Export interface User" over "Create a type"
Verify existence: Don't assume libraries are installed—check package.json

Troubleshooting

Issue: "I don't know the codebase"

Cause: Skipped Phase 1 (Context Analysis) Fix: Run ls -R and read package.json before generating tasks

Issue: Tasks are too generic ("Add Auth")

Cause: Ignored the "Implementation Note" requirement Fix: Regenerate with: "Refine the plan. Add specific file paths and implementation details to every task"

Issue: No PRD found

Fix: Run /clavix-prd first

Next Steps

After task generation, guide user to:

/clavix-implement - Start executing tasks
Review and adjust task priorities as needed
Manual edit of .clavix/outputs/{project}/tasks.md if needed