22 — Project Management & Zoho Integration

Version: 1.0
Date: 2026-03-21
Tech Lead: Rui Rosa
Scope: Task lifecycle, status workflow, Claude ↔ Zoho ↔ Azure DevOps integration, best practices

---

1. Context

This project uses Zoho Projects as the single source of truth for project management. Development work is performed 99% by Claude Code (AI agent), which creates branches, implements features, opens PRs, and deploys — all autonomously.

This creates a unique requirement: the project management system must be optimized for AI-driven development where human intervention is limited to prioritization, review, and validation.

1.1 Platform Integration Map

1.2 Key Principles

Principle	Description
Single source of truth	Every development action is reflected in Zoho — no work exists only in Git
AI-first statuses	Statuses optimized for Claude’s workflow, not a traditional human team
Human gates	Humans only act at review, validation, and prioritization gates
Bidirectional traceability	Every PR links to a Zoho task; every Zoho task links to its PR
Comment-driven progress	Detailed progress lives in comments; statuses show pipeline position

---

2. Zoho Project Structure

2.1 Project Identifiers

Item	Value
Portal	wygroup
Project	Savoy Signature Hotels (P894)
Task key format	P894-T{XXX}
Task URL pattern	https://projects.zoho.com/portal/wygroup#zp/task-detail/{taskSystemId}

2.2 Tasklists (Sprint Organization)

Tasklist	ID	Purpose
DEV Sprint 0 — Setup & Infra	1990636000017517013	Monorepo, Azure, Cloudflare, pipelines, CMS setup
DEV Sprint 1 — Foundations & Heroes	1990636000017519011	Header, Footer, Main Menu, Heroes, Breadcrumbs, Error Page
DEV Sprint 2 — Core Modules	1990636000017518059	Item Cards, Quotes, Highlight, Banner, Slider, Text Image, RTE, Full Image, Icon List, Decorative Type
DEV Sprint 3 — Interactive Components	1990636000017520071	Slider Categories, Slider, FAQs, Image Gallery, Logo Carousel, Cross-Content Cards
DEV Sprint 4 — Advanced Features	1990636000017520075	Booking Bar, Form, Modal, Social Media, Social Share, Newsletter
DEV Sprint QA — Tests & Validation	1990636000017516055	Cross-module testing, E2E, visual regression, performance
BACKLOG	1990636000010437441	Future work, not yet scoped or estimated

2.3 Task Naming Conventions

Work type	Naming pattern	Example
Module development	M{XX} {Name} — Development	M27 Text Image — Development
Infrastructure	INFRA — {Description}	INFRA — Setup Storybook 10 Environment
Bug fix	FIX — {Module/Area}: {Description}	FIX — M11 Banner: mobile overflow
Feature	FEAT — {Description}	FEAT — Auth Gate for DEV environments
Security	SEC — {Description}	SEC — Security Pipeline & Pentesting
Chore	CHORE — {Description}	CHORE — Upgrade pnpm to 9.x

---

3. Task Status Workflow

3.1 Previous Statuses (Legacy)

#	Status	Problem
1	1. Backlog	OK — kept
2	2. To Do	OK — kept
5	5. Work in progress	Too broad — covers everything from “just started” to “almost done”
6	6. Code Review	Conflates PR review, design review, and QA into one status
7	7. Done	No separation between QA acceptance and final sign-off
99	99. Dropped	OK — kept

3.2 Status Workflow (13 Statuses)

The workflow uses the Ready/Doing split pattern from Kanban for each human gate. This makes queue time (waiting) vs active time (working) measurable per team.

3.3 Status Definitions

#	Status	Who Acts	Type	Entry Trigger	Exit Trigger
1	1. Backlog	Nobody	—	Task created	Prioritized into sprint
2	2. To Do	Nobody	Queue	Sprint planning	Claude picks it up
3	3. In Development	Claude	Active	Branch created, work begins	PR created OR needs input
4	4. Awaiting Input	Human	Active	Claude blocked on decision/Figma/info	Human responds → back to 3
5	5. Dev — Ready for Review	Nobody	Queue → Rui	PR created	Tech Lead picks up review
6	6. Dev — In Review	Tech Lead	Active	Tech Lead starts review	Code approved OR changes requested
7	7. Design — Ready for Review	Nobody	Queue → Design	Code review approved	Design team picks up
8	8. Design — In Review	Design Team	Active	Design team starts review	Design approved OR issues found
9	9. QA — Ready for Acceptance	Nobody	Queue → QA/PM	Design approved, deployed to DEV	QA/PM picks up testing
10	10. QA — In Acceptance	QA/PM	Active	QA/PM starts testing on DEV	QA passes OR issues found
11	11. QA — Accepted	Nobody	Queue → PO/TL	QA team validates	PO or Tech Lead closes
12	12. Done	—	—	PO/Tech Lead final sign-off	—
99	99. Dropped	—	—	Decision to cancel	—

