care-book-block-ultimate/specs/001-wordpress-plugin-para/plan.md

Implementation Plan: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare

Branch: 001-wordpress-plugin-para | Date: 2025-09-10 | Spec: spec.md Input: Feature specification from /specs/001-wordpress-plugin-para/spec.md

Execution Flow (/plan command scope)

1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
4. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
6. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
8. STOP - Ready for /tasks command

IMPORTANT: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:

• Phase 2: /tasks command creates tasks.md
• Phase 3-4: Implementation execution (manual or via tools)

Summary

WordPress plugin que permite controlo granular sobre a visibilidade de médicos e serviços no sistema de agendamento público do KiviCare, mantendo acesso total no painel administrativo. Utiliza abordagem CSS-first para evitar instabilidade crítica identificada em versões anteriores, com integração segura via hooks WordPress e KiviCare.

Technical Context

Language/Version: PHP 7.4+ (WordPress compatibility requirement)
Primary Dependencies: WordPress 5.0+, KiviCare Plugin 3.0.0+, MySQL 5.7+
Storage: MySQL via WordPress $wpdb API (custom table wp_care_booking_restrictions)
Testing: PHPUnit with WordPress testing framework
Target Platform: WordPress hosting environment (Linux servers with PHP/MySQL stack) Project Type: single (WordPress plugin with admin interface and frontend filtering)
Performance Goals: <5% overhead on appointment page loading, <2 minutes admin configuration time
Constraints: CSS-first approach to avoid shortcode conflicts, zero website downtime during operation
Scale/Scope: Support clinics with thousands of doctors/services, 100% compatibility with KiviCare updates

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Simplicity:

• Projects: 1 (WordPress plugin with admin panel + frontend filtering)
• Using framework directly? YES (WordPress hooks/filters, no wrapper classes)
• Single data model? YES (wp_care_booking_restrictions table, no DTOs)
• Avoiding patterns? YES (Direct WordPress $wpdb access, no Repository/UoW)

Architecture:

• EVERY feature as library? N/A (WordPress plugin architecture - classes with hooks)
• Libraries listed: N/A (WordPress plugin with core classes)
• CLI per library: N/A (WordPress admin interface, no CLI needed)
• Library docs: WordPress plugin documentation format planned

Testing (NON-NEGOTIABLE):

• RED-GREEN-Refactor cycle enforced? YES (PHPUnit tests before implementation)
• Git commits show tests before implementation? YES (will be enforced)
• Order: Contract→Integration→E2E→Unit strictly followed? YES
• Real dependencies used? YES (actual WordPress/KiviCare installation)
• Integration tests for: KiviCare hooks, WordPress database, admin interface
• FORBIDDEN: Implementation before test, skipping RED phase - ENFORCED

Observability:

• Structured logging included? YES (WordPress debug.log integration)
• Frontend logs → backend? YES (admin actions logged to WordPress)
• Error context sufficient? YES (detailed error messages and recovery)

Versioning:

• Version number assigned? 1.0.0 (WordPress plugin versioning)
• BUILD increments on every change? YES (plugin version updates)
• Breaking changes handled? YES (WordPress activation/deactivation hooks)

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)

Source Code (repository root)

# Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

# Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

# Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]

ios/ or android/
└── [platform-specific structure]

Structure Decision: Option 1 (Single WordPress Plugin Project) - Standard WordPress plugin structure with admin interface and frontend integration

Phase 0: Outline & Research

1. Extract unknowns from Technical Context above:

   • For each NEEDS CLARIFICATION → research task
   • For each dependency → best practices task
   • For each integration → patterns task

2. Generate and dispatch research agents:

   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   

3. Consolidate findings in research.md using format:

   • Decision: [what was chosen]
   • Rationale: [why chosen]
   • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from feature spec → data-model.md:

   • Entity name, fields, relationships
   • Validation rules from requirements
   • State transitions if applicable

2. Generate API contracts from functional requirements:

   • For each user action → endpoint
   • Use standard REST/GraphQL patterns
   • Output OpenAPI/GraphQL schema to /contracts/

3. Generate contract tests from contracts:

   • One test file per endpoint
   • Assert request/response schemas
   • Tests must fail (no implementation yet)

4. Extract test scenarios from user stories:

   • Each story → integration test scenario
   • Quickstart test = story validation steps

5. Update agent file incrementally (O(1) operation):

   • Run /scripts/update-agent-context.sh [claude|gemini|copilot] for your AI assistant
   • If exists: Add only NEW tech from current plan
   • Preserve manual additions between markers
   • Update recent changes (keep last 3)
   • Keep under 150 lines for token efficiency
   • Output to repository root

Output: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file

Phase 2: Task Planning Approach

This section describes what the /tasks command will do - DO NOT execute during /plan

Task Generation Strategy:

• Load /templates/tasks-template.md as WordPress plugin task base
• Generate tasks from Phase 1 design docs (contracts, data-model.md, quickstart.md)
• Database schema → table creation task with activation hook [P]
• Admin API contracts → AJAX endpoint test tasks [P]
• KiviCare hook contracts → integration test tasks
• Admin interface → UI component tasks
• Frontend filtering → CSS injection and hook implementation tasks
• Each quickstart scenario → end-to-end validation task

WordPress-Specific Ordering Strategy:

1. Foundation: Plugin structure, autoloader, activation hooks
2. Database: Table creation, model classes [P]
3. Contract Tests: AJAX endpoints, KiviCare hooks [P]
4. Core Logic: Restriction management, caching, validation
5. Admin Interface: UI components, AJAX handlers
6. Frontend Integration: CSS injection, KiviCare hooks
7. Integration Tests: End-to-end scenarios from quickstart.md
8. Performance & Security: Optimization, security validation

Estimated Output: 20-25 numbered WordPress plugin tasks in tasks.md

IMPORTANT: This phase is executed by the /tasks command, NOT by /plan

Phase 3+: Future Implementation

These phases are beyond the scope of the /plan command

Phase 3: Task execution (/tasks command creates tasks.md)
Phase 4: Implementation (execute tasks.md following constitutional principles)
Phase 5: Validation (run tests, execute quickstart.md, performance validation)

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

Progress Tracking

This checklist is updated during execution flow

Phase Status:

• Phase 0: Research complete (/plan command) - research.md created
• Phase 1: Design complete (/plan command) - data-model.md, contracts/, quickstart.md, CLAUDE.md created
• Phase 2: Task planning complete (/plan command - approach described)
• Phase 3: Tasks generated (/tasks command)
• Phase 4: Implementation complete
• Phase 5: Validation passed

Gate Status:

• Initial Constitution Check: PASS
• Post-Design Constitution Check: PASS
• All NEEDS CLARIFICATION resolved
• Complexity deviations documented (none required)

---

Based on Constitution v2.1.1 - See /memory/constitution.md