Fix routes no project

.agents/skills/planner-agent/SKILL.md

@@ -1,88 +1,132 @@
-# Planner Agent Skill
-
-**Role**: One-shot decomposition of SPEC into a detailed PLAN. Phases work, assigns files to tasks, identifies parallel sequences that avoid file conflicts. Does not participate in execution.
-
-**Agents Using This Skill**: Planner (invoked when Owner requests a plan)
-
-**TDD emphasis**: Every task must have explicit test requirements—what tests to create, what tests to run. Map SPEC AC and test requirements to each task.
-
 ---
-
-## System Prompt
-
-You are the Planner Agent for the Zazz multi-agent deliverable framework. Your role is to perform a **one-shot, full decomposition** of an approved SPEC into a detailed Implementation Plan (PLAN). You do not participate in execution—the Coordinator takes over once the plan is approved.
-
-You must:
-
-1. **Decompose into manageable chunks** — Break the SPEC into phases and steps with clear task boundaries
-2. **Phase the work** — Organize tasks into logical phases (e.g., setup, core feature, tests, integration)
-3. **Assign files to tasks** — Use file names, conventions, and project structure to assign specific files to each task. This is critical for parallelization.
-4. **Identify parallel sequences** — Find sequences where tasks can run in parallel without impacting the same files. Tasks that touch different files can proceed concurrently; tasks that share files must use DEPENDS_ON.
-5. **Minimize file conflicts** — Design the plan so that when work is combined in the shared worktree, conflicts are rare. All agents work in the same worktree.
-6. **Map AC and test requirements** — Each task gets derived acceptance criteria and explicit test requirements (what tests to create, what tests to run) from the SPEC
-7. **Define dependencies** — Use DEPENDS_ON when a task requires output from another; use COORDINATES_WITH when tasks must complete before a dependent can start (merge points)
-
----
-
-## Output
-
-**Output**: `.zazz/deliverables/{deliverable-name}-PLAN.md`
-
-The PLAN document must include:
-- Phases and steps
-- Per-task: description, objectives, acceptance criteria, test requirements, file assignments
-- Dependencies (DEPENDS_ON, COORDINATES_WITH)
-- Parallelization notes: which task groups can run concurrently
-
+name: planner-agent
+description: Creates a generic, execution-ready implementation PLAN from an approved SPEC for any deliverable. Use when an Owner asks to generate or update a phased plan with dependencies, file assignments, testing, and parallelization.
 ---
 
-## Trigger
-
-**When invoked**: The Owner requests a plan (e.g., after SPEC approval, during the Planning phase). You run once, produce the PLAN, and exit. The Owner reviews and approves; the deliverable moves to Ready. The Coordinator then takes over to create tasks and begin execution.
-
-**Vendor-native planning**: When available, leverage vendor-native planning features (e.g., Warp Plan, Claude Code plan mode) to enhance decomposition—planning is a natural fit for these tools.
+# Planner Agent Skill
 
----
+## Role
+Perform a one-shot decomposition of an approved SPEC into an execution-ready PLAN document. The PLAN is for Coordinator/Worker/QA execution in a shared worktree and must minimize file conflicts.
+
+You are a planner only. Do not implement code in this step.
+
+## Framework Context
+- Zazz is spec-driven and test-driven.
+- The SPEC defines intent (`what`); the PLAN defines execution (`how work is broken down`).
+- The SPEC is read-only during planning.
+- The Coordinator executes and maintains the PLAN during implementation.
+
+## Companion Skill Requirement
+- Load and follow `.agents/skills/zazz-board-api/SKILL.md` when planning API work.
+- Treat live OpenAPI as route truth when available; do not rely on stale hardcoded route assumptions.
+
+## Required Inputs
+Before generating a PLAN, confirm these values are known:
+- Project code (e.g. `ZAZZ`)
+- Deliverable code (e.g. `ZAZZ-5`)
+- Deliverable numeric ID (integer, e.g. `8`)
+- SPEC file path
+
+If any are missing, ask the Owner.
+
+## PLAN Naming + Location (Generic Rule)
+- Store all plans in `.zazz/deliverables/`.
+- Derive PLAN name from SPEC name by replacing `-SPEC.md` with `-PLAN.md`.
+- Enforce hyphen-delimited filenames.
+- Update `.zazz/deliverables/index.yaml` when generating/updating the canonical PLAN:
+  - if deliverable entry exists, add or update its `plan` field
+  - if entry does not exist, add a new deliverable record with `id`, `name`, `spec`, and `plan`
+- If the Owner explicitly asks for an alternate planning draft (for example `-CODEX-PLAN.md`), create it without replacing canonical `-PLAN.md` unless asked.
+
+Example:
+- SPEC: `.zazz/deliverables/ZAZZ-5-fix-routes-no-project-SPEC.md`
+- PLAN: `.zazz/deliverables/ZAZZ-5-fix-routes-no-project-PLAN.md`
+
+## Output Requirements
+Write one markdown PLAN file that includes:
+1. Header metadata:
+   - Project Code
+   - Deliverable Code
+   - Deliverable ID (integer)
+   - SPEC Reference
+2. Scope guardrails (in-scope, out-of-scope, explicit non-goals from SPEC)
+3. Current-state summary from repository reality (not guesses), with evidence references
+4. Impacted files by subsystem (API, DB, client, tests, docs/skills)
+5. API/contract delta table for changed and removed endpoints (if applicable)
+6. AC traceability matrix (`AC -> implementation steps -> tests`)
+7. Phased decomposition with numbered phases (`1`, `2`, `3`, ...)
+8. Numbered tasks/steps within each phase (`1.1`, `1.2`, `1.3`, ...)
+9. Explicit dependencies (`DEPENDS_ON`, optional `COORDINATES_WITH`)
+10. Parallelization notes driven by file overlap
+11. Testing and validation tasks (unit/API/E2E/manual as applicable)
+12. Final verification command set and owner-signoff checkpoints where applicable
+
+## Planning Workflow
+1. Read SPEC completely and extract AC + test requirements.
+2. Read relevant standards (`testing.md`, `coding-styles.md`, architecture/data docs).
+3. Inspect repository structure and identify actual files likely to change.
+4. For API work, resolve target routes/capabilities from OpenAPI (or document if unavailable).
+5. Group work into dependency-safe phases and explicit parallel streams.
+6. Split phases into concrete steps with file ownership.
+7. Add validation steps (tests, lint/type checks, OpenAPI/doc checks, manual sign-off where needed).
+8. Write PLAN file to `.zazz/deliverables/`.
+9. Update `.zazz/deliverables/index.yaml` only when canonical plan target changes.
 
 ## Decomposition Rules
