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:

   Copy

   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