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:

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.

1. •

   Scan Directory Structure:

   • •Run ls -R src (or relevant folders) to see the file layout
   • •Identify folder conventions (features/, components/, services/)
2. •

   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.
3. •

   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?
4. •

   Output Summary:

   code

   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

1. •

   Locate PRD:

   • •Check .clavix/outputs/<project-name>/ for full-prd.md, quick-prd.md
   • •If missing, check legacy .clavix/outputs/summarize/
2. •

   Read PRD: Ingest all requirements

3. •

   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

1. •

   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"
2. •

   Specific File Paths Required:

   • •Bad: "Create a user profile component"
   • •Good: "Create src/components/user/UserProfile.tsx. Export as default"
3. •

   Technical Constraints:

   • •Bad: "Add validation"
   • •Good: "Use zod schema in src/schemas/user.ts. Integrate with react-hook-form"
4. •

   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
5. •

   Draft Tasks: Create tasks using the Task Format Reference below

6. •

   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

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:

1. •

   Did I detect stack correctly?

   • •Check if referenced libraries exist in package.json
   • •Confirm folder structure matches my assumptions
2. •

   Are file paths correct?

   • •Reference actual existing directories
   • •Don't assume directories that don't exist
3. •

   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:

1. •Did I correctly identify the file structure and patterns?
2. •Are the specific file paths correct?
3. •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