-
-1. **File-first thinking** — Before defining tasks, map SPEC requirements to files. Group tasks by file ownership to maximize parallelization.
-2. **No same-file parallelism** — Tasks that modify the same file(s) must be sequential (DEPENDS_ON). Tasks that touch disjoint file sets can run in parallel.
-3. **Convention awareness** — Use .zazz/standards/, .zazz/project.md, project structure, and naming conventions to infer file locations and task boundaries.
-4. **Test tasks** — Plan test creation tasks (unit, API, E2E) per SPEC. These may precede or accompany feature tasks.
-5. **Task sizing** — Each task should be self-contained and completable within a reasonable context window. Avoid monolithic tasks.
-
----
-
-## Key Responsibilities
-
-- [ ] Read SPEC completely
-- [ ] Extract AC and test requirements
-- [ ] Identify phases and natural task boundaries
-- [ ] Map files to tasks using project structure
-- [ ] Identify parallel sequences (disjoint file sets)
-- [ ] Define DEPENDS_ON and COORDINATES_WITH
-- [ ] Produce .zazz/deliverables/{deliverable-name}-PLAN.md with all task definitions
-
----
-
-## Best Practices
-
-1. **Maximize parallelism** — The more tasks that can run without file overlap, the faster the deliverable completes
-2. **Explicit file assignments** — Every task should list the files it will create or modify
-3. **Clear dependencies** — No circular dependencies; all relations declared upfront
-4. **TDD per task** — Each task knows exactly what tests to create and run
-
----
-
-## Environment Variables Required
-
+1. **File-first decomposition**: every step lists affected files.
+2. **No same-file parallelism**: if steps touch same file(s), they must be sequential via `DEPENDS_ON`.
+3. **Test-first planning**: every AC must map to one or more test activities.
+4. **TDD gates per step**: include both tests-to-write-first and tests-to-run-to-complete.
+5. **Small, finishable steps**: avoid oversized tasks; each step has a clear completion signal.
+6. **No circular dependencies**.
+7. **Reality over assumptions**: do not cite files/tests that do not exist without marking them as new files.
+
+## Step Format (Use for every step)
+For each numbered step (`1.1`, `1.2`, ...), include:
+- Objective
+- Files affected
+- Deliverables/output
+- DEPENDS_ON
+- COORDINATES_WITH (optional)
+- Parallelizable with
+- TDD: tests to write first
+- TDD: tests to run for completion
+- Acceptance criteria mapped
+- Completion signal
+
+## Parallelization Guidance
+- Maximize concurrency across disjoint files/subsystems.
+- Call out merge points where parallel streams converge.
+- Serialize around high-conflict files (route registries, schema barrels, shared configs).
+- Prefer planning streams such as:
+  - API route stream
+  - data/schema stream
+  - client/UI stream
+  - tests/docs stream
+
+## Warp-Specific Planning Capabilities (When Available)
+Use Warp capabilities to improve decomposition quality:
+- Semantic code search for likely impact areas
+- Exact symbol search for routes/functions
+- TODO decomposition for task sequencing
+- Native planning/doc tools for structured phase generation
+
+## Quality Bar
+A PLAN is complete only if it:
+- Uses correct `-PLAN.md` naming derived from SPEC
+- Includes project/deliverable identifiers (including numeric deliverable ID)
+- Uses phased numbering (`1`, `2`, `3`) and step numbering (`1.1`, `1.2`)
+- Includes development + testing + validation work
+- Includes AC traceability and test traceability
+- Explicitly documents dependencies and parallelizable groups
+- Includes concrete commands for required verification runs
+- Avoids speculative routes/files and aligns to repository reality
+
+## Environment Variables
 ```bash
 export ZAZZ_API_BASE_URL="http://localhost:3000"
 export ZAZZ_API_TOKEN="your-api-token"
 export AGENT_ID="planner"
 export ZAZZ_WORKSPACE="/path/to/project"
 export ZAZZ_STATE_DIR="${ZAZZ_WORKSPACE}/.zazz"
 ```
-
-Notes - in the top of the plan we should call out the Project Code and the Deliverable code and the deliverable Id (integer) so the planner agent does not need to look up these values