3.4 Queue vs Active — Team Responsibility

Key insight: Queue columns (light colors) measure wait time. Active columns (dark colors) measure work time. If queue columns accumulate tasks, that team is the bottleneck.

3.5 AI Development Sub-Phases (Tags + Progress)

While Claude is in 3. In Development, internal progress is tracked via tags and percent_complete — not additional statuses. This keeps the board clean while providing visibility into Claude’s current phase.

Tags

Tag	Phase	Description
ai:storybook	Phase A	Types, stories, test scaffolding
ai:react	Phase B	Component, mapper, SCSS, unit tests
ai:visual-testing	Phase B7	Pixel Perfect validation against Figma
ai:umbraco	Phase C	Element Type migration, CMS integration
ai:pre-pr	Pre-PR	Self-review — lint, typecheck, all tests green

Claude updates the tag when transitioning between phases. If a session ends mid-phase, the next session reads the tag to know where to resume.

Note: If the Zoho MCP server does not support tag management via API, Claude tracks sub-phases via percent_complete + structured comments. The tags serve as a visual reference in the Zoho backoffice (managed manually or via future API support).

Progress Mapping

percent_complete	Phase	What it means
0%	Not started	Task picked up, branch not yet created
10%	Phase A start	Scaffold + types created
20%	Phase A done	Stories + test file complete
30%	Phase B start	Component implementation started
50%	Phase B done	Component + mapper + tests passing
60%	Phase B7 start	Visual testing started
70%	Phase B7 done	Both desktop (≤5%) and mobile (≤10%) pass
80%	Phase C start	Umbraco migration started
90%	Phase C done	Element Type created, Block List registered, content tested
95%	Pre-PR	Self-review — lint, typecheck, tests, visual regression
100%	PR created	Status transitions to 5. Dev — Ready for Review

Claude updates percent_complete via zoho_update_task at each phase transition, accompanied by a structured comment.

Phase Transition Comment Template

<b>Phase Update — {Phase Name}</b>
<br>
<b>Task:</b> {taskName}
<b>Phase:</b> {previous} → {current}
<b>Progress:</b> {percent}%
<b>Date:</b> {date}
<br>
<b>Completed:</b>
- {what was done in previous phase}
<br>
<b>Next:</b>
- {what will be done in current phase}

3.6 Status Name Rules (Critical)

Status names passed to zoho_update_task MUST be exact strings — the API silently ignores invalid names.

#	Valid (exact string)	Common mistakes (WILL FAIL SILENTLY)
1	1. Backlog	Backlog, backlog
2	2. To Do	To Do, TODO, To do
3	3. In Development	In Development, Development, Dev
4	4. Awaiting Input	Awaiting Input, Blocked, Waiting
5	5. Dev — Ready for Review	Dev Ready, Ready for Review, Dev - Ready
6	6. Dev — In Review	Dev In Review, In Review, Code Review
7	7. Design — Ready for Review	Design Ready, Ready for Design
8	8. Design — In Review	Design Review, In Design Review
9	9. QA — Ready for Acceptance	QA Ready, Ready for QA
10	10. QA — In Acceptance	QA In Acceptance, In QA
11	11. QA — Accepted	QA Accepted, Accepted
12	12. Done	Done, Completed, Complete
99	99. Dropped	Dropped, Cancelled

Rule: Always copy status names from this table. Never type from memory. The dash is an em-dash (—), not a hyphen (-).

---

4. Task Lifecycle (End-to-End)

4.1 Complete Lifecycle Flow

4.2 Status Transitions — Decision Tree

4.3 Who Transitions Each Status

Not all transitions are done by Claude. This table clarifies ownership:

From	To	Who transitions	How
2. To Do	3. In Development	Claude	Automatic when work starts
3. In Development	4. Awaiting Input	Claude	When blocked on human input
4. Awaiting Input	3. In Development	Claude	When input received
3. In Development	5. Dev — Ready for Review	Claude	When PR is created
5. Dev — Ready for Review	6. Dev — In Review	Tech Lead	When starts reviewing
6. Dev — In Review	7. Design — Ready for Review	Tech Lead	When code approved
6. Dev — In Review	3. In Development	Tech Lead	When changes requested
7. Design — Ready for Review	8. Design — In Review	Design Team	When starts reviewing
8. Design — In Review	9. QA — Ready for Acceptance	Design Team	When design approved
8. Design — In Review	3. In Development	Design Team	When issues found
9. QA — Ready for Acceptance	10. QA — In Acceptance	QA/PM	When starts testing
10. QA — In Acceptance	11. QA — Accepted	QA/PM	When QA passes
10. QA — In Acceptance	3. In Development	QA/PM	When bugs found
11. QA — Accepted	12. Done	PO / Tech Lead	Final sign-off

Rule: Claude only transitions statuses 2→3, 3→4, 4→3, and 3→5. All other transitions are human-driven. Claude may post comments at any stage but must not change statuses owned by other teams.

---

5. Zoho ↔ Git ↔ Azure DevOps Integration

5.1 Traceability Chain

Every piece of work must have a complete traceability chain linking all platforms:

5.2 PR ↔ Zoho Linking Rules

Element	Where	Format
Zoho task key	PR title	feat(m27): Text Image module [P894-T431]
Zoho task URL	PR description	[P894-T431 — M27 Text Image](https://projects.zoho.com/...)
PR URL	Zoho comment	<a href="{prUrl}">#{prNumber} — {title}&lt;/a&gt;
Storybook URL	Zoho comment	<a href="https://savoy-dev-storybook.wycreative.com/...">View in Storybook&lt;/a&gt;
DEV site URL	Zoho comment	<a href="https://savoy-dev-signature.wycreative.com">DEV Site&lt;/a&gt;

5.3 Branch ↔ Task Mapping

Branch pattern	Zoho task type	Example
feat/m{XX}-{name}	Module task	feat/m27-text-image → M27 Text Image — Development
fix/{description}	Bug fix task	fix/hero-slider-mobile → FIX — M05: mobile overflow
chore/{description}	Infra/chore task	chore/upgrade-storybook → CHORE — Upgrade Storybook 10
docs/{description}	Docs task	docs/prd-zoho → DOCS — Zoho integration PRD

---

6. Claude’s Zoho Responsibilities

6.1 What Claude Owns

Claude only controls a subset of status transitions. This scope is intentionally limited — human gates belong to humans.

6.2 What Claude MUST NOT Do

Rule	Reason
Never transition statuses 6→7, 7→8, 8→9, 9→10, 10→11, 11→12	These belong to human teams (Dev, Design, QA, PO)
Never move to 12. Done	Only PO/Tech Lead closes tasks
Never skip status transitions	Stakeholders rely on the board for visibility
Never start work without a linked Zoho task	Breaks traceability
Never create a PR without Zoho task key in title	Required for bidirectional linking
Never silently skip a failed status update	Must retry once, then notify user
Never skip the Design Review Handoff comment	Design team depends on it for context

6.3 Task ID Persistence

The task_id obtained during initial lookup MUST be retained throughout the session. Context compression in long sessions can cause loss.

Mitigation strategy:

1. After lookup, announce to user: "Zoho task: P894-T{XXX} (ID: {task_id}) — {taskName}"
2. Before every Zoho API call, verify task_id is still in context
3. If lost, re-fetch via zoho_search_tasks before proceeding
4. Never skip a Zoho update because the ID was lost

---

7. Comment Templates

7.1 Comment Timing & Purpose

7.2 Comment Templates Reference

All comment templates use HTML format. Zoho renders <br> with extra vertical spacing — use <br> only between distinct sections, not at the end of every line.

Development Started

<b>Development Started</b>
<br>
<b>Task:</b> {taskName}
<b>Branch:</b> {branchName}
<b>Worktree:</b> {worktreePath}
<b>Date:</b> {date}
<br>
<b>Scope:</b>
- {deliverable 1}
- {deliverable 2}
<br>
<i>Status updated to "3. In Development".</i>

Awaiting Input

<b>Awaiting Input</b>
<br>
<b>Task:</b> {taskName}
<b>Branch:</b> {branchName}
<b>Current phase:</b> {Phase A/B/B7/C}
<b>Date:</b> {date}
<br>
<b>What I need:</b>
{detailed description of what decision/information/asset is needed}
<br>
<b>Options (if applicable):</b>
1. {option A} — {pros/cons}
2. {option B} — {pros/cons}
<br>
<i>Status updated to "4. Awaiting Input". Development paused until response.</i>

Input Received — Resuming

<b>Development Resumed</b>
<br>
<b>Task:</b> {taskName}
<b>Blocked from:</b> {startDate} to {endDate}
<b>Resolution:</b> {what was decided/provided}
<br>
<i>Status updated to "3. In Development".</i>

PR Created (Standard)

<b>PR Created</b>
<br>
<b>PR:</b> <a href="{prUrl}">#{prNumber} — {prTitle}</a>
<b>Branch:</b> {branchName} → develop
<b>Author:</b> Claude Code
<b>Status:</b> Pending Dev Review
<br>
<b>Changes:</b>
- {change 1}
- {change 2}
<br>
<b>Pre-PR Checks:</b>
- [x] TypeScript clean (pnpm typecheck)
- [x] Linter clean (pnpm lint)
- [x] Unit tests pass (pnpm --filter modules test)
- [x] Visual tests pass (pnpm --filter storybook visual:test)
<br>
<i>Status updated to "5. Dev — Ready for Review".</i>

PR Created (Module — extended)

<b>PR Created — Module M{XX}</b>
<br>
<b>PR:</b> <a href="{prUrl}">#{prNumber} — {prTitle}</a>
<b>Branch:</b> {branchName} → develop
<b>Author:</b> Claude Code
<b>Status:</b> Pending Dev Review
<br>
<b>Changes:</b>
- {change 1}
- {change 2}
<br>
<b>Pre-PR Checks:</b>
- [x] TypeScript clean
- [x] Linter clean
- [x] Unit tests pass
- [x] Visual tests: desktop {X}% / mobile {Y}%
<br>
<b>Development Phases Completed:</b>
- [x] Phase A — Storybook (types, stories, test file)
- [x] Phase B — React (component, mapper, SCSS)
- [x] Phase B7 — Pixel Perfect (desktop ≤5%, mobile ≤10%)
- [x] Phase C — Umbraco (migration, Block List, content tested)
<br>
<i>Status updated to "5. Dev — Ready for Review".</i>

Design Review Handoff (CRITICAL)

This is the most important comment in the workflow. The Design team may not have context on the task — this comment must be self-contained with everything they need to validate the work.

<b>Design Review Handoff — Module M{XX} {Name}</b>
<br>
<b>Task:</b> <a href="{zohoTaskUrl}">P894-T{XXX} — {taskName}</a>
<b>PR:</b> <a href="{prUrl}">#{prNumber}</a> (code approved by Tech Lead)
<b>Date:</b> {date}
<br>
<b>Figma Reference</b>
<br>
<b>Desktop:</b> <a href="{figmaDesktopUrl}">Figma Desktop ({figmaPageName})</a>
<b>Mobile:</b> <a href="{figmaMobileUrl}">Figma Mobile ({figmaPageName})</a>
<br>
<b>Where to Review</b>
<br>
<b>Storybook (isolated component):</b>
<a href="https://savoy-dev-storybook.wycreative.com/?path=/docs/modules-m{xx}---{kebab-name}--docs">Module Documentation</a>
<a href="https://savoy-dev-storybook.wycreative.com/?path=/story/modules-m{xx}---{kebab-name}--figma-fidelity">FigmaFidelity Story</a>
<br>
<b>DEV Site (in context):</b>
<a href="https://savoy-dev-signature.wycreative.com/{testPagePath}">Savoy Signature</a>
<a href="https://savoy-dev-{altSiteKey}.wycreative.com/{testPagePath}">{Alt Hotel Name}</a>
<br>
<b>Umbraco CMS:</b>
<a href="https://savoy-dev-cms.wycreative.com/umbraco">Open Backoffice</a> → {contentPath}
<br>
<b>Acceptance Criteria</b>
<br>
<b>Visual Fidelity:</b>
- [ ] Desktop layout matches Figma (spacing, alignment, typography)
- [ ] Mobile layout matches Figma (spacing, alignment, typography)
- [ ] Fluid responsive between 375px and 1440px (no jumps or clipping)
- [ ] Colors match design tokens for Savoy Palace theme
- [ ] Typography (font, size, weight, line-height) matches Figma
- [ ] Images display at correct aspect ratio and crop
<br>
<b>Interaction & Behaviour:</b>
- [ ] {interaction criterion 1 — e.g., "Hover states on CTA buttons"}
- [ ] {interaction criterion 2 — e.g., "Accordion expand/collapse animation"}
- [ ] Keyboard navigation works (Tab, Enter, Escape)
<br>
<b>Multi-Theme:</b>
- [ ] Test in Storybook theme switcher with at least 3 themes
- [ ] Colors and fonts adapt correctly per theme
<br>
<b>Content Variants:</b>
- [ ] Works with long text (no overflow or clipping)
- [ ] Works with minimal content (no broken layout)
- [ ] Works with empty optional fields (graceful fallback)
<br>
<b>Pixel Perfect Results (automated):</b>
Desktop diff: {X}% (threshold: ≤5%)
Mobile diff: {Y}% (threshold: ≤10%)
<br>
<b>Notes for Design Team:</b>
{any specific decisions made during implementation, deviations from Figma with reasoning, or areas that need special attention}
<br>
<i>Status updated to "7. Design — Ready for Review".</i>
<i>Please update to "8. Design — In Review" when you start reviewing.</i>

Rule: This comment MUST be posted by Claude when the PR is approved by the Tech Lead (transition 6→7). It is the Design team’s primary source of context. Every field must be filled — no placeholders.

PR Merged

<b>PR Merged</b>
<br>
<b>PR:</b> <a href="{prUrl}">#{prNumber}</a> merged to <b>develop</b>
<b>Merged by:</b> {user}
<b>Date:</b> {date}
<br>
<i>Awaiting deployment to DEV environment.</i>

Deployed to DEV

<b>Deployed to DEV</b>
<br>
<b>Deploy PR:</b> <a href="{deployPrUrl}">#{deployPrNumber}</a>
<b>Date:</b> {date}
<br>
<b>Test URLs:</b>
- <a href="https://savoy-dev-signature.wycreative.com">DEV Site (Signature)</a>
- <a href="https://savoy-dev-storybook.wycreative.com">Storybook</a>
- <a href="https://savoy-dev-cms.wycreative.com/umbraco">Umbraco CMS</a>
<br>
<i>Status: "9. QA — Ready for Acceptance". Ready for testing.</i>

QA Accepted

<b>QA Accepted</b>
<br>
<b>Task:</b> {taskName}
<b>Tested by:</b> {qaTeamMember}
<b>Date:</b> {date}
<br>
<b>Test Results:</b>
- {what was tested}
- {any notes or observations}
<br>
<i>Status updated to "11. QA — Accepted". Awaiting PO/Tech Lead sign-off for "12. Done".</i>

Rollback

<b>Rollback</b>
<br>
<b>PR:</b> <a href="{prUrl}">#{prNumber}</a> reverted from <b>develop</b>
<b>Reason:</b> {why the rollback was needed}
<b>Date:</b> {date}
<br>
<b>Next steps:</b> {what needs to happen before re-merge}
<br>
<i>Status reverted to "3. In Development".</i>

---

8. Error Handling & Resilience

8.1 Status Update Failures

Rules:

1. Retry failed zoho_update_task exactly once
2. If retry fails, notify user immediately with error details
3. Never silently skip a failed update
4. If user approves skipping, log the intended status in the next comment posted to the task

8.2 Task ID Loss (Context Compression)

8.3 Task Not Found at Start

---

9. Development Passes (Iterative Cycles)

9.1 The Problem

When AI development outpaces design, modules are often built before Figma is finalized — or even before it exists. This creates two scenarios:

Scenario	Example	What’s missing
Module built against draft Figma	M27 Text Image — Figma exists but not approved	Final visual alignment, possible layout changes
Module built without any Figma	M28 Icon List — built from PRD/spec only	Full Figma analysis, visual alignment, pixel-perfect testing

The standard single-pass workflow (A→B→B7→C→Done) doesn’t account for this. Modules need to cycle back through specific phases when design arrives or changes.

9.2 Pass Types

A module can go through multiple development passes. Each pass is tracked via a tag and a structured re-entry comment.

Pass	Tag	When triggered	Re-entry point	Phases repeated
Pass 1 — Initial Build	pass:initial	First development	Phase A	A → B → B7* → C
Pass 2 — Design Revision	pass:design-revision	Final Figma arrives or Figma changes significantly	Phase A1 (re-analyse)	A1 → B (fixes) → B7 (full)
Pass 3 — Polish	pass:polish	Design Review feedback with minor issues	Phase B	B (CSS fixes) → B7
Pass N — Hotfix	pass:hotfix	Bug found post-QA	Phase B	B (fix) → B7

*Phase B7 in Pass 1: If no Figma exists, B7 (Pixel Perfect) is skipped during Pass 1. If a draft Figma exists, B7 runs against the draft but results are informational only (threshold failures don’t block). The hard gate B7 only applies in Pass 2+ when final Figma is available.

9.3 Design Availability Tags

Track the Figma status on each task to know which pass is needed:

Tag	Meaning	What Claude does
design:none	No Figma exists for this module	Build from PRD/spec; skip Phase B7; Phase C OK if content model is known
design:draft	Figma exists but not approved	Build against draft; run B7 informally (no hard gate); expect Pass 2
design:final	Figma approved by client	Full B7 hard gate; pixel-perfect validation required
design:revised	Figma changed after initial build	Pass 2 triggered; compare changes and fix

Claude sets the design tag at the start of each pass based on Figma availability.

9.4 How Passes Work on the Board

The task re-enters 3. In Development for each new pass. The board shows it moving backwards — this is expected and normal.

Key rules:

• When a task cycles back to 3. In Development, Claude posts a Re-entry Comment (see section 9.6)
• The percent_complete resets to the re-entry point percentage (e.g., 0% for full re-entry, 50% for B-only)
• The pass tag (pass:design-revision) is updated
• Previous pass history is preserved in comments — never deleted

9.5 Re-Entry Decision Tree

When the user says “Figma is ready for M{XX}” or “Design changed for M{XX}“:

9.6 Re-Entry Comment Template

When a task cycles back to 3. In Development for a new pass:

<b>Development Pass {N} — {Pass Type}</b>
<br>
<b>Task:</b> {taskName}
<b>Previous status:</b> {previousStatus}
<b>Reason:</b> {why re-entering development}
<b>Date:</b> {date}
<br>
<b>Design Status Change:</b>
<b>Previous:</b> {design:none|draft}
<b>Current:</b> {design:final|revised}
<b>Figma Desktop:</b> <a href="{figmaDesktopUrl}">{linkText}</a>
<b>Figma Mobile:</b> <a href="{figmaMobileUrl}">{linkText}</a>
<br>
<b>What Changed (Figma vs Current Implementation):</b>
- {change 1 — e.g., "Title now left-aligned instead of centered"}
- {change 2 — e.g., "New CTA button added below description"}
- {change 3 — e.g., "Mobile layout changed from stacked to side-by-side"}
<br>
<b>Re-entry Point:</b> Phase {A1|B|B7}
<b>Phases to Repeat:</b> {A1 → B → B7 | B → B7 | B7 only}
<b>Estimated Scope:</b> {small — CSS tweaks | medium — layout changes | large — structural rework}
<br>
<b>Progress Reset:</b> {percent}% (was {previousPercent}%)
<br>
<i>Status: "3. In Development". Pass {N} ({passType}) started.</i>

9.7 Modules Without Figma — Phase Adjustments

When building a module with design:none:

Phase	Normal (with Figma)	Without Figma
A1 — Figma Analysis	Analyse Figma designs	Skip — use PRD/spec descriptions
A3 — Types	Match Figma content structure	Define from PRD content model
A4 — Stories	FigmaFidelity story with exact Figma content	Skip FigmaFidelity — create Default with realistic content
B1 — Component	Match Figma pixel-perfect	Build reasonable layout from PRD; use similar modules as reference
B7 — Visual Testing	Hard gate: desktop ≤5%, mobile ≤10%	Skip entirely — no Figma baseline to compare against
C — Umbraco	Element Type matches Figma fields	Element Type matches PRD fields — may need revision in Pass 2

When Figma arrives (Pass 2):

1. A1 — Full Figma analysis (desktop + mobile)
2. A4 — Create FigmaFidelity story with exact Figma content
3. B1 — Align component to Figma (CSS/layout fixes)
4. B7 — Fetch Figma baselines → run pixel-perfect (hard gate now applies)
5. C — Verify Element Type fields match Figma; add migration if content model changed

9.8 Impact on Metrics

Multi-pass modules affect cycle time metrics. Track separately:

Metric	How to handle
Total cycle time	Measure from first 2. To Do to final 12. Done (includes all passes)
Per-pass cycle time	Measure each 3. In Development → 11. QA Accepted cycle separately
Pass count	Track average passes per module — target: ≤ 2
Design-blocked time	Time between Pass 1 completion and Pass 2 start (waiting for Figma)
Rework ratio	Lines changed in Pass 2+ vs Pass 1 — lower is better (initial build was close)

---

10. Zoho MCP Tools Reference

10.1 Available Tools

Action	Tool	Required params	Optional params
Search tasks	zoho_search_tasks	query	status (open/closed/all)
Get task details	zoho_get_task	task_id	raw
List tasks	zoho_list_tasks	—	status, tasklist_id, owner, limit
List tasklists	zoho_list_tasklists	—	—
List milestones	zoho_list_milestones	—	status
Create task	zoho_create_task	name, tasklist_id	description, priority, cf_type, cf_figma, cf_storybook, cf_git, cf_environment, cf_doc_learn, parent_task_id, start_date, end_date
Update task	zoho_update_task	task_id	status_name, name, description, priority, percent_complete, start_date, end_date
Add comment	zoho_add_comment	task_id, content (HTML)	—
List comments	zoho_list_comments	task_id	—
Get custom fields	zoho_get_custom_fields	—	—

10.2 Custom Fields

Field	API key	Type	Values
Type	cf_type	Enum	Task, Management & Governance, Design, Setup, Functional, Component, Module, Template, Content
Environment	cf_environment	Enum	LOCAL, DEV, DEV-CLIENT, ACC-QUA, PROD
Figma URL	cf_figma	URL	Figma design link
Storybook URL	cf_storybook	URL	Storybook story link
Git URL	cf_git	URL	Repository / branch link
DOC / Learn	cf_doc_learn	URL	Documentation link

10.3 Date Format

Zoho API uses MM-DD-YYYY format for dates. Always convert before sending:

March 21, 2026 → 03-21-2026

---

11. URL Patterns

Resource	Pattern
Zoho task	https://projects.zoho.com/portal/wygroup#zp/task-detail/{taskSystemId}
Azure DevOps PR	https://dev.azure.com/Bycom/Savoy%20Signature/_git/Savoy%20Signature/pullrequest/{prId}
Storybook (module)	https://savoy-dev-storybook.wycreative.com/?path=/docs/modules-m{xx}---{kebab-name}--docs
Storybook (component)	https://savoy-dev-storybook.wycreative.com/?path=/docs/ui-{component-name}--docs
Umbraco backoffice	https://savoy-dev-cms.wycreative.com/umbraco
DEV site (Signature)	https://savoy-dev-signature.wycreative.com
DEV site (per hotel)	https://savoy-dev-{site-key}.wycreative.com
DEV site (direct, no auth)	https://app-nextjs-savoy-dev.azurewebsites.net

---

12. Best Practices

12.1 For Claude (AI Agent)

Practice	Why
Post “Development Started” comment + set tag ai:storybook immediately	Stakeholders know work has begun; next session knows where to resume
Update percent_complete at every phase transition	Progress bar visible in Zoho without opening the task
Use 4. Awaiting Input whenever blocked on human decision	Makes bottlenecks visible on the board
Post the Design Review Handoff comment with ALL fields filled	Design team’s only source of context — must be self-contained
Always link PR ↔ Zoho bidirectionally	Traceability works in both directions
Retry failed status updates, never skip silently	Status board must reflect reality
Re-fetch task_id if lost, never guess	Wrong task updates are worse than none
Only transition statuses you own (2→3, 3↔4, 3→5)	Human gates belong to humans

12.2 For Tech Lead (Rui)

Practice	Why
Move 5 → 6 when picking up a PR review	Makes “active review” visible vs “queued”
Move 6 → 7 when code approved, post approval comment	Design team gets notified
Move 6 → 3 when changes requested	Claude knows to fix and re-submit
Move 11 → 12 for final sign-off	Only PO/Tech Lead closes tasks
Check 4. Awaiting Input daily	Claude’s bottleneck — your response unblocks progress
Check 5. Dev — Ready for Review daily	PRs waiting for you

12.3 For Design Team (Liliana, João)

Practice	Why
Move 7 → 8 when starting a design review	Makes “active review” visible
Read the Design Review Handoff comment carefully	Contains Figma links, Storybook URLs, acceptance criteria
Test in Storybook first (isolated), then DEV site (in context)	Storybook shows all variants; DEV shows real data
Use Storybook theme switcher to test at least 3 themes	Theming issues are common
Test at 375px, 768px, 1024px, 1440px	Responsive must be fluid between breakpoints
Post a detailed comment when approving or rejecting	Claude needs specifics to fix issues
Move 8 → 9 when approved, or 8 → 3 when issues found	Clear next step for QA or Claude

12.4 For QA / PM (Gabriela, Michelle)

Practice	Why
Move 9 → 10 when starting acceptance testing	Makes “active testing” visible
Test on DEV site with real CMS content	Storybook uses mock data; DEV uses real API
Verify active=false hides the module	Required for every module
Post detailed comment when accepting or rejecting	Specifics help Claude fix faster
Move 10 → 11 when QA passes	Awaits PO/Tech Lead final sign-off

12.5 Anti-Patterns

#	Anti-Pattern	Correct Approach
1	Starting development without a Zoho task	Search first; create or request link if not found
2	Starting work without “Development Started” comment	Post comment + update tag + set percent immediately
3	Using wrong status name (e.g., Dev - Ready)	Copy exact string with em-dash: 5. Dev — Ready for Review
4	Silently skipping failed status update	Retry once, then notify user
5	Losing task_id in long sessions	Announce after lookup; re-fetch if lost
6	Claude transitioning human-owned statuses	Only transition 2→3, 3↔4, 3→5 — everything else is human
7	PR without Zoho task key in title	Every PR title includes [P894-T{XXX}]
8	Creating PR without posting Zoho comment	Post structured comment with pre-PR checks
9	Skipping Design Review Handoff comment	Design team has no context without it — CRITICAL
10	Moving to 12. Done without PO/TL sign-off	QA Accepted (11) is not Done (12) — separate gate
11	Rolling back without notifying Zoho	Post rollback comment + revert status to 3
12	Not updating percent_complete during development	Progress bar invisible — stakeholders can’t see progress within “In Development”
13	Leaving task in 3. In Development between sessions	Update tag and percent so next session knows where to resume
14	Building module without setting design:none or design:draft tag	Always set design availability tag at start — determines whether B7 is a hard gate
15	Running B7 as hard gate when Figma doesn’t exist	B7 is skipped for design:none; informational-only for design:draft; hard gate only for design:final
16	Re-entering development without a Re-entry Comment	Every pass must start with a structured comment explaining why, what changed, and which phases to repeat
17	Deleting previous pass comments when cycling back	All pass history must be preserved in comments — never delete previous iterations

---

13. Kanban Board Layout

13.1 Full Board

┌─────────┬────────┬──────────┬──────────┬───────────┬───────────┬────────────┬────────────┬────────────┬────────────┬────────────┬──────┐
│ Backlog │ To Do  │  In Dev  │ Awaiting │Dev—Ready  │Dev—In     │Design—Ready│Design—In   │ QA—Ready   │ QA—In      │QA—Accepted │ Done │
│         │        │          │  Input   │for Review │Review     │for Review  │Review      │for Accept. │Acceptance  │            │      │
│         │        │          │          │           │           │            │            │            │            │            │      │
│ future  │ queue  │ CLAUDE   │ HUMAN    │queue→Rui  │ RUI       │queue→Design│ DESIGN     │queue→QA    │ QA/PM      │queue→PO/TL │  ✓   │
│         │        │ (active) │ (blocked)│           │ (active)  │            │ (active)   │            │ (active)   │            │      │
│         │        │          │          │           │           │            │            │            │            │            │      │
│  grey   │  blue  │ purple   │ orange   │light blue │ blue      │ light pink │ pink       │light green │ green      │dark green  │green │
└─────────┴────────┴──────────┴──────────┴───────────┴───────────┴────────────┴────────────┴────────────┴────────────┴────────────┴──────┘
                       │                                  │                        │                        │
                       │◄─────────────────────────────────┘ (changes requested)    │                        │
                       │◄──────────────────────────────────────────────────────────┘ (design issues)        │
                       │◄──────────────────────────────────────────────────────────────────────────────────┘ (bugs found)

13.2 Simplified View (Grouped by Team)

For a high-level view, the 13 statuses can be grouped into 5 swimlanes:

13.3 Reading the Board — Key Signals

Signal	Meaning	Action
Tasks pile up in 4. Awaiting Input	Claude is blocked waiting for humans	Tech Lead must respond
Tasks pile up in 5. Dev — Ready for Review	PRs waiting for code review	Tech Lead must schedule review
Tasks pile up in 7. Design — Ready for Review	Code approved but Design hasn’t started	Design Team must pick up reviews
Tasks pile up in 9. QA — Ready for Acceptance	Design approved but QA hasn’t tested	QA/PM must test on DEV
Tasks pile up in 11. QA — Accepted	QA passed but not officially closed	PO/Tech Lead must sign off
Empty 2. To Do	Claude has nothing to work on	Prioritize from Backlog
Multiple tasks in 3. In Development	Claude may have stale sessions	Check if sessions are active or abandoned

---

14. Metrics & Reporting

14.1 Key Metrics to Track

Metric	How to measure	Target
Claude development time	Duration in status 3 (In Development)	Baseline: 4-8h per module
Awaiting Input time	Duration in status 4	< 4 hours
Dev queue time	Duration in status 5 (Ready for Review)	< 8 hours
Dev review time	Duration in status 6 (In Review)	< 4 hours
Design queue time	Duration in status 7 (Ready for Review)	< 24 hours
Design review time	Duration in status 8 (In Review)	< 48 hours
QA queue time	Duration in status 9 (Ready for Acceptance)	< 24 hours
QA acceptance time	Duration in status 10 (In Acceptance)	< 24 hours
Sign-off queue time	Duration in status 11 (Accepted → Done)	< 8 hours
End-to-end cycle time	2. To Do → 12. Done	< 1 week per module
Tasks completed per week	Count reaching 12. Done	Increasing trend
Human bottleneck ratio	Tasks in queue statuses (5+7+9+11) vs total open	< 30%

14.2 Queue vs Active Time Analysis

The Ready/In split enables measuring where time is actually spent:

Key insight: In AI-driven development, the active development time (30%) is smaller than the total human review time (50%). The biggest optimization lever is reducing queue times (35%) — the time tasks sit waiting for humans to pick them up.

14.3 Bottleneck Identification

Queue/Active Ratio	What it means	Action
Queue >> Active (same team)	Team has capacity but tasks aren’t being noticed	Improve notifications / daily review routine
Active >> Queue (same team)	Reviews are thorough but slow	Check if acceptance criteria are clear enough
Multiple teams with high queue	Systemic issue — too many tasks in flight	Reduce WIP limits; batch fewer tasks before review cycles
Only one team with high queue	Specific team bottleneck	Address with that team directly

---

15. References

Resource	Location
Zoho integration rules (canonical)	.claude/rules/zoho-integration.md
Git workflow rules	.claude/rules/git-workflow.md
Anti-patterns	.claude/rules/anti-patterns.md
CI/CD pipeline	.azure/pipelines/deploy-dev.yml
Module lifecycle	.claude/rules/frontend-module.md
PRD Index	docs/PRD/00_Introduction_and_Index.md