clear-planner

Clear Planner

Purpose

Creates implementation plans. Invoked FIRST for every user request.

This skill IS:

• The mandatory entry point for the PLAN phase of any significant work
• An 8-step workflow that produces approved implementation plans
• The bridge between user intent and structured execution

This skill IS NOT: Executing the plan (that's the builder's job)

8-Step Workflow

Step 1: Understand Intent        -> Create planning-manifest.json
    |
Step 2: Run Discovery
    |
Step 3: Detect Scenario (agenting / documentation)
    |
Step 4: Gather Context           <- Return here on "Adjust" or "Modify"
    |
Step 5: Load Scenario Template
    |
Step 6: Present Approach         -> GATE: "Proceed" / "Adjust"
    |
Step 7: Create Session Artifacts -> Creates plan-manifest.json + implementation-plan.md
    |
Step 8: Present Full Plan        -> GATE: "Approve" / "Modify" / "Cancel"
    |
HANDOFF to implementation

Self-tracking: See references/planning-workflow-schema.md for the planner's own state tracking.

Step 1: Understand Intent

Parse the user's request:

• What do they want to accomplish?
• What files/systems are involved?
• Is there a clear objective?

Create the session folder + planning-manifest.json in one step:

.claude/quality/sessions/{YYYYMMDD}_{HHMMSS}_{slug}/
  planning-manifest.json   <- Track planner's own workflow state

Do NOT call mkdir first. Use the Write tool directly on .claude/quality/sessions/{YYYYMMDD}_{HHMMSS}_{slug}/planning-manifest.json. Write auto-creates any missing parent directories, and the shipped allowlist already covers Write(.claude/quality/sessions/**) — so the folder pops into existence without a permission prompt, regardless of OS or whether the working-dir reference is relative or absolute. (Calling mkdir adds a Bash permission round-trip with no benefit; previous skill versions did, which caused intermittent prompts on Windows where path resolution sometimes expanded to absolutes outside the allowlist.)

If unclear: Ask clarifying questions before proceeding.

CRITICAL: Manifest Maintenance

After EACH step, update planning-manifest.json:

1. Mark current step status: "completed" with result
2. Set next step status: "in_progress"
3. Update currentStep integer
4. Populate result fields as work is done

{
  "currentStep": 2,
  "workflow": {
    "steps": [
      { "step": 1, "name": "Understand Intent", "status": "completed", "result": "..." },
      { "step": 2, "name": "Run Discovery", "status": "in_progress" }
    ]
  }
}

This is NON-NEGOTIABLE. See references/planning-workflow-schema.md for full schema.

Step 2: Run Discovery

Run all three discovery scripts:

# Find existing agents
bash .claude/agents/agent-discovery/find_agents.sh

# Find existing skills
bash .claude/skills/skill-discovery/find_skills.sh

# Find relevant lessons
python .claude/scripts/find_lessons.py --tags "#{scenarioType}"

Document findings for inclusion in manifest.

Step 3: Detect Scenario

Two scenarios based on what's affected:

| Scenario | Trigger | Description | | ----------------- | ------------------------------------------ | -------------------------------------------------- | | AGENTING | Affects /.claude folders | Agent/skill creation, modification, ecosystem work | | DOCUMENTATION | Affects /docs folder or context data points | Context creation, updates, refinement |

Mixed work: If both apply, identify primary scenario and note secondary.

Step 4: Gather Context (Scenario-Specific)

AGENTING Scenario

Recommended: Use ecosystem-manager skill for context gathering.

Before creating or modifying agents/skills:

1. Run discovery scripts (Step 2 results)
2. Check for overlaps with existing agents/skills
3. Review relevant lessons
4. Identify gaps and design recommendations

If the ecosystem-manager skill is available, invoke it for overlap detection and ecosystem analysis.

DOCUMENTATION Scenario

Self-discovery: review discovery results, identify related docs, check cross-references, verify alignment.

Step 5: Load Scenario Template

Load the appropriate template from references/scenario-phases.md (defines phases, tasks, capabilities, and learnings capture). Templates: agenting, documentation.

Step 6: Present Approach for Alignment

Present to user before creating documents: (1) restatement of intent, (2) key discovery findings (agents, overlaps, lessons), (3) proposed approach (scenario, phases, risks).

Then use the AskUserQuestion tool:

• Question: "Does this approach look right?"
• Options: Proceed (create plan artifacts) / Adjust (revise — tell me what to change)

Gate 1: Approach Alignment

| Response | Behavior | | --- | --- | | "Proceed" | Continue to Step 7 | | "Adjust" | Return to Step 4 with user feedback |

WAIT for user response before Step 7.

Step 7: Create Session & Artifacts

Only after user "Proceed" from Step 6.

Session folder already exists from Step 1. Add the plan artifacts:

.claude/quality/sessions/{YYYYMMDD}_{HHMMSS}_{slug}/
  planning-manifest.json    <- Already exists (from Step 1)
  plan-manifest.json        <- Create now
  implementation-plan.md    <- Create now

Create two files:

plan-manifest.json

{
  "sessionId": "20260127_120000_feature-name",
  "triggeredBy": "clear-planner",
  "scenarioType": "documentation",
  "taskDescription": "Brief description of what we're doing",
  "createdAt": "2026-01-27T12:00:00Z",
  "planStatus": "awaiting_approval",
  "discoveryResults": {
    "agentsFound": [],
    "skillsFound": [],
    "relevantLessons": []
  },
  "plan": {
    "totalPhases": 5,
    "phases": ["Phase 1: ...", "Phase 2: ..."]
  },
  "tasks": [
    {
      "id": "P1_001",
      "phase": 1,
      "content": "Task description",
      "activeForm": "Doing the task",
      "status": "pending"
    }
  ]
}

implementation-plan.md

Structure: Header (session ID, scenario, status) -> Discovery Results -> Problem Statement -> Proposed Solution -> Tasks by Phase (table per phase with ID/Task/Status) -> Artifacts (paths to session files) -> Next Actions (Approve/Modify/Cancel).

For full template, see references/plan-manifest-schema.md

Step 8: Present Full Plan for Approval

Present to user with:

1. Summary - What will be done
2. Task list - Organized by phase
3. URLs to artifacts:
4. {session}/plan-manifest.json
5. {session}/implementation-plan.md

Then use the AskUserQuestion tool:

• Question: "Ready to implement this plan?"
• Options: Approve (start implementation) / Modify (revise — tell me what to change) / Cancel (stop here)

Gate 2: Plan Approval

| Response | Behavior | | ------------- | ------------------------------------------------------------------------- | | "Approve" | 1. Update manifests (status="approved") 2. Handoff to implementation | | "Modify" | Return to Step 4 (Gather Context) with existing plan as additional context | | "Cancel" | Stop planning, archive session |

CRITICAL: STOP AND WAIT for user approval.

Do not proceed with execution until user explicitly says "Approve".

On "Approve":

1. Update planning-manifest.json: Set Step 8 status="completed", gate.response="Approve"
2. Update plan-manifest.json: Set planStatus="approved", add userApproval object
3. Handoff to implementation

Mandatory Final Phase (All Scenarios)

Every AGENTING plan MUST include an integration audit + ecosystem state update + learnings capture phase. Every DOCUMENTATION plan MUST